JSON: avoid recent library version usage
[users/jgh/exim.git] / doc / doc-docbook / spec.xfpt
1 . /////////////////////////////////////////////////////////////////////////////
2 . This is the primary source of the Exim Manual. It is an xfpt document that is
3 . converted into DocBook XML for subsequent conversion into printing and online
4 . formats. The markup used herein is "standard" xfpt markup, with some extras.
5 . The markup is summarized in a file called Markup.txt.
6 .
7 . WARNING: When you use the .new macro, make sure it appears *before* any
8 . adjacent index items; otherwise you get an empty "paragraph" which causes
9 . unwanted vertical space.
10 . /////////////////////////////////////////////////////////////////////////////
11
12 .include stdflags
13 .include stdmacs
14
15 . /////////////////////////////////////////////////////////////////////////////
16 . This outputs the standard DocBook boilerplate.
17 . /////////////////////////////////////////////////////////////////////////////
18
19 .docbook
20
21 . /////////////////////////////////////////////////////////////////////////////
22 . These lines are processing instructions for the Simple DocBook Processor that
23 . Philip Hazel has developed as a less cumbersome way of making PostScript and
24 . PDFs than using xmlto and fop. They will be ignored by all other XML
25 . processors.
26 . /////////////////////////////////////////////////////////////////////////////
27
28 .literal xml
29 <?sdop
30   foot_right_recto="&chaptertitle; (&chapternumber;)"
31   foot_right_verso="&chaptertitle; (&chapternumber;)"
32   toc_chapter_blanks="yes,yes"
33   table_warn_overflow="overprint"
34 ?>
35 .literal off
36
37 . /////////////////////////////////////////////////////////////////////////////
38 . This generate the outermost <book> element that wraps then entire document.
39 . /////////////////////////////////////////////////////////////////////////////
40
41 .book
42
43 . /////////////////////////////////////////////////////////////////////////////
44 . These definitions set some parameters and save some typing.
45 . Update the Copyright year (only) when changing content.
46 . /////////////////////////////////////////////////////////////////////////////
47
48 .set previousversion "4.91"
49 .include ./local_params
50
51 .set ACL "access control lists (ACLs)"
52 .set I   "&nbsp;&nbsp;&nbsp;&nbsp;"
53
54 .macro copyyear
55 2018
56 .endmacro
57
58 . /////////////////////////////////////////////////////////////////////////////
59 . Additional xfpt markup used by this document, over and above the default
60 . provided in the xfpt library.
61 . /////////////////////////////////////////////////////////////////////////////
62
63 . --- Override the &$ flag to automatically insert a $ with the variable name
64
65 .flag &$  $&   "<varname>$"  "</varname>"
66
67 . --- Short flags for daggers in option headings. They will always be inside
68 . --- an italic string, but we want the daggers to be roman.
69
70 .flag &!!      "</emphasis>&dagger;<emphasis>"
71 .flag &!?      "</emphasis>&Dagger;<emphasis>"
72
73 . --- A macro for an Exim option definition heading, generating a one-line
74 . --- table with four columns. For cases when the option name is given with
75 . --- a space, so that it can be split, a fifth argument is used for the
76 . --- index entry.
77
78 .macro option
79 .arg 5
80 .oindex "&%$5%&"
81 .endarg
82 .arg -5
83 .oindex "&%$1%&"
84 .endarg
85 .itable all 0 0 4 8* left 6* center 6* center 6* right
86 .row "&%$1%&" "Use: &'$2'&" "Type: &'$3'&" "Default: &'$4'&"
87 .endtable
88 .endmacro
89
90 . --- A macro for the common 2-column tables. The width of the first column
91 . --- is suitable for the many tables at the start of the main options chapter;
92 . --- the small number of other 2-column tables override it.
93
94 .macro table2 196pt 254pt
95 .itable none 0 0 2 $1 left $2 left
96 .endmacro
97
98 . --- A macro that generates .row, but puts &I; at the start of the first
99 . --- argument, thus indenting it. Assume a minimum of two arguments, and
100 . --- allow up to four arguments, which is as many as we'll ever need.
101
102 .macro irow
103 .arg 4
104 .row "&I;$1" "$2" "$3" "$4"
105 .endarg
106 .arg -4
107 .arg 3
108 .row "&I;$1" "$2" "$3"
109 .endarg
110 .arg -3
111 .row "&I;$1" "$2"
112 .endarg
113 .endarg
114 .endmacro
115
116 . --- Macros for option, variable, and concept index entries. For a "range"
117 . --- style of entry, use .scindex for the start and .ecindex for the end. The
118 . --- first argument of .scindex and the only argument of .ecindex must be the
119 . --- ID that ties them together.
120
121 .macro cindex
122 &<indexterm role="concept">&
123 &<primary>&$1&</primary>&
124 .arg 2
125 &<secondary>&$2&</secondary>&
126 .endarg
127 &</indexterm>&
128 .endmacro
129
130 .macro scindex
131 &<indexterm role="concept" id="$1" class="startofrange">&
132 &<primary>&$2&</primary>&
133 .arg 3
134 &<secondary>&$3&</secondary>&
135 .endarg
136 &</indexterm>&
137 .endmacro
138
139 .macro ecindex
140 &<indexterm role="concept" startref="$1" class="endofrange"/>&
141 .endmacro
142
143 .macro oindex
144 &<indexterm role="option">&
145 &<primary>&$1&</primary>&
146 .arg 2
147 &<secondary>&$2&</secondary>&
148 .endarg
149 &</indexterm>&
150 .endmacro
151
152 .macro vindex
153 &<indexterm role="variable">&
154 &<primary>&$1&</primary>&
155 .arg 2
156 &<secondary>&$2&</secondary>&
157 .endarg
158 &</indexterm>&
159 .endmacro
160
161 .macro index
162 .echo "** Don't use .index; use .cindex or .oindex or .vindex"
163 .endmacro
164 . ////////////////////////////////////////////////////////////////////////////
165
166
167 . ////////////////////////////////////////////////////////////////////////////
168 . The <bookinfo> element is removed from the XML before processing for Ascii
169 . output formats.
170 . ////////////////////////////////////////////////////////////////////////////
171
172 .literal xml
173 <bookinfo>
174 <title>Specification of the Exim Mail Transfer Agent</title>
175 <titleabbrev>The Exim MTA</titleabbrev>
176 <date>
177 .fulldate
178 </date>
179 <author><firstname>Exim</firstname><surname>Maintainers</surname></author>
180 <authorinitials>EM</authorinitials>
181 <revhistory><revision>
182 .versiondatexml
183   <authorinitials>EM</authorinitials>
184 </revision></revhistory>
185 <copyright><year>
186 .copyyear
187            </year><holder>University of Cambridge</holder></copyright>
188 </bookinfo>
189 .literal off
190
191
192 . /////////////////////////////////////////////////////////////////////////////
193 . This chunk of literal XML implements index entries of the form "x, see y" and
194 . "x, see also y". However, the DocBook DTD doesn't allow <indexterm> entries
195 . at the top level, so we have to put the .chapter directive first.
196 . /////////////////////////////////////////////////////////////////////////////
197
198 .chapter "Introduction" "CHID1"
199 .literal xml
200
201 <indexterm role="variable">
202   <primary>$1, $2, etc.</primary>
203   <see><emphasis>numerical variables</emphasis></see>
204 </indexterm>
205 <indexterm role="concept">
206   <primary>address</primary>
207   <secondary>rewriting</secondary>
208   <see><emphasis>rewriting</emphasis></see>
209 </indexterm>
210 <indexterm role="concept">
211   <primary>Bounce Address Tag Validation</primary>
212   <see><emphasis>BATV</emphasis></see>
213 </indexterm>
214 <indexterm role="concept">
215   <primary>Client SMTP Authorization</primary>
216   <see><emphasis>CSA</emphasis></see>
217 </indexterm>
218 <indexterm role="concept">
219   <primary>CR character</primary>
220   <see><emphasis>carriage return</emphasis></see>
221 </indexterm>
222 <indexterm role="concept">
223   <primary>CRL</primary>
224   <see><emphasis>certificate revocation list</emphasis></see>
225 </indexterm>
226 <indexterm role="concept">
227   <primary>delivery</primary>
228   <secondary>failure report</secondary>
229   <see><emphasis>bounce message</emphasis></see>
230 </indexterm>
231 <indexterm role="concept">
232   <primary>dialup</primary>
233   <see><emphasis>intermittently connected hosts</emphasis></see>
234 </indexterm>
235 <indexterm role="concept">
236   <primary>exiscan</primary>
237   <see><emphasis>content scanning</emphasis></see>
238 </indexterm>
239 <indexterm role="concept">
240   <primary>failover</primary>
241   <see><emphasis>fallback</emphasis></see>
242 </indexterm>
243 <indexterm role="concept">
244   <primary>fallover</primary>
245   <see><emphasis>fallback</emphasis></see>
246 </indexterm>
247 <indexterm role="concept">
248   <primary>filter</primary>
249   <secondary>Sieve</secondary>
250   <see><emphasis>Sieve filter</emphasis></see>
251 </indexterm>
252 <indexterm role="concept">
253   <primary>ident</primary>
254   <see><emphasis>RFC 1413</emphasis></see>
255 </indexterm>
256 <indexterm role="concept">
257   <primary>LF character</primary>
258   <see><emphasis>linefeed</emphasis></see>
259 </indexterm>
260 <indexterm role="concept">
261   <primary>maximum</primary>
262   <seealso><emphasis>limit</emphasis></seealso>
263 </indexterm>
264 <indexterm role="concept">
265   <primary>monitor</primary>
266   <see><emphasis>Exim monitor</emphasis></see>
267 </indexterm>
268 <indexterm role="concept">
269   <primary>no_<emphasis>xxx</emphasis></primary>
270   <see>entry for xxx</see>
271 </indexterm>
272 <indexterm role="concept">
273   <primary>NUL</primary>
274   <see><emphasis>binary zero</emphasis></see>
275 </indexterm>
276 <indexterm role="concept">
277   <primary>passwd file</primary>
278   <see><emphasis>/etc/passwd</emphasis></see>
279 </indexterm>
280 <indexterm role="concept">
281   <primary>process id</primary>
282   <see><emphasis>pid</emphasis></see>
283 </indexterm>
284 <indexterm role="concept">
285   <primary>RBL</primary>
286   <see><emphasis>DNS list</emphasis></see>
287 </indexterm>
288 <indexterm role="concept">
289   <primary>redirection</primary>
290   <see><emphasis>address redirection</emphasis></see>
291 </indexterm>
292 <indexterm role="concept">
293   <primary>return path</primary>
294   <seealso><emphasis>envelope sender</emphasis></seealso>
295 </indexterm>
296 <indexterm role="concept">
297   <primary>scanning</primary>
298   <see><emphasis>content scanning</emphasis></see>
299 </indexterm>
300 <indexterm role="concept">
301   <primary>SSL</primary>
302   <see><emphasis>TLS</emphasis></see>
303 </indexterm>
304 <indexterm role="concept">
305   <primary>string</primary>
306   <secondary>expansion</secondary>
307   <see><emphasis>expansion</emphasis></see>
308 </indexterm>
309 <indexterm role="concept">
310   <primary>top bit</primary>
311   <see><emphasis>8-bit characters</emphasis></see>
312 </indexterm>
313 <indexterm role="concept">
314   <primary>variables</primary>
315   <see><emphasis>expansion, variables</emphasis></see>
316 </indexterm>
317 <indexterm role="concept">
318   <primary>zero, binary</primary>
319   <see><emphasis>binary zero</emphasis></see>
320 </indexterm>
321
322 .literal off
323
324
325 . /////////////////////////////////////////////////////////////////////////////
326 . This is the real start of the first chapter. See the comment above as to why
327 . we can't have the .chapter line here.
328 . chapter "Introduction"
329 . /////////////////////////////////////////////////////////////////////////////
330
331 Exim is a mail transfer agent (MTA) for hosts that are running Unix or
332 Unix-like operating systems. It was designed on the assumption that it would be
333 run on hosts that are permanently connected to the Internet. However, it can be
334 used on intermittently connected hosts with suitable configuration adjustments.
335
336 Configuration files currently exist for the following operating systems: AIX,
337 BSD/OS (aka BSDI), Darwin (Mac OS X), DGUX, Dragonfly, FreeBSD, GNU/Hurd,
338 GNU/Linux, HI-OSF (Hitachi), HI-UX, HP-UX, IRIX, MIPS RISCOS, NetBSD, OpenBSD,
339 OpenUNIX, QNX, SCO, SCO SVR4.2 (aka UNIX-SV), Solaris (aka SunOS5), SunOS4,
340 Tru64-Unix (formerly Digital UNIX, formerly DEC-OSF1), Ultrix, and Unixware.
341 Some of these operating systems are no longer current and cannot easily be
342 tested, so the configuration files may no longer work in practice.
343
344 There are also configuration files for compiling Exim in the Cygwin environment
345 that can be installed on systems running Windows. However, this document does
346 not contain any information about running Exim in the Cygwin environment.
347
348 The terms and conditions for the use and distribution of Exim are contained in
349 the file &_NOTICE_&. Exim is distributed under the terms of the GNU General
350 Public Licence, a copy of which may be found in the file &_LICENCE_&.
351
352 The use, supply or promotion of Exim for the purpose of sending bulk,
353 unsolicited electronic mail is incompatible with the basic aims of the program,
354 which revolve around the free provision of a service that enhances the quality
355 of personal communications. The author of Exim regards indiscriminate
356 mass-mailing as an antisocial, irresponsible abuse of the Internet.
357
358 Exim owes a great deal to Smail 3 and its author, Ron Karr. Without the
359 experience of running and working on the Smail 3 code, I could never have
360 contemplated starting to write a new MTA. Many of the ideas and user interfaces
361 were originally taken from Smail 3, though the actual code of Exim is entirely
362 new, and has developed far beyond the initial concept.
363
364 Many people, both in Cambridge and around the world, have contributed to the
365 development and the testing of Exim, and to porting it to various operating
366 systems. I am grateful to them all. The distribution now contains a file called
367 &_ACKNOWLEDGMENTS_&, in which I have started recording the names of
368 contributors.
369
370
371 .section "Exim documentation" "SECID1"
372 . Keep this example change bar when updating the documentation!
373
374 .new
375 .cindex "documentation"
376 This edition of the Exim specification applies to version &version() of Exim.
377 Substantive changes from the &previousversion; edition are marked in some
378 renditions of the document; this paragraph is so marked if the rendition is
379 capable of showing a change indicator.
380 .wen
381
382 This document is very much a reference manual; it is not a tutorial. The reader
383 is expected to have some familiarity with the SMTP mail transfer protocol and
384 with general Unix system administration. Although there are some discussions
385 and examples in places, the information is mostly organized in a way that makes
386 it easy to look up, rather than in a natural order for sequential reading.
387 Furthermore, the manual aims to cover every aspect of Exim in detail, including
388 a number of rarely-used, special-purpose features that are unlikely to be of
389 very wide interest.
390
391 .cindex "books about Exim"
392 An &"easier"& discussion of Exim which provides more in-depth explanatory,
393 introductory, and tutorial material can be found in a book entitled &'The Exim
394 SMTP Mail Server'& (second edition, 2007), published by UIT Cambridge
395 (&url(https://www.uit.co.uk/exim-book/)).
396
397 This book also contains a chapter that gives a general introduction to SMTP and
398 Internet mail. Inevitably, however, the book is unlikely to be fully up-to-date
399 with the latest release of Exim. (Note that the earlier book about Exim,
400 published by O'Reilly, covers Exim 3, and many things have changed in Exim 4.)
401
402 .cindex "Debian" "information sources"
403 If you are using a Debian distribution of Exim, you will find information about
404 Debian-specific features in the file
405 &_/usr/share/doc/exim4-base/README.Debian_&.
406 The command &(man update-exim.conf)& is another source of Debian-specific
407 information.
408
409 .cindex "&_doc/NewStuff_&"
410 .cindex "&_doc/ChangeLog_&"
411 .cindex "change log"
412 As the program develops, there may be features in newer versions that have not
413 yet made it into this document, which is updated only when the most significant
414 digit of the fractional part of the version number changes. Specifications of
415 new features that are not yet in this manual are placed in the file
416 &_doc/NewStuff_& in the Exim distribution.
417
418 Some features may be classified as &"experimental"&. These may change
419 incompatibly while they are developing, or even be withdrawn. For this reason,
420 they are not documented in this manual. Information about experimental features
421 can be found in the file &_doc/experimental.txt_&.
422
423 All changes to the program (whether new features, bug fixes, or other kinds of
424 change) are noted briefly in the file called &_doc/ChangeLog_&.
425
426 .cindex "&_doc/spec.txt_&"
427 This specification itself is available as an ASCII file in &_doc/spec.txt_& so
428 that it can easily be searched with a text editor. Other files in the &_doc_&
429 directory are:
430
431 .table2 100pt
432 .row &_OptionLists.txt_&     "list of all options in alphabetical order"
433 .row &_dbm.discuss.txt_&     "discussion about DBM libraries"
434 .row &_exim.8_&              "a man page of Exim's command line options"
435 .row &_experimental.txt_&    "documentation of experimental features"
436 .row &_filter.txt_&          "specification of the filter language"
437 .row &_Exim3.upgrade_&       "upgrade notes from release 2 to release 3"
438 .row &_Exim4.upgrade_&       "upgrade notes from release 3 to release 4"
439 .row &_openssl.txt_&         "installing a current OpenSSL release"
440 .endtable
441
442 The main specification and the specification of the filtering language are also
443 available in other formats (HTML, PostScript, PDF, and Texinfo). Section
444 &<<SECTavail>>& below tells you how to get hold of these.
445
446
447
448 .section "FTP and web sites" "SECID2"
449 .cindex "web site"
450 .cindex "FTP site"
451 The primary site for Exim source distributions is the &%exim.org%& FTP site,
452 available over HTTPS, HTTP and FTP.  These services, and the &%exim.org%&
453 website, are hosted at the University of Cambridge.
454
455 .cindex "wiki"
456 .cindex "FAQ"
457 As well as Exim distribution tar files, the Exim web site contains a number of
458 differently formatted versions of the documentation. A recent addition to the
459 online information is the Exim wiki (&url(https://wiki.exim.org)),
460 which contains what used to be a separate FAQ, as well as various other
461 examples, tips, and know-how that have been contributed by Exim users.
462 The wiki site should always redirect to the correct place, which is currently
463 provided by GitHub, and is open to editing by anyone with a GitHub account.
464
465 .cindex Bugzilla
466 An Exim Bugzilla exists at &url(https://bugs.exim.org). You can use
467 this to report bugs, and also to add items to the wish list. Please search
468 first to check that you are not duplicating a previous entry.
469 Please do not ask for configuration help in the bug-tracker.
470
471
472 .section "Mailing lists" "SECID3"
473 .cindex "mailing lists" "for Exim users"
474 The following Exim mailing lists exist:
475
476 .table2 140pt
477 .row &'exim-announce@exim.org'&   "Moderated, low volume announcements list"
478 .row &'exim-users@exim.org'&      "General discussion list"
479 .row &'exim-dev@exim.org'&        "Discussion of bugs, enhancements, etc."
480 .row &'exim-cvs@exim.org'&        "Automated commit messages from the VCS"
481 .endtable
482
483 You can subscribe to these lists, change your existing subscriptions, and view
484 or search the archives via the mailing lists link on the Exim home page.
485 .cindex "Debian" "mailing list for"
486 If you are using a Debian distribution of Exim, you may wish to subscribe to
487 the Debian-specific mailing list &'pkg-exim4-users@lists.alioth.debian.org'&
488 via this web page:
489 .display
490 &url(https://alioth-lists.debian.net/cgi-bin/mailman/listinfo/pkg-exim4-users)
491 .endd
492 Please ask Debian-specific questions on this list and not on the general Exim
493 lists.
494
495 .section "Bug reports" "SECID5"
496 .cindex "bug reports"
497 .cindex "reporting bugs"
498 Reports of obvious bugs can be emailed to &'bugs@exim.org'& or reported
499 via the Bugzilla (&url(https://bugs.exim.org)). However, if you are unsure
500 whether some behaviour is a bug or not, the best thing to do is to post a
501 message to the &'exim-dev'& mailing list and have it discussed.
502
503
504
505 .section "Where to find the Exim distribution" "SECTavail"
506 .cindex "FTP site"
507 .cindex "HTTPS download site"
508 .cindex "distribution" "ftp site"
509 .cindex "distribution" "https site"
510 The master distribution site for the Exim distribution is
511 .display
512 &url(https://downloads.exim.org/)
513 .endd
514 The service is available over HTTPS, HTTP and FTP.
515 We encourage people to migrate to HTTPS.
516
517 The content served at &url(https://downloads.exim.org/) is identical to the
518 content served at &url(https://ftp.exim.org/pub/exim) and
519 &url(ftp://ftp.exim.org/pub/exim).
520
521 If accessing via a hostname containing &'ftp'&, then the file references that
522 follow are relative to the &_exim_& directories at these sites.
523 If accessing via the hostname &'downloads'& then the subdirectories described
524 here are top-level directories.
525
526 There are now quite a number of independent mirror sites around
527 the world. Those that I know about are listed in the file called &_Mirrors_&.
528
529 Within the top exim directory there are subdirectories called &_exim3_& (for
530 previous Exim 3 distributions), &_exim4_& (for the latest Exim 4
531 distributions), and &_Testing_& for testing versions. In the &_exim4_&
532 subdirectory, the current release can always be found in files called
533 .display
534 &_exim-n.nn.tar.xz_&
535 &_exim-n.nn.tar.gz_&
536 &_exim-n.nn.tar.bz2_&
537 .endd
538 where &'n.nn'& is the highest such version number in the directory. The three
539 files contain identical data; the only difference is the type of compression.
540 The &_.xz_& file is usually the smallest, while the &_.gz_& file is the
541 most portable to old systems.
542
543 .cindex "distribution" "signing details"
544 .cindex "distribution" "public key"
545 .cindex "public key for signed distribution"
546 The distributions will be PGP signed by an individual key of the Release
547 Coordinator.  This key will have a uid containing an email address in the
548 &'exim.org'& domain and will have signatures from other people, including
549 other Exim maintainers.  We expect that the key will be in the "strong set" of
550 PGP keys.  There should be a trust path to that key from Nigel Metheringham's
551 PGP key, a version of which can be found in the release directory in the file
552 &_nigel-pubkey.asc_&.  All keys used will be available in public keyserver pools,
553 such as &'pool.sks-keyservers.net'&.
554
555 At time of last update, releases were being made by Jeremy Harris and signed
556 with key &'0xBCE58C8CE41F32DF'&.  Other recent keys used for signing are those
557 of Heiko Schlittermann, &'0x26101B62F69376CE'&,
558 and of Phil Pennock, &'0x4D1E900E14C1CC04'&.
559
560 The signatures for the tar bundles are in:
561 .display
562 &_exim-n.nn.tar.xz.asc_&
563 &_exim-n.nn.tar.gz.asc_&
564 &_exim-n.nn.tar.bz2.asc_&
565 .endd
566 For each released version, the log of changes is made separately available in a
567 separate file in the directory &_ChangeLogs_& so that it is possible to
568 find out what has changed without having to download the entire distribution.
569
570 .cindex "documentation" "available formats"
571 The main distribution contains ASCII versions of this specification and other
572 documentation; other formats of the documents are available in separate files
573 inside the &_exim4_& directory of the FTP site:
574 .display
575 &_exim-html-n.nn.tar.gz_&
576 &_exim-pdf-n.nn.tar.gz_&
577 &_exim-postscript-n.nn.tar.gz_&
578 &_exim-texinfo-n.nn.tar.gz_&
579 .endd
580 These tar files contain only the &_doc_& directory, not the complete
581 distribution, and are also available in &_.bz2_& and &_.xz_& forms.
582
583
584 .section "Limitations" "SECID6"
585 .ilist
586 .cindex "limitations of Exim"
587 .cindex "bang paths" "not handled by Exim"
588 Exim is designed for use as an Internet MTA, and therefore handles addresses in
589 RFC 2822 domain format only. It cannot handle UUCP &"bang paths"&, though
590 simple two-component bang paths can be converted by a straightforward rewriting
591 configuration. This restriction does not prevent Exim from being interfaced to
592 UUCP as a transport mechanism, provided that domain addresses are used.
593 .next
594 .cindex "domainless addresses"
595 .cindex "address" "without domain"
596 Exim insists that every address it handles has a domain attached. For incoming
597 local messages, domainless addresses are automatically qualified with a
598 configured domain value. Configuration options specify from which remote
599 systems unqualified addresses are acceptable. These are then qualified on
600 arrival.
601 .next
602 .cindex "transport" "external"
603 .cindex "external transports"
604 The only external transport mechanisms that are currently implemented are SMTP
605 and LMTP over a TCP/IP network (including support for IPv6). However, a pipe
606 transport is available, and there are facilities for writing messages to files
607 and pipes, optionally in &'batched SMTP'& format; these facilities can be used
608 to send messages to other transport mechanisms such as UUCP, provided they can
609 handle domain-style addresses. Batched SMTP input is also catered for.
610 .next
611 Exim is not designed for storing mail for dial-in hosts. When the volumes of
612 such mail are large, it is better to get the messages &"delivered"& into files
613 (that is, off Exim's queue) and subsequently passed on to the dial-in hosts by
614 other means.
615 .next
616 Although Exim does have basic facilities for scanning incoming messages, these
617 are not comprehensive enough to do full virus or spam scanning. Such operations
618 are best carried out using additional specialized software packages. If you
619 compile Exim with the content-scanning extension, straightforward interfaces to
620 a number of common scanners are provided.
621 .endlist
622
623
624 .section "Run time configuration" "SECID7"
625 Exim's run time configuration is held in a single text file that is divided
626 into a number of sections. The entries in this file consist of keywords and
627 values, in the style of Smail 3 configuration files. A default configuration
628 file which is suitable for simple online installations is provided in the
629 distribution, and is described in chapter &<<CHAPdefconfil>>& below.
630
631
632 .section "Calling interface" "SECID8"
633 .cindex "Sendmail compatibility" "command line interface"
634 Like many MTAs, Exim has adopted the Sendmail command line interface so that it
635 can be a straight replacement for &_/usr/lib/sendmail_& or
636 &_/usr/sbin/sendmail_& when sending mail, but you do not need to know anything
637 about Sendmail in order to run Exim. For actions other than sending messages,
638 Sendmail-compatible options also exist, but those that produce output (for
639 example, &%-bp%&, which lists the messages on the queue) do so in Exim's own
640 format. There are also some additional options that are compatible with Smail
641 3, and some further options that are new to Exim. Chapter &<<CHAPcommandline>>&
642 documents all Exim's command line options. This information is automatically
643 made into the man page that forms part of the Exim distribution.
644
645 Control of messages on the queue can be done via certain privileged command
646 line options. There is also an optional monitor program called &'eximon'&,
647 which displays current information in an X window, and which contains a menu
648 interface to Exim's command line administration options.
649
650
651
652 .section "Terminology" "SECID9"
653 .cindex "terminology definitions"
654 .cindex "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.
658
659 .cindex "bounce message" "definition of"
660 When a message cannot be delivered, it is normally returned to the sender in a
661 delivery failure message or a &"non-delivery report"& (NDR). The term
662 &'bounce'& is commonly used for this action, and the error reports are often
663 called &'bounce messages'&. This is a convenient shorthand for &"delivery
664 failure error report"&. Such messages have an empty sender address in the
665 message's &'envelope'& (see below) to ensure that they cannot themselves give
666 rise to further bounce messages.
667
668 The term &'default'& appears frequently in this manual. It is used to qualify a
669 value which is used in the absence of any setting in the configuration. It may
670 also qualify an action which is taken unless a configuration setting specifies
671 otherwise.
672
673 The term &'defer'& is used when the delivery of a message to a specific
674 destination cannot immediately take place for some reason (a remote host may be
675 down, or a user's local mailbox may be full). Such deliveries are &'deferred'&
676 until a later time.
677
678 The word &'domain'& is sometimes used to mean all but the first component of a
679 host's name. It is &'not'& used in that sense here, where it normally refers to
680 the part of an email address following the @ sign.
681
682 .cindex "envelope, definition of"
683 .cindex "sender" "definition of"
684 A message in transit has an associated &'envelope'&, as well as a header and a
685 body. The envelope contains a sender address (to which bounce messages should
686 be delivered), and any number of recipient addresses. References to the
687 sender or the recipients of a message usually mean the addresses in the
688 envelope. An MTA uses these addresses for delivery, and for returning bounce
689 messages, not the addresses that appear in the header lines.
690
691 .cindex "message" "header, definition of"
692 .cindex "header section" "definition of"
693 The &'header'& of a message is the first part of a message's text, consisting
694 of a number of lines, each of which has a name such as &'From:'&, &'To:'&,
695 &'Subject:'&, etc. Long header lines can be split over several text lines by
696 indenting the continuations. The header is separated from the body by a blank
697 line.
698
699 .cindex "local part" "definition of"
700 .cindex "domain" "definition of"
701 The term &'local part'&, which is taken from RFC 2822, is used to refer to that
702 part of an email address that precedes the @ sign. The part that follows the
703 @ sign is called the &'domain'& or &'mail domain'&.
704
705 .cindex "local delivery" "definition of"
706 .cindex "remote delivery, definition of"
707 The terms &'local delivery'& and &'remote delivery'& are used to distinguish
708 delivery to a file or a pipe on the local host from delivery by SMTP over
709 TCP/IP to another host. As far as Exim is concerned, all hosts other than the
710 host it is running on are &'remote'&.
711
712 .cindex "return path" "definition of"
713 &'Return path'& is another name that is used for the sender address in a
714 message's envelope.
715
716 .cindex "queue" "definition of"
717 The term &'queue'& is used to refer to the set of messages awaiting delivery,
718 because this term is in widespread use in the context of MTAs. However, in
719 Exim's case the reality is more like a pool than a queue, because there is
720 normally no ordering of waiting messages.
721
722 .cindex "queue runner" "definition of"
723 The term &'queue runner'& is used to describe a process that scans the queue
724 and attempts to deliver those messages whose retry times have come. This term
725 is used by other MTAs, and also relates to the command &%runq%&, but in Exim
726 the waiting messages are normally processed in an unpredictable order.
727
728 .cindex "spool directory" "definition of"
729 The term &'spool directory'& is used for a directory in which Exim keeps the
730 messages on its queue &-- that is, those that it is in the process of
731 delivering. This should not be confused with the directory in which local
732 mailboxes are stored, which is called a &"spool directory"& by some people. In
733 the Exim documentation, &"spool"& is always used in the first sense.
734
735
736
737
738
739
740 . ////////////////////////////////////////////////////////////////////////////
741 . ////////////////////////////////////////////////////////////////////////////
742
743 .chapter "Incorporated code" "CHID2"
744 .cindex "incorporated code"
745 .cindex "regular expressions" "library"
746 .cindex "PCRE"
747 .cindex "OpenDMARC"
748 A number of pieces of external code are included in the Exim distribution.
749
750 .ilist
751 Regular expressions are supported in the main Exim program and in the
752 Exim monitor using the freely-distributable PCRE library, copyright
753 &copy; University of Cambridge. The source to PCRE is no longer shipped with
754 Exim, so you will need to use the version of PCRE shipped with your system,
755 or obtain and install the full version of the library from
756 &url(ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre).
757 .next
758 .cindex "cdb" "acknowledgment"
759 Support for the cdb (Constant DataBase) lookup method is provided by code
760 contributed by Nigel Metheringham of (at the time he contributed it) Planet
761 Online Ltd. The implementation is completely contained within the code of Exim.
762 It does not link against an external cdb library. The code contains the
763 following statements:
764
765 .blockquote
766 Copyright &copy; 1998 Nigel Metheringham, Planet Online Ltd
767
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
771 version.
772 This code implements Dan Bernstein's Constant DataBase (cdb) spec. Information,
773 the spec and sample code for cdb can be obtained from
774 &url(https://cr.yp.to/cdb.html). This implementation borrows
775 some code from Dan Bernstein's implementation (which has no license
776 restrictions applied to it).
777 .endblockquote
778 .next
779 .cindex "SPA authentication"
780 .cindex "Samba project"
781 .cindex "Microsoft Secure Password Authentication"
782 Client support for Microsoft's &'Secure Password Authentication'& is provided
783 by code contributed by Marc Prud'hommeaux. Server support was contributed by
784 Tom Kistner. This includes code taken from the Samba project, which is released
785 under the Gnu GPL.
786 .next
787 .cindex "Cyrus"
788 .cindex "&'pwcheck'& daemon"
789 .cindex "&'pwauthd'& daemon"
790 Support for calling the Cyrus &'pwcheck'& and &'saslauthd'& daemons is provided
791 by code taken from the Cyrus-SASL library and adapted by Alexander S.
792 Sabourenkov. The permission notice appears below, in accordance with the
793 conditions expressed therein.
794
795 .blockquote
796 Copyright &copy; 2001 Carnegie Mellon University.  All rights reserved.
797
798 Redistribution and use in source and binary forms, with or without
799 modification, are permitted provided that the following conditions
800 are met:
801
802 .olist
803 Redistributions of source code must retain the above copyright
804 notice, this list of conditions and the following disclaimer.
805 .next
806 Redistributions in binary form must reproduce the above copyright
807 notice, this list of conditions and the following disclaimer in
808 the documentation and/or other materials provided with the
809 distribution.
810 .next
811 The name &"Carnegie Mellon University"& must not be used to
812 endorse or promote products derived from this software without
813 prior written permission. For permission or any other legal
814 details, please contact
815 .display
816               Office of Technology Transfer
817               Carnegie Mellon University
818               5000 Forbes Avenue
819               Pittsburgh, PA  15213-3890
820               (412) 268-4387, fax: (412) 268-7395
821               tech-transfer@andrew.cmu.edu
822 .endd
823 .next
824 Redistributions of any form whatsoever must retain the following
825 acknowledgment:
826
827 &"This product includes software developed by Computing Services
828 at Carnegie Mellon University (&url(https://www.cmu.edu/computing/)."&
829
830 CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO
831 THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
832 AND FITNESS, IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY BE LIABLE
833 FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
834 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
835 AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING
836 OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
837 .endlist
838 .endblockquote
839
840 .next
841 .cindex "Exim monitor" "acknowledgment"
842 .cindex "X-windows"
843 .cindex "Athena"
844 The Exim Monitor program, which is an X-Window application, includes
845 modified versions of the Athena StripChart and TextPop widgets.
846 This code is copyright by DEC and MIT, and their permission notice appears
847 below, in accordance with the conditions expressed therein.
848
849 .blockquote
850 Copyright 1987, 1988 by Digital Equipment Corporation, Maynard, Massachusetts,
851 and the Massachusetts Institute of Technology, Cambridge, Massachusetts.
852
853 All Rights Reserved
854
855 Permission to use, copy, modify, and distribute this software and its
856 documentation for any purpose and without fee is hereby granted,
857 provided that the above copyright notice appear in all copies and that
858 both that copyright notice and this permission notice appear in
859 supporting documentation, and that the names of Digital or MIT not be
860 used in advertising or publicity pertaining to distribution of the
861 software without specific, written prior permission.
862
863 DIGITAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
864 ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL
865 DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR
866 ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
867 WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
868 ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
869 SOFTWARE.
870 .endblockquote
871
872 .next
873 .cindex "opendmarc" "acknowledgment"
874 The DMARC implementation uses the OpenDMARC library which is Copyrighted by
875 The Trusted Domain Project. Portions of Exim source which use OpenDMARC
876 derived code are indicated in the respective source files. The full OpenDMARC
877 license is provided in the LICENSE.opendmarc file contained in the distributed
878 source code.
879
880 .next
881 Many people have contributed code fragments, some large, some small, that were
882 not covered by any specific licence requirements. It is assumed that the
883 contributors are happy to see their code incorporated into Exim under the GPL.
884 .endlist
885
886
887
888
889
890 . ////////////////////////////////////////////////////////////////////////////
891 . ////////////////////////////////////////////////////////////////////////////
892
893 .chapter "How Exim receives and delivers mail" "CHID11" &&&
894          "Receiving and delivering mail"
895
896
897 .section "Overall philosophy" "SECID10"
898 .cindex "design philosophy"
899 Exim is designed to work efficiently on systems that are permanently connected
900 to the Internet and are handling a general mix of mail. In such circumstances,
901 most messages can be delivered immediately. Consequently, Exim does not
902 maintain independent queues of messages for specific domains or hosts, though
903 it does try to send several messages in a single SMTP connection after a host
904 has been down, and it also maintains per-host retry information.
905
906
907 .section "Policy control" "SECID11"
908 .cindex "policy control" "overview"
909 Policy controls are now an important feature of MTAs that are connected to the
910 Internet. Perhaps their most important job is to stop MTAs being abused as
911 &"open relays"& by misguided individuals who send out vast amounts of
912 unsolicited junk, and want to disguise its source. Exim provides flexible
913 facilities for specifying policy controls on incoming mail:
914
915 .ilist
916 .cindex "&ACL;" "introduction"
917 Exim 4 (unlike previous versions of Exim) implements policy controls on
918 incoming mail by means of &'Access Control Lists'& (ACLs). Each list is a
919 series of statements that may either grant or deny access. ACLs can be used at
920 several places in the SMTP dialogue while receiving a message from a remote
921 host. However, the most common places are after each RCPT command, and at the
922 very end of the message. The sysadmin can specify conditions for accepting or
923 rejecting individual recipients or the entire message, respectively, at these
924 two points (see chapter &<<CHAPACL>>&). Denial of access results in an SMTP
925 error code.
926 .next
927 An ACL is also available for locally generated, non-SMTP messages. In this
928 case, the only available actions are to accept or deny the entire message.
929 .next
930 When Exim is compiled with the content-scanning extension, facilities are
931 provided in the ACL mechanism for passing the message to external virus and/or
932 spam scanning software. The result of such a scan is passed back to the ACL,
933 which can then use it to decide what to do with the message.
934 .next
935 When a message has been received, either from a remote host or from the local
936 host, but before the final acknowledgment has been sent, a locally supplied C
937 function called &[local_scan()]& can be run to inspect the message and decide
938 whether to accept it or not (see chapter &<<CHAPlocalscan>>&). If the message
939 is accepted, the list of recipients can be modified by the function.
940 .next
941 Using the &[local_scan()]& mechanism is another way of calling external scanner
942 software. The &%SA-Exim%& add-on package works this way. It does not require
943 Exim to be compiled with the content-scanning extension.
944 .next
945 After a message has been accepted, a further checking mechanism is available in
946 the form of the &'system filter'& (see chapter &<<CHAPsystemfilter>>&). This
947 runs at the start of every delivery process.
948 .endlist
949
950
951
952 .section "User filters" "SECID12"
953 .cindex "filter" "introduction"
954 .cindex "Sieve filter"
955 In a conventional Exim configuration, users are able to run private filters by
956 setting up appropriate &_.forward_& files in their home directories. See
957 chapter &<<CHAPredirect>>& (about the &(redirect)& router) for the
958 configuration needed to support this, and the separate document entitled
959 &'Exim's interfaces to mail filtering'& for user details. Two different kinds
960 of filtering are available:
961
962 .ilist
963 Sieve filters are written in the standard filtering language that is defined
964 by RFC 3028.
965 .next
966 Exim filters are written in a syntax that is unique to Exim, but which is more
967 powerful than Sieve, which it pre-dates.
968 .endlist
969
970 User filters are run as part of the routing process, described below.
971
972
973
974 .section "Message identification" "SECTmessiden"
975 .cindex "message ids" "details of format"
976 .cindex "format" "of message id"
977 .cindex "id of message"
978 .cindex "base62"
979 .cindex "base36"
980 .cindex "Darwin"
981 .cindex "Cygwin"
982 Every message handled by Exim is given a &'message id'& which is sixteen
983 characters long. It is divided into three parts, separated by hyphens, for
984 example &`16VDhn-0001bo-D3`&. Each part is a sequence of letters and digits,
985 normally encoding numbers in base 62. However, in the Darwin operating
986 system (Mac OS X) and when Exim is compiled to run under Cygwin, base 36
987 (avoiding the use of lower case letters) is used instead, because the message
988 id is used to construct file names, and the names of files in those systems are
989 not always case-sensitive.
990
991 .cindex "pid (process id)" "re-use of"
992 The detail of the contents of the message id have changed as Exim has evolved.
993 Earlier versions relied on the operating system not re-using a process id (pid)
994 within one second. On modern operating systems, this assumption can no longer
995 be made, so the algorithm had to be changed. To retain backward compatibility,
996 the format of the message id was retained, which is why the following rules are
997 somewhat eccentric:
998
999 .ilist
1000 The first six characters of the message id are the time at which the message
1001 started to be received, to a granularity of one second. That is, this field
1002 contains the number of seconds since the start of the epoch (the normal Unix
1003 way of representing the date and time of day).
1004 .next
1005 After the first hyphen, the next six characters are the id of the process that
1006 received the message.
1007 .next
1008 There are two different possibilities for the final two characters:
1009 .olist
1010 .oindex "&%localhost_number%&"
1011 If &%localhost_number%& is not set, this value is the fractional part of the
1012 time of reception, normally in units of 1/2000 of a second, but for systems
1013 that must use base 36 instead of base 62 (because of case-insensitive file
1014 systems), the units are 1/1000 of a second.
1015 .next
1016 If &%localhost_number%& is set, it is multiplied by 200 (100) and added to
1017 the fractional part of the time, which in this case is in units of 1/200
1018 (1/100) of a second.
1019 .endlist
1020 .endlist
1021
1022 After a message has been received, Exim waits for the clock to tick at the
1023 appropriate resolution before proceeding, so that if another message is
1024 received by the same process, or by another process with the same (re-used)
1025 pid, it is guaranteed that the time will be different. In most cases, the clock
1026 will already have ticked while the message was being received.
1027
1028
1029 .section "Receiving mail" "SECID13"
1030 .cindex "receiving mail"
1031 .cindex "message" "reception"
1032 The only way Exim can receive mail from another host is using SMTP over
1033 TCP/IP, in which case the sender and recipient addresses are transferred using
1034 SMTP commands. However, from a locally running process (such as a user's MUA),
1035 there are several possibilities:
1036
1037 .ilist
1038 If the process runs Exim with the &%-bm%& option, the message is read
1039 non-interactively (usually via a pipe), with the recipients taken from the
1040 command line, or from the body of the message if &%-t%& is also used.
1041 .next
1042 If the process runs Exim with the &%-bS%& option, the message is also read
1043 non-interactively, but in this case the recipients are listed at the start of
1044 the message in a series of SMTP RCPT commands, terminated by a DATA
1045 command. This is so-called &"batch SMTP"& format,
1046 but it isn't really SMTP. The SMTP commands are just another way of passing
1047 envelope addresses in a non-interactive submission.
1048 .next
1049 If the process runs Exim with the &%-bs%& option, the message is read
1050 interactively, using the SMTP protocol. A two-way pipe is normally used for
1051 passing data between the local process and the Exim process.
1052 This is &"real"& SMTP and is handled in the same way as SMTP over TCP/IP. For
1053 example, the ACLs for SMTP commands are used for this form of submission.
1054 .next
1055 A local process may also make a TCP/IP call to the host's loopback address
1056 (127.0.0.1) or any other of its IP addresses. When receiving messages, Exim
1057 does not treat the loopback address specially. It treats all such connections
1058 in the same way as connections from other hosts.
1059 .endlist
1060
1061
1062 .cindex "message sender, constructed by Exim"
1063 .cindex "sender" "constructed by Exim"
1064 In the three cases that do not involve TCP/IP, the sender address is
1065 constructed from the login name of the user that called Exim and a default
1066 qualification domain (which can be set by the &%qualify_domain%& configuration
1067 option). For local or batch SMTP, a sender address that is passed using the
1068 SMTP MAIL command is ignored. However, the system administrator may allow
1069 certain users (&"trusted users"&) to specify a different sender address
1070 unconditionally, or all users to specify certain forms of different sender
1071 address. The &%-f%& option or the SMTP MAIL command is used to specify these
1072 different addresses. See section &<<SECTtrustedadmin>>& for details of trusted
1073 users, and the &%untrusted_set_sender%& option for a way of allowing untrusted
1074 users to change sender addresses.
1075
1076 Messages received by either of the non-interactive mechanisms are subject to
1077 checking by the non-SMTP ACL, if one is defined. Messages received using SMTP
1078 (either over TCP/IP, or interacting with a local process) can be checked by a
1079 number of ACLs that operate at different times during the SMTP session. Either
1080 individual recipients, or the entire message, can be rejected if local policy
1081 requirements are not met. The &[local_scan()]& function (see chapter
1082 &<<CHAPlocalscan>>&) is run for all incoming messages.
1083
1084 Exim can be configured not to start a delivery process when a message is
1085 received; this can be unconditional, or depend on the number of incoming SMTP
1086 connections or the system load. In these situations, new messages wait on the
1087 queue until a queue runner process picks them up. However, in standard
1088 configurations under normal conditions, delivery is started as soon as a
1089 message is received.
1090
1091
1092
1093
1094
1095 .section "Handling an incoming message" "SECID14"
1096 .cindex "spool directory" "files that hold a message"
1097 .cindex "file" "how a message is held"
1098 When Exim accepts a message, it writes two files in its spool directory. The
1099 first contains the envelope information, the current status of the message, and
1100 the header lines, and the second contains the body of the message. The names of
1101 the two spool files consist of the message id, followed by &`-H`& for the
1102 file containing the envelope and header, and &`-D`& for the data file.
1103
1104 .cindex "spool directory" "&_input_& sub-directory"
1105 By default all these message files are held in a single directory called
1106 &_input_& inside the general Exim spool directory. Some operating systems do
1107 not perform very well if the number of files in a directory gets large; to
1108 improve performance in such cases, the &%split_spool_directory%& option can be
1109 used. This causes Exim to split up the input files into 62 sub-directories
1110 whose names are single letters or digits. When this is done, the queue is
1111 processed one sub-directory at a time instead of all at once, which can improve
1112 overall performance even when there are not enough files in each directory to
1113 affect file system performance.
1114
1115 The envelope information consists of the address of the message's sender and
1116 the addresses of the recipients. This information is entirely separate from
1117 any addresses contained in the header lines. The status of the message includes
1118 a list of recipients who have already received the message. The format of the
1119 first spool file is described in chapter &<<CHAPspool>>&.
1120
1121 .cindex "rewriting" "addresses"
1122 Address rewriting that is specified in the rewrite section of the configuration
1123 (see chapter &<<CHAPrewrite>>&) is done once and for all on incoming addresses,
1124 both in the header lines and the envelope, at the time the message is accepted.
1125 If during the course of delivery additional addresses are generated (for
1126 example, via aliasing), these new addresses are rewritten as soon as they are
1127 generated. At the time a message is actually delivered (transported) further
1128 rewriting can take place; because this is a transport option, it can be
1129 different for different forms of delivery. It is also possible to specify the
1130 addition or removal of certain header lines at the time the message is
1131 delivered (see chapters &<<CHAProutergeneric>>& and
1132 &<<CHAPtransportgeneric>>&).
1133
1134
1135
1136 .section "Life of a message" "SECID15"
1137 .cindex "message" "life of"
1138 .cindex "message" "frozen"
1139 A message remains in the spool directory until it is completely delivered to
1140 its recipients or to an error address, or until it is deleted by an
1141 administrator or by the user who originally created it. In cases when delivery
1142 cannot proceed &-- for example, when a message can neither be delivered to its
1143 recipients nor returned to its sender, the message is marked &"frozen"& on the
1144 spool, and no more deliveries are attempted.
1145
1146 .cindex "frozen messages" "thawing"
1147 .cindex "message" "thawing frozen"
1148 An administrator can &"thaw"& such messages when the problem has been
1149 corrected, and can also freeze individual messages by hand if necessary. In
1150 addition, an administrator can force a delivery error, causing a bounce message
1151 to be sent.
1152
1153 .oindex "&%timeout_frozen_after%&"
1154 .oindex "&%ignore_bounce_errors_after%&"
1155 There are options called &%ignore_bounce_errors_after%& and
1156 &%timeout_frozen_after%&, which discard frozen messages after a certain time.
1157 The first applies only to frozen bounces, the second to any frozen messages.
1158
1159 .cindex "message" "log file for"
1160 .cindex "log" "file for each message"
1161 While Exim is working on a message, it writes information about each delivery
1162 attempt to its main log file. This includes successful, unsuccessful, and
1163 delayed deliveries for each recipient (see chapter &<<CHAPlog>>&). The log
1164 lines are also written to a separate &'message log'& file for each message.
1165 These logs are solely for the benefit of the administrator, and are normally
1166 deleted along with the spool files when processing of a message is complete.
1167 The use of individual message logs can be disabled by setting
1168 &%no_message_logs%&; this might give an improvement in performance on very busy
1169 systems.
1170
1171 .cindex "journal file"
1172 .cindex "file" "journal"
1173 All the information Exim itself needs to set up a delivery is kept in the first
1174 spool file, along with the header lines. When a successful delivery occurs, the
1175 address is immediately written at the end of a journal file, whose name is the
1176 message id followed by &`-J`&. At the end of a delivery run, if there are some
1177 addresses left to be tried again later, the first spool file (the &`-H`& file)
1178 is updated to indicate which these are, and the journal file is then deleted.
1179 Updating the spool file is done by writing a new file and renaming it, to
1180 minimize the possibility of data loss.
1181
1182 Should the system or the program crash after a successful delivery but before
1183 the spool file has been updated, the journal is left lying around. The next
1184 time Exim attempts to deliver the message, it reads the journal file and
1185 updates the spool file before proceeding. This minimizes the chances of double
1186 deliveries caused by crashes.
1187
1188
1189
1190 .section "Processing an address for delivery" "SECTprocaddress"
1191 .cindex "drivers" "definition of"
1192 .cindex "router" "definition of"
1193 .cindex "transport" "definition of"
1194 The main delivery processing elements of Exim are called &'routers'& and
1195 &'transports'&, and collectively these are known as &'drivers'&. Code for a
1196 number of them is provided in the source distribution, and compile-time options
1197 specify which ones are included in the binary. Run time options specify which
1198 ones are actually used for delivering messages.
1199
1200 .cindex "drivers" "instance definition"
1201 Each driver that is specified in the run time configuration is an &'instance'&
1202 of that particular driver type. Multiple instances are allowed; for example,
1203 you can set up several different &(smtp)& transports, each with different
1204 option values that might specify different ports or different timeouts. Each
1205 instance has its own identifying name. In what follows we will normally use the
1206 instance name when discussing one particular instance (that is, one specific
1207 configuration of the driver), and the generic driver name when discussing
1208 the driver's features in general.
1209
1210 A &'router'& is a driver that operates on an address, either determining how
1211 its delivery should happen, by assigning it to a specific transport, or
1212 converting the address into one or more new addresses (for example, via an
1213 alias file). A router may also explicitly choose to fail an address, causing it
1214 to be bounced.
1215
1216 A &'transport'& is a driver that transmits a copy of the message from Exim's
1217 spool to some destination. There are two kinds of transport: for a &'local'&
1218 transport, the destination is a file or a pipe on the local host, whereas for a
1219 &'remote'& transport the destination is some other host. A message is passed
1220 to a specific transport as a result of successful routing. If a message has
1221 several recipients, it may be passed to a number of different transports.
1222
1223 .cindex "preconditions" "definition of"
1224 An address is processed by passing it to each configured router instance in
1225 turn, subject to certain preconditions, until a router accepts the address or
1226 specifies that it should be bounced. We will describe this process in more
1227 detail shortly. First, as a simple example, we consider how each recipient
1228 address in a message is processed in a small configuration of three routers.
1229
1230 To make this a more concrete example, it is described in terms of some actual
1231 routers, but remember, this is only an example. You can configure Exim's
1232 routers in many different ways, and there may be any number of routers in a
1233 configuration.
1234
1235 The first router that is specified in a configuration is often one that handles
1236 addresses in domains that are not recognized specially by the local host. These
1237 are typically addresses for arbitrary domains on the Internet. A precondition
1238 is set up which looks for the special domains known to the host (for example,
1239 its own domain name), and the router is run for addresses that do &'not'&
1240 match. Typically, this is a router that looks up domains in the DNS in order to
1241 find the hosts to which this address routes. If it succeeds, the address is
1242 assigned to a suitable SMTP transport; if it does not succeed, the router is
1243 configured to fail the address.
1244
1245 The second router is reached only when the domain is recognized as one that
1246 &"belongs"& to the local host. This router does redirection &-- also known as
1247 aliasing and forwarding. When it generates one or more new addresses from the
1248 original, each of them is routed independently from the start. Otherwise, the
1249 router may cause an address to fail, or it may simply decline to handle the
1250 address, in which case the address is passed to the next router.
1251
1252 The final router in many configurations is one that checks to see if the
1253 address belongs to a local mailbox. The precondition may involve a check to
1254 see if the local part is the name of a login account, or it may look up the
1255 local part in a file or a database. If its preconditions are not met, or if
1256 the router declines, we have reached the end of the routers. When this happens,
1257 the address is bounced.
1258
1259
1260
1261 .section "Processing an address for verification" "SECID16"
1262 .cindex "router" "for verification"
1263 .cindex "verifying address" "overview"
1264 As well as being used to decide how to deliver to an address, Exim's routers
1265 are also used for &'address verification'&. Verification can be requested as
1266 one of the checks to be performed in an ACL for incoming messages, on both
1267 sender and recipient addresses, and it can be tested using the &%-bv%& and
1268 &%-bvs%& command line options.
1269
1270 When an address is being verified, the routers are run in &"verify mode"&. This
1271 does not affect the way the routers work, but it is a state that can be
1272 detected. By this means, a router can be skipped or made to behave differently
1273 when verifying. A common example is a configuration in which the first router
1274 sends all messages to a message-scanning program, unless they have been
1275 previously scanned. Thus, the first router accepts all addresses without any
1276 checking, making it useless for verifying. Normally, the &%no_verify%& option
1277 would be set for such a router, causing it to be skipped in verify mode.
1278
1279
1280
1281
1282 .section "Running an individual router" "SECTrunindrou"
1283 .cindex "router" "running details"
1284 .cindex "preconditions" "checking"
1285 .cindex "router" "result of running"
1286 As explained in the example above, a number of preconditions are checked before
1287 running a router. If any are not met, the router is skipped, and the address is
1288 passed to the next router. When all the preconditions on a router &'are'& met,
1289 the router is run. What happens next depends on the outcome, which is one of
1290 the following:
1291
1292 .ilist
1293 &'accept'&: The router accepts the address, and either assigns it to a
1294 transport, or generates one or more &"child"& addresses. Processing the
1295 original address ceases,
1296 .oindex "&%unseen%&"
1297 unless the &%unseen%& option is set on the router. This option
1298 can be used to set up multiple deliveries with different routing (for example,
1299 for keeping archive copies of messages). When &%unseen%& is set, the address is
1300 passed to the next router. Normally, however, an &'accept'& return marks the
1301 end of routing.
1302
1303 Any child addresses generated by the router are processed independently,
1304 starting with the first router by default. It is possible to change this by
1305 setting the &%redirect_router%& option to specify which router to start at for
1306 child addresses. Unlike &%pass_router%& (see below) the router specified by
1307 &%redirect_router%& may be anywhere in the router configuration.
1308 .next
1309 &'pass'&: The router recognizes the address, but cannot handle it itself. It
1310 requests that the address be passed to another router. By default the address
1311 is passed to the next router, but this can be changed by setting the
1312 &%pass_router%& option. However, (unlike &%redirect_router%&) the named router
1313 must be below the current router (to avoid loops).
1314 .next
1315 &'decline'&: The router declines to accept the address because it does not
1316 recognize it at all. By default, the address is passed to the next router, but
1317 this can be prevented by setting the &%no_more%& option. When &%no_more%& is
1318 set, all the remaining routers are skipped. In effect, &%no_more%& converts
1319 &'decline'& into &'fail'&.
1320 .next
1321 &'fail'&: The router determines that the address should fail, and queues it for
1322 the generation of a bounce message. There is no further processing of the
1323 original address unless &%unseen%& is set on the router.
1324 .next
1325 &'defer'&: The router cannot handle the address at the present time. (A
1326 database may be offline, or a DNS lookup may have timed out.) No further
1327 processing of the address happens in this delivery attempt. It is tried again
1328 next time the message is considered for delivery.
1329 .next
1330 &'error'&: There is some error in the router (for example, a syntax error in
1331 its configuration). The action is as for defer.
1332 .endlist
1333
1334 If an address reaches the end of the routers without having been accepted by
1335 any of them, it is bounced as unrouteable. The default error message in this
1336 situation is &"unrouteable address"&, but you can set your own message by
1337 making use of the &%cannot_route_message%& option. This can be set for any
1338 router; the value from the last router that &"saw"& the address is used.
1339
1340 Sometimes while routing you want to fail a delivery when some conditions are
1341 met but others are not, instead of passing the address on for further routing.
1342 You can do this by having a second router that explicitly fails the delivery
1343 when the relevant conditions are met. The &(redirect)& router has a &"fail"&
1344 facility for this purpose.
1345
1346
1347 .section "Duplicate addresses" "SECID17"
1348 .cindex "case of local parts"
1349 .cindex "address duplicate, discarding"
1350 .cindex "duplicate addresses"
1351 Once routing is complete, Exim scans the addresses that are assigned to local
1352 and remote transports, and discards any duplicates that it finds. During this
1353 check, local parts are treated as case-sensitive. This happens only when
1354 actually delivering a message; when testing routers with &%-bt%&, all the
1355 routed addresses are shown.
1356
1357
1358
1359 .section "Router preconditions" "SECTrouprecon"
1360 .cindex "router" "preconditions, order of processing"
1361 .cindex "preconditions" "order of processing"
1362 The preconditions that are tested for each router are listed below, in the
1363 order in which they are tested. The individual configuration options are
1364 described in more detail in chapter &<<CHAProutergeneric>>&.
1365
1366 .ilist
1367 .cindex affix "router precondition"
1368 The &%local_part_prefix%& and &%local_part_suffix%& options can specify that
1369 the local parts handled by the router may or must have certain prefixes and/or
1370 suffixes. If a mandatory affix (prefix or suffix) is not present, the router is
1371 skipped. These conditions are tested first. When an affix is present, it is
1372 removed from the local part before further processing, including the evaluation
1373 of any other conditions.
1374 .next
1375 Routers can be designated for use only when not verifying an address, that is,
1376 only when routing it for delivery (or testing its delivery routing). If the
1377 &%verify%& option is set false, the router is skipped when Exim is verifying an
1378 address.
1379 Setting the &%verify%& option actually sets two options, &%verify_sender%& and
1380 &%verify_recipient%&, which independently control the use of the router for
1381 sender and recipient verification. You can set these options directly if
1382 you want a router to be used for only one type of verification.
1383 Note that cutthrough delivery is classed as a recipient verification for this purpose.
1384 .next
1385 If the &%address_test%& option is set false, the router is skipped when Exim is
1386 run with the &%-bt%& option to test an address routing. This can be helpful
1387 when the first router sends all new messages to a scanner of some sort; it
1388 makes it possible to use &%-bt%& to test subsequent delivery routing without
1389 having to simulate the effect of the scanner.
1390 .next
1391 Routers can be designated for use only when verifying an address, as
1392 opposed to routing it for delivery. The &%verify_only%& option controls this.
1393 Again, cutthrough delivery counts as a verification.
1394 .next
1395 Individual routers can be explicitly skipped when running the routers to
1396 check an address given in the SMTP EXPN command (see the &%expn%& option).
1397 .next
1398 If the &%domains%& option is set, the domain of the address must be in the set
1399 of domains that it defines.
1400 .next
1401 .vindex "&$local_part_prefix$&"
1402 .vindex "&$local_part$&"
1403 .vindex "&$local_part_suffix$&"
1404 .cindex affix "router precondition"
1405 If the &%local_parts%& option is set, the local part of the address must be in
1406 the set of local parts that it defines. If &%local_part_prefix%& or
1407 &%local_part_suffix%& is in use, the prefix or suffix is removed from the local
1408 part before this check. If you want to do precondition tests on local parts
1409 that include affixes, you can do so by using a &%condition%& option (see below)
1410 that uses the variables &$local_part$&, &$local_part_prefix$&, and
1411 &$local_part_suffix$& as necessary.
1412 .next
1413 .vindex "&$local_user_uid$&"
1414 .vindex "&$local_user_gid$&"
1415 .vindex "&$home$&"
1416 If the &%check_local_user%& option is set, the local part must be the name of
1417 an account on the local host. If this check succeeds, the uid and gid of the
1418 local user are placed in &$local_user_uid$& and &$local_user_gid$& and the
1419 user's home directory is placed in &$home$&; these values can be used in the
1420 remaining preconditions.
1421 .next
1422 If the &%router_home_directory%& option is set, it is expanded at this point,
1423 because it overrides the value of &$home$&. If this expansion were left till
1424 later, the value of &$home$& as set by &%check_local_user%& would be used in
1425 subsequent tests. Having two different values of &$home$& in the same router
1426 could lead to confusion.
1427 .next
1428 If the &%senders%& option is set, the envelope sender address must be in the
1429 set of addresses that it defines.
1430 .next
1431 If the &%require_files%& option is set, the existence or non-existence of
1432 specified files is tested.
1433 .next
1434 .cindex "customizing" "precondition"
1435 If the &%condition%& option is set, it is evaluated and tested. This option
1436 uses an expanded string to allow you to set up your own custom preconditions.
1437 Expanded strings are described in chapter &<<CHAPexpand>>&.
1438 .endlist
1439
1440
1441 Note that &%require_files%& comes near the end of the list, so you cannot use
1442 it to check for the existence of a file in which to lookup up a domain, local
1443 part, or sender. However, as these options are all expanded, you can use the
1444 &%exists%& expansion condition to make such tests within each condition. The
1445 &%require_files%& option is intended for checking files that the router may be
1446 going to use internally, or which are needed by a specific transport (for
1447 example, &_.procmailrc_&).
1448
1449
1450
1451 .section "Delivery in detail" "SECID18"
1452 .cindex "delivery" "in detail"
1453 When a message is to be delivered, the sequence of events is as follows:
1454
1455 .ilist
1456 If a system-wide filter file is specified, the message is passed to it. The
1457 filter may add recipients to the message, replace the recipients, discard the
1458 message, cause a new message to be generated, or cause the message delivery to
1459 fail. The format of the system filter file is the same as for Exim user filter
1460 files, described in the separate document entitled &'Exim's interfaces to mail
1461 filtering'&.
1462 .cindex "Sieve filter" "not available for system filter"
1463 (&*Note*&: Sieve cannot be used for system filter files.)
1464
1465 Some additional features are available in system filters &-- see chapter
1466 &<<CHAPsystemfilter>>& for details. Note that a message is passed to the system
1467 filter only once per delivery attempt, however many recipients it has. However,
1468 if there are several delivery attempts because one or more addresses could not
1469 be immediately delivered, the system filter is run each time. The filter
1470 condition &%first_delivery%& can be used to detect the first run of the system
1471 filter.
1472 .next
1473 Each recipient address is offered to each configured router in turn, subject to
1474 its preconditions, until one is able to handle it. If no router can handle the
1475 address, that is, if they all decline, the address is failed. Because routers
1476 can be targeted at particular domains, several locally handled domains can be
1477 processed entirely independently of each other.
1478 .next
1479 .cindex "routing" "loops in"
1480 .cindex "loop" "while routing"
1481 A router that accepts an address may assign it to a local or a remote
1482 transport. However, the transport is not run at this time. Instead, the address
1483 is placed on a list for the particular transport, which will be run later.
1484 Alternatively, the router may generate one or more new addresses (typically
1485 from alias, forward, or filter files). New addresses are fed back into this
1486 process from the top, but in order to avoid loops, a router ignores any address
1487 which has an identically-named ancestor that was processed by itself.
1488 .next
1489 When all the routing has been done, addresses that have been successfully
1490 handled are passed to their assigned transports. When local transports are
1491 doing real local deliveries, they handle only one address at a time, but if a
1492 local transport is being used as a pseudo-remote transport (for example, to
1493 collect batched SMTP messages for transmission by some other means) multiple
1494 addresses can be handled. Remote transports can always handle more than one
1495 address at a time, but can be configured not to do so, or to restrict multiple
1496 addresses to the same domain.
1497 .next
1498 Each local delivery to a file or a pipe runs in a separate process under a
1499 non-privileged uid, and these deliveries are run one at a time. Remote
1500 deliveries also run in separate processes, normally under a uid that is private
1501 to Exim (&"the Exim user"&), but in this case, several remote deliveries can be
1502 run in parallel. The maximum number of simultaneous remote deliveries for any
1503 one message is set by the &%remote_max_parallel%& option.
1504 The order in which deliveries are done is not defined, except that all local
1505 deliveries happen before any remote deliveries.
1506 .next
1507 .cindex "queue runner"
1508 When it encounters a local delivery during a queue run, Exim checks its retry
1509 database to see if there has been a previous temporary delivery failure for the
1510 address before running the local transport. If there was a previous failure,
1511 Exim does not attempt a new delivery until the retry time for the address is
1512 reached. However, this happens only for delivery attempts that are part of a
1513 queue run. Local deliveries are always attempted when delivery immediately
1514 follows message reception, even if retry times are set for them. This makes for
1515 better behaviour if one particular message is causing problems (for example,
1516 causing quota overflow, or provoking an error in a filter file).
1517 .next
1518 .cindex "delivery" "retry in remote transports"
1519 Remote transports do their own retry handling, since an address may be
1520 deliverable to one of a number of hosts, each of which may have a different
1521 retry time. If there have been previous temporary failures and no host has
1522 reached its retry time, no delivery is attempted, whether in a queue run or
1523 not. See chapter &<<CHAPretry>>& for details of retry strategies.
1524 .next
1525 If there were any permanent errors, a bounce message is returned to an
1526 appropriate address (the sender in the common case), with details of the error
1527 for each failing address. Exim can be configured to send copies of bounce
1528 messages to other addresses.
1529 .next
1530 .cindex "delivery" "deferral"
1531 If one or more addresses suffered a temporary failure, the message is left on
1532 the queue, to be tried again later. Delivery of these addresses is said to be
1533 &'deferred'&.
1534 .next
1535 When all the recipient addresses have either been delivered or bounced,
1536 handling of the message is complete. The spool files and message log are
1537 deleted, though the message log can optionally be preserved if required.
1538 .endlist
1539
1540
1541
1542
1543 .section "Retry mechanism" "SECID19"
1544 .cindex "delivery" "retry mechanism"
1545 .cindex "retry" "description of mechanism"
1546 .cindex "queue runner"
1547 Exim's mechanism for retrying messages that fail to get delivered at the first
1548 attempt is the queue runner process. You must either run an Exim daemon that
1549 uses the &%-q%& option with a time interval to start queue runners at regular
1550 intervals, or use some other means (such as &'cron'&) to start them. If you do
1551 not arrange for queue runners to be run, messages that fail temporarily at the
1552 first attempt will remain on your queue for ever. A queue runner process works
1553 its way through the queue, one message at a time, trying each delivery that has
1554 passed its retry time.
1555 You can run several queue runners at once.
1556
1557 Exim uses a set of configured rules to determine when next to retry the failing
1558 address (see chapter &<<CHAPretry>>&). These rules also specify when Exim
1559 should give up trying to deliver to the address, at which point it generates a
1560 bounce message. If no retry rules are set for a particular host, address, and
1561 error combination, no retries are attempted, and temporary errors are treated
1562 as permanent.
1563
1564
1565
1566 .section "Temporary delivery failure" "SECID20"
1567 .cindex "delivery" "temporary failure"
1568 There are many reasons why a message may not be immediately deliverable to a
1569 particular address. Failure to connect to a remote machine (because it, or the
1570 connection to it, is down) is one of the most common. Temporary failures may be
1571 detected during routing as well as during the transport stage of delivery.
1572 Local deliveries may be delayed if NFS files are unavailable, or if a mailbox
1573 is on a file system where the user is over quota. Exim can be configured to
1574 impose its own quotas on local mailboxes; where system quotas are set they will
1575 also apply.
1576
1577 If a host is unreachable for a period of time, a number of messages may be
1578 waiting for it by the time it recovers, and sending them in a single SMTP
1579 connection is clearly beneficial. Whenever a delivery to a remote host is
1580 deferred,
1581 .cindex "hints database" "deferred deliveries"
1582 Exim makes a note in its hints database, and whenever a successful
1583 SMTP delivery has happened, it looks to see if any other messages are waiting
1584 for the same host. If any are found, they are sent over the same SMTP
1585 connection, subject to a configuration limit as to the maximum number in any
1586 one connection.
1587
1588
1589
1590 .section "Permanent delivery failure" "SECID21"
1591 .cindex "delivery" "permanent failure"
1592 .cindex "bounce message" "when generated"
1593 When a message cannot be delivered to some or all of its intended recipients, a
1594 bounce message is generated. Temporary delivery failures turn into permanent
1595 errors when their timeout expires. All the addresses that fail in a given
1596 delivery attempt are listed in a single message. If the original message has
1597 many recipients, it is possible for some addresses to fail in one delivery
1598 attempt and others to fail subsequently, giving rise to more than one bounce
1599 message. The wording of bounce messages can be customized by the administrator.
1600 See chapter &<<CHAPemsgcust>>& for details.
1601
1602 .cindex "&'X-Failed-Recipients:'& header line"
1603 Bounce messages contain an &'X-Failed-Recipients:'& header line that lists the
1604 failed addresses, for the benefit of programs that try to analyse such messages
1605 automatically.
1606
1607 .cindex "bounce message" "recipient of"
1608 A bounce message is normally sent to the sender of the original message, as
1609 obtained from the message's envelope. For incoming SMTP messages, this is the
1610 address given in the MAIL command. However, when an address is expanded via a
1611 forward or alias file, an alternative address can be specified for delivery
1612 failures of the generated addresses. For a mailing list expansion (see section
1613 &<<SECTmailinglists>>&) it is common to direct bounce messages to the manager
1614 of the list.
1615
1616
1617
1618 .section "Failures to deliver bounce messages" "SECID22"
1619 .cindex "bounce message" "failure to deliver"
1620 If a bounce message (either locally generated or received from a remote host)
1621 itself suffers a permanent delivery failure, the message is left on the queue,
1622 but it is frozen, awaiting the attention of an administrator. There are options
1623 that can be used to make Exim discard such failed messages, or to keep them
1624 for only a short time (see &%timeout_frozen_after%& and
1625 &%ignore_bounce_errors_after%&).
1626
1627
1628
1629
1630
1631 . ////////////////////////////////////////////////////////////////////////////
1632 . ////////////////////////////////////////////////////////////////////////////
1633
1634 .chapter "Building and installing Exim" "CHID3"
1635 .scindex IIDbuex "building Exim"
1636
1637 .section "Unpacking" "SECID23"
1638 Exim is distributed as a gzipped or bzipped tar file which, when unpacked,
1639 creates a directory with the name of the current release (for example,
1640 &_exim-&version()_&) into which the following files are placed:
1641
1642 .table2 140pt
1643 .irow &_ACKNOWLEDGMENTS_& "contains some acknowledgments"
1644 .irow &_CHANGES_&         "contains a reference to where changes are &&&
1645   documented"
1646 .irow &_LICENCE_&         "the GNU General Public Licence"
1647 .irow &_Makefile_&        "top-level make file"
1648 .irow &_NOTICE_&          "conditions for the use of Exim"
1649 .irow &_README_&          "list of files, directories and simple build &&&
1650   instructions"
1651 .endtable
1652
1653 Other files whose names begin with &_README_& may also be present. The
1654 following subdirectories are created:
1655
1656 .table2 140pt
1657 .irow &_Local_&           "an empty directory for local configuration files"
1658 .irow &_OS_&              "OS-specific files"
1659 .irow &_doc_&             "documentation files"
1660 .irow &_exim_monitor_&    "source files for the Exim monitor"
1661 .irow &_scripts_&         "scripts used in the build process"
1662 .irow &_src_&             "remaining source files"
1663 .irow &_util_&            "independent utilities"
1664 .endtable
1665
1666 The main utility programs are contained in the &_src_& directory, and are built
1667 with the Exim binary. The &_util_& directory contains a few optional scripts
1668 that may be useful to some sites.
1669
1670
1671 .section "Multiple machine architectures and operating systems" "SECID24"
1672 .cindex "building Exim" "multiple OS/architectures"
1673 The building process for Exim is arranged to make it easy to build binaries for
1674 a number of different architectures and operating systems from the same set of
1675 source files. Compilation does not take place in the &_src_& directory.
1676 Instead, a &'build directory'& is created for each architecture and operating
1677 system.
1678 .cindex "symbolic link" "to build directory"
1679 Symbolic links to the sources are installed in this directory, which is where
1680 the actual building takes place. In most cases, Exim can discover the machine
1681 architecture and operating system for itself, but the defaults can be
1682 overridden if necessary.
1683 .cindex compiler requirements
1684 .cindex compiler version
1685 A C99-capable compiler will be required for the build.
1686
1687
1688 .section "PCRE library" "SECTpcre"
1689 .cindex "PCRE library"
1690 Exim no longer has an embedded PCRE library as the vast majority of
1691 modern systems include PCRE as a system library, although you may need
1692 to install the PCRE or PCRE development package for your operating
1693 system. If your system has a normal PCRE installation the Exim build
1694 process will need no further configuration. If the library or the
1695 headers are in an unusual location you will need to either set the PCRE_LIBS
1696 and INCLUDE directives appropriately,
1697 or set PCRE_CONFIG=yes to use the installed &(pcre-config)& command.
1698 If your operating system has no
1699 PCRE support then you will need to obtain and build the current PCRE
1700 from &url(ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/).
1701 More information on PCRE is available at &url(https://www.pcre.org/).
1702
1703 .section "DBM libraries" "SECTdb"
1704 .cindex "DBM libraries" "discussion of"
1705 .cindex "hints database" "DBM files used for"
1706 Even if you do not use any DBM files in your configuration, Exim still needs a
1707 DBM library in order to operate, because it uses indexed files for its hints
1708 databases. Unfortunately, there are a number of DBM libraries in existence, and
1709 different operating systems often have different ones installed.
1710
1711 .cindex "Solaris" "DBM library for"
1712 .cindex "IRIX, DBM library for"
1713 .cindex "BSD, DBM library for"
1714 .cindex "Linux, DBM library for"
1715 If you are using Solaris, IRIX, one of the modern BSD systems, or a modern
1716 Linux distribution, the DBM configuration should happen automatically, and you
1717 may be able to ignore this section. Otherwise, you may have to learn more than
1718 you would like about DBM libraries from what follows.
1719
1720 .cindex "&'ndbm'& DBM library"
1721 Licensed versions of Unix normally contain a library of DBM functions operating
1722 via the &'ndbm'& interface, and this is what Exim expects by default. Free
1723 versions of Unix seem to vary in what they contain as standard. In particular,
1724 some early versions of Linux have no default DBM library, and different
1725 distributors have chosen to bundle different libraries with their packaged
1726 versions. However, the more recent releases seem to have standardized on the
1727 Berkeley DB library.
1728
1729 Different DBM libraries have different conventions for naming the files they
1730 use. When a program opens a file called &_dbmfile_&, there are several
1731 possibilities:
1732
1733 .olist
1734 A traditional &'ndbm'& implementation, such as that supplied as part of
1735 Solaris, operates on two files called &_dbmfile.dir_& and &_dbmfile.pag_&.
1736 .next
1737 .cindex "&'gdbm'& DBM library"
1738 The GNU library, &'gdbm'&, operates on a single file. If used via its &'ndbm'&
1739 compatibility interface it makes two different hard links to it with names
1740 &_dbmfile.dir_& and &_dbmfile.pag_&, but if used via its native interface, the
1741 file name is used unmodified.
1742 .next
1743 .cindex "Berkeley DB library"
1744 The Berkeley DB package, if called via its &'ndbm'& compatibility interface,
1745 operates on a single file called &_dbmfile.db_&, but otherwise looks to the
1746 programmer exactly the same as the traditional &'ndbm'& implementation.
1747 .next
1748 If the Berkeley package is used in its native mode, it operates on a single
1749 file called &_dbmfile_&; the programmer's interface is somewhat different to
1750 the traditional &'ndbm'& interface.
1751 .next
1752 To complicate things further, there are several very different versions of the
1753 Berkeley DB package. Version 1.85 was stable for a very long time, releases
1754 2.&'x'& and 3.&'x'& were current for a while, but the latest versions when Exim last revamped support were numbered 4.&'x'&.
1755 Maintenance of some of the earlier releases has ceased. All versions of
1756 Berkeley DB could be obtained from
1757 &url(http://www.sleepycat.com/), which is now a redirect to their new owner's
1758 page with far newer versions listed.
1759 It is probably wise to plan to move your storage configurations away from
1760 Berkeley DB format, as today there are smaller and simpler alternatives more
1761 suited to Exim's usage model.
1762 .next
1763 .cindex "&'tdb'& DBM library"
1764 Yet another DBM library, called &'tdb'&, is available from
1765 &url(https://sourceforge.net/projects/tdb/files/). It has its own interface, and also
1766 operates on a single file.
1767 .endlist
1768
1769 .cindex "USE_DB"
1770 .cindex "DBM libraries" "configuration for building"
1771 Exim and its utilities can be compiled to use any of these interfaces. In order
1772 to use any version of the Berkeley DB package in native mode, you must set
1773 USE_DB in an appropriate configuration file (typically
1774 &_Local/Makefile_&). For example:
1775 .code
1776 USE_DB=yes
1777 .endd
1778 Similarly, for gdbm you set USE_GDBM, and for tdb you set USE_TDB. An
1779 error is diagnosed if you set more than one of these.
1780
1781 At the lowest level, the build-time configuration sets none of these options,
1782 thereby assuming an interface of type (1). However, some operating system
1783 configuration files (for example, those for the BSD operating systems and
1784 Linux) assume type (4) by setting USE_DB as their default, and the
1785 configuration files for Cygwin set USE_GDBM. Anything you set in
1786 &_Local/Makefile_&, however, overrides these system defaults.
1787
1788 As well as setting USE_DB, USE_GDBM, or USE_TDB, it may also be
1789 necessary to set DBMLIB, to cause inclusion of the appropriate library, as
1790 in one of these lines:
1791 .code
1792 DBMLIB = -ldb
1793 DBMLIB = -ltdb
1794 .endd
1795 Settings like that will work if the DBM library is installed in the standard
1796 place. Sometimes it is not, and the library's header file may also not be in
1797 the default path. You may need to set INCLUDE to specify where the header
1798 file is, and to specify the path to the library more fully in DBMLIB, as in
1799 this example:
1800 .code
1801 INCLUDE=-I/usr/local/include/db-4.1
1802 DBMLIB=/usr/local/lib/db-4.1/libdb.a
1803 .endd
1804 There is further detailed discussion about the various DBM libraries in the
1805 file &_doc/dbm.discuss.txt_& in the Exim distribution.
1806
1807
1808
1809 .section "Pre-building configuration" "SECID25"
1810 .cindex "building Exim" "pre-building configuration"
1811 .cindex "configuration for building Exim"
1812 .cindex "&_Local/Makefile_&"
1813 .cindex "&_src/EDITME_&"
1814 Before building Exim, a local configuration file that specifies options
1815 independent of any operating system has to be created with the name
1816 &_Local/Makefile_&. A template for this file is supplied as the file
1817 &_src/EDITME_&, and it contains full descriptions of all the option settings
1818 therein. These descriptions are therefore not repeated here. If you are
1819 building Exim for the first time, the simplest thing to do is to copy
1820 &_src/EDITME_& to &_Local/Makefile_&, then read it and edit it appropriately.
1821
1822 There are three settings that you must supply, because Exim will not build
1823 without them. They are the location of the run time configuration file
1824 (CONFIGURE_FILE), the directory in which Exim binaries will be installed
1825 (BIN_DIRECTORY), and the identity of the Exim user (EXIM_USER and
1826 maybe EXIM_GROUP as well). The value of CONFIGURE_FILE can in fact be
1827 a colon-separated list of file names; Exim uses the first of them that exists.
1828
1829 There are a few other parameters that can be specified either at build time or
1830 at run time, to enable the same binary to be used on a number of different
1831 machines. However, if the locations of Exim's spool directory and log file
1832 directory (if not within the spool directory) are fixed, it is recommended that
1833 you specify them in &_Local/Makefile_& instead of at run time, so that errors
1834 detected early in Exim's execution (such as a malformed configuration file) can
1835 be logged.
1836
1837 .cindex "content scanning" "specifying at build time"
1838 Exim's interfaces for calling virus and spam scanning software directly from
1839 access control lists are not compiled by default. If you want to include these
1840 facilities, you need to set
1841 .code
1842 WITH_CONTENT_SCAN=yes
1843 .endd
1844 in your &_Local/Makefile_&. For details of the facilities themselves, see
1845 chapter &<<CHAPexiscan>>&.
1846
1847
1848 .cindex "&_Local/eximon.conf_&"
1849 .cindex "&_exim_monitor/EDITME_&"
1850 If you are going to build the Exim monitor, a similar configuration process is
1851 required. The file &_exim_monitor/EDITME_& must be edited appropriately for
1852 your installation and saved under the name &_Local/eximon.conf_&. If you are
1853 happy with the default settings described in &_exim_monitor/EDITME_&,
1854 &_Local/eximon.conf_& can be empty, but it must exist.
1855
1856 This is all the configuration that is needed in straightforward cases for known
1857 operating systems. However, the building process is set up so that it is easy
1858 to override options that are set by default or by operating-system-specific
1859 configuration files, for example to change the name of the C compiler, which
1860 defaults to &%gcc%&. See section &<<SECToverride>>& below for details of how to
1861 do this.
1862
1863
1864
1865 .section "Support for iconv()" "SECID26"
1866 .cindex "&[iconv()]& support"
1867 .cindex "RFC 2047"
1868 The contents of header lines in messages may be encoded according to the rules
1869 described RFC 2047. This makes it possible to transmit characters that are not
1870 in the ASCII character set, and to label them as being in a particular
1871 character set. When Exim is inspecting header lines by means of the &%$h_%&
1872 mechanism, it decodes them, and translates them into a specified character set
1873 (default is set at build time). The translation is possible only if the operating system
1874 supports the &[iconv()]& function.
1875
1876 However, some of the operating systems that supply &[iconv()]& do not support
1877 very many conversions. The GNU &%libiconv%& library (available from
1878 &url(https://www.gnu.org/software/libiconv/)) can be installed on such
1879 systems to remedy this deficiency, as well as on systems that do not supply
1880 &[iconv()]& at all. After installing &%libiconv%&, you should add
1881 .code
1882 HAVE_ICONV=yes
1883 .endd
1884 to your &_Local/Makefile_& and rebuild Exim.
1885
1886
1887
1888 .section "Including TLS/SSL encryption support" "SECTinctlsssl"
1889 .cindex "TLS" "including support for TLS"
1890 .cindex "encryption" "including support for"
1891 .cindex "SUPPORT_TLS"
1892 .cindex "OpenSSL" "building Exim with"
1893 .cindex "GnuTLS" "building Exim with"
1894 Exim can be built to support encrypted SMTP connections, using the STARTTLS
1895 command as per RFC 2487. It can also support legacy clients that expect to
1896 start a TLS session immediately on connection to a non-standard port (see the
1897 &%tls_on_connect_ports%& runtime option and the &%-tls-on-connect%& command
1898 line option).
1899
1900 If you want to build Exim with TLS support, you must first install either the
1901 OpenSSL or GnuTLS library. There is no cryptographic code in Exim itself for
1902 implementing SSL.
1903
1904 If OpenSSL is installed, you should set
1905 .code
1906 SUPPORT_TLS=yes
1907 TLS_LIBS=-lssl -lcrypto
1908 .endd
1909 in &_Local/Makefile_&. You may also need to specify the locations of the
1910 OpenSSL library and include files. For example:
1911 .code
1912 SUPPORT_TLS=yes
1913 TLS_LIBS=-L/usr/local/openssl/lib -lssl -lcrypto
1914 TLS_INCLUDE=-I/usr/local/openssl/include/
1915 .endd
1916 .cindex "pkg-config" "OpenSSL"
1917 If you have &'pkg-config'& available, then instead you can just use:
1918 .code
1919 SUPPORT_TLS=yes
1920 USE_OPENSSL_PC=openssl
1921 .endd
1922 .cindex "USE_GNUTLS"
1923 If GnuTLS is installed, you should set
1924 .code
1925 SUPPORT_TLS=yes
1926 USE_GNUTLS=yes
1927 TLS_LIBS=-lgnutls -ltasn1 -lgcrypt
1928 .endd
1929 in &_Local/Makefile_&, and again you may need to specify the locations of the
1930 library and include files. For example:
1931 .code
1932 SUPPORT_TLS=yes
1933 USE_GNUTLS=yes
1934 TLS_LIBS=-L/usr/gnu/lib -lgnutls -ltasn1 -lgcrypt
1935 TLS_INCLUDE=-I/usr/gnu/include
1936 .endd
1937 .cindex "pkg-config" "GnuTLS"
1938 If you have &'pkg-config'& available, then instead you can just use:
1939 .code
1940 SUPPORT_TLS=yes
1941 USE_GNUTLS=yes
1942 USE_GNUTLS_PC=gnutls
1943 .endd
1944
1945 You do not need to set TLS_INCLUDE if the relevant directory is already
1946 specified in INCLUDE. Details of how to configure Exim to make use of TLS are
1947 given in chapter &<<CHAPTLS>>&.
1948
1949
1950
1951
1952 .section "Use of tcpwrappers" "SECID27"
1953
1954 .cindex "tcpwrappers, building Exim to support"
1955 .cindex "USE_TCP_WRAPPERS"
1956 .cindex "TCP_WRAPPERS_DAEMON_NAME"
1957 .cindex "tcp_wrappers_daemon_name"
1958 Exim can be linked with the &'tcpwrappers'& library in order to check incoming
1959 SMTP calls using the &'tcpwrappers'& control files. This may be a convenient
1960 alternative to Exim's own checking facilities for installations that are
1961 already making use of &'tcpwrappers'& for other purposes. To do this, you
1962 should set USE_TCP_WRAPPERS in &_Local/Makefile_&, arrange for the file
1963 &_tcpd.h_& to be available at compile time, and also ensure that the library
1964 &_libwrap.a_& is available at link time, typically by including &%-lwrap%& in
1965 EXTRALIBS_EXIM. For example, if &'tcpwrappers'& is installed in &_/usr/local_&,
1966 you might have
1967 .code
1968 USE_TCP_WRAPPERS=yes
1969 CFLAGS=-O -I/usr/local/include
1970 EXTRALIBS_EXIM=-L/usr/local/lib -lwrap
1971 .endd
1972 in &_Local/Makefile_&. The daemon name to use in the &'tcpwrappers'& control
1973 files is &"exim"&. For example, the line
1974 .code
1975 exim : LOCAL  192.168.1.  .friendly.domain.example
1976 .endd
1977 in your &_/etc/hosts.allow_& file allows connections from the local host, from
1978 the subnet 192.168.1.0/24, and from all hosts in &'friendly.domain.example'&.
1979 All other connections are denied. The daemon name used by &'tcpwrappers'&
1980 can be changed at build time by setting TCP_WRAPPERS_DAEMON_NAME in
1981 &_Local/Makefile_&, or by setting tcp_wrappers_daemon_name in the
1982 configure file. Consult the &'tcpwrappers'& documentation for
1983 further details.
1984
1985
1986 .section "Including support for IPv6" "SECID28"
1987 .cindex "IPv6" "including support for"
1988 Exim contains code for use on systems that have IPv6 support. Setting
1989 &`HAVE_IPV6=YES`& in &_Local/Makefile_& causes the IPv6 code to be included;
1990 it may also be necessary to set IPV6_INCLUDE and IPV6_LIBS on systems
1991 where the IPv6 support is not fully integrated into the normal include and
1992 library files.
1993
1994 Two different types of DNS record for handling IPv6 addresses have been
1995 defined. AAAA records (analogous to A records for IPv4) are in use, and are
1996 currently seen as the mainstream. Another record type called A6 was proposed
1997 as better than AAAA because it had more flexibility. However, it was felt to be
1998 over-complex, and its status was reduced to &"experimental"&.
1999 Exim used to
2000 have a compile option for including A6 record support but this has now been
2001 withdrawn.
2002
2003
2004
2005 .section "Dynamically loaded lookup module support" "SECTdynamicmodules"
2006 .cindex "lookup modules"
2007 .cindex "dynamic modules"
2008 .cindex ".so building"
2009 On some platforms, Exim supports not compiling all lookup types directly into
2010 the main binary, instead putting some into external modules which can be loaded
2011 on demand.
2012 This permits packagers to build Exim with support for lookups with extensive
2013 library dependencies without requiring all users to install all of those
2014 dependencies.
2015 Most, but not all, lookup types can be built this way.
2016
2017 Set &`LOOKUP_MODULE_DIR`& to the directory into which the modules will be
2018 installed; Exim will only load modules from that directory, as a security
2019 measure.  You will need to set &`CFLAGS_DYNAMIC`& if not already defined
2020 for your OS; see &_OS/Makefile-Linux_& for an example.
2021 Some other requirements for adjusting &`EXTRALIBS`& may also be necessary,
2022 see &_src/EDITME_& for details.
2023
2024 Then, for each module to be loaded dynamically, define the relevant
2025 &`LOOKUP_`&<&'lookup_type'&> flags to have the value "2" instead of "yes".
2026 For example, this will build in lsearch but load sqlite and mysql support
2027 on demand:
2028 .code
2029 LOOKUP_LSEARCH=yes
2030 LOOKUP_SQLITE=2
2031 LOOKUP_MYSQL=2
2032 .endd
2033
2034
2035 .section "The building process" "SECID29"
2036 .cindex "build directory"
2037 Once &_Local/Makefile_& (and &_Local/eximon.conf_&, if required) have been
2038 created, run &'make'& at the top level. It determines the architecture and
2039 operating system types, and creates a build directory if one does not exist.
2040 For example, on a Sun system running Solaris 8, the directory
2041 &_build-SunOS5-5.8-sparc_& is created.
2042 .cindex "symbolic link" "to source files"
2043 Symbolic links to relevant source files are installed in the build directory.
2044
2045 If this is the first time &'make'& has been run, it calls a script that builds
2046 a make file inside the build directory, using the configuration files from the
2047 &_Local_& directory. The new make file is then passed to another instance of
2048 &'make'&. This does the real work, building a number of utility scripts, and
2049 then compiling and linking the binaries for the Exim monitor (if configured), a
2050 number of utility programs, and finally Exim itself. The command &`make
2051 makefile`& can be used to force a rebuild of the make file in the build
2052 directory, should this ever be necessary.
2053
2054 If you have problems building Exim, check for any comments there may be in the
2055 &_README_& file concerning your operating system, and also take a look at the
2056 FAQ, where some common problems are covered.
2057
2058
2059
2060 .section 'Output from &"make"&' "SECID283"
2061 The output produced by the &'make'& process for compile lines is often very
2062 unreadable, because these lines can be very long. For this reason, the normal
2063 output is suppressed by default, and instead output similar to that which
2064 appears when compiling the 2.6 Linux kernel is generated: just a short line for
2065 each module that is being compiled or linked. However, it is still possible to
2066 get the full output, by calling &'make'& like this:
2067 .code
2068 FULLECHO='' make -e
2069 .endd
2070 The value of FULLECHO defaults to &"@"&, the flag character that suppresses
2071 command reflection in &'make'&. When you ask for the full output, it is
2072 given in addition to the short output.
2073
2074
2075
2076 .section "Overriding build-time options for Exim" "SECToverride"
2077 .cindex "build-time options, overriding"
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
2083 order:
2084 .display
2085 &_OS/Makefile-Default_&
2086 &_OS/Makefile-_&<&'ostype'&>
2087 &_Local/Makefile_&
2088 &_Local/Makefile-_&<&'ostype'&>
2089 &_Local/Makefile-_&<&'archtype'&>
2090 &_Local/Makefile-_&<&'ostype'&>-<&'archtype'&>
2091 &_OS/Makefile-Base_&
2092 .endd
2093 .cindex "&_Local/Makefile_&"
2094 .cindex "building Exim" "operating system type"
2095 .cindex "building Exim" "architecture type"
2096 where <&'ostype'&> is the operating system type and <&'archtype'&> is the
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.
2100
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 &'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.
2110
2111
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
2116 default values are.
2117
2118
2119 .cindex "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 .cindex "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
2132 .code
2133 CC=cc
2134 CFLAGS=-std1
2135 .endd
2136 If you are compiling for just one operating system, it may be easier to put
2137 these lines directly into &_Local/Makefile_&.
2138
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.
2142
2143
2144 .cindex "NIS lookup type" "including support for"
2145 .cindex "NIS+ lookup type" "including support for"
2146 .cindex "LDAP" "including support for"
2147 .cindex "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:
2154 .code
2155 LOOKUP_LDAP=yes
2156 LOOKUP_NIS=yes
2157 LOOKUP_NISPLUS=yes
2158 .endd
2159 and similar settings apply to the other lookup types. They are all listed in
2160 &_src/EDITME_&. In many cases the relevant include files and interface
2161 libraries need to be installed before compiling Exim.
2162 .cindex "cdb" "including support for"
2163 However, there are some optional lookup types (such as cdb) for which
2164 the code is entirely contained within Exim, and no external include
2165 files or libraries are required. When a lookup type is not included in the
2166 binary, attempts to configure Exim to use it cause run time configuration
2167 errors.
2168
2169 .cindex "pkg-config" "lookups"
2170 .cindex "pkg-config" "authenticators"
2171 Many systems now use a tool called &'pkg-config'& to encapsulate information
2172 about how to compile against a library; Exim has some initial support for
2173 being able to use pkg-config for lookups and authenticators.  For any given
2174 makefile variable which starts &`LOOKUP_`& or &`AUTH_`&, you can add a new
2175 variable with the &`_PC`& suffix in the name and assign as the value the
2176 name of the package to be queried.  The results of querying via the
2177 &'pkg-config'& command will be added to the appropriate Makefile variables
2178 with &`+=`& directives, so your version of &'make'& will need to support that
2179 syntax.  For instance:
2180 .code
2181 LOOKUP_SQLITE=yes
2182 LOOKUP_SQLITE_PC=sqlite3
2183 AUTH_GSASL=yes
2184 AUTH_GSASL_PC=libgsasl
2185 AUTH_HEIMDAL_GSSAPI=yes
2186 AUTH_HEIMDAL_GSSAPI_PC=heimdal-gssapi
2187 .endd
2188
2189 .cindex "Perl" "including support for"
2190 Exim can be linked with an embedded Perl interpreter, allowing Perl
2191 subroutines to be called during string expansion. To enable this facility,
2192 .code
2193 EXIM_PERL=perl.o
2194 .endd
2195 must be defined in &_Local/Makefile_&. Details of this facility are given in
2196 chapter &<<CHAPperl>>&.
2197
2198 .cindex "X11 libraries, location of"
2199 The location of the X11 libraries is something that varies a lot between
2200 operating systems, and there may be different versions of X11 to cope
2201 with. Exim itself makes no use of X11, but if you are compiling the Exim
2202 monitor, the X11 libraries must be available.
2203 The following three variables are set in &_OS/Makefile-Default_&:
2204 .code
2205 X11=/usr/X11R6
2206 XINCLUDE=-I$(X11)/include
2207 XLFLAGS=-L$(X11)/lib
2208 .endd
2209 These are overridden in some of the operating-system configuration files. For
2210 example, in &_OS/Makefile-SunOS5_& there is
2211 .code
2212 X11=/usr/openwin
2213 XINCLUDE=-I$(X11)/include
2214 XLFLAGS=-L$(X11)/lib -R$(X11)/lib
2215 .endd
2216 If you need to override the default setting for your operating system, place a
2217 definition of all three of these variables into your
2218 &_Local/Makefile-<ostype>_& file.
2219
2220 .cindex "EXTRALIBS"
2221 If you need to add any extra libraries to the link steps, these can be put in a
2222 variable called EXTRALIBS, which appears in all the link commands, but by
2223 default is not defined. In contrast, EXTRALIBS_EXIM is used only on the
2224 command for linking the main Exim binary, and not for any associated utilities.
2225
2226 .cindex "DBM libraries" "configuration for building"
2227 There is also DBMLIB, which appears in the link commands for binaries that
2228 use DBM functions (see also section &<<SECTdb>>&). Finally, there is
2229 EXTRALIBS_EXIMON, which appears only in the link step for the Exim monitor
2230 binary, and which can be used, for example, to include additional X11
2231 libraries.
2232
2233 .cindex "configuration file" "editing"
2234 The make file copes with rebuilding Exim correctly if any of the configuration
2235 files are edited. However, if an optional configuration file is deleted, it is
2236 necessary to touch the associated non-optional file (that is,
2237 &_Local/Makefile_& or &_Local/eximon.conf_&) before rebuilding.
2238
2239
2240 .section "OS-specific header files" "SECID30"
2241 .cindex "&_os.h_&"
2242 .cindex "building Exim" "OS-specific C header files"
2243 The &_OS_& directory contains a number of files with names of the form
2244 &_os.h-<ostype>_&. These are system-specific C header files that should not
2245 normally need to be changed. There is a list of macro settings that are
2246 recognized in the file &_OS/os.configuring_&, which should be consulted if you
2247 are porting Exim to a new operating system.
2248
2249
2250
2251 .section "Overriding build-time options for the monitor" "SECID31"
2252 .cindex "building Eximon"
2253 A similar process is used for overriding things when building the Exim monitor,
2254 where the files that are involved are
2255 .display
2256 &_OS/eximon.conf-Default_&
2257 &_OS/eximon.conf-_&<&'ostype'&>
2258 &_Local/eximon.conf_&
2259 &_Local/eximon.conf-_&<&'ostype'&>
2260 &_Local/eximon.conf-_&<&'archtype'&>
2261 &_Local/eximon.conf-_&<&'ostype'&>-<&'archtype'&>
2262 .endd
2263 .cindex "&_Local/eximon.conf_&"
2264 As with Exim itself, the final three files need not exist, and in this case the
2265 &_OS/eximon.conf-<ostype>_& file is also optional. The default values in
2266 &_OS/eximon.conf-Default_& can be overridden dynamically by setting environment
2267 variables of the same name, preceded by EXIMON_. For example, setting
2268 EXIMON_LOG_DEPTH in the environment overrides the value of
2269 LOG_DEPTH at run time.
2270 .ecindex IIDbuex
2271
2272
2273 .section "Installing Exim binaries and scripts" "SECID32"
2274 .cindex "installing Exim"
2275 .cindex "BIN_DIRECTORY"
2276 The command &`make install`& runs the &(exim_install)& script with no
2277 arguments. The script copies binaries and utility scripts into the directory
2278 whose name is specified by the BIN_DIRECTORY setting in &_Local/Makefile_&.
2279 .cindex "setuid" "installing Exim with"
2280 The install script copies files only if they are newer than the files they are
2281 going to replace. The Exim binary is required to be owned by root and have the
2282 &'setuid'& bit set, for normal configurations. Therefore, you must run &`make
2283 install`& as root so that it can set up the Exim binary in this way. However, in
2284 some special situations (for example, if a host is doing no local deliveries)
2285 it may be possible to run Exim without making the binary setuid root (see
2286 chapter &<<CHAPsecurity>>& for details).
2287
2288 .cindex "CONFIGURE_FILE"
2289 Exim's run time configuration file is named by the CONFIGURE_FILE setting
2290 in &_Local/Makefile_&. If this names a single file, and the file does not
2291 exist, the default configuration file &_src/configure.default_& is copied there
2292 by the installation script. If a run time configuration file already exists, it
2293 is left alone. If CONFIGURE_FILE is a colon-separated list, naming several
2294 alternative files, no default is installed.
2295
2296 .cindex "system aliases file"
2297 .cindex "&_/etc/aliases_&"
2298 One change is made to the default configuration file when it is installed: the
2299 default configuration contains a router that references a system aliases file.
2300 The path to this file is set to the value specified by
2301 SYSTEM_ALIASES_FILE in &_Local/Makefile_& (&_/etc/aliases_& by default).
2302 If the system aliases file does not exist, the installation script creates it,
2303 and outputs a comment to the user.
2304
2305 The created file contains no aliases, but it does contain comments about the
2306 aliases a site should normally have. Mail aliases have traditionally been
2307 kept in &_/etc/aliases_&. However, some operating systems are now using
2308 &_/etc/mail/aliases_&. You should check if yours is one of these, and change
2309 Exim's configuration if necessary.
2310
2311 The default configuration uses the local host's name as the only local domain,
2312 and is set up to do local deliveries into the shared directory &_/var/mail_&,
2313 running as the local user. System aliases and &_.forward_& files in users' home
2314 directories are supported, but no NIS or NIS+ support is configured. Domains
2315 other than the name of the local host are routed using the DNS, with delivery
2316 over SMTP.
2317
2318 It is possible to install Exim for special purposes (such as building a binary
2319 distribution) in a private part of the file system. You can do this by a
2320 command such as
2321 .code
2322 make DESTDIR=/some/directory/ install
2323 .endd
2324 This has the effect of pre-pending the specified directory to all the file
2325 paths, except the name of the system aliases file that appears in the default
2326 configuration. (If a default alias file is created, its name &'is'& modified.)
2327 For backwards compatibility, ROOT is used if DESTDIR is not set,
2328 but this usage is deprecated.
2329
2330 .cindex "installing Exim" "what is not installed"
2331 Running &'make install'& does not copy the Exim 4 conversion script
2332 &'convert4r4'&. You will probably run this only once if you are
2333 upgrading from Exim 3. None of the documentation files in the &_doc_&
2334 directory are copied, except for the info files when you have set
2335 INFO_DIRECTORY, as described in section &<<SECTinsinfdoc>>& below.
2336
2337 For the utility programs, old versions are renamed by adding the suffix &_.O_&
2338 to their names. The Exim binary itself, however, is handled differently. It is
2339 installed under a name that includes the version number and the compile number,
2340 for example &_exim-&version()-1_&. The script then arranges for a symbolic link
2341 called &_exim_& to point to the binary. If you are updating a previous version
2342 of Exim, the script takes care to ensure that the name &_exim_& is never absent
2343 from the directory (as seen by other processes).
2344
2345 .cindex "installing Exim" "testing the script"
2346 If you want to see what the &'make install'& will do before running it for
2347 real, you can pass the &%-n%& option to the installation script by this
2348 command:
2349 .code
2350 make INSTALL_ARG=-n install
2351 .endd
2352 The contents of the variable INSTALL_ARG are passed to the installation
2353 script. You do not need to be root to run this test. Alternatively, you can run
2354 the installation script directly, but this must be from within the build
2355 directory. For example, from the top-level Exim directory you could use this
2356 command:
2357 .code
2358 (cd build-SunOS5-5.5.1-sparc; ../scripts/exim_install -n)
2359 .endd
2360 .cindex "installing Exim" "install script options"
2361 There are two other options that can be supplied to the installation script.
2362
2363 .ilist
2364 &%-no_chown%& bypasses the call to change the owner of the installed binary
2365 to root, and the call to make it a setuid binary.
2366 .next
2367 &%-no_symlink%& bypasses the setting up of the symbolic link &_exim_& to the
2368 installed binary.
2369 .endlist
2370
2371 INSTALL_ARG can be used to pass these options to the script. For example:
2372 .code
2373 make INSTALL_ARG=-no_symlink install
2374 .endd
2375 The installation script can also be given arguments specifying which files are
2376 to be copied. For example, to install just the Exim binary, and nothing else,
2377 without creating the symbolic link, you could use:
2378 .code
2379 make INSTALL_ARG='-no_symlink exim' install
2380 .endd
2381
2382
2383
2384 .section "Installing info documentation" "SECTinsinfdoc"
2385 .cindex "installing Exim" "&'info'& documentation"
2386 Not all systems use the GNU &'info'& system for documentation, and for this
2387 reason, the Texinfo source of Exim's documentation is not included in the main
2388 distribution. Instead it is available separately from the ftp site (see section
2389 &<<SECTavail>>&).
2390
2391 If you have defined INFO_DIRECTORY in &_Local/Makefile_& and the Texinfo
2392 source of the documentation is found in the source tree, running &`make
2393 install`& automatically builds the info files and installs them.
2394
2395
2396
2397 .section "Setting up the spool directory" "SECID33"
2398 .cindex "spool directory" "creating"
2399 When it starts up, Exim tries to create its spool directory if it does not
2400 exist. The Exim uid and gid are used for the owner and group of the spool
2401 directory. Sub-directories are automatically created in the spool directory as
2402 necessary.
2403
2404
2405
2406
2407 .section "Testing" "SECID34"
2408 .cindex "testing" "installation"
2409 Having installed Exim, you can check that the run time configuration file is
2410 syntactically valid by running the following command, which assumes that the
2411 Exim binary directory is within your PATH environment variable:
2412 .code
2413 exim -bV
2414 .endd
2415 If there are any errors in the configuration file, Exim outputs error messages.
2416 Otherwise it outputs the version number and build date,
2417 the DBM library that is being used, and information about which drivers and
2418 other optional code modules are included in the binary.
2419 Some simple routing tests can be done by using the address testing option. For
2420 example,
2421 .display
2422 &`exim -bt`& <&'local username'&>
2423 .endd
2424 should verify that it recognizes a local mailbox, and
2425 .display
2426 &`exim -bt`& <&'remote address'&>
2427 .endd
2428 a remote one. Then try getting it to deliver mail, both locally and remotely.
2429 This can be done by passing messages directly to Exim, without going through a
2430 user agent. For example:
2431 .code
2432 exim -v postmaster@your.domain.example
2433 From: user@your.domain.example
2434 To: postmaster@your.domain.example
2435 Subject: Testing Exim
2436
2437 This is a test message.
2438 ^D
2439 .endd
2440 The &%-v%& option causes Exim to output some verification of what it is doing.
2441 In this case you should see copies of three log lines, one for the message's
2442 arrival, one for its delivery, and one containing &"Completed"&.
2443
2444 .cindex "delivery" "problems with"
2445 If you encounter problems, look at Exim's log files (&'mainlog'& and
2446 &'paniclog'&) to see if there is any relevant information there. Another source
2447 of information is running Exim with debugging turned on, by specifying the
2448 &%-d%& option. If a message is stuck on Exim's spool, you can force a delivery
2449 with debugging turned on by a command of the form
2450 .display
2451 &`exim -d -M`& <&'exim-message-id'&>
2452 .endd
2453 You must be root or an &"admin user"& in order to do this. The &%-d%& option
2454 produces rather a lot of output, but you can cut this down to specific areas.
2455 For example, if you use &%-d-all+route%& only the debugging information
2456 relevant to routing is included. (See the &%-d%& option in chapter
2457 &<<CHAPcommandline>>& for more details.)
2458
2459 .cindex '&"sticky"& bit'
2460 .cindex "lock files"
2461 One specific problem that has shown up on some sites is the inability to do
2462 local deliveries into a shared mailbox directory, because it does not have the
2463 &"sticky bit"& set on it. By default, Exim tries to create a lock file before
2464 writing to a mailbox file, and if it cannot create the lock file, the delivery
2465 is deferred. You can get round this either by setting the &"sticky bit"& on the
2466 directory, or by setting a specific group for local deliveries and allowing
2467 that group to create files in the directory (see the comments above the
2468 &(local_delivery)& transport in the default configuration file). Another
2469 approach is to configure Exim not to use lock files, but just to rely on
2470 &[fcntl()]& locking instead. However, you should do this only if all user
2471 agents also use &[fcntl()]& locking. For further discussion of locking issues,
2472 see chapter &<<CHAPappendfile>>&.
2473
2474 One thing that cannot be tested on a system that is already running an MTA is
2475 the receipt of incoming SMTP mail on the standard SMTP port. However, the
2476 &%-oX%& option can be used to run an Exim daemon that listens on some other
2477 port, or &'inetd'& can be used to do this. The &%-bh%& option and the
2478 &'exim_checkaccess'& utility can be used to check out policy controls on
2479 incoming SMTP mail.
2480
2481 Testing a new version on a system that is already running Exim can most easily
2482 be done by building a binary with a different CONFIGURE_FILE setting. From
2483 within the run time configuration, all other file and directory names
2484 that Exim uses can be altered, in order to keep it entirely clear of the
2485 production version.
2486
2487
2488 .section "Replacing another MTA with Exim" "SECID35"
2489 .cindex "replacing another MTA"
2490 Building and installing Exim for the first time does not of itself put it in
2491 general use. The name by which the system's MTA is called by mail user agents
2492 is either &_/usr/sbin/sendmail_&, or &_/usr/lib/sendmail_& (depending on the
2493 operating system), and it is necessary to make this name point to the &'exim'&
2494 binary in order to get the user agents to pass messages to Exim. This is
2495 normally done by renaming any existing file and making &_/usr/sbin/sendmail_&
2496 or &_/usr/lib/sendmail_&
2497 .cindex "symbolic link" "to &'exim'& binary"
2498 a symbolic link to the &'exim'& binary. It is a good idea to remove any setuid
2499 privilege and executable status from the old MTA. It is then necessary to stop
2500 and restart the mailer daemon, if one is running.
2501
2502 .cindex "FreeBSD, MTA indirection"
2503 .cindex "&_/etc/mail/mailer.conf_&"
2504 Some operating systems have introduced alternative ways of switching MTAs. For
2505 example, if you are running FreeBSD, you need to edit the file
2506 &_/etc/mail/mailer.conf_& instead of setting up a symbolic link as just
2507 described. A typical example of the contents of this file for running Exim is
2508 as follows:
2509 .code
2510 sendmail            /usr/exim/bin/exim
2511 send-mail           /usr/exim/bin/exim
2512 mailq               /usr/exim/bin/exim -bp
2513 newaliases          /usr/bin/true
2514 .endd
2515 Once you have set up the symbolic link, or edited &_/etc/mail/mailer.conf_&,
2516 your Exim installation is &"live"&. Check it by sending a message from your
2517 favourite user agent.
2518
2519 You should consider what to tell your users about the change of MTA. Exim may
2520 have different capabilities to what was previously running, and there are
2521 various operational differences such as the text of messages produced by
2522 command line options and in bounce messages. If you allow your users to make
2523 use of Exim's filtering capabilities, you should make the document entitled
2524 &'Exim's interface to mail filtering'& available to them.
2525
2526
2527
2528 .section "Upgrading Exim" "SECID36"
2529 .cindex "upgrading Exim"
2530 If you are already running Exim on your host, building and installing a new
2531 version automatically makes it available to MUAs, or any other programs that
2532 call the MTA directly. However, if you are running an Exim daemon, you do need
2533 to send it a HUP signal, to make it re-execute itself, and thereby pick up the
2534 new binary. You do not need to stop processing mail in order to install a new
2535 version of Exim. The install script does not modify an existing runtime
2536 configuration file.
2537
2538
2539
2540
2541 .section "Stopping the Exim daemon on Solaris" "SECID37"
2542 .cindex "Solaris" "stopping Exim on"
2543 The standard command for stopping the mailer daemon on Solaris is
2544 .code
2545 /etc/init.d/sendmail stop
2546 .endd
2547 If &_/usr/lib/sendmail_& has been turned into a symbolic link, this script
2548 fails to stop Exim because it uses the command &'ps -e'& and greps the output
2549 for the text &"sendmail"&; this is not present because the actual program name
2550 (that is, &"exim"&) is given by the &'ps'& command with these options. A
2551 solution is to replace the line that finds the process id with something like
2552 .code
2553 pid=`cat /var/spool/exim/exim-daemon.pid`
2554 .endd
2555 to obtain the daemon's pid directly from the file that Exim saves it in.
2556
2557 Note, however, that stopping the daemon does not &"stop Exim"&. Messages can
2558 still be received from local processes, and if automatic delivery is configured
2559 (the normal case), deliveries will still occur.
2560
2561
2562
2563
2564 . ////////////////////////////////////////////////////////////////////////////
2565 . ////////////////////////////////////////////////////////////////////////////
2566
2567 .chapter "The Exim command line" "CHAPcommandline"
2568 .scindex IIDclo1 "command line" "options"
2569 .scindex IIDclo2 "options" "command line"
2570 Exim's command line takes the standard Unix form of a sequence of options,
2571 each starting with a hyphen character, followed by a number of arguments. The
2572 options are compatible with the main options of Sendmail, and there are also
2573 some additional options, some of which are compatible with Smail 3. Certain
2574 combinations of options do not make sense, and provoke an error if used.
2575 The form of the arguments depends on which options are set.
2576
2577
2578 .section "Setting options by program name" "SECID38"
2579 .cindex "&'mailq'&"
2580 If Exim is called under the name &'mailq'&, it behaves as if the option &%-bp%&
2581 were present before any other options.
2582 The &%-bp%& option requests a listing of the contents of the mail queue on the
2583 standard output.
2584 This feature is for compatibility with some systems that contain a command of
2585 that name in one of the standard libraries, symbolically linked to
2586 &_/usr/sbin/sendmail_& or &_/usr/lib/sendmail_&.
2587
2588 .cindex "&'rsmtp'&"
2589 If Exim is called under the name &'rsmtp'& it behaves as if the option &%-bS%&
2590 were present before any other options, for compatibility with Smail. The
2591 &%-bS%& option is used for reading in a number of messages in batched SMTP
2592 format.
2593
2594 .cindex "&'rmail'&"
2595 If Exim is called under the name &'rmail'& it behaves as if the &%-i%& and
2596 &%-oee%& options were present before any other options, for compatibility with
2597 Smail. The name &'rmail'& is used as an interface by some UUCP systems.
2598
2599 .cindex "&'runq'&"
2600 .cindex "queue runner"
2601 If Exim is called under the name &'runq'& it behaves as if the option &%-q%&
2602 were present before any other options, for compatibility with Smail. The &%-q%&
2603 option causes a single queue runner process to be started.
2604
2605 .cindex "&'newaliases'&"
2606 .cindex "alias file" "building"
2607 .cindex "Sendmail compatibility" "calling Exim as &'newaliases'&"
2608 If Exim is called under the name &'newaliases'& it behaves as if the option
2609 &%-bi%& were present before any other options, for compatibility with Sendmail.
2610 This option is used for rebuilding Sendmail's alias file. Exim does not have
2611 the concept of a single alias file, but can be configured to run a given
2612 command if called with the &%-bi%& option.
2613
2614
2615 .section "Trusted and admin users" "SECTtrustedadmin"
2616 Some Exim options are available only to &'trusted users'& and others are
2617 available only to &'admin users'&. In the description below, the phrases &"Exim
2618 user"& and &"Exim group"& mean the user and group defined by EXIM_USER and
2619 EXIM_GROUP in &_Local/Makefile_& or set by the &%exim_user%& and
2620 &%exim_group%& options. These do not necessarily have to use the name &"exim"&.
2621
2622 .ilist
2623 .cindex "trusted users" "definition of"
2624 .cindex "user" "trusted definition of"
2625 The trusted users are root, the Exim user, any user listed in the
2626 &%trusted_users%& configuration option, and any user whose current group or any
2627 supplementary group is one of those listed in the &%trusted_groups%&
2628 configuration option. Note that the Exim group is not automatically trusted.
2629
2630 .cindex '&"From"& line'
2631 .cindex "envelope sender"
2632 Trusted users are always permitted to use the &%-f%& option or a leading
2633 &"From&~"& line to specify the envelope sender of a message that is passed to
2634 Exim through the local interface (see the &%-bm%& and &%-f%& options below).
2635 See the &%untrusted_set_sender%& option for a way of permitting non-trusted
2636 users to set envelope senders.
2637
2638 .cindex "&'From:'& header line"
2639 .cindex "&'Sender:'& header line"
2640 .cindex "header lines" "From:"
2641 .cindex "header lines" "Sender:"
2642 For a trusted user, there is never any check on the contents of the &'From:'&
2643 header line, and a &'Sender:'& line is never added. Furthermore, any existing
2644 &'Sender:'& line in incoming local (non-TCP/IP) messages is not removed.
2645
2646 Trusted users may also specify a host name, host address, interface address,
2647 protocol name, ident value, and authentication data when submitting a message
2648 locally. Thus, they are able to insert messages into Exim's queue locally that
2649 have the characteristics of messages received from a remote host. Untrusted
2650 users may in some circumstances use &%-f%&, but can never set the other values
2651 that are available to trusted users.
2652 .next
2653 .cindex "user" "admin definition of"
2654 .cindex "admin user" "definition of"
2655 The admin users are root, the Exim user, and any user that is a member of the
2656 Exim group or of any group listed in the &%admin_groups%& configuration option.
2657 The current group does not have to be one of these groups.
2658
2659 Admin users are permitted to list the queue, and to carry out certain
2660 operations on messages, for example, to force delivery failures. It is also
2661 necessary to be an admin user in order to see the full information provided by
2662 the Exim monitor, and full debugging output.
2663
2664 By default, the use of the &%-M%&, &%-q%&, &%-R%&, and &%-S%& options to cause
2665 Exim to attempt delivery of messages on its queue is restricted to admin users.
2666 However, this restriction can be relaxed by setting the &%prod_requires_admin%&
2667 option false (that is, specifying &%no_prod_requires_admin%&).
2668
2669 Similarly, the use of the &%-bp%& option to list all the messages in the queue
2670 is restricted to admin users unless &%queue_list_requires_admin%& is set
2671 false.
2672 .endlist
2673
2674
2675 &*Warning*&: If you configure your system so that admin users are able to
2676 edit Exim's configuration file, you are giving those users an easy way of
2677 getting root. There is further discussion of this issue at the start of chapter
2678 &<<CHAPconf>>&.
2679
2680
2681
2682
2683 .section "Command line options" "SECID39"
2684 Exim's command line options are described in alphabetical order below. If none
2685 of the options that specifies a specific action (such as starting the daemon or
2686 a queue runner, or testing an address, or receiving a message in a specific
2687 format, or listing the queue) are present, and there is at least one argument
2688 on the command line, &%-bm%& (accept a local message on the standard input,
2689 with the arguments specifying the recipients) is assumed. Otherwise, Exim
2690 outputs a brief message about itself and exits.
2691
2692 . ////////////////////////////////////////////////////////////////////////////
2693 . Insert a stylized XML comment here, to identify the start of the command line
2694 . options. This is for the benefit of the Perl script that automatically
2695 . creates a man page for the options.
2696 . ////////////////////////////////////////////////////////////////////////////
2697
2698 .literal xml
2699 <!-- === Start of command line options === -->
2700 .literal off
2701
2702
2703 .vlist
2704 .vitem &%--%&
2705 .oindex "--"
2706 .cindex "options" "command line; terminating"
2707 This is a pseudo-option whose only purpose is to terminate the options and
2708 therefore to cause subsequent command line items to be treated as arguments
2709 rather than options, even if they begin with hyphens.
2710
2711 .vitem &%--help%&
2712 .oindex "&%--help%&"
2713 This option causes Exim to output a few sentences stating what it is.
2714 The same output is generated if the Exim binary is called with no options and
2715 no arguments.
2716
2717 .vitem &%--version%&
2718 .oindex "&%--version%&"
2719 This option is an alias for &%-bV%& and causes version information to be
2720 displayed.
2721
2722 .vitem &%-Ac%& &&&
2723        &%-Am%&
2724 .oindex "&%-Ac%&"
2725 .oindex "&%-Am%&"
2726 These options are used by Sendmail for selecting configuration files and are
2727 ignored by Exim.
2728
2729 .vitem &%-B%&<&'type'&>
2730 .oindex "&%-B%&"
2731 .cindex "8-bit characters"
2732 .cindex "Sendmail compatibility" "8-bit characters"
2733 This is a Sendmail option for selecting 7 or 8 bit processing. Exim is 8-bit
2734 clean; it ignores this option.
2735
2736 .vitem &%-bd%&
2737 .oindex "&%-bd%&"
2738 .cindex "daemon"
2739 .cindex "SMTP" "listener"
2740 .cindex "queue runner"
2741 This option runs Exim as a daemon, awaiting incoming SMTP connections. Usually
2742 the &%-bd%& option is combined with the &%-q%&<&'time'&> option, to specify
2743 that the daemon should also initiate periodic queue runs.
2744
2745 The &%-bd%& option can be used only by an admin user. If either of the &%-d%&
2746 (debugging) or &%-v%& (verifying) options are set, the daemon does not
2747 disconnect from the controlling terminal. When running this way, it can be
2748 stopped by pressing ctrl-C.
2749
2750 By default, Exim listens for incoming connections to the standard SMTP port on
2751 all the host's running interfaces. However, it is possible to listen on other
2752 ports, on multiple ports, and only on specific interfaces. Chapter
2753 &<<CHAPinterfaces>>& contains a description of the options that control this.
2754
2755 When a listening daemon
2756 .cindex "daemon" "process id (pid)"
2757 .cindex "pid (process id)" "of daemon"
2758 is started without the use of &%-oX%& (that is, without overriding the normal
2759 configuration), it writes its process id to a file called &_exim-daemon.pid_&
2760 in Exim's spool directory. This location can be overridden by setting
2761 PID_FILE_PATH in &_Local/Makefile_&. The file is written while Exim is still
2762 running as root.
2763
2764 When &%-oX%& is used on the command line to start a listening daemon, the
2765 process id is not written to the normal pid file path. However, &%-oP%& can be
2766 used to specify a path on the command line if a pid file is required.
2767
2768 The SIGHUP signal
2769 .cindex "SIGHUP"
2770 .cindex "daemon" "restarting"
2771 can be used to cause the daemon to re-execute itself. This should be done
2772 whenever Exim's configuration file, or any file that is incorporated into it by
2773 means of the &%.include%& facility, is changed, and also whenever a new version
2774 of Exim is installed. It is not necessary to do this when other files that are
2775 referenced from the configuration (for example, alias files) are changed,
2776 because these are reread each time they are used.
2777
2778 .vitem &%-bdf%&
2779 .oindex "&%-bdf%&"
2780 This option has the same effect as &%-bd%& except that it never disconnects
2781 from the controlling terminal, even when no debugging is specified.
2782
2783 .vitem &%-be%&
2784 .oindex "&%-be%&"
2785 .cindex "testing" "string expansion"
2786 .cindex "expansion" "testing"
2787 Run Exim in expansion testing mode. Exim discards its root privilege, to
2788 prevent ordinary users from using this mode to read otherwise inaccessible
2789 files. If no arguments are given, Exim runs interactively, prompting for lines
2790 of data. Otherwise, it processes each argument in turn.
2791
2792 If Exim was built with USE_READLINE=yes in &_Local/Makefile_&, it tries
2793 to load the &%libreadline%& library dynamically whenever the &%-be%& option is
2794 used without command line arguments. If successful, it uses the &[readline()]&
2795 function, which provides extensive line-editing facilities, for reading the
2796 test data. A line history is supported.
2797
2798 Long expansion expressions can be split over several lines by using backslash
2799 continuations. As in Exim's run time configuration, white space at the start of
2800 continuation lines is ignored. Each argument or data line is passed through the
2801 string expansion mechanism, and the result is output. Variable values from the
2802 configuration file (for example, &$qualify_domain$&) are available, but no
2803 message-specific values (such as &$message_exim_id$&) are set, because no message
2804 is being processed (but see &%-bem%& and &%-Mset%&).
2805
2806 &*Note*&: If you use this mechanism to test lookups, and you change the data
2807 files or databases you are using, you must exit and restart Exim before trying
2808 the same lookup again. Otherwise, because each Exim process caches the results
2809 of lookups, you will just get the same result as before.
2810
2811 Macro processing is done on lines before string-expansion: new macros can be
2812 defined and macros will be expanded.
2813 Because macros in the config file are often used for secrets, those are only
2814 available to admin users.
2815
2816 .vitem &%-bem%&&~<&'filename'&>
2817 .oindex "&%-bem%&"
2818 .cindex "testing" "string expansion"
2819 .cindex "expansion" "testing"
2820 This option operates like &%-be%& except that it must be followed by the name
2821 of a file. For example:
2822 .code
2823 exim -bem /tmp/testmessage
2824 .endd
2825 The file is read as a message (as if receiving a locally-submitted non-SMTP
2826 message) before any of the test expansions are done. Thus, message-specific
2827 variables such as &$message_size$& and &$header_from:$& are available. However,
2828 no &'Received:'& header is added to the message. If the &%-t%& option is set,
2829 recipients are read from the headers in the normal way, and are shown in the
2830 &$recipients$& variable. Note that recipients cannot be given on the command
2831 line, because further arguments are taken as strings to expand (just like
2832 &%-be%&).
2833
2834 .vitem &%-bF%&&~<&'filename'&>
2835 .oindex "&%-bF%&"
2836 .cindex "system filter" "testing"
2837 .cindex "testing" "system filter"
2838 This option is the same as &%-bf%& except that it assumes that the filter being
2839 tested is a system filter. The additional commands that are available only in
2840 system filters are recognized.
2841
2842 .vitem &%-bf%&&~<&'filename'&>
2843 .oindex "&%-bf%&"
2844 .cindex "filter" "testing"
2845 .cindex "testing" "filter file"
2846 .cindex "forward file" "testing"
2847 .cindex "testing" "forward file"
2848 .cindex "Sieve filter" "testing"
2849 This option runs Exim in user filter testing mode; the file is the filter file
2850 to be tested, and a test message must be supplied on the standard input. If
2851 there are no message-dependent tests in the filter, an empty file can be
2852 supplied.
2853
2854 If you want to test a system filter file, use &%-bF%& instead of &%-bf%&. You
2855 can use both &%-bF%& and &%-bf%& on the same command, in order to test a system
2856 filter and a user filter in the same run. For example:
2857 .code
2858 exim -bF /system/filter -bf /user/filter </test/message
2859 .endd
2860 This is helpful when the system filter adds header lines or sets filter
2861 variables that are used by the user filter.
2862
2863 If the test filter file does not begin with one of the special lines
2864 .code
2865 # Exim filter
2866 # Sieve filter
2867 .endd
2868 it is taken to be a normal &_.forward_& file, and is tested for validity under
2869 that interpretation. See sections &<<SECTitenonfilred>>& to
2870 &<<SECTspecitredli>>& for a description of the possible contents of non-filter
2871 redirection lists.
2872
2873 The result of an Exim command that uses &%-bf%&, provided no errors are
2874 detected, is a list of the actions that Exim would try to take if presented
2875 with the message for real. More details of filter testing are given in the
2876 separate document entitled &'Exim's interfaces to mail filtering'&.
2877
2878 When testing a filter file,
2879 .cindex "&""From""& line"
2880 .cindex "envelope sender"
2881 .oindex "&%-f%&" "for filter testing"
2882 the envelope sender can be set by the &%-f%& option,
2883 or by a &"From&~"& line at the start of the test message. Various parameters
2884 that would normally be taken from the envelope recipient address of the message
2885 can be set by means of additional command line options (see the next four
2886 options).
2887
2888 .vitem &%-bfd%&&~<&'domain'&>
2889 .oindex "&%-bfd%&"
2890 .vindex "&$qualify_domain$&"
2891 This sets the domain of the recipient address when a filter file is being
2892 tested by means of the &%-bf%& option. The default is the value of
2893 &$qualify_domain$&.
2894
2895 .vitem &%-bfl%&&~<&'local&~part'&>
2896 .oindex "&%-bfl%&"
2897 This sets the local part of the recipient address when a filter file is being
2898 tested by means of the &%-bf%& option. The default is the username of the
2899 process that calls Exim. A local part should be specified with any prefix or
2900 suffix stripped, because that is how it appears to the filter when a message is
2901 actually being delivered.
2902
2903 .vitem &%-bfp%&&~<&'prefix'&>
2904 .oindex "&%-bfp%&"
2905 .cindex affix "filter testing"
2906 This sets the prefix of the local part of the recipient address when a filter
2907 file is being tested by means of the &%-bf%& option. The default is an empty
2908 prefix.
2909
2910 .vitem &%-bfs%&&~<&'suffix'&>
2911 .oindex "&%-bfs%&"
2912 .cindex affix "filter testing"
2913 This sets the suffix of the local part of the recipient address when a filter
2914 file is being tested by means of the &%-bf%& option. The default is an empty
2915 suffix.
2916
2917 .vitem &%-bh%&&~<&'IP&~address'&>
2918 .oindex "&%-bh%&"
2919 .cindex "testing" "incoming SMTP"
2920 .cindex "SMTP" "testing incoming"
2921 .cindex "testing" "relay control"
2922 .cindex "relaying" "testing configuration"
2923 .cindex "policy control" "testing"
2924 .cindex "debugging" "&%-bh%& option"
2925 This option runs a fake SMTP session as if from the given IP address, using the
2926 standard input and output. The IP address may include a port number at the end,
2927 after a full stop. For example:
2928 .code
2929 exim -bh 10.9.8.7.1234
2930 exim -bh fe80::a00:20ff:fe86:a061.5678
2931 .endd
2932 When an IPv6 address is given, it is converted into canonical form. In the case
2933 of the second example above, the value of &$sender_host_address$& after
2934 conversion to the canonical form is
2935 &`fe80:0000:0000:0a00:20ff:fe86:a061.5678`&.
2936
2937 Comments as to what is going on are written to the standard error file. These
2938 include lines beginning with &"LOG"& for anything that would have been logged.
2939 This facility is provided for testing configuration options for incoming
2940 messages, to make sure they implement the required policy. For example, you can
2941 test your relay controls using &%-bh%&.
2942
2943 &*Warning 1*&:
2944 .cindex "RFC 1413"
2945 You can test features of the configuration that rely on ident (RFC 1413)
2946 information by using the &%-oMt%& option. However, Exim cannot actually perform
2947 an ident callout when testing using &%-bh%& because there is no incoming SMTP
2948 connection.
2949
2950 &*Warning 2*&: Address verification callouts (see section &<<SECTcallver>>&)
2951 are also skipped when testing using &%-bh%&. If you want these callouts to
2952 occur, use &%-bhc%& instead.
2953
2954 Messages supplied during the testing session are discarded, and nothing is
2955 written to any of the real log files. There may be pauses when DNS (and other)
2956 lookups are taking place, and of course these may time out. The &%-oMi%& option
2957 can be used to specify a specific IP interface and port if this is important,
2958 and &%-oMaa%& and &%-oMai%& can be used to set parameters as if the SMTP
2959 session were authenticated.
2960
2961 The &'exim_checkaccess'& utility is a &"packaged"& version of &%-bh%& whose
2962 output just states whether a given recipient address from a given host is
2963 acceptable or not. See section &<<SECTcheckaccess>>&.
2964
2965 Features such as authentication and encryption, where the client input is not
2966 plain text, cannot easily be tested with &%-bh%&. Instead, you should use a
2967 specialized SMTP test program such as
2968 &url(https://www.jetmore.org/john/code/swaks/,swaks).
2969
2970 .vitem &%-bhc%&&~<&'IP&~address'&>
2971 .oindex "&%-bhc%&"
2972 This option operates in the same way as &%-bh%&, except that address
2973 verification callouts are performed if required. This includes consulting and
2974 updating the callout cache database.
2975
2976 .vitem &%-bi%&
2977 .oindex "&%-bi%&"
2978 .cindex "alias file" "building"
2979 .cindex "building alias file"
2980 .cindex "Sendmail compatibility" "&%-bi%& option"
2981 Sendmail interprets the &%-bi%& option as a request to rebuild its alias file.
2982 Exim does not have the concept of a single alias file, and so it cannot mimic
2983 this behaviour. However, calls to &_/usr/lib/sendmail_& with the &%-bi%& option
2984 tend to appear in various scripts such as NIS make files, so the option must be
2985 recognized.
2986
2987 If &%-bi%& is encountered, the command specified by the &%bi_command%&
2988 configuration option is run, under the uid and gid of the caller of Exim. If
2989 the &%-oA%& option is used, its value is passed to the command as an argument.
2990 The command set by &%bi_command%& may not contain arguments. The command can
2991 use the &'exim_dbmbuild'& utility, or some other means, to rebuild alias files
2992 if this is required. If the &%bi_command%& option is not set, calling Exim with
2993 &%-bi%& is a no-op.
2994
2995 . // Keep :help first, then the rest in alphabetical order
2996 .vitem &%-bI:help%&
2997 .oindex "&%-bI:help%&"
2998 .cindex "querying exim information"
2999 We shall provide various options starting &`-bI:`& for querying Exim for
3000 information.  The output of many of these will be intended for machine
3001 consumption.  This one is not.  The &%-bI:help%& option asks Exim for a
3002 synopsis of supported options beginning &`-bI:`&.  Use of any of these
3003 options shall cause Exim to exit after producing the requested output.
3004
3005 .vitem &%-bI:dscp%&
3006 .oindex "&%-bI:dscp%&"
3007 .cindex "DSCP" "values"
3008 This option causes Exim to emit an alphabetically sorted list of all
3009 recognised DSCP names.
3010
3011 .vitem &%-bI:sieve%&
3012 .oindex "&%-bI:sieve%&"
3013 .cindex "Sieve filter" "capabilities"
3014 This option causes Exim to emit an alphabetically sorted list of all supported
3015 Sieve protocol extensions on stdout, one per line.  This is anticipated to be
3016 useful for ManageSieve (RFC 5804) implementations, in providing that protocol's
3017 &`SIEVE`& capability response line.  As the precise list may depend upon
3018 compile-time build options, which this option will adapt to, this is the only
3019 way to guarantee a correct response.
3020
3021 .vitem &%-bm%&
3022 .oindex "&%-bm%&"
3023 .cindex "local message reception"
3024 This option runs an Exim receiving process that accepts an incoming,
3025 locally-generated message on the standard input. The recipients are given as the
3026 command arguments (except when &%-t%& is also present &-- see below). Each
3027 argument can be a comma-separated list of RFC 2822 addresses. This is the
3028 default option for selecting the overall action of an Exim call; it is assumed
3029 if no other conflicting option is present.
3030
3031 If any addresses in the message are unqualified (have no domain), they are
3032 qualified by the values of the &%qualify_domain%& or &%qualify_recipient%&
3033 options, as appropriate. The &%-bnq%& option (see below) provides a way of
3034 suppressing this for special cases.
3035
3036 Policy checks on the contents of local messages can be enforced by means of
3037 the non-SMTP ACL. See chapter &<<CHAPACL>>& for details.
3038
3039 .cindex "return code" "for &%-bm%&"
3040 The return code is zero if the message is successfully accepted. Otherwise, the
3041 action is controlled by the &%-oe%&&'x'& option setting &-- see below.
3042
3043 The format
3044 .cindex "message" "format"
3045 .cindex "format" "message"
3046 .cindex "&""From""& line"
3047 .cindex "UUCP" "&""From""& line"
3048 .cindex "Sendmail compatibility" "&""From""& line"
3049 of the message must be as defined in RFC 2822, except that, for
3050 compatibility with Sendmail and Smail, a line in one of the forms
3051 .code
3052 From sender Fri Jan  5 12:55 GMT 1997
3053 From sender Fri, 5 Jan 97 12:55:01
3054 .endd
3055 (with the weekday optional, and possibly with additional text after the date)
3056 is permitted to appear at the start of the message. There appears to be no
3057 authoritative specification of the format of this line. Exim recognizes it by
3058 matching against the regular expression defined by the &%uucp_from_pattern%&
3059 option, which can be changed if necessary.
3060
3061 .oindex "&%-f%&" "overriding &""From""& line"
3062 The specified sender is treated as if it were given as the argument to the
3063 &%-f%& option, but if a &%-f%& option is also present, its argument is used in
3064 preference to the address taken from the message. The caller of Exim must be a
3065 trusted user for the sender of a message to be set in this way.
3066
3067 .vitem &%-bmalware%&&~<&'filename'&>
3068 .oindex "&%-bmalware%&"
3069 .cindex "testing", "malware"
3070 .cindex "malware scan test"
3071 This debugging option causes Exim to scan the given file or directory
3072 (depending on the used scanner interface),
3073 using the malware scanning framework.  The option of &%av_scanner%& influences
3074 this option, so if &%av_scanner%&'s value is dependent upon an expansion then
3075 the expansion should have defaults which apply to this invocation.  ACLs are
3076 not invoked, so if &%av_scanner%& references an ACL variable then that variable
3077 will never be populated and &%-bmalware%& will fail.
3078
3079 Exim will have changed working directory before resolving the filename, so
3080 using fully qualified pathnames is advisable.  Exim will be running as the Exim
3081 user when it tries to open the file, rather than as the invoking user.
3082 This option requires admin privileges.
3083
3084 The &%-bmalware%& option will not be extended to be more generally useful,
3085 there are better tools for file-scanning.  This option exists to help
3086 administrators verify their Exim and AV scanner configuration.
3087
3088 .vitem &%-bnq%&
3089 .oindex "&%-bnq%&"
3090 .cindex "address qualification, suppressing"
3091 By default, Exim automatically qualifies unqualified addresses (those
3092 without domains) that appear in messages that are submitted locally (that
3093 is, not over TCP/IP). This qualification applies both to addresses in
3094 envelopes, and addresses in header lines. Sender addresses are qualified using
3095 &%qualify_domain%&, and recipient addresses using &%qualify_recipient%& (which
3096 defaults to the value of &%qualify_domain%&).
3097
3098 Sometimes, qualification is not wanted. For example, if &%-bS%& (batch SMTP) is
3099 being used to re-submit messages that originally came from remote hosts after
3100 content scanning, you probably do not want to qualify unqualified addresses in
3101 header lines. (Such lines will be present only if you have not enabled a header
3102 syntax check in the appropriate ACL.)
3103
3104 The &%-bnq%& option suppresses all qualification of unqualified addresses in
3105 messages that originate on the local host. When this is used, unqualified
3106 addresses in the envelope provoke errors (causing message rejection) and
3107 unqualified addresses in header lines are left alone.
3108
3109
3110 .vitem &%-bP%&
3111 .oindex "&%-bP%&"
3112 .cindex "configuration options" "extracting"
3113 .cindex "options" "configuration &-- extracting"
3114 If this option is given with no arguments, it causes the values of all Exim's
3115 main configuration options to be written to the standard output. The values
3116 of one or more specific options can be requested by giving their names as
3117 arguments, for example:
3118 .code
3119 exim -bP qualify_domain hold_domains
3120 .endd
3121 .cindex "hiding configuration option values"
3122 .cindex "configuration options" "hiding value of"
3123 .cindex "options" "hiding value of"
3124 However, any option setting that is preceded by the word &"hide"& in the
3125 configuration file is not shown in full, except to an admin user. For other
3126 users, the output is as in this example:
3127 .code
3128 mysql_servers = <value not displayable>
3129 .endd
3130 If &%config%& is given as an argument, the config is
3131 output, as it was parsed, any include file resolved, any comment removed.
3132
3133 If &%config_file%& is given as an argument, the name of the run time
3134 configuration file is output. (&%configure_file%& works too, for
3135 backward compatibility.)
3136 If a list of configuration files was supplied, the value that is output here
3137 is the name of the file that was actually used.
3138
3139 .cindex "options" "hiding name of"
3140 If the &%-n%& flag is given, then for most modes of &%-bP%& operation the
3141 name will not be output.
3142
3143 .cindex "daemon" "process id (pid)"
3144 .cindex "pid (process id)" "of daemon"
3145 If &%log_file_path%& or &%pid_file_path%& are given, the names of the
3146 directories where log files and daemon pid files are written are output,
3147 respectively. If these values are unset, log files are written in a
3148 sub-directory of the spool directory called &%log%&, and the pid file is
3149 written directly into the spool directory.
3150
3151 If &%-bP%& is followed by a name preceded by &`+`&, for example,
3152 .code
3153 exim -bP +local_domains
3154 .endd
3155 it searches for a matching named list of any type (domain, host, address, or
3156 local part) and outputs what it finds.
3157
3158 .cindex "options" "router &-- extracting"
3159 .cindex "options" "transport &-- extracting"
3160 .cindex "options" "authenticator &-- extracting"
3161 If one of the words &%router%&, &%transport%&, or &%authenticator%& is given,
3162 followed by the name of an appropriate driver instance, the option settings for
3163 that driver are output. For example:
3164 .code
3165 exim -bP transport local_delivery
3166 .endd
3167 The generic driver options are output first, followed by the driver's private
3168 options. A list of the names of drivers of a particular type can be obtained by
3169 using one of the words &%router_list%&, &%transport_list%&, or
3170 &%authenticator_list%&, and a complete list of all drivers with their option
3171 settings can be obtained by using &%routers%&, &%transports%&, or
3172 &%authenticators%&.
3173
3174 .cindex "environment"
3175 If &%environment%& is given as an argument, the set of environment
3176 variables is output, line by line. Using the &%-n%& flag suppresses the value of the
3177 variables.
3178
3179 .cindex "options" "macro &-- extracting"
3180 If invoked by an admin user, then &%macro%&, &%macro_list%& and &%macros%&
3181 are available, similarly to the drivers.  Because macros are sometimes used
3182 for storing passwords, this option is restricted.
3183 The output format is one item per line.
3184 For the "-bP macro <name>" form, if no such macro is found
3185 the exit status will be nonzero.
3186
3187 .vitem &%-bp%&
3188 .oindex "&%-bp%&"
3189 .cindex "queue" "listing messages on"
3190 .cindex "listing" "messages on the queue"
3191 This option requests a listing of the contents of the mail queue on the
3192 standard output. If the &%-bp%& option is followed by a list of message ids,
3193 just those messages are listed. By default, this option can be used only by an
3194 admin user. However, the &%queue_list_requires_admin%& option can be set false
3195 to allow any user to see the queue.
3196
3197 Each message on the queue is displayed as in the following example:
3198 .code
3199 25m  2.9K 0t5C6f-0000c8-00 <alice@wonderland.fict.example>
3200           red.king@looking-glass.fict.example
3201           <other addresses>
3202 .endd
3203 .cindex "message" "size in queue listing"
3204 .cindex "size" "of message"
3205 The first line contains the length of time the message has been on the queue
3206 (in this case 25 minutes), the size of the message (2.9K), the unique local
3207 identifier for the message, and the message sender, as contained in the
3208 envelope. For bounce messages, the sender address is empty, and appears as
3209 &"<>"&. If the message was submitted locally by an untrusted user who overrode
3210 the default sender address, the user's login name is shown in parentheses
3211 before the sender address.
3212
3213 .cindex "frozen messages" "in queue listing"
3214 If the message is frozen (attempts to deliver it are suspended) then the text
3215 &"*** frozen ***"& is displayed at the end of this line.
3216
3217 The recipients of the message (taken from the envelope, not the headers) are
3218 displayed on subsequent lines. Those addresses to which the message has already
3219 been delivered are marked with the letter D. If an original address gets
3220 expanded into several addresses via an alias or forward file, the original is
3221 displayed with a D only when deliveries for all of its child addresses are
3222 complete.
3223
3224
3225 .vitem &%-bpa%&
3226 .oindex "&%-bpa%&"
3227 This option operates like &%-bp%&, but in addition it shows delivered addresses
3228 that were generated from the original top level address(es) in each message by
3229 alias or forwarding operations. These addresses are flagged with &"+D"& instead
3230 of just &"D"&.
3231
3232
3233 .vitem &%-bpc%&
3234 .oindex "&%-bpc%&"
3235 .cindex "queue" "count of messages on"
3236 This option counts the number of messages on the queue, and writes the total
3237 to the standard output. It is restricted to admin users, unless
3238 &%queue_list_requires_admin%& is set false.
3239
3240
3241 .vitem &%-bpr%&
3242 .oindex "&%-bpr%&"
3243 This option operates like &%-bp%&, but the output is not sorted into
3244 chronological order of message arrival. This can speed it up when there are
3245 lots of messages on the queue, and is particularly useful if the output is
3246 going to be post-processed in a way that doesn't need the sorting.
3247
3248 .vitem &%-bpra%&
3249 .oindex "&%-bpra%&"
3250 This option is a combination of &%-bpr%& and &%-bpa%&.
3251
3252 .vitem &%-bpru%&
3253 .oindex "&%-bpru%&"
3254 This option is a combination of &%-bpr%& and &%-bpu%&.
3255
3256
3257 .vitem &%-bpu%&
3258 .oindex "&%-bpu%&"
3259 This option operates like &%-bp%& but shows only undelivered top-level
3260 addresses for each message displayed. Addresses generated by aliasing or
3261 forwarding are not shown, unless the message was deferred after processing by a
3262 router with the &%one_time%& option set.
3263
3264
3265 .vitem &%-brt%&
3266 .oindex "&%-brt%&"
3267 .cindex "testing" "retry configuration"
3268 .cindex "retry" "configuration testing"
3269 This option is for testing retry rules, and it must be followed by up to three
3270 arguments. It causes Exim to look for a retry rule that matches the values
3271 and to write it to the standard output. For example:
3272 .code
3273 exim -brt bach.comp.mus.example
3274 Retry rule: *.comp.mus.example  F,2h,15m; F,4d,30m;
3275 .endd
3276 See chapter &<<CHAPretry>>& for a description of Exim's retry rules. The first
3277 argument, which is required, can be a complete address in the form
3278 &'local_part@domain'&, or it can be just a domain name. If the second argument
3279 contains a dot, it is interpreted as an optional second domain name; if no
3280 retry rule is found for the first argument, the second is tried. This ties in
3281 with Exim's behaviour when looking for retry rules for remote hosts &-- if no
3282 rule is found that matches the host, one that matches the mail domain is
3283 sought. Finally, an argument that is the name of a specific delivery error, as
3284 used in setting up retry rules, can be given. For example:
3285 .code
3286 exim -brt haydn.comp.mus.example quota_3d
3287 Retry rule: *@haydn.comp.mus.example quota_3d  F,1h,15m
3288 .endd
3289
3290 .vitem &%-brw%&
3291 .oindex "&%-brw%&"
3292 .cindex "testing" "rewriting"
3293 .cindex "rewriting" "testing"
3294 This option is for testing address rewriting rules, and it must be followed by
3295 a single argument, consisting of either a local part without a domain, or a
3296 complete address with a fully qualified domain. Exim outputs how this address
3297 would be rewritten for each possible place it might appear. See chapter
3298 &<<CHAPrewrite>>& for further details.
3299
3300 .vitem &%-bS%&
3301 .oindex "&%-bS%&"
3302 .cindex "SMTP" "batched incoming"
3303 .cindex "batched SMTP input"
3304 This option is used for batched SMTP input, which is an alternative interface
3305 for non-interactive local message submission. A number of messages can be
3306 submitted in a single run. However, despite its name, this is not really SMTP
3307 input. Exim reads each message's envelope from SMTP commands on the standard
3308 input, but generates no responses. If the caller is trusted, or
3309 &%untrusted_set_sender%& is set, the senders in the SMTP MAIL commands are
3310 believed; otherwise the sender is always the caller of Exim.
3311
3312 The message itself is read from the standard input, in SMTP format (leading
3313 dots doubled), terminated by a line containing just a single dot. An error is
3314 provoked if the terminating dot is missing. A further message may then follow.
3315
3316 As for other local message submissions, the contents of incoming batch SMTP
3317 messages can be checked using the non-SMTP ACL (see chapter &<<CHAPACL>>&).
3318 Unqualified addresses are automatically qualified using &%qualify_domain%& and
3319 &%qualify_recipient%&, as appropriate, unless the &%-bnq%& option is used.
3320
3321 Some other SMTP commands are recognized in the input. HELO and EHLO act
3322 as RSET; VRFY, EXPN, ETRN, and HELP act as NOOP;
3323 QUIT quits, ignoring the rest of the standard input.
3324
3325 .cindex "return code" "for &%-bS%&"
3326 If any error is encountered, reports are written to the standard output and
3327 error streams, and Exim gives up immediately. The return code is 0 if no error
3328 was detected; it is 1 if one or more messages were accepted before the error
3329 was detected; otherwise it is 2.
3330
3331 More details of input using batched SMTP are given in section
3332 &<<SECTincomingbatchedSMTP>>&.
3333
3334 .vitem &%-bs%&
3335 .oindex "&%-bs%&"
3336 .cindex "SMTP" "local input"
3337 .cindex "local SMTP input"
3338 This option causes Exim to accept one or more messages by reading SMTP commands
3339 on the standard input, and producing SMTP replies on the standard output. SMTP
3340 policy controls, as defined in ACLs (see chapter &<<CHAPACL>>&) are applied.
3341 Some user agents use this interface as a way of passing locally-generated
3342 messages to the MTA.
3343
3344 In
3345 .cindex "sender" "source of"
3346 this usage, if the caller of Exim is trusted, or &%untrusted_set_sender%& is
3347 set, the senders of messages are taken from the SMTP MAIL commands.
3348 Otherwise the content of these commands is ignored and the sender is set up as
3349 the calling user. Unqualified addresses are automatically qualified using
3350 &%qualify_domain%& and &%qualify_recipient%&, as appropriate, unless the
3351 &%-bnq%& option is used.
3352
3353 .cindex "inetd"
3354 The
3355 &%-bs%& option is also used to run Exim from &'inetd'&, as an alternative to
3356 using a listening daemon. Exim can distinguish the two cases by checking
3357 whether the standard input is a TCP/IP socket. When Exim is called from
3358 &'inetd'&, the source of the mail is assumed to be remote, and the comments
3359 above concerning senders and qualification do not apply. In this situation,
3360 Exim behaves in exactly the same way as it does when receiving a message via
3361 the listening daemon.
3362
3363 .vitem &%-bt%&
3364 .oindex "&%-bt%&"
3365 .cindex "testing" "addresses"
3366 .cindex "address" "testing"
3367 This option runs Exim in address testing mode, in which each argument is taken
3368 as a recipient address to be tested for deliverability. The results are
3369 written to the standard output. If a test fails, and the caller is not an admin
3370 user, no details of the failure are output, because these might contain
3371 sensitive information such as usernames and passwords for database lookups.
3372
3373 If no arguments are given, Exim runs in an interactive manner, prompting with a
3374 right angle bracket for addresses to be tested.
3375
3376 Unlike the &%-be%& test option, you cannot arrange for Exim to use the
3377 &[readline()]& function, because it is running as &'root'& and there are
3378 security issues.
3379
3380 Each address is handled as if it were the recipient address of a message
3381 (compare the &%-bv%& option). It is passed to the routers and the result is
3382 written to the standard output. However, any router that has
3383 &%no_address_test%& set is bypassed. This can make &%-bt%& easier to use for
3384 genuine routing tests if your first router passes everything to a scanner
3385 program.
3386
3387 .cindex "return code" "for &%-bt%&"
3388 The return code is 2 if any address failed outright; it is 1 if no address
3389 failed outright but at least one could not be resolved for some reason. Return
3390 code 0 is given only when all addresses succeed.
3391
3392 .cindex "duplicate addresses"
3393 &*Note*&: When actually delivering a message, Exim removes duplicate recipient
3394 addresses after routing is complete, so that only one delivery takes place.
3395 This does not happen when testing with &%-bt%&; the full results of routing are
3396 always shown.
3397
3398 &*Warning*&: &%-bt%& can only do relatively simple testing. If any of the
3399 routers in the configuration makes any tests on the sender address of a
3400 message,
3401 .oindex "&%-f%&" "for address testing"
3402 you can use the &%-f%& option to set an appropriate sender when running
3403 &%-bt%& tests. Without it, the sender is assumed to be the calling user at the
3404 default qualifying domain. However, if you have set up (for example) routers
3405 whose behaviour depends on the contents of an incoming message, you cannot test
3406 those conditions using &%-bt%&. The &%-N%& option provides a possible way of
3407 doing such tests.
3408
3409 .vitem &%-bV%&
3410 .oindex "&%-bV%&"
3411 .cindex "version number of Exim"
3412 This option causes Exim to write the current version number, compilation
3413 number, and compilation date of the &'exim'& binary to the standard output.
3414 It also lists the DBM library that is being used, the optional modules (such as
3415 specific lookup types), the drivers that are included in the binary, and the
3416 name of the run time configuration file that is in use.
3417
3418 As part of its operation, &%-bV%& causes Exim to read and syntax check its
3419 configuration file. However, this is a static check only. It cannot check
3420 values that are to be expanded. For example, although a misspelt ACL verb is
3421 detected, an error in the verb's arguments is not. You cannot rely on &%-bV%&
3422 alone to discover (for example) all the typos in the configuration; some
3423 realistic testing is needed. The &%-bh%& and &%-N%& options provide more
3424 dynamic testing facilities.
3425
3426 .vitem &%-bv%&
3427 .oindex "&%-bv%&"
3428 .cindex "verifying address" "using &%-bv%&"
3429 .cindex "address" "verification"
3430 This option runs Exim in address verification mode, in which each argument is
3431 taken as a recipient address to be verified by the routers. (This does
3432 not involve any verification callouts). During normal operation, verification
3433 happens mostly as a consequence processing a &%verify%& condition in an ACL
3434 (see chapter &<<CHAPACL>>&). If you want to test an entire ACL, possibly
3435 including callouts, see the &%-bh%& and &%-bhc%& options.
3436
3437 If verification fails, and the caller is not an admin user, no details of the
3438 failure are output, because these might contain sensitive information such as
3439 usernames and passwords for database lookups.
3440
3441 If no arguments are given, Exim runs in an interactive manner, prompting with a
3442 right angle bracket for addresses to be verified.
3443
3444 Unlike the &%-be%& test option, you cannot arrange for Exim to use the
3445 &[readline()]& function, because it is running as &'exim'& and there are
3446 security issues.
3447
3448 Verification differs from address testing (the &%-bt%& option) in that routers
3449 that have &%no_verify%& set are skipped, and if the address is accepted by a
3450 router that has &%fail_verify%& set, verification fails. The address is
3451 verified as a recipient if &%-bv%& is used; to test verification for a sender
3452 address, &%-bvs%& should be used.
3453
3454 If the &%-v%& option is not set, the output consists of a single line for each
3455 address, stating whether it was verified or not, and giving a reason in the
3456 latter case. Without &%-v%&, generating more than one address by redirection
3457 causes verification to end successfully, without considering the generated
3458 addresses. However, if just one address is generated, processing continues,
3459 and the generated address must verify successfully for the overall verification
3460 to succeed.
3461
3462 When &%-v%& is set, more details are given of how the address has been handled,
3463 and in the case of address redirection, all the generated addresses are also
3464 considered. Verification may succeed for some and fail for others.
3465
3466 The
3467 .cindex "return code" "for &%-bv%&"
3468 return code is 2 if any address failed outright; it is 1 if no address
3469 failed outright but at least one could not be resolved for some reason. Return
3470 code 0 is given only when all addresses succeed.
3471
3472 If any of the routers in the configuration makes any tests on the sender
3473 address of a message, you should use the &%-f%& option to set an appropriate
3474 sender when running &%-bv%& tests. Without it, the sender is assumed to be the
3475 calling user at the default qualifying domain.
3476
3477 .vitem &%-bvs%&
3478 .oindex "&%-bvs%&"
3479 This option acts like &%-bv%&, but verifies the address as a sender rather
3480 than a recipient address. This affects any rewriting and qualification that
3481 might happen.
3482
3483 .vitem &%-bw%&
3484 .oindex "&%-bw%&"
3485 .cindex "daemon"
3486 .cindex "inetd"
3487 .cindex "inetd" "wait mode"
3488 This option runs Exim as a daemon, awaiting incoming SMTP connections,
3489 similarly to the &%-bd%& option.  All port specifications on the command-line
3490 and in the configuration file are ignored.  Queue-running may not be specified.
3491
3492 In this mode, Exim expects to be passed a socket as fd 0 (stdin) which is
3493 listening for connections.  This permits the system to start up and have
3494 inetd (or equivalent) listen on the SMTP ports, starting an Exim daemon for
3495 each port only when the first connection is received.
3496
3497 If the option is given as &%-bw%&<&'time'&> then the time is a timeout, after
3498 which the daemon will exit, which should cause inetd to listen once more.
3499
3500 .vitem &%-C%&&~<&'filelist'&>
3501 .oindex "&%-C%&"
3502 .cindex "configuration file" "alternate"
3503 .cindex "CONFIGURE_FILE"
3504 .cindex "alternate configuration file"
3505 This option causes Exim to find the run time configuration file from the given
3506 list instead of from the list specified by the CONFIGURE_FILE
3507 compile-time setting. Usually, the list will consist of just a single file
3508 name, but it can be a colon-separated list of names. In this case, the first
3509 file that exists is used. Failure to open an existing file stops Exim from
3510 proceeding any further along the list, and an error is generated.
3511
3512 When this option is used by a caller other than root, and the list is different
3513 from the compiled-in list, Exim gives up its root privilege immediately, and
3514 runs with the real and effective uid and gid set to those of the caller.
3515 However, if a TRUSTED_CONFIG_LIST file is defined in &_Local/Makefile_&, that
3516 file contains a list of full pathnames, one per line, for configuration files
3517 which are trusted. Root privilege is retained for any configuration file so
3518 listed, as long as the caller is the Exim user (or the user specified in the
3519 CONFIGURE_OWNER option, if any), and as long as the configuration file is
3520 not writeable by inappropriate users or groups.
3521
3522 Leaving TRUSTED_CONFIG_LIST unset precludes the possibility of testing a
3523 configuration using &%-C%& right through message reception and delivery,
3524 even if the caller is root. The reception works, but by that time, Exim is
3525 running as the Exim user, so when it re-executes to regain privilege for the
3526 delivery, the use of &%-C%& causes privilege to be lost. However, root can
3527 test reception and delivery using two separate commands (one to put a message
3528 on the queue, using &%-odq%&, and another to do the delivery, using &%-M%&).
3529
3530 If ALT_CONFIG_PREFIX is defined &_in Local/Makefile_&, it specifies a
3531 prefix string with which any file named in a &%-C%& command line option
3532 must start. In addition, the file name must not contain the sequence &`/../`&.
3533 However, if the value of the &%-C%& option is identical to the value of
3534 CONFIGURE_FILE in &_Local/Makefile_&, Exim ignores &%-C%& and proceeds as
3535 usual. There is no default setting for ALT_CONFIG_PREFIX; when it is
3536 unset, any file name can be used with &%-C%&.
3537
3538 ALT_CONFIG_PREFIX can be used to confine alternative configuration files
3539 to a directory to which only root has access. This prevents someone who has
3540 broken into the Exim account from running a privileged Exim with an arbitrary
3541 configuration file.
3542
3543 The &%-C%& facility is useful for ensuring that configuration files are
3544 syntactically correct, but cannot be used for test deliveries, unless the
3545 caller is privileged, or unless it is an exotic configuration that does not
3546 require privilege. No check is made on the owner or group of the files
3547 specified by this option.
3548
3549
3550 .vitem &%-D%&<&'macro'&>=<&'value'&>
3551 .oindex "&%-D%&"
3552 .cindex "macro" "setting on command line"
3553 This option can be used to override macro definitions in the configuration file
3554 (see section &<<SECTmacrodefs>>&). However, like &%-C%&, if it is used by an
3555 unprivileged caller, it causes Exim to give up its root privilege.
3556 If DISABLE_D_OPTION is defined in &_Local/Makefile_&, the use of &%-D%& is
3557 completely disabled, and its use causes an immediate error exit.
3558
3559 If WHITELIST_D_MACROS is defined in &_Local/Makefile_& then it should be a
3560 colon-separated list of macros which are considered safe and, if &%-D%& only
3561 supplies macros from this list, and the values are acceptable, then Exim will
3562 not give up root privilege if the caller is root, the Exim run-time user, or
3563 the CONFIGURE_OWNER, if set.  This is a transition mechanism and is expected
3564 to be removed in the future.  Acceptable values for the macros satisfy the
3565 regexp: &`^[A-Za-z0-9_/.-]*$`&
3566
3567 The entire option (including equals sign if present) must all be within one
3568 command line item. &%-D%& can be used to set the value of a macro to the empty
3569 string, in which case the equals sign is optional. These two commands are
3570 synonymous:
3571 .code
3572 exim -DABC  ...
3573 exim -DABC= ...
3574 .endd
3575 To include spaces in a macro definition item, quotes must be used. If you use
3576 quotes, spaces are permitted around the macro name and the equals sign. For
3577 example:
3578 .code
3579 exim '-D ABC = something' ...
3580 .endd
3581 &%-D%& may be repeated up to 10 times on a command line.
3582 Only macro names up to 22 letters long can be set.
3583
3584
3585 .vitem &%-d%&<&'debug&~options'&>
3586 .oindex "&%-d%&"
3587 .cindex "debugging" "list of selectors"
3588 .cindex "debugging" "&%-d%& option"
3589 This option causes debugging information to be written to the standard
3590 error stream. It is restricted to admin users because debugging output may show
3591 database queries that contain password information. Also, the details of users'
3592 filter files should be protected. If a non-admin user uses &%-d%&, Exim
3593 writes an error message to the standard error stream and exits with a non-zero
3594 return code.
3595
3596 When &%-d%& is used, &%-v%& is assumed. If &%-d%& is given on its own, a lot of
3597 standard debugging data is output. This can be reduced, or increased to include
3598 some more rarely needed information, by directly following &%-d%& with a string
3599 made up of names preceded by plus or minus characters. These add or remove sets
3600 of debugging data, respectively. For example, &%-d+filter%& adds filter
3601 debugging, whereas &%-d-all+filter%& selects only filter debugging. Note that
3602 no spaces are allowed in the debug setting. The available debugging categories
3603 are:
3604 .display
3605 &`acl            `& ACL interpretation
3606 &`auth           `& authenticators
3607 &`deliver        `& general delivery logic
3608 &`dns            `& DNS lookups (see also resolver)
3609 &`dnsbl          `& DNS black list (aka RBL) code
3610 &`exec           `& arguments for &[execv()]& calls
3611 &`expand         `& detailed debugging for string expansions
3612 &`filter         `& filter handling
3613 &`hints_lookup   `& hints data lookups
3614 &`host_lookup    `& all types of name-to-IP address handling
3615 &`ident          `& ident lookup
3616 &`interface      `& lists of local interfaces
3617 &`lists          `& matching things in lists
3618 &`load           `& system load checks
3619 &`local_scan     `& can be used by &[local_scan()]& (see chapter &&&
3620                     &<<CHAPlocalscan>>&)
3621 &`lookup         `& general lookup code and all lookups
3622 &`memory         `& memory handling
3623 &`noutf8         `& modifier: avoid UTF-8 line-drawing
3624 &`pid            `& modifier: add pid to debug output lines
3625 &`process_info   `& setting info for the process log
3626 &`queue_run      `& queue runs
3627 &`receive        `& general message reception logic
3628 &`resolver       `& turn on the DNS resolver's debugging output
3629 &`retry          `& retry handling
3630 &`rewrite        `& address rewriting
3631 &`route          `& address routing
3632 &`timestamp      `& modifier: add timestamp to debug output lines
3633 &`tls            `& TLS logic
3634 &`transport      `& transports
3635 &`uid            `& changes of uid/gid and looking up uid/gid
3636 &`verify         `& address verification logic
3637 &`all            `& almost all of the above (see below), and also &%-v%&
3638 .endd
3639 The &`all`& option excludes &`memory`& when used as &`+all`&, but includes it
3640 for &`-all`&. The reason for this is that &`+all`& is something that people
3641 tend to use when generating debug output for Exim maintainers. If &`+memory`&
3642 is included, an awful lot of output that is very rarely of interest is
3643 generated, so it now has to be explicitly requested. However, &`-all`& does
3644 turn everything off.
3645
3646 .cindex "resolver, debugging output"
3647 .cindex "DNS resolver, debugging output"
3648 The &`resolver`& option produces output only if the DNS resolver was compiled
3649 with DEBUG enabled. This is not the case in some operating systems. Also,
3650 unfortunately, debugging output from the DNS resolver is written to stdout
3651 rather than stderr.
3652
3653 The default (&%-d%& with no argument) omits &`expand`&, &`filter`&,
3654 &`interface`&, &`load`&, &`memory`&, &`pid`&, &`resolver`&, and &`timestamp`&.
3655 However, the &`pid`& selector is forced when debugging is turned on for a
3656 daemon, which then passes it on to any re-executed Exims. Exim also
3657 automatically adds the pid to debug lines when several remote deliveries are
3658 run in parallel.
3659
3660 The &`timestamp`& selector causes the current time to be inserted at the start
3661 of all debug output lines. This can be useful when trying to track down delays
3662 in processing.
3663
3664 .new
3665 .cindex debugging "UTF-8 in"
3666 .cindex UTF-8 "in debug output"
3667 The &`noutf8`& selector disables the use of
3668 UTF-8 line-drawing characters to group related information.
3669 When disabled. ascii-art is used instead.
3670 Using the &`+all`& option does not set this modifier,
3671 .wen
3672
3673 If the &%debug_print%& option is set in any driver, it produces output whenever
3674 any debugging is selected, or if &%-v%& is used.
3675
3676 .vitem &%-dd%&<&'debug&~options'&>
3677 .oindex "&%-dd%&"
3678 This option behaves exactly like &%-d%& except when used on a command that
3679 starts a daemon process. In that case, debugging is turned off for the
3680 subprocesses that the daemon creates. Thus, it is useful for monitoring the
3681 behaviour of the daemon without creating as much output as full debugging does.
3682
3683 .vitem &%-dropcr%&
3684 .oindex "&%-dropcr%&"
3685 This is an obsolete option that is now a no-op. It used to affect the way Exim
3686 handled CR and LF characters in incoming messages. What happens now is
3687 described in section &<<SECTlineendings>>&.
3688
3689 .vitem &%-E%&
3690 .oindex "&%-E%&"
3691 .cindex "bounce message" "generating"
3692 This option specifies that an incoming message is a locally-generated delivery
3693 failure report. It is used internally by Exim when handling delivery failures
3694 and is not intended for external use. Its only effect is to stop Exim
3695 generating certain messages to the postmaster, as otherwise message cascades
3696 could occur in some situations. As part of the same option, a message id may
3697 follow the characters &%-E%&. If it does, the log entry for the receipt of the
3698 new message contains the id, following &"R="&, as a cross-reference.
3699
3700 .vitem &%-e%&&'x'&
3701 .oindex "&%-e%&&'x'&"
3702 There are a number of Sendmail options starting with &%-oe%& which seem to be
3703 called by various programs without the leading &%o%& in the option. For
3704 example, the &%vacation%& program uses &%-eq%&. Exim treats all options of the
3705 form &%-e%&&'x'& as synonymous with the corresponding &%-oe%&&'x'& options.
3706
3707 .vitem &%-F%&&~<&'string'&>
3708 .oindex "&%-F%&"
3709 .cindex "sender" "name"
3710 .cindex "name" "of sender"
3711 This option sets the sender's full name for use when a locally-generated
3712 message is being accepted. In the absence of this option, the user's &'gecos'&
3713 entry from the password data is used. As users are generally permitted to alter
3714 their &'gecos'& entries, no security considerations are involved. White space
3715 between &%-F%& and the <&'string'&> is optional.
3716
3717 .vitem &%-f%&&~<&'address'&>
3718 .oindex "&%-f%&"
3719 .cindex "sender" "address"
3720 .cindex "address" "sender"
3721 .cindex "trusted users"
3722 .cindex "envelope sender"
3723 .cindex "user" "trusted"
3724 This option sets the address of the envelope sender of a locally-generated
3725 message (also known as the return path). The option can normally be used only
3726 by a trusted user, but &%untrusted_set_sender%& can be set to allow untrusted
3727 users to use it.
3728
3729 Processes running as root or the Exim user are always trusted. Other
3730 trusted users are defined by the &%trusted_users%& or &%trusted_groups%&
3731 options. In the absence of &%-f%&, or if the caller is not trusted, the sender
3732 of a local message is set to the caller's login name at the default qualify
3733 domain.
3734
3735 There is one exception to the restriction on the use of &%-f%&: an empty sender
3736 can be specified by any user, trusted or not, to create a message that can
3737 never provoke a bounce. An empty sender can be specified either as an empty
3738 string, or as a pair of angle brackets with nothing between them, as in these
3739 examples of shell commands:
3740 .code
3741 exim -f '<>' user@domain
3742 exim -f "" user@domain
3743 .endd
3744 In addition, the use of &%-f%& is not restricted when testing a filter file
3745 with &%-bf%& or when testing or verifying addresses using the &%-bt%& or
3746 &%-bv%& options.
3747
3748 Allowing untrusted users to change the sender address does not of itself make
3749 it possible to send anonymous mail. Exim still checks that the &'From:'& header
3750 refers to the local user, and if it does not, it adds a &'Sender:'& header,
3751 though this can be overridden by setting &%no_local_from_check%&.
3752
3753 White
3754 .cindex "&""From""& line"
3755 space between &%-f%& and the <&'address'&> is optional (that is, they can be
3756 given as two arguments or one combined argument). The sender of a
3757 locally-generated message can also be set (when permitted) by an initial
3758 &"From&~"& line in the message &-- see the description of &%-bm%& above &-- but
3759 if &%-f%& is also present, it overrides &"From&~"&.
3760
3761 .vitem &%-G%&
3762 .oindex "&%-G%&"
3763 .cindex "submission fixups, suppressing (command-line)"
3764 This option is equivalent to an ACL applying:
3765 .code
3766 control = suppress_local_fixups
3767 .endd
3768 for every message received.  Note that Sendmail will complain about such
3769 bad formatting, where Exim silently just does not fix it up.  This may change
3770 in future.
3771
3772 As this affects audit information, the caller must be a trusted user to use
3773 this option.
3774
3775 .vitem &%-h%&&~<&'number'&>
3776 .oindex "&%-h%&"
3777 .cindex "Sendmail compatibility" "&%-h%& option ignored"
3778 This option is accepted for compatibility with Sendmail, but has no effect. (In
3779 Sendmail it overrides the &"hop count"& obtained by counting &'Received:'&
3780 headers.)
3781
3782 .vitem &%-i%&
3783 .oindex "&%-i%&"
3784 .cindex "Solaris" "&'mail'& command"
3785 .cindex "dot" "in incoming non-SMTP message"
3786 This option, which has the same effect as &%-oi%&, specifies that a dot on a
3787 line by itself should not terminate an incoming, non-SMTP message. I can find
3788 no documentation for this option in Solaris 2.4 Sendmail, but the &'mailx'&
3789 command in Solaris 2.4 uses it. See also &%-ti%&.
3790
3791 .vitem &%-L%&&~<&'tag'&>
3792 .oindex "&%-L%&"
3793 .cindex "syslog" "process name; set with flag"
3794 This option is equivalent to setting &%syslog_processname%& in the config
3795 file and setting &%log_file_path%& to &`syslog`&.
3796 Its use is restricted to administrators.  The configuration file has to be
3797 read and parsed, to determine access rights, before this is set and takes
3798 effect, so early configuration file errors will not honour this flag.
3799
3800 The tag should not be longer than 32 characters.
3801
3802 .vitem &%-M%&&~<&'message&~id'&>&~<&'message&~id'&>&~...
3803 .oindex "&%-M%&"
3804 .cindex "forcing delivery"
3805 .cindex "delivery" "forcing attempt"
3806 .cindex "frozen messages" "forcing delivery"
3807 This option requests Exim to run a delivery attempt on each message in turn. If
3808 any of the messages are frozen, they are automatically thawed before the
3809 delivery attempt. The settings of &%queue_domains%&, &%queue_smtp_domains%&,
3810 and &%hold_domains%& are ignored.
3811
3812 Retry
3813 .cindex "hints database" "overriding retry hints"
3814 hints for any of the addresses are overridden &-- Exim tries to deliver even if
3815 the normal retry time has not yet been reached. This option requires the caller
3816 to be an admin user. However, there is an option called &%prod_requires_admin%&
3817 which can be set false to relax this restriction (and also the same requirement
3818 for the &%-q%&, &%-R%&, and &%-S%& options).
3819
3820 The deliveries happen synchronously, that is, the original Exim process does
3821 not terminate until all the delivery attempts have finished. No output is
3822 produced unless there is a serious error. If you want to see what is happening,
3823 use the &%-v%& option as well, or inspect Exim's main log.
3824
3825 .vitem &%-Mar%&&~<&'message&~id'&>&~<&'address'&>&~<&'address'&>&~...
3826 .oindex "&%-Mar%&"
3827 .cindex "message" "adding recipients"
3828 .cindex "recipient" "adding"
3829 This option requests Exim to add the addresses to the list of recipients of the
3830 message (&"ar"& for &"add recipients"&). The first argument must be a message
3831 id, and the remaining ones must be email addresses. However, if the message is
3832 active (in the middle of a delivery attempt), it is not altered. This option
3833 can be used only by an admin user.
3834
3835 .vitem "&%-MC%&&~<&'transport'&>&~<&'hostname'&>&~<&'sequence&~number'&>&&&
3836         &~<&'message&~id'&>"
3837 .oindex "&%-MC%&"
3838 .cindex "SMTP" "passed connection"
3839 .cindex "SMTP" "multiple deliveries"
3840 .cindex "multiple SMTP deliveries"
3841 This option is not intended for use by external callers. It is used internally
3842 by Exim to invoke another instance of itself to deliver a waiting message using
3843 an existing SMTP connection, which is passed as the standard input. Details are
3844 given in chapter &<<CHAPSMTP>>&. This must be the final option, and the caller
3845 must be root or the Exim user in order to use it.
3846
3847 .vitem &%-MCA%&
3848 .oindex "&%-MCA%&"
3849 This option is not intended for use by external callers. It is used internally
3850 by Exim in conjunction with the &%-MC%& option. It signifies that the
3851 connection to the remote host has been authenticated.
3852
3853 .vitem &%-MCD%&
3854 .oindex "&%-MCD%&"
3855 This option is not intended for use by external callers. It is used internally
3856 by Exim in conjunction with the &%-MC%& option. It signifies that the
3857 remote host supports the ESMTP &_DSN_& extension.
3858
3859 .vitem &%-MCG%&&~<&'queue&~name'&>
3860 .oindex "&%-MCG%&"
3861 This option is not intended for use by external callers. It is used internally
3862 by Exim in conjunction with the &%-MC%& option. It signifies that an
3863 alternate queue is used, named by the following argument.
3864
3865 .vitem &%-MCK%&
3866 .oindex "&%-MCK%&"
3867 This option is not intended for use by external callers. It is used internally
3868 by Exim in conjunction with the &%-MC%& option. It signifies that a
3869 remote host supports the ESMTP &_CHUNKING_& extension.
3870
3871 .vitem &%-MCP%&
3872 .oindex "&%-MCP%&"
3873 This option is not intended for use by external callers. It is used internally
3874 by Exim in conjunction with the &%-MC%& option. It signifies that the server to
3875 which Exim is connected supports pipelining.
3876
3877 .vitem &%-MCQ%&&~<&'process&~id'&>&~<&'pipe&~fd'&>
3878 .oindex "&%-MCQ%&"
3879 This option is not intended for use by external callers. It is used internally
3880 by Exim in conjunction with the &%-MC%& option when the original delivery was
3881 started by a queue runner. It passes on the process id of the queue runner,
3882 together with the file descriptor number of an open pipe. Closure of the pipe
3883 signals the final completion of the sequence of processes that are passing
3884 messages through the same SMTP connection.
3885
3886 .vitem &%-MCS%&
3887 .oindex "&%-MCS%&"
3888 This option is not intended for use by external callers. It is used internally
3889 by Exim in conjunction with the &%-MC%& option, and passes on the fact that the
3890 SMTP SIZE option should be used on messages delivered down the existing
3891 connection.
3892
3893 .vitem &%-MCT%&
3894 .oindex "&%-MCT%&"
3895 This option is not intended for use by external callers. It is used internally
3896 by Exim in conjunction with the &%-MC%& option, and passes on the fact that the
3897 host to which Exim is connected supports TLS encryption.
3898
3899 .vitem &%-MCt%&&~<&'IP&~address'&>&~<&'port'&>&~<&'cipher'&>
3900 .oindex "&%-MCt%&"
3901 This option is not intended for use by external callers. It is used internally
3902 by Exim in conjunction with the &%-MC%& option, and passes on the fact that the
3903 connection is being proxied by a parent process for handling TLS encryption.
3904 The arguments give the local address and port being proxied, and the TLS cipher.
3905
3906 .vitem &%-Mc%&&~<&'message&~id'&>&~<&'message&~id'&>&~...
3907 .oindex "&%-Mc%&"
3908 .cindex "hints database" "not overridden by &%-Mc%&"
3909 .cindex "delivery" "manually started &-- not forced"
3910 This option requests Exim to run a delivery attempt on each message in turn,
3911 but unlike the &%-M%& option, it does check for retry hints, and respects any
3912 that are found. This option is not very useful to external callers. It is
3913 provided mainly for internal use by Exim when it needs to re-invoke itself in
3914 order to regain root privilege for a delivery (see chapter &<<CHAPsecurity>>&).
3915 However, &%-Mc%& can be useful when testing, in order to run a delivery that
3916 respects retry times and other options such as &%hold_domains%& that are
3917 overridden when &%-M%& is used. Such a delivery does not count as a queue run.
3918 If you want to run a specific delivery as if in a queue run, you should use
3919 &%-q%& with a message id argument. A distinction between queue run deliveries
3920 and other deliveries is made in one or two places.
3921
3922 .vitem &%-Mes%&&~<&'message&~id'&>&~<&'address'&>
3923 .oindex "&%-Mes%&"
3924 .cindex "message" "changing sender"
3925 .cindex "sender" "changing"
3926 This option requests Exim to change the sender address in the message to the
3927 given address, which must be a fully qualified address or &"<>"& (&"es"& for
3928 &"edit sender"&). There must be exactly two arguments. The first argument must
3929 be a message id, and the second one an email address. However, if the message
3930 is active (in the middle of a delivery attempt), its status is not altered.
3931 This option can be used only by an admin user.
3932
3933 .vitem &%-Mf%&&~<&'message&~id'&>&~<&'message&~id'&>&~...
3934 .oindex "&%-Mf%&"
3935 .cindex "freezing messages"
3936 .cindex "message" "manually freezing"
3937 This option requests Exim to mark each listed message as &"frozen"&. This
3938 prevents any delivery attempts taking place until the message is &"thawed"&,
3939 either manually or as a result of the &%auto_thaw%& configuration option.
3940 However, if any of the messages are active (in the middle of a delivery
3941 attempt), their status is not altered. This option can be used only by an admin
3942 user.
3943
3944 .vitem &%-Mg%&&~<&'message&~id'&>&~<&'message&~id'&>&~...
3945 .oindex "&%-Mg%&"
3946 .cindex "giving up on messages"
3947 .cindex "message" "abandoning delivery attempts"
3948 .cindex "delivery" "abandoning further attempts"
3949 This option requests Exim to give up trying to deliver the listed messages,
3950 including any that are frozen. However, if any of the messages are active,
3951 their status is not altered. For non-bounce messages, a delivery error message
3952 is sent to the sender, containing the text &"cancelled by administrator"&.
3953 Bounce messages are just discarded. This option can be used only by an admin
3954 user.
3955
3956 .vitem &%-Mmad%&&~<&'message&~id'&>&~<&'message&~id'&>&~...
3957 .oindex "&%-Mmad%&"
3958 .cindex "delivery" "cancelling all"
3959 This option requests Exim to mark all the recipient addresses in the messages
3960 as already delivered (&"mad"& for &"mark all delivered"&). However, if any
3961 message is active (in the middle of a delivery attempt), its status is not
3962 altered. This option can be used only by an admin user.
3963
3964 .vitem &%-Mmd%&&~<&'message&~id'&>&~<&'address'&>&~<&'address'&>&~...
3965 .oindex "&%-Mmd%&"
3966 .cindex "delivery" "cancelling by address"
3967 .cindex "recipient" "removing"
3968 .cindex "removing recipients"
3969 This option requests Exim to mark the given addresses as already delivered
3970 (&"md"& for &"mark delivered"&). The first argument must be a message id, and
3971 the remaining ones must be email addresses. These are matched to recipient
3972 addresses in the message in a case-sensitive manner. If the message is active
3973 (in the middle of a delivery attempt), its status is not altered. This option
3974 can be used only by an admin user.
3975
3976 .vitem &%-Mrm%&&~<&'message&~id'&>&~<&'message&~id'&>&~...
3977 .oindex "&%-Mrm%&"
3978 .cindex "removing messages"
3979 .cindex "abandoning mail"
3980 .cindex "message" "manually discarding"
3981 This option requests Exim to remove the given messages from the queue. No
3982 bounce messages are sent; each message is simply forgotten. However, if any of
3983 the messages are active, their status is not altered. This option can be used
3984 only by an admin user or by the user who originally caused the message to be
3985 placed on the queue.
3986
3987 . .new
3988 . .vitem &%-MS%&
3989 . .oindex "&%-MS%&"
3990 . .cindex REQUIRETLS
3991 . This option is used to request REQUIRETLS processing on the message.
3992 . It is used internally by Exim in conjunction with -E when generating
3993 . a bounce message.
3994 . .wen
3995
3996 .vitem &%-Mset%&&~<&'message&~id'&>
3997 .oindex "&%-Mset%&"
3998 .cindex "testing" "string expansion"
3999 .cindex "expansion" "testing"
4000 This option is useful only in conjunction with &%-be%& (that is, when testing
4001 string expansions). Exim loads the given message from its spool before doing
4002 the test expansions, thus setting message-specific variables such as
4003 &$message_size$& and the header variables. The &$recipients$& variable is made
4004 available. This feature is provided to make it easier to test expansions that
4005 make use of these variables. However, this option can be used only by an admin
4006 user. See also &%-bem%&.
4007
4008 .vitem &%-Mt%&&~<&'message&~id'&>&~<&'message&~id'&>&~...
4009 .oindex "&%-Mt%&"
4010 .cindex "thawing messages"
4011 .cindex "unfreezing messages"
4012 .cindex "frozen messages" "thawing"
4013 .cindex "message" "thawing frozen"
4014 This option requests Exim to &"thaw"& any of the listed messages that are
4015 &"frozen"&, so that delivery attempts can resume. However, if any of the
4016 messages are active, their status is not altered. This option can be used only
4017 by an admin user.
4018
4019 .vitem &%-Mvb%&&~<&'message&~id'&>
4020 .oindex "&%-Mvb%&"
4021 .cindex "listing" "message body"
4022 .cindex "message" "listing body of"
4023 This option causes the contents of the message body (-D) spool file to be
4024 written to the standard output. This option can be used only by an admin user.
4025
4026 .vitem &%-Mvc%&&~<&'message&~id'&>
4027 .oindex "&%-Mvc%&"
4028 .cindex "message" "listing in RFC 2822 format"
4029 .cindex "listing" "message in RFC 2822 format"
4030 This option causes a copy of the complete message (header lines plus body) to
4031 be written to the standard output in RFC 2822 format. This option can be used
4032 only by an admin user.
4033
4034 .vitem &%-Mvh%&&~<&'message&~id'&>
4035 .oindex "&%-Mvh%&"
4036 .cindex "listing" "message headers"
4037 .cindex "header lines" "listing"
4038 .cindex "message" "listing header lines"
4039 This option causes the contents of the message headers (-H) spool file to be
4040 written to the standard output. This option can be used only by an admin user.
4041
4042 .vitem &%-Mvl%&&~<&'message&~id'&>
4043 .oindex "&%-Mvl%&"
4044 .cindex "listing" "message log"
4045 .cindex "message" "listing message log"
4046 This option causes the contents of the message log spool file to be written to
4047 the standard output. This option can be used only by an admin user.
4048
4049 .vitem &%-m%&
4050 .oindex "&%-m%&"
4051 This is apparently a synonym for &%-om%& that is accepted by Sendmail, so Exim
4052 treats it that way too.
4053
4054 .vitem &%-N%&
4055 .oindex "&%-N%&"
4056 .cindex "debugging" "&%-N%& option"
4057 .cindex "debugging" "suppressing delivery"
4058 This is a debugging option that inhibits delivery of a message at the transport
4059 level. It implies &%-v%&. Exim goes through many of the motions of delivery &--
4060 it just doesn't actually transport the message, but instead behaves as if it
4061 had successfully done so. However, it does not make any updates to the retry
4062 database, and the log entries for deliveries are flagged with &"*>"& rather
4063 than &"=>"&.
4064
4065 Because &%-N%& discards any message to which it applies, only root or the Exim
4066 user are allowed to use it with &%-bd%&, &%-q%&, &%-R%& or &%-M%&. In other
4067 words, an ordinary user can use it only when supplying an incoming message to
4068 which it will apply. Although transportation never fails when &%-N%& is set, an
4069 address may be deferred because of a configuration problem on a transport, or a
4070 routing problem. Once &%-N%& has been used for a delivery attempt, it sticks to
4071 the message, and applies to any subsequent delivery attempts that may happen
4072 for that message.
4073
4074 .vitem &%-n%&
4075 .oindex "&%-n%&"
4076 This option is interpreted by Sendmail to mean &"no aliasing"&.
4077 For normal modes of operation, it is ignored by Exim.
4078 When combined with &%-bP%& it makes the output more terse (suppresses
4079 option names, environment values and config pretty printing).
4080
4081 .vitem &%-O%&&~<&'data'&>
4082 .oindex "&%-O%&"
4083 This option is interpreted by Sendmail to mean &`set option`&. It is ignored by
4084 Exim.
4085
4086 .vitem &%-oA%&&~<&'file&~name'&>
4087 .oindex "&%-oA%&"
4088 .cindex "Sendmail compatibility" "&%-oA%& option"
4089 This option is used by Sendmail in conjunction with &%-bi%& to specify an
4090 alternative alias file name. Exim handles &%-bi%& differently; see the
4091 description above.
4092
4093 .vitem &%-oB%&&~<&'n'&>
4094 .oindex "&%-oB%&"
4095 .cindex "SMTP" "passed connection"
4096 .cindex "SMTP" "multiple deliveries"
4097 .cindex "multiple SMTP deliveries"
4098 This is a debugging option which limits the maximum number of messages that can
4099 be delivered down one SMTP connection, overriding the value set in any &(smtp)&
4100 transport. If <&'n'&> is omitted, the limit is set to 1.
4101
4102 .vitem &%-odb%&
4103 .oindex "&%-odb%&"
4104 .cindex "background delivery"
4105 .cindex "delivery" "in the background"
4106 This option applies to all modes in which Exim accepts incoming messages,
4107 including the listening daemon. It requests &"background"& delivery of such
4108 messages, which means that the accepting process automatically starts a
4109 delivery process for each message received, but does not wait for the delivery
4110 processes to finish.
4111
4112 When all the messages have been received, the reception process exits,
4113 leaving the delivery processes to finish in their own time. The standard output
4114 and error streams are closed at the start of each delivery process.
4115 This is the default action if none of the &%-od%& options are present.
4116
4117 If one of the queueing options in the configuration file
4118 (&%queue_only%& or &%queue_only_file%&, for example) is in effect, &%-odb%&
4119 overrides it if &%queue_only_override%& is set true, which is the default
4120 setting. If &%queue_only_override%& is set false, &%-odb%& has no effect.
4121
4122 .vitem &%-odf%&
4123 .oindex "&%-odf%&"
4124 .cindex "foreground delivery"
4125 .cindex "delivery" "in the foreground"
4126 This option requests &"foreground"& (synchronous) delivery when Exim has
4127 accepted a locally-generated message. (For the daemon it is exactly the same as
4128 &%-odb%&.) A delivery process is automatically started to deliver the message,
4129 and Exim waits for it to complete before proceeding.
4130
4131 The original Exim reception process does not finish until the delivery
4132 process for the final message has ended. The standard error stream is left open
4133 during deliveries.
4134
4135 However, like &%-odb%&, this option has no effect if &%queue_only_override%& is
4136 false and one of the queueing options in the configuration file is in effect.
4137
4138 If there is a temporary delivery error during foreground delivery, the
4139 message is left on the queue for later delivery, and the original reception
4140 process exits. See chapter &<<CHAPnonqueueing>>& for a way of setting up a
4141 restricted configuration that never queues messages.
4142
4143
4144 .vitem &%-odi%&
4145 .oindex "&%-odi%&"
4146 This option is synonymous with &%-odf%&. It is provided for compatibility with
4147 Sendmail.
4148
4149 .vitem &%-odq%&
4150 .oindex "&%-odq%&"
4151 .cindex "non-immediate delivery"
4152 .cindex "delivery" "suppressing immediate"
4153 .cindex "queueing incoming messages"
4154 This option applies to all modes in which Exim accepts incoming messages,
4155 including the listening daemon. It specifies that the accepting process should
4156 not automatically start a delivery process for each message received. Messages
4157 are placed on the queue, and remain there until a subsequent queue runner
4158 process encounters them. There are several configuration options (such as
4159 &%queue_only%&) that can be used to queue incoming messages under certain
4160 conditions. This option overrides all of them and also &%-odqs%&. It always
4161 forces queueing.
4162
4163 .vitem &%-odqs%&
4164 .oindex "&%-odqs%&"
4165 .cindex "SMTP" "delaying delivery"
4166 This option is a hybrid between &%-odb%&/&%-odi%& and &%-odq%&.
4167 However, like &%-odb%& and &%-odi%&, this option has no effect if
4168 &%queue_only_override%& is false and one of the queueing options in the
4169 configuration file is in effect.
4170
4171 When &%-odqs%& does operate, a delivery process is started for each incoming
4172 message, in the background by default, but in the foreground if &%-odi%& is
4173 also present. The recipient addresses are routed, and local deliveries are done
4174 in the normal way. However, if any SMTP deliveries are required, they are not
4175 done at this time, so the message remains on the queue until a subsequent queue
4176 runner process encounters it. Because routing was done, Exim knows which
4177 messages are waiting for which hosts, and so a number of messages for the same
4178 host can be sent in a single SMTP connection. The &%queue_smtp_domains%&
4179 configuration option has the same effect for specific domains. See also the
4180 &%-qq%& option.
4181
4182 .vitem &%-oee%&
4183 .oindex "&%-oee%&"
4184 .cindex "error" "reporting"
4185 If an error is detected while a non-SMTP message is being received (for
4186 example, a malformed address), the error is reported to the sender in a mail
4187 message.
4188
4189 .cindex "return code" "for &%-oee%&"
4190 Provided
4191 this error message is successfully sent, the Exim receiving process
4192 exits with a return code of zero. If not, the return code is 2 if the problem
4193 is that the original message has no recipients, or 1 for any other error.
4194 This is the default &%-oe%&&'x'& option if Exim is called as &'rmail'&.
4195
4196 .vitem &%-oem%&
4197 .oindex "&%-oem%&"
4198 .cindex "error" "reporting"
4199 .cindex "return code" "for &%-oem%&"
4200 This is the same as &%-oee%&, except that Exim always exits with a non-zero
4201 return code, whether or not the error message was successfully sent.
4202 This is the default &%-oe%&&'x'& option, unless Exim is called as &'rmail'&.
4203
4204 .vitem &%-oep%&
4205 .oindex "&%-oep%&"
4206 .cindex "error" "reporting"
4207 If an error is detected while a non-SMTP message is being received, the
4208 error is reported by writing a message to the standard error file (stderr).
4209 .cindex "return code" "for &%-oep%&"
4210 The return code is 1 for all errors.
4211
4212 .vitem &%-oeq%&
4213 .oindex "&%-oeq%&"
4214 .cindex "error" "reporting"
4215 This option is supported for compatibility with Sendmail, but has the same
4216 effect as &%-oep%&.
4217
4218 .vitem &%-oew%&
4219 .oindex "&%-oew%&"
4220 .cindex "error" "reporting"
4221 This option is supported for compatibility with Sendmail, but has the same
4222 effect as &%-oem%&.
4223
4224 .vitem &%-oi%&
4225 .oindex "&%-oi%&"
4226 .cindex "dot" "in incoming non-SMTP message"
4227 This option, which has the same effect as &%-i%&, specifies that a dot on a
4228 line by itself should not terminate an incoming, non-SMTP message. Otherwise, a
4229 single dot does terminate, though Exim does no special processing for other
4230 lines that start with a dot. This option is set by default if Exim is called as
4231 &'rmail'&. See also &%-ti%&.
4232
4233 .vitem &%-oitrue%&
4234 .oindex "&%-oitrue%&"
4235 This option is treated as synonymous with &%-oi%&.
4236
4237 .vitem &%-oMa%&&~<&'host&~address'&>
4238 .oindex "&%-oMa%&"
4239 .cindex "sender" "host address, specifying for local message"
4240 A number of options starting with &%-oM%& can be used to set values associated
4241 with remote hosts on locally-submitted messages (that is, messages not received
4242 over TCP/IP). These options can be used by any caller in conjunction with the
4243 &%-bh%&, &%-be%&, &%-bf%&, &%-bF%&, &%-bt%&, or &%-bv%& testing options. In
4244 other circumstances, they are ignored unless the caller is trusted.
4245
4246 The &%-oMa%& option sets the sender host address. This may include a port
4247 number at the end, after a full stop (period). For example:
4248 .code
4249 exim -bs -oMa 10.9.8.7.1234
4250 .endd
4251 An alternative syntax is to enclose the IP address in square brackets,
4252 followed by a colon and the port number:
4253 .code
4254 exim -bs -oMa [10.9.8.7]:1234
4255 .endd
4256 The IP address is placed in the &$sender_host_address$& variable, and the
4257 port, if present, in &$sender_host_port$&. If both &%-oMa%& and &%-bh%&
4258 are present on the command line, the sender host IP address is taken from
4259 whichever one is last.
4260
4261 .vitem &%-oMaa%&&~<&'name'&>
4262 .oindex "&%-oMaa%&"
4263 .cindex "authentication" "name, specifying for local message"
4264 See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMaa%&
4265 option sets the value of &$sender_host_authenticated$& (the authenticator
4266 name). See chapter &<<CHAPSMTPAUTH>>& for a discussion of SMTP authentication.
4267 This option can be used with &%-bh%& and &%-bs%& to set up an
4268 authenticated SMTP session without actually using the SMTP AUTH command.
4269
4270 .vitem &%-oMai%&&~<&'string'&>
4271 .oindex "&%-oMai%&"
4272 .cindex "authentication" "id, specifying for local message"
4273 See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMai%&
4274 option sets the value of &$authenticated_id$& (the id that was authenticated).
4275 This overrides the default value (the caller's login id, except with &%-bh%&,
4276 where there is no default) for messages from local sources. See chapter
4277 &<<CHAPSMTPAUTH>>& for a discussion of authenticated ids.
4278
4279 .vitem &%-oMas%&&~<&'address'&>
4280 .oindex "&%-oMas%&"
4281 .cindex "authentication" "sender, specifying for local message"
4282 See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMas%&
4283 option sets the authenticated sender value in &$authenticated_sender$&. It
4284 overrides the sender address that is created from the caller's login id for
4285 messages from local sources, except when &%-bh%& is used, when there is no
4286 default. For both &%-bh%& and &%-bs%&, an authenticated sender that is
4287 specified on a MAIL command overrides this value. See chapter
4288 &<<CHAPSMTPAUTH>>& for a discussion of authenticated senders.
4289
4290 .vitem &%-oMi%&&~<&'interface&~address'&>
4291 .oindex "&%-oMi%&"
4292 .cindex "interface" "address, specifying for local message"
4293 See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMi%&
4294 option sets the IP interface address value. A port number may be included,
4295 using the same syntax as for &%-oMa%&. The interface address is placed in
4296 &$received_ip_address$& and the port number, if present, in &$received_port$&.
4297
4298 .vitem &%-oMm%&&~<&'message&~reference'&>
4299 .oindex "&%-oMm%&"
4300 .cindex "message reference" "message reference, specifying for local message"
4301 See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMm%&
4302 option sets the message reference, e.g. message-id, and is logged during
4303 delivery. This is useful when some kind of audit trail is required to tie
4304 messages together. The format of the message reference is checked and will
4305 abort if the format is invalid. The option will only be accepted if exim is
4306 running in trusted mode, not as any regular user.
4307
4308 The best example of a message reference is when Exim sends a bounce message.
4309 The message reference is the message-id of the original message for which Exim
4310 is sending the bounce.
4311
4312 .vitem &%-oMr%&&~<&'protocol&~name'&>
4313 .oindex "&%-oMr%&"
4314 .cindex "protocol, specifying for local message"
4315 .vindex "&$received_protocol$&"
4316 See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMr%&
4317 option sets the received protocol value that is stored in
4318 &$received_protocol$&. However, it does not apply (and is ignored) when &%-bh%&
4319 or &%-bs%& is used. For &%-bh%&, the protocol is forced to one of the standard
4320 SMTP protocol names (see the description of &$received_protocol$& in section
4321 &<<SECTexpvar>>&). For &%-bs%&, the protocol is always &"local-"& followed by
4322 one of those same names. For &%-bS%& (batched SMTP) however, the protocol can
4323 be set by &%-oMr%&. Repeated use of this option is not supported.
4324
4325 .vitem &%-oMs%&&~<&'host&~name'&>
4326 .oindex "&%-oMs%&"
4327 .cindex "sender" "host name, specifying for local message"
4328 See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMs%&
4329 option sets the sender host name in &$sender_host_name$&. When this option is
4330 present, Exim does not attempt to look up a host name from an IP address; it
4331 uses the name it is given.
4332
4333 .vitem &%-oMt%&&~<&'ident&~string'&>
4334 .oindex "&%-oMt%&"
4335 .cindex "sender" "ident string, specifying for local message"
4336 See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMt%&
4337 option sets the sender ident value in &$sender_ident$&. The default setting for
4338 local callers is the login id of the calling process, except when &%-bh%& is
4339 used, when there is no default.
4340
4341 .vitem &%-om%&
4342 .oindex "&%-om%&"
4343 .cindex "Sendmail compatibility" "&%-om%& option ignored"
4344 In Sendmail, this option means &"me too"&, indicating that the sender of a
4345 message should receive a copy of the message if the sender appears in an alias
4346 expansion. Exim always does this, so the option does nothing.
4347
4348 .vitem &%-oo%&
4349 .oindex "&%-oo%&"
4350 .cindex "Sendmail compatibility" "&%-oo%& option ignored"
4351 This option is ignored. In Sendmail it specifies &"old style headers"&,
4352 whatever that means.
4353
4354 .vitem &%-oP%&&~<&'path'&>
4355 .oindex "&%-oP%&"
4356 .cindex "pid (process id)" "of daemon"
4357 .cindex "daemon" "process id (pid)"
4358 This option is useful only in conjunction with &%-bd%& or &%-q%& with a time
4359 value. The option specifies the file to which the process id of the daemon is
4360 written. When &%-oX%& is used with &%-bd%&, or when &%-q%& with a time is used
4361 without &%-bd%&, this is the only way of causing Exim to write a pid file,
4362 because in those cases, the normal pid file is not used.
4363
4364 .vitem &%-or%&&~<&'time'&>
4365 .oindex "&%-or%&"
4366 .cindex "timeout" "for non-SMTP input"
4367 This option sets a timeout value for incoming non-SMTP messages. If it is not
4368 set, Exim will wait forever for the standard input. The value can also be set
4369 by the &%receive_timeout%& option. The format used for specifying times is
4370 described in section &<<SECTtimeformat>>&.
4371
4372 .vitem &%-os%&&~<&'time'&>
4373 .oindex "&%-os%&"
4374 .cindex "timeout" "for SMTP input"
4375 .cindex "SMTP" "input timeout"
4376 This option sets a timeout value for incoming SMTP messages. The timeout
4377 applies to each SMTP command and block of data. The value can also be set by
4378 the &%smtp_receive_timeout%& option; it defaults to 5 minutes. The format used
4379 for specifying times is described in section &<<SECTtimeformat>>&.
4380
4381 .vitem &%-ov%&
4382 .oindex "&%-ov%&"
4383 This option has exactly the same effect as &%-v%&.
4384
4385 .vitem &%-oX%&&~<&'number&~or&~string'&>
4386 .oindex "&%-oX%&"
4387 .cindex "TCP/IP" "setting listening ports"
4388 .cindex "TCP/IP" "setting listening interfaces"
4389 .cindex "port" "receiving TCP/IP"
4390 This option is relevant only when the &%-bd%& (start listening daemon) option
4391 is also given. It controls which ports and interfaces the daemon uses. Details
4392 of the syntax, and how it interacts with configuration file options, are given
4393 in chapter &<<CHAPinterfaces>>&. When &%-oX%& is used to start a daemon, no pid
4394 file is written unless &%-oP%& is also present to specify a pid file name.
4395
4396 .vitem &%-pd%&
4397 .oindex "&%-pd%&"
4398 .cindex "Perl" "starting the interpreter"
4399 This option applies when an embedded Perl interpreter is linked with Exim (see
4400 chapter &<<CHAPperl>>&). It overrides the setting of the &%perl_at_start%&
4401 option, forcing the starting of the interpreter to be delayed until it is
4402 needed.
4403
4404 .vitem &%-ps%&
4405 .oindex "&%-ps%&"
4406 .cindex "Perl" "starting the interpreter"
4407 This option applies when an embedded Perl interpreter is linked with Exim (see
4408 chapter &<<CHAPperl>>&). It overrides the setting of the &%perl_at_start%&
4409 option, forcing the starting of the interpreter to occur as soon as Exim is
4410 started.
4411
4412 .vitem &%-p%&<&'rval'&>:<&'sval'&>
4413 .oindex "&%-p%&"
4414 For compatibility with Sendmail, this option is equivalent to
4415 .display
4416 &`-oMr`& <&'rval'&> &`-oMs`& <&'sval'&>
4417 .endd
4418 It sets the incoming protocol and host name (for trusted callers). The
4419 host name and its colon can be omitted when only the protocol is to be set.
4420 Note the Exim already has two private options, &%-pd%& and &%-ps%&, that refer
4421 to embedded Perl. It is therefore impossible to set a protocol value of &`d`&
4422 or &`s`& using this option (but that does not seem a real limitation).
4423 Repeated use of this option is not supported.
4424
4425 .vitem &%-q%&
4426 .oindex "&%-q%&"
4427 .cindex "queue runner" "starting manually"
4428 This option is normally restricted to admin users. However, there is a
4429 configuration option called &%prod_requires_admin%& which can be set false to
4430 relax this restriction (and also the same requirement for the &%-M%&, &%-R%&,
4431 and &%-S%& options).
4432
4433 .cindex "queue runner" "description of operation"
4434 If other commandline options do not specify an action,
4435 the &%-q%& option starts one queue runner process. This scans the queue of
4436 waiting messages, and runs a delivery process for each one in turn. It waits
4437 for each delivery process to finish before starting the next one. A delivery
4438 process may not actually do any deliveries if the retry times for the addresses
4439 have not been reached. Use &%-qf%& (see below) if you want to override this.
4440
4441 If
4442 .cindex "SMTP" "passed connection"
4443 .cindex "SMTP" "multiple deliveries"
4444 .cindex "multiple SMTP deliveries"
4445 the delivery process spawns other processes to deliver other messages down
4446 passed SMTP connections, the queue runner waits for these to finish before
4447 proceeding.
4448
4449 When all the queued messages have been considered, the original queue runner
4450 process terminates. In other words, a single pass is made over the waiting
4451 mail, one message at a time. Use &%-q%& with a time (see below) if you want
4452 this to be repeated periodically.
4453
4454 Exim processes the waiting messages in an unpredictable order. It isn't very
4455 random, but it is likely to be different each time, which is all that matters.
4456 If one particular message screws up a remote MTA, other messages to the same
4457 MTA have a chance of getting through if they get tried first.
4458
4459 It is possible to cause the messages to be processed in lexical message id
4460 order, which is essentially the order in which they arrived, by setting the
4461 &%queue_run_in_order%& option, but this is not recommended for normal use.
4462
4463 .vitem &%-q%&<&'qflags'&>
4464 The &%-q%& option may be followed by one or more flag letters that change its
4465 behaviour. They are all optional, but if more than one is present, they must
4466 appear in the correct order. Each flag is described in a separate item below.
4467
4468 .vitem &%-qq...%&
4469 .oindex "&%-qq%&"
4470 .cindex "queue" "double scanning"
4471 .cindex "queue" "routing"
4472 .cindex "routing" "whole queue before delivery"
4473 An option starting with &%-qq%& requests a two-stage queue run. In the first
4474 stage, the queue is scanned as if the &%queue_smtp_domains%& option matched
4475 every domain. Addresses are routed, local deliveries happen, but no remote
4476 transports are run.
4477
4478 .cindex "hints database" "remembering routing"
4479 The hints database that remembers which messages are waiting for specific hosts
4480 is updated, as if delivery to those hosts had been deferred. After this is
4481 complete, a second, normal queue scan happens, with routing and delivery taking
4482 place as normal. Messages that are routed to the same host should mostly be
4483 delivered down a single SMTP
4484 .cindex "SMTP" "passed connection"
4485 .cindex "SMTP" "multiple deliveries"
4486 .cindex "multiple SMTP deliveries"
4487 connection because of the hints that were set up during the first queue scan.
4488 This option may be useful for hosts that are connected to the Internet
4489 intermittently.
4490
4491 .vitem &%-q[q]i...%&
4492 .oindex "&%-qi%&"
4493 .cindex "queue" "initial delivery"
4494 If the &'i'& flag is present, the queue runner runs delivery processes only for
4495 those messages that haven't previously been tried. (&'i'& stands for &"initial
4496 delivery"&.) This can be helpful if you are putting messages on the queue using
4497 &%-odq%& and want a queue runner just to process the new messages.
4498
4499 .vitem &%-q[q][i]f...%&
4500 .oindex "&%-qf%&"
4501 .cindex "queue" "forcing delivery"
4502 .cindex "delivery" "forcing in queue run"
4503 If one &'f'& flag is present, a delivery attempt is forced for each non-frozen
4504 message, whereas without &'f'& only those non-frozen addresses that have passed
4505 their retry times are tried.
4506
4507 .vitem &%-q[q][i]ff...%&
4508 .oindex "&%-qff%&"
4509 .cindex "frozen messages" "forcing delivery"
4510 If &'ff'& is present, a delivery attempt is forced for every message, whether
4511 frozen or not.
4512
4513 .vitem &%-q[q][i][f[f]]l%&
4514 .oindex "&%-ql%&"
4515 .cindex "queue" "local deliveries only"
4516 The &'l'& (the letter &"ell"&) flag specifies that only local deliveries are to
4517 be done. If a message requires any remote deliveries, it remains on the queue
4518 for later delivery.
4519
4520 .vitem &%-q[q][i][f[f]][l][G<name>[/<time>]]]%&
4521 .oindex "&%-qG%&"
4522 .cindex queue named
4523 .cindex "named queues"
4524 .cindex "queue" "delivering specific messages"
4525 If the &'G'& flag and a name is present, the queue runner operates on the
4526 queue with the given name rather than the default queue.
4527 The name should not contain a &'/'& character.
4528 For a periodic queue run (see below)
4529 append to the name a slash and a time value.
4530
4531 If other commandline options specify an action, a &'-qG<name>'& option
4532 will specify a queue to operate on.
4533 For example:
4534 .code
4535 exim -bp -qGquarantine
4536 mailq -qGquarantine
4537 exim -qGoffpeak -Rf @special.domain.example
4538 .endd
4539
4540 .vitem &%-q%&<&'qflags'&>&~<&'start&~id'&>&~<&'end&~id'&>
4541 When scanning the queue, Exim can be made to skip over messages whose ids are
4542 lexically less than a given value by following the &%-q%& option with a
4543 starting message id. For example:
4544 .code
4545 exim -q 0t5C6f-0000c8-00
4546 .endd
4547 Messages that arrived earlier than &`0t5C6f-0000c8-00`& are not inspected. If a
4548 second message id is given, messages whose ids are lexically greater than it
4549 are also skipped. If the same id is given twice, for example,
4550 .code
4551 exim -q 0t5C6f-0000c8-00 0t5C6f-0000c8-00
4552 .endd
4553 just one delivery process is started, for that message. This differs from
4554 &%-M%& in that retry data is respected, and it also differs from &%-Mc%& in
4555 that it counts as a delivery from a queue run. Note that the selection
4556 mechanism does not affect the order in which the messages are scanned. There
4557 are also other ways of selecting specific sets of messages for delivery in a
4558 queue run &-- see &%-R%& and &%-S%&.
4559
4560 .vitem &%-q%&<&'qflags'&><&'time'&>
4561 .cindex "queue runner" "starting periodically"
4562 .cindex "periodic queue running"
4563 When a time value is present, the &%-q%& option causes Exim to run as a daemon,
4564 starting a queue runner process at intervals specified by the given time value
4565 (whose format is described in section &<<SECTtimeformat>>&). This form of the
4566 &%-q%& option is commonly combined with the &%-bd%& option, in which case a
4567 single daemon process handles both functions. A common way of starting up a
4568 combined daemon at system boot time is to use a command such as
4569 .code
4570 /usr/exim/bin/exim -bd -q30m
4571 .endd
4572 Such a daemon listens for incoming SMTP calls, and also starts a queue runner
4573 process every 30 minutes.
4574
4575 When a daemon is started by &%-q%& with a time value, but without &%-bd%&, no
4576 pid file is written unless one is explicitly requested by the &%-oP%& option.
4577
4578 .vitem &%-qR%&<&'rsflags'&>&~<&'string'&>
4579 .oindex "&%-qR%&"
4580 This option is synonymous with &%-R%&. It is provided for Sendmail
4581 compatibility.
4582
4583 .vitem &%-qS%&<&'rsflags'&>&~<&'string'&>
4584 .oindex "&%-qS%&"
4585 This option is synonymous with &%-S%&.
4586
4587 .vitem &%-R%&<&'rsflags'&>&~<&'string'&>
4588 .oindex "&%-R%&"
4589 .cindex "queue runner" "for specific recipients"
4590 .cindex "delivery" "to given domain"
4591 .cindex "domain" "delivery to"
4592 The <&'rsflags'&> may be empty, in which case the white space before the string
4593 is optional, unless the string is &'f'&, &'ff'&, &'r'&, &'rf'&, or &'rff'&,
4594 which are the possible values for <&'rsflags'&>. White space is required if
4595 <&'rsflags'&> is not empty.
4596
4597 This option is similar to &%-q%& with no time value, that is, it causes Exim to
4598 perform a single queue run, except that, when scanning the messages on the
4599 queue, Exim processes only those that have at least one undelivered recipient
4600 address containing the given string, which is checked in a case-independent
4601 way. If the <&'rsflags'&> start with &'r'&, <&'string'&> is interpreted as a
4602 regular expression; otherwise it is a literal string.
4603
4604 If you want to do periodic queue runs for messages with specific recipients,
4605 you can combine &%-R%& with &%-q%& and a time value. For example:
4606 .code
4607 exim -q25m -R @special.domain.example
4608 .endd
4609 This example does a queue run for messages with recipients in the given domain
4610 every 25 minutes. Any additional flags that are specified with &%-q%& are
4611 applied to each queue run.
4612
4613 Once a message is selected for delivery by this mechanism, all its addresses
4614 are processed. For the first selected message, Exim overrides any retry
4615 information and forces a delivery attempt for each undelivered address. This
4616 means that if delivery of any address in the first message is successful, any
4617 existing retry information is deleted, and so delivery attempts for that
4618 address in subsequently selected messages (which are processed without forcing)
4619 will run. However, if delivery of any address does not succeed, the retry
4620 information is updated, and in subsequently selected messages, the failing
4621 address will be skipped.
4622
4623 .cindex "frozen messages" "forcing delivery"
4624 If the <&'rsflags'&> contain &'f'& or &'ff'&, the delivery forcing applies to
4625 all selected messages, not just the first; frozen messages are included when
4626 &'ff'& is present.
4627
4628 The &%-R%& option makes it straightforward to initiate delivery of all messages
4629 to a given domain after a host has been down for some time. When the SMTP
4630 command ETRN is accepted by its ACL (see chapter &<<CHAPACL>>&), its default
4631 effect is to run Exim with the &%-R%& option, but it can be configured to run
4632 an arbitrary command instead.
4633
4634 .vitem &%-r%&
4635 .oindex "&%-r%&"
4636 This is a documented (for Sendmail) obsolete alternative name for &%-f%&.
4637
4638 .vitem &%-S%&<&'rsflags'&>&~<&'string'&>
4639 .oindex "&%-S%&"
4640 .cindex "delivery" "from given sender"
4641 .cindex "queue runner" "for specific senders"
4642 This option acts like &%-R%& except that it checks the string against each
4643 message's sender instead of against the recipients. If &%-R%& is also set, both
4644 conditions must be met for a message to be selected. If either of the options
4645 has &'f'& or &'ff'& in its flags, the associated action is taken.
4646
4647 .vitem &%-Tqt%&&~<&'times'&>
4648 .oindex "&%-Tqt%&"
4649 This is an option that is exclusively for use by the Exim testing suite. It is not
4650 recognized when Exim is run normally. It allows for the setting up of explicit
4651 &"queue times"& so that various warning/retry features can be tested.
4652
4653 .vitem &%-t%&
4654 .oindex "&%-t%&"
4655 .cindex "recipient" "extracting from header lines"
4656 .cindex "&'Bcc:'& header line"
4657 .cindex "&'Cc:'& header line"
4658 .cindex "&'To:'& header line"
4659 When Exim is receiving a locally-generated, non-SMTP message on its standard
4660 input, the &%-t%& option causes the recipients of the message to be obtained
4661 from the &'To:'&, &'Cc:'&, and &'Bcc:'& header lines in the message instead of
4662 from the command arguments. The addresses are extracted before any rewriting
4663 takes place and the &'Bcc:'& header line, if present, is then removed.
4664
4665 .cindex "Sendmail compatibility" "&%-t%& option"
4666 If the command has any arguments, they specify addresses to which the message
4667 is &'not'& to be delivered. That is, the argument addresses are removed from
4668 the recipients list obtained from the headers. This is compatible with Smail 3
4669 and in accordance with the documented behaviour of several versions of
4670 Sendmail, as described in man pages on a number of operating systems (e.g.
4671 Solaris 8, IRIX 6.5, HP-UX 11). However, some versions of Sendmail &'add'&
4672 argument addresses to those obtained from the headers, and the O'Reilly
4673 Sendmail book documents it that way. Exim can be made to add argument addresses
4674 instead of subtracting them by setting the option
4675 &%extract_addresses_remove_arguments%& false.
4676
4677 .cindex "&%Resent-%& header lines" "with &%-t%&"
4678 If there are any &%Resent-%& header lines in the message, Exim extracts
4679 recipients from all &'Resent-To:'&, &'Resent-Cc:'&, and &'Resent-Bcc:'& header
4680 lines instead of from &'To:'&, &'Cc:'&, and &'Bcc:'&. This is for compatibility
4681 with Sendmail and other MTAs. (Prior to release 4.20, Exim gave an error if
4682 &%-t%& was used in conjunction with &%Resent-%& header lines.)
4683
4684 RFC 2822 talks about different sets of &%Resent-%& header lines (for when a
4685 message is resent several times). The RFC also specifies that they should be
4686 added at the front of the message, and separated by &'Received:'& lines. It is
4687 not at all clear how &%-t%& should operate in the present of multiple sets,
4688 nor indeed exactly what constitutes a &"set"&.
4689 In practice, it seems that MUAs do not follow the RFC. The &%Resent-%& lines
4690 are often added at the end of the header, and if a message is resent more than
4691 once, it is common for the original set of &%Resent-%& headers to be renamed as
4692 &%X-Resent-%& when a new set is added. This removes any possible ambiguity.
4693
4694 .vitem &%-ti%&
4695 .oindex "&%-ti%&"
4696 This option is exactly equivalent to &%-t%& &%-i%&. It is provided for
4697 compatibility with Sendmail.
4698
4699 .vitem &%-tls-on-connect%&
4700 .oindex "&%-tls-on-connect%&"
4701 .cindex "TLS" "use without STARTTLS"
4702 .cindex "TLS" "automatic start"
4703 This option is available when Exim is compiled with TLS support. It forces all
4704 incoming SMTP connections to behave as if the incoming port is listed in the
4705 &%tls_on_connect_ports%& option. See section &<<SECTsupobssmt>>& and chapter
4706 &<<CHAPTLS>>& for further details.
4707
4708
4709 .vitem &%-U%&
4710 .oindex "&%-U%&"
4711 .cindex "Sendmail compatibility" "&%-U%& option ignored"
4712 Sendmail uses this option for &"initial message submission"&, and its
4713 documentation states that in future releases, it may complain about
4714 syntactically invalid messages rather than fixing them when this flag is not
4715 set. Exim ignores this option.
4716
4717 .vitem &%-v%&
4718 .oindex "&%-v%&"
4719 This option causes Exim to write information to the standard error stream,
4720 describing what it is doing. In particular, it shows the log lines for
4721 receiving and delivering a message, and if an SMTP connection is made, the SMTP
4722 dialogue is shown. Some of the log lines shown may not actually be written to
4723 the log if the setting of &%log_selector%& discards them. Any relevant
4724 selectors are shown with each log line. If none are shown, the logging is
4725 unconditional.
4726
4727 .vitem &%-x%&
4728 .oindex "&%-x%&"
4729 AIX uses &%-x%& for a private purpose (&"mail from a local mail program has
4730 National Language Support extended characters in the body of the mail item"&).
4731 It sets &%-x%& when calling the MTA from its &%mail%& command. Exim ignores
4732 this option.
4733
4734 .vitem &%-X%&&~<&'logfile'&>
4735 .oindex "&%-X%&"
4736 This option is interpreted by Sendmail to cause debug information to be sent
4737 to the named file.  It is ignored by Exim.
4738
4739 .vitem &%-z%&&~<&'log-line'&>
4740 .oindex "&%-z%&"
4741 This option writes its argument to Exim's logfile.
4742 Use is restricted to administrators; the intent is for operational notes.
4743 Quotes should be used to maintain a multi-word item as a single argument,
4744 under most shells.
4745 .endlist
4746
4747 .ecindex IIDclo1
4748 .ecindex IIDclo2
4749
4750
4751 . ////////////////////////////////////////////////////////////////////////////
4752 . Insert a stylized DocBook comment here, to identify the end of the command
4753 . line options. This is for the benefit of the Perl script that automatically
4754 . creates a man page for the options.
4755 . ////////////////////////////////////////////////////////////////////////////
4756
4757 .literal xml
4758 <!-- === End of command line options === -->
4759 .literal off
4760
4761
4762
4763
4764
4765 . ////////////////////////////////////////////////////////////////////////////
4766 . ////////////////////////////////////////////////////////////////////////////
4767
4768
4769 .chapter "The Exim run time configuration file" "CHAPconf" &&&
4770          "The runtime configuration file"
4771
4772 .cindex "run time configuration"
4773 .cindex "configuration file" "general description"
4774 .cindex "CONFIGURE_FILE"
4775 .cindex "configuration file" "errors in"
4776 .cindex "error" "in configuration file"
4777 .cindex "return code" "for bad configuration"
4778 Exim uses a single run time configuration file that is read whenever an Exim
4779 binary is executed. Note that in normal operation, this happens frequently,
4780 because Exim is designed to operate in a distributed manner, without central
4781 control.
4782
4783 If a syntax error is detected while reading the configuration file, Exim
4784 writes a message on the standard error, and exits with a non-zero return code.
4785 The message is also written to the panic log. &*Note*&: Only simple syntax
4786 errors can be detected at this time. The values of any expanded options are
4787 not checked until the expansion happens, even when the expansion does not
4788 actually alter the string.
4789
4790 The name of the configuration file is compiled into the binary for security
4791 reasons, and is specified by the CONFIGURE_FILE compilation option. In
4792 most configurations, this specifies a single file. However, it is permitted to
4793 give a colon-separated list of file names, in which case Exim uses the first
4794 existing file in the list.
4795
4796 .cindex "EXIM_USER"
4797 .cindex "EXIM_GROUP"
4798 .cindex "CONFIGURE_OWNER"
4799 .cindex "CONFIGURE_GROUP"
4800 .cindex "configuration file" "ownership"
4801 .cindex "ownership" "configuration file"
4802 The run time configuration file must be owned by root or by the user that is
4803 specified at compile time by the CONFIGURE_OWNER option (if set). The
4804 configuration file must not be world-writeable, or group-writeable unless its
4805 group is the root group or the one specified at compile time by the
4806 CONFIGURE_GROUP option.
4807
4808 &*Warning*&: In a conventional configuration, where the Exim binary is setuid
4809 to root, anybody who is able to edit the run time configuration file has an
4810 easy way to run commands as root. If you specify a user or group in the
4811 CONFIGURE_OWNER or CONFIGURE_GROUP options, then that user and/or any users
4812 who are members of that group will trivially be able to obtain root privileges.
4813
4814 Up to Exim version 4.72, the run time configuration file was also permitted to
4815 be writeable by the Exim user and/or group. That has been changed in Exim 4.73
4816 since it offered a simple privilege escalation for any attacker who managed to
4817 compromise the Exim user account.
4818
4819 A default configuration file, which will work correctly in simple situations,
4820 is provided in the file &_src/configure.default_&. If CONFIGURE_FILE
4821 defines just one file name, the installation process copies the default
4822 configuration to a new file of that name if it did not previously exist. If
4823 CONFIGURE_FILE is a list, no default is automatically installed. Chapter
4824 &<<CHAPdefconfil>>& is a &"walk-through"& discussion of the default
4825 configuration.
4826
4827
4828
4829 .section "Using a different configuration file" "SECID40"
4830 .cindex "configuration file" "alternate"
4831 A one-off alternate configuration can be specified by the &%-C%& command line
4832 option, which may specify a single file or a list of files. However, when
4833 &%-C%& is used, Exim gives up its root privilege, unless called by root (or
4834 unless the argument for &%-C%& is identical to the built-in value from
4835 CONFIGURE_FILE), or is listed in the TRUSTED_CONFIG_LIST file and the caller
4836 is the Exim user or the user specified in the CONFIGURE_OWNER setting. &%-C%&
4837 is useful mainly for checking the syntax of configuration files before
4838 installing them. No owner or group checks are done on a configuration file
4839 specified by &%-C%&, if root privilege has been dropped.
4840
4841 Even the Exim user is not trusted to specify an arbitrary configuration file
4842 with the &%-C%& option to be used with root privileges, unless that file is
4843 listed in the TRUSTED_CONFIG_LIST file. This locks out the possibility of
4844 testing a configuration using &%-C%& right through message reception and
4845 delivery, even if the caller is root. The reception works, but by that time,
4846 Exim is running as the Exim user, so when it re-execs to regain privilege for
4847 the delivery, the use of &%-C%& causes privilege to be lost. However, root
4848 can test reception and delivery using two separate commands (one to put a
4849 message on the queue, using &%-odq%&, and another to do the delivery, using
4850 &%-M%&).
4851
4852 If ALT_CONFIG_PREFIX is defined &_in Local/Makefile_&, it specifies a
4853 prefix string with which any file named in a &%-C%& command line option must
4854 start. In addition, the file name must not contain the sequence &"&`/../`&"&.
4855 There is no default setting for ALT_CONFIG_PREFIX; when it is unset, any file
4856 name can be used with &%-C%&.
4857
4858 One-off changes to a configuration can be specified by the &%-D%& command line
4859 option, which defines and overrides values for macros used inside the
4860 configuration file. However, like &%-C%&, the use of this option by a
4861 non-privileged user causes Exim to discard its root privilege.
4862 If DISABLE_D_OPTION is defined in &_Local/Makefile_&, the use of &%-D%& is
4863 completely disabled, and its use causes an immediate error exit.
4864
4865 The WHITELIST_D_MACROS option in &_Local/Makefile_& permits the binary builder
4866 to declare certain macro names trusted, such that root privilege will not
4867 necessarily be discarded.
4868 WHITELIST_D_MACROS defines a colon-separated list of macros which are
4869 considered safe and, if &%-D%& only supplies macros from this list, and the
4870 values are acceptable, then Exim will not give up root privilege if the caller
4871 is root, the Exim run-time user, or the CONFIGURE_OWNER, if set.  This is a
4872 transition mechanism and is expected to be removed in the future.  Acceptable
4873 values for the macros satisfy the regexp: &`^[A-Za-z0-9_/.-]*$`&
4874
4875 Some sites may wish to use the same Exim binary on different machines that
4876 share a file system, but to use different configuration files on each machine.
4877 If CONFIGURE_FILE_USE_NODE is defined in &_Local/Makefile_&, Exim first
4878 looks for a file whose name is the configuration file name followed by a dot
4879 and the machine's node name, as obtained from the &[uname()]& function. If this
4880 file does not exist, the standard name is tried. This processing occurs for
4881 each file name in the list given by CONFIGURE_FILE or &%-C%&.
4882
4883 In some esoteric situations different versions of Exim may be run under
4884 different effective uids and the CONFIGURE_FILE_USE_EUID is defined to
4885 help with this. See the comments in &_src/EDITME_& for details.
4886
4887
4888
4889 .section "Configuration file format" "SECTconffilfor"
4890 .cindex "configuration file" "format of"
4891 .cindex "format" "configuration file"
4892 Exim's configuration file is divided into a number of different parts. General
4893 option settings must always appear at the start of the file. The other parts
4894 are all optional, and may appear in any order. Each part other than the first
4895 is introduced by the word &"begin"& followed by at least one literal
4896 space, and the name of the part. The optional parts are:
4897
4898 .ilist
4899 &'ACL'&: Access control lists for controlling incoming SMTP mail (see chapter
4900 &<<CHAPACL>>&).
4901 .next
4902 .cindex "AUTH" "configuration"
4903 &'authenticators'&: Configuration settings for the authenticator drivers. These
4904 are concerned with the SMTP AUTH command (see chapter &<<CHAPSMTPAUTH>>&).
4905 .next
4906 &'routers'&: Configuration settings for the router drivers. Routers process
4907 addresses and determine how the message is to be delivered (see chapters
4908 &<<CHAProutergeneric>>&&--&<<CHAPredirect>>&).
4909 .next
4910 &'transports'&: Configuration settings for the transport drivers. Transports
4911 define mechanisms for copying messages to destinations (see chapters
4912 &<<CHAPtransportgeneric>>&&--&<<CHAPsmtptrans>>&).
4913 .next
4914 &'retry'&: Retry rules, for use when a message cannot be delivered immediately.
4915 If there is no retry section, or if it is empty (that is, no retry rules are
4916 defined), Exim will not retry deliveries. In this situation, temporary errors
4917 are treated the same as permanent errors. Retry rules are discussed in chapter
4918 &<<CHAPretry>>&.
4919 .next
4920 &'rewrite'&: Global address rewriting rules, for use when a message arrives and
4921 when new addresses are generated during delivery. Rewriting is discussed in
4922 chapter &<<CHAPrewrite>>&.
4923 .next
4924 &'local_scan'&: Private options for the &[local_scan()]& function. If you
4925 want to use this feature, you must set
4926 .code
4927 LOCAL_SCAN_HAS_OPTIONS=yes
4928 .endd
4929 in &_Local/Makefile_& before building Exim. Details of the &[local_scan()]&
4930 facility are given in chapter &<<CHAPlocalscan>>&.
4931 .endlist
4932
4933 .cindex "configuration file" "leading white space in"
4934 .cindex "configuration file" "trailing white space in"
4935 .cindex "white space" "in configuration file"
4936 Leading and trailing white space in configuration lines is always ignored.
4937
4938 Blank lines in the file, and lines starting with a # character (ignoring
4939 leading white space) are treated as comments and are ignored. &*Note*&: A
4940 # character other than at the beginning of a line is not treated specially,
4941 and does not introduce a comment.
4942
4943 Any non-comment line can be continued by ending it with a backslash. Note that
4944 the general rule for white space means that trailing white space after the
4945 backslash and leading white space at the start of continuation
4946 lines is ignored. Comment lines beginning with # (but not empty lines) may
4947 appear in the middle of a sequence of continuation lines.
4948
4949 A convenient way to create a configuration file is to start from the
4950 default, which is supplied in &_src/configure.default_&, and add, delete, or
4951 change settings as required.
4952
4953 The ACLs, retry rules, and rewriting rules have their own syntax which is
4954 described in chapters &<<CHAPACL>>&, &<<CHAPretry>>&, and &<<CHAPrewrite>>&,
4955 respectively. The other parts of the configuration file have some syntactic
4956 items in common, and these are described below, from section &<<SECTcos>>&
4957 onwards. Before that, the inclusion, macro, and conditional facilities are
4958 described.
4959
4960
4961
4962 .section "File inclusions in the configuration file" "SECID41"
4963 .cindex "inclusions in configuration file"
4964 .cindex "configuration file" "including other files"
4965 .cindex "&`.include`& in configuration file"
4966 .cindex "&`.include_if_exists`& in configuration file"
4967 You can include other files inside Exim's run time configuration file by
4968 using this syntax:
4969 .display
4970 &`.include`& <&'file name'&>
4971 &`.include_if_exists`& <&'file name'&>
4972 .endd
4973 on a line by itself. Double quotes round the file name are optional. If you use
4974 the first form, a configuration error occurs if the file does not exist; the
4975 second form does nothing for non-existent files.
4976 The first form allows a relative name. It is resolved relative to
4977 the directory of the including file. For the second form an absolute file
4978 name is required.
4979
4980 Includes may be nested to any depth, but remember that Exim reads its
4981 configuration file often, so it is a good idea to keep them to a minimum.
4982 If you change the contents of an included file, you must HUP the daemon,
4983 because an included file is read only when the configuration itself is read.
4984
4985 The processing of inclusions happens early, at a physical line level, so, like
4986 comment lines, an inclusion can be used in the middle of an option setting,
4987 for example:
4988 .code
4989 hosts_lookup = a.b.c \
4990                .include /some/file
4991 .endd
4992 Include processing happens after macro processing (see below). Its effect is to
4993 process the lines of the included file as if they occurred inline where the
4994 inclusion appears.
4995
4996
4997
4998 .section "Macros in the configuration file" "SECTmacrodefs"
4999 .cindex "macro" "description of"
5000 .cindex "configuration file" "macros"
5001 If a line in the main part of the configuration (that is, before the first
5002 &"begin"& line) begins with an upper case letter, it is taken as a macro
5003 definition, and must be of the form
5004 .display
5005 <&'name'&> = <&'rest of line'&>
5006 .endd
5007 The name must consist of letters, digits, and underscores, and need not all be
5008 in upper case, though that is recommended. The rest of the line, including any
5009 continuations, is the replacement text, and has leading and trailing white
5010 space removed. Quotes are not removed. The replacement text can never end with
5011 a backslash character, but this doesn't seem to be a serious limitation.
5012
5013 Macros may also be defined between router, transport, authenticator, or ACL
5014 definitions. They may not, however, be defined within an individual driver or
5015 ACL, or in the &%local_scan%&, retry, or rewrite sections of the configuration.
5016
5017 .section "Macro substitution" "SECID42"
5018 Once a macro is defined, all subsequent lines in the file (and any included
5019 files) are scanned for the macro name; if there are several macros, the line is
5020 scanned for each in turn, in the order in which the macros are defined. The
5021 replacement text is not re-scanned for the current macro, though it is scanned
5022 for subsequently defined macros. For this reason, a macro name may not contain
5023 the name of a previously defined macro as a substring. You could, for example,
5024 define
5025 .display
5026 &`ABCD_XYZ = `&<&'something'&>
5027 &`ABCD = `&<&'something else'&>
5028 .endd
5029 but putting the definitions in the opposite order would provoke a configuration
5030 error. Macro expansion is applied to individual physical lines from the file,
5031 before checking for line continuation or file inclusion (see above). If a line
5032 consists solely of a macro name, and the expansion of the macro is empty, the
5033 line is ignored. A macro at the start of a line may turn the line into a
5034 comment line or a &`.include`& line.
5035
5036
5037 .section "Redefining macros" "SECID43"
5038 Once defined, the value of a macro can be redefined later in the configuration
5039 (or in an included file). Redefinition is specified by using &'=='& instead of
5040 &'='&. For example:
5041 .code
5042 MAC =  initial value
5043 ...
5044 MAC == updated value
5045 .endd
5046 Redefinition does not alter the order in which the macros are applied to the
5047 subsequent lines of the configuration file. It is still the same order in which
5048 the macros were originally defined. All that changes is the macro's value.
5049 Redefinition makes it possible to accumulate values. For example:
5050 .code
5051 MAC =  initial value
5052 ...
5053 MAC == MAC and something added
5054 .endd
5055 This can be helpful in situations where the configuration file is built
5056 from a number of other files.
5057
5058 .section "Overriding macro values" "SECID44"
5059 The values set for macros in the configuration file can be overridden by the
5060 &%-D%& command line option, but Exim gives up its root privilege when &%-D%& is
5061 used, unless called by root or the Exim user. A definition on the command line
5062 using the &%-D%& option causes all definitions and redefinitions within the
5063 file to be ignored.
5064
5065
5066
5067 .section "Example of macro usage" "SECID45"
5068 As an example of macro usage, consider a configuration where aliases are looked
5069 up in a MySQL database. It helps to keep the file less cluttered if long
5070 strings such as SQL statements are defined separately as macros, for example:
5071 .code
5072 ALIAS_QUERY = select mailbox from user where \
5073               login='${quote_mysql:$local_part}';
5074 .endd
5075 This can then be used in a &(redirect)& router setting like this:
5076 .code
5077 data = ${lookup mysql{ALIAS_QUERY}}
5078 .endd
5079 In earlier versions of Exim macros were sometimes used for domain, host, or
5080 address lists. In Exim 4 these are handled better by named lists &-- see
5081 section &<<SECTnamedlists>>&.
5082
5083
5084 .section "Builtin macros" "SECTbuiltinmacros"
5085 Exim defines some macros depending on facilities available, which may
5086 differ due to build-time definitions and from one release to another.
5087 All of these macros start with an underscore.
5088 They can be used to conditionally include parts of a configuration
5089 (see below).
5090
5091 The following classes of macros are defined:
5092 .display
5093 &` _HAVE_*                    `&  build-time defines
5094 &` _DRIVER_ROUTER_*           `&  router drivers
5095 &` _DRIVER_TRANSPORT_*        `&  transport drivers
5096 &` _DRIVER_AUTHENTICATOR_*    `&  authenticator drivers
5097 &` _LOG_*                     `&  log_selector values
5098 &` _OPT_MAIN_*                `&  main config options
5099 &` _OPT_ROUTERS_*             `&  generic router options
5100 &` _OPT_TRANSPORTS_*          `&  generic transport options
5101 &` _OPT_AUTHENTICATORS_*      `&  generic authenticator options
5102 &` _OPT_ROUTER_*_*            `&  private router options
5103 &` _OPT_TRANSPORT_*_*         `&  private transport options
5104 &` _OPT_AUTHENTICATOR_*_*     `&  private authenticator options
5105 .endd
5106
5107 Use an &"exim -bP macros"& command to get the list of macros.
5108
5109
5110 .section "Conditional skips in the configuration file" "SECID46"
5111 .cindex "configuration file" "conditional skips"
5112 .cindex "&`.ifdef`&"
5113 You can use the directives &`.ifdef`&, &`.ifndef`&, &`.elifdef`&,
5114 &`.elifndef`&, &`.else`&, and &`.endif`& to dynamically include or exclude
5115 portions of the configuration file. The processing happens whenever the file is
5116 read (that is, when an Exim binary starts to run).
5117
5118 The implementation is very simple. Instances of the first four directives must
5119 be followed by text that includes the names of one or macros. The condition
5120 that is tested is whether or not any macro substitution has taken place in the
5121 line. Thus:
5122 .code
5123 .ifdef AAA
5124 message_size_limit = 50M
5125 .else
5126 message_size_limit = 100M
5127 .endif
5128 .endd
5129 sets a message size limit of 50M if the macro &`AAA`& is defined
5130 (or &`A`& or &`AA`&), and 100M
5131 otherwise. If there is more than one macro named on the line, the condition
5132 is true if any of them are defined. That is, it is an &"or"& condition. To
5133 obtain an &"and"& condition, you need to use nested &`.ifdef`&s.
5134
5135 Although you can use a macro expansion to generate one of these directives,
5136 it is not very useful, because the condition &"there was a macro substitution
5137 in this line"& will always be true.
5138
5139 Text following &`.else`& and &`.endif`& is ignored, and can be used as comment
5140 to clarify complicated nestings.
5141
5142
5143
5144 .section "Common option syntax" "SECTcos"
5145 .cindex "common option syntax"
5146 .cindex "syntax of common options"
5147 .cindex "configuration file" "common option syntax"
5148 For the main set of options, driver options, and &[local_scan()]& options,
5149 each setting is on a line by itself, and starts with a name consisting of
5150 lower-case letters and underscores. Many options require a data value, and in
5151 these cases the name must be followed by an equals sign (with optional white
5152 space) and then the value. For example:
5153 .code
5154 qualify_domain = mydomain.example.com
5155 .endd
5156 .cindex "hiding configuration option values"
5157 .cindex "configuration options" "hiding value of"
5158 .cindex "options" "hiding value of"
5159 Some option settings may contain sensitive data, for example, passwords for
5160 accessing databases. To stop non-admin users from using the &%-bP%& command
5161 line option to read these values, you can precede the option settings with the
5162 word &"hide"&. For example:
5163 .code
5164 hide mysql_servers = localhost/users/admin/secret-password
5165 .endd
5166 For non-admin users, such options are displayed like this:
5167 .code
5168 mysql_servers = <value not displayable>
5169 .endd
5170 If &"hide"& is used on a driver option, it hides the value of that option on
5171 all instances of the same driver.
5172
5173 The following sections describe the syntax used for the different data types
5174 that are found in option settings.
5175
5176
5177 .section "Boolean options" "SECID47"
5178 .cindex "format" "boolean"
5179 .cindex "boolean configuration values"
5180 .oindex "&%no_%&&'xxx'&"
5181 .oindex "&%not_%&&'xxx'&"
5182 Options whose type is given as boolean are on/off switches. There are two
5183 different ways of specifying such options: with and without a data value. If
5184 the option name is specified on its own without data, the switch is turned on;
5185 if it is preceded by &"no_"& or &"not_"& the switch is turned off. However,
5186 boolean options may be followed by an equals sign and one of the words
5187 &"true"&, &"false"&, &"yes"&, or &"no"&, as an alternative syntax. For example,
5188 the following two settings have exactly the same effect:
5189 .code
5190 queue_only
5191 queue_only = true
5192 .endd
5193 The following two lines also have the same (opposite) effect:
5194 .code
5195 no_queue_only
5196 queue_only = false
5197 .endd
5198 You can use whichever syntax you prefer.
5199
5200
5201
5202
5203 .section "Integer values" "SECID48"
5204 .cindex "integer configuration values"
5205 .cindex "format" "integer"
5206 If an option's type is given as &"integer"&, the value can be given in decimal,
5207 hexadecimal, or octal. If it starts with a digit greater than zero, a decimal
5208 number is assumed. Otherwise, it is treated as an octal number unless it starts
5209 with the characters &"0x"&, in which case the remainder is interpreted as a
5210 hexadecimal number.
5211
5212 If an integer value is followed by the letter K, it is multiplied by 1024; if
5213 it is followed by the letter M, it is multiplied by 1024x1024;
5214 if by the letter G, 1024x1024x1024.
5215 When the values
5216 of integer option settings are output, values which are an exact multiple of
5217 1024 or 1024x1024 are sometimes, but not always, printed using the letters K
5218 and M. The printing style is independent of the actual input format that was
5219 used.
5220
5221
5222 .section "Octal integer values" "SECID49"
5223 .cindex "integer format"
5224 .cindex "format" "octal integer"
5225 If an option's type is given as &"octal integer"&, its value is always
5226 interpreted as an octal number, whether or not it starts with the digit zero.
5227 Such options are always output in octal.
5228
5229
5230 .section "Fixed point numbers" "SECID50"
5231 .cindex "fixed point configuration values"
5232 .cindex "format" "fixed point"
5233 If an option's type is given as &"fixed-point"&, its value must be a decimal
5234 integer, optionally followed by a decimal point and up to three further digits.
5235
5236
5237
5238 .section "Time intervals" "SECTtimeformat"
5239 .cindex "time interval" "specifying in configuration"
5240 .cindex "format" "time interval"
5241 A time interval is specified as a sequence of numbers, each followed by one of
5242 the following letters, with no intervening white space:
5243
5244 .table2 30pt
5245 .irow &%s%& seconds
5246 .irow &%m%& minutes
5247 .irow &%h%& hours
5248 .irow &%d%& days
5249 .irow &%w%& weeks
5250 .endtable
5251
5252 For example, &"3h50m"& specifies 3 hours and 50 minutes. The values of time
5253 intervals are output in the same format. Exim does not restrict the values; it
5254 is perfectly acceptable, for example, to specify &"90m"& instead of &"1h30m"&.
5255
5256
5257
5258 .section "String values" "SECTstrings"
5259 .cindex "string" "format of configuration values"
5260 .cindex "format" "string"
5261 If an option's type is specified as &"string"&, the value can be specified with
5262 or without double-quotes. If it does not start with a double-quote, the value
5263 consists of the remainder of the line plus any continuation lines, starting at
5264 the first character after any leading white space, with trailing white space
5265 removed, and with no interpretation of the characters in the string. Because
5266 Exim removes comment lines (those beginning with #) at an early stage, they can
5267 appear in the middle of a multi-line string. The following two settings are
5268 therefore equivalent:
5269 .code
5270 trusted_users = uucp:mail
5271 trusted_users = uucp:\
5272                 # This comment line is ignored
5273                 mail
5274 .endd
5275 .cindex "string" "quoted"
5276 .cindex "escape characters in quoted strings"
5277 If a string does start with a double-quote, it must end with a closing
5278 double-quote, and any backslash characters other than those used for line
5279 continuation are interpreted as escape characters, as follows:
5280
5281 .table2 100pt
5282 .irow &`\\`&                     "single backslash"
5283 .irow &`\n`&                     "newline"
5284 .irow &`\r`&                     "carriage return"
5285 .irow &`\t`&                     "tab"
5286 .irow "&`\`&<&'octal digits'&>"  "up to 3 octal digits specify one character"
5287 .irow "&`\x`&<&'hex digits'&>"   "up to 2 hexadecimal digits specify one &&&
5288                                    character"
5289 .endtable
5290
5291 If a backslash is followed by some other character, including a double-quote
5292 character, that character replaces the pair.
5293
5294 Quoting is necessary only if you want to make use of the backslash escapes to
5295 insert special characters, or if you need to specify a value with leading or
5296 trailing spaces. These cases are rare, so quoting is almost never needed in
5297 current versions of Exim. In versions of Exim before 3.14, quoting was required
5298 in order to continue lines, so you may come across older configuration files
5299 and examples that apparently quote unnecessarily.
5300
5301
5302 .section "Expanded strings" "SECID51"
5303 .cindex "expansion" "definition of"
5304 Some strings in the configuration file are subjected to &'string expansion'&,
5305 by which means various parts of the string may be changed according to the
5306 circumstances (see chapter &<<CHAPexpand>>&). The input syntax for such strings
5307 is as just described; in particular, the handling of backslashes in quoted
5308 strings is done as part of the input process, before expansion takes place.
5309 However, backslash is also an escape character for the expander, so any
5310 backslashes that are required for that reason must be doubled if they are
5311 within a quoted configuration string.
5312
5313
5314 .section "User and group names" "SECID52"
5315 .cindex "user name" "format of"
5316 .cindex "format" "user name"
5317 .cindex "groups" "name format"
5318 .cindex "format" "group name"
5319 User and group names are specified as strings, using the syntax described
5320 above, but the strings are interpreted specially. A user or group name must
5321 either consist entirely of digits, or be a name that can be looked up using the
5322 &[getpwnam()]& or &[getgrnam()]& function, as appropriate.
5323
5324
5325 .section "List construction" "SECTlistconstruct"
5326 .cindex "list" "syntax of in configuration"
5327 .cindex "format" "list item in configuration"
5328 .cindex "string" "list, definition of"
5329 The data for some configuration options is a list of items, with colon as the
5330 default separator. Many of these options are shown with type &"string list"& in
5331 the descriptions later in this document. Others are listed as &"domain list"&,
5332 &"host list"&, &"address list"&, or &"local part list"&. Syntactically, they
5333 are all the same; however, those other than &"string list"& are subject to
5334 particular kinds of interpretation, as described in chapter
5335 &<<CHAPdomhosaddlists>>&.
5336
5337 In all these cases, the entire list is treated as a single string as far as the
5338 input syntax is concerned. The &%trusted_users%& setting in section
5339 &<<SECTstrings>>& above is an example. If a colon is actually needed in an item
5340 in a list, it must be entered as two colons. Leading and trailing white space
5341 on each item in a list is ignored. This makes it possible to include items that
5342 start with a colon, and in particular, certain forms of IPv6 address. For
5343 example, the list
5344 .code
5345 local_interfaces = 127.0.0.1 : ::::1
5346 .endd
5347 contains two IP addresses, the IPv4 address 127.0.0.1 and the IPv6 address ::1.
5348
5349 &*Note*&: Although leading and trailing white space is ignored in individual
5350 list items, it is not ignored when parsing the list. The space after the first
5351 colon in the example above is necessary. If it were not there, the list would
5352 be interpreted as the two items 127.0.0.1:: and 1.
5353
5354 .section "Changing list separators" "SECTlistsepchange"
5355 .cindex "list separator" "changing"
5356 .cindex "IPv6" "addresses in lists"
5357 Doubling colons in IPv6 addresses is an unwelcome chore, so a mechanism was
5358 introduced to allow the separator character to be changed. If a list begins
5359 with a left angle bracket, followed by any punctuation character, that
5360 character is used instead of colon as the list separator. For example, the list
5361 above can be rewritten to use a semicolon separator like this:
5362 .code
5363 local_interfaces = <; 127.0.0.1 ; ::1
5364 .endd
5365 This facility applies to all lists, with the exception of the list in
5366 &%log_file_path%&. It is recommended that the use of non-colon separators be
5367 confined to circumstances where they really are needed.
5368
5369 .cindex "list separator" "newline as"
5370 .cindex "newline" "as list separator"
5371 It is also possible to use newline and other control characters (those with
5372 code values less than 32, plus DEL) as separators in lists. Such separators
5373 must be provided literally at the time the list is processed. For options that
5374 are string-expanded, you can write the separator using a normal escape
5375 sequence. This will be processed by the expander before the string is
5376 interpreted as a list. For example, if a newline-separated list of domains is
5377 generated by a lookup, you can process it directly by a line such as this:
5378 .code
5379 domains = <\n ${lookup mysql{.....}}
5380 .endd
5381 This avoids having to change the list separator in such data. You are unlikely
5382 to want to use a control character as a separator in an option that is not
5383 expanded, because the value is literal text. However, it can be done by giving
5384 the value in quotes. For example:
5385 .code
5386 local_interfaces = "<\n 127.0.0.1 \n ::1"
5387 .endd
5388 Unlike printing character separators, which can be included in list items by
5389 doubling, it is not possible to include a control character as data when it is
5390 set as the separator. Two such characters in succession are interpreted as
5391 enclosing an empty list item.
5392
5393
5394
5395 .section "Empty items in lists" "SECTempitelis"
5396 .cindex "list" "empty item in"
5397 An empty item at the end of a list is always ignored. In other words, trailing
5398 separator characters are ignored. Thus, the list in
5399 .code
5400 senders = user@domain :
5401 .endd
5402 contains only a single item. If you want to include an empty string as one item
5403 in a list, it must not be the last item. For example, this list contains three
5404 items, the second of which is empty:
5405 .code
5406 senders = user1@domain : : user2@domain
5407 .endd
5408 &*Note*&: There must be white space between the two colons, as otherwise they
5409 are interpreted as representing a single colon data character (and the list
5410 would then contain just one item). If you want to specify a list that contains
5411 just one, empty item, you can do it as in this example:
5412 .code
5413 senders = :
5414 .endd
5415 In this case, the first item is empty, and the second is discarded because it
5416 is at the end of the list.
5417
5418
5419
5420
5421 .section "Format of driver configurations" "SECTfordricon"
5422 .cindex "drivers" "configuration format"
5423 There are separate parts in the configuration for defining routers, transports,
5424 and authenticators. In each part, you are defining a number of driver
5425 instances, each with its own set of options. Each driver instance is defined by
5426 a sequence of lines like this:
5427 .display
5428 <&'instance name'&>:
5429   <&'option'&>
5430   ...
5431   <&'option'&>
5432 .endd
5433 In the following example, the instance name is &(localuser)&, and it is
5434 followed by three options settings:
5435 .code
5436 localuser:
5437   driver = accept
5438   check_local_user
5439   transport = local_delivery
5440 .endd
5441 For each driver instance, you specify which Exim code module it uses &-- by the
5442 setting of the &%driver%& option &-- and (optionally) some configuration
5443 settings. For example, in the case of transports, if you want a transport to
5444 deliver with SMTP you would use the &(smtp)& driver; if you want to deliver to
5445 a local file you would use the &(appendfile)& driver. Each of the drivers is
5446 described in detail in its own separate chapter later in this manual.
5447
5448 You can have several routers, transports, or authenticators that are based on
5449 the same underlying driver (each must have a different instance name).
5450
5451 The order in which routers are defined is important, because addresses are
5452 passed to individual routers one by one, in order. The order in which
5453 transports are defined does not matter at all. The order in which
5454 authenticators are defined is used only when Exim, as a client, is searching
5455 them to find one that matches an authentication mechanism offered by the
5456 server.
5457
5458 .cindex "generic options"
5459 .cindex "options" "generic &-- definition of"
5460 Within a driver instance definition, there are two kinds of option: &'generic'&
5461 and &'private'&. The generic options are those that apply to all drivers of the
5462 same type (that is, all routers, all transports or all authenticators). The
5463 &%driver%& option is a generic option that must appear in every definition.
5464 .cindex "private options"
5465 The private options are special for each driver, and none need appear, because
5466 they all have default values.
5467
5468 The options may appear in any order, except that the &%driver%& option must
5469 precede any private options, since these depend on the particular driver. For
5470 this reason, it is recommended that &%driver%& always be the first option.
5471
5472 Driver instance names, which are used for reference in log entries and
5473 elsewhere, can be any sequence of letters, digits, and underscores (starting
5474 with a letter) and must be unique among drivers of the same type. A router and
5475 a transport (for example) can each have the same name, but no two router
5476 instances can have the same name. The name of a driver instance should not be
5477 confused with the name of the underlying driver module. For example, the
5478 configuration lines:
5479 .code
5480 remote_smtp:
5481   driver = smtp
5482 .endd
5483 create an instance of the &(smtp)& transport driver whose name is
5484 &(remote_smtp)&. The same driver code can be used more than once, with
5485 different instance names and different option settings each time. A second
5486 instance of the &(smtp)& transport, with different options, might be defined
5487 thus:
5488 .code
5489 special_smtp:
5490   driver = smtp
5491   port = 1234
5492   command_timeout = 10s
5493 .endd
5494 The names &(remote_smtp)& and &(special_smtp)& would be used to reference
5495 these transport instances from routers, and these names would appear in log
5496 lines.
5497
5498 Comment lines may be present in the middle of driver specifications. The full
5499 list of option settings for any particular driver instance, including all the
5500 defaulted values, can be extracted by making use of the &%-bP%& command line
5501 option.
5502
5503
5504
5505
5506
5507
5508 . ////////////////////////////////////////////////////////////////////////////
5509 . ////////////////////////////////////////////////////////////////////////////
5510
5511 .chapter "The default configuration file" "CHAPdefconfil"
5512 .scindex IIDconfiwal "configuration file" "default &""walk through""&"
5513 .cindex "default" "configuration file &""walk through""&"
5514 The default configuration file supplied with Exim as &_src/configure.default_&
5515 is sufficient for a host with simple mail requirements. As an introduction to
5516 the way Exim is configured, this chapter &"walks through"& the default
5517 configuration, giving brief explanations of the settings. Detailed descriptions
5518 of the options are given in subsequent chapters. The default configuration file
5519 itself contains extensive comments about ways you might want to modify the
5520 initial settings. However, note that there are many options that are not
5521 mentioned at all in the default configuration.
5522
5523
5524
5525 .section "Main configuration settings" "SECTdefconfmain"
5526 The main (global) configuration option settings must always come first in the
5527 file. The first thing you'll see in the file, after some initial comments, is
5528 the line
5529 .code
5530 # primary_hostname =
5531 .endd
5532 This is a commented-out setting of the &%primary_hostname%& option. Exim needs
5533 to know the official, fully qualified name of your host, and this is where you
5534 can specify it. However, in most cases you do not need to set this option. When
5535 it is unset, Exim uses the &[uname()]& system function to obtain the host name.
5536
5537 The first three non-comment configuration lines are as follows:
5538 .code
5539 domainlist local_domains    = @
5540 domainlist relay_to_domains =
5541 hostlist   relay_from_hosts = 127.0.0.1
5542 .endd
5543 These are not, in fact, option settings. They are definitions of two named
5544 domain lists and one named host list. Exim allows you to give names to lists of
5545 domains, hosts, and email addresses, in order to make it easier to manage the
5546 configuration file (see section &<<SECTnamedlists>>&).
5547
5548 The first line defines a domain list called &'local_domains'&; this is used
5549 later in the configuration to identify domains that are to be delivered
5550 on the local host.
5551
5552 .cindex "@ in a domain list"
5553 There is just one item in this list, the string &"@"&. This is a special form
5554 of entry which means &"the name of the local host"&. Thus, if the local host is
5555 called &'a.host.example'&, mail to &'any.user@a.host.example'& is expected to
5556 be delivered locally. Because the local host's name is referenced indirectly,
5557 the same configuration file can be used on different hosts.
5558
5559 The second line defines a domain list called &'relay_to_domains'&, but the
5560 list itself is empty. Later in the configuration we will come to the part that
5561 controls mail relaying through the local host; it allows relaying to any
5562 domains in this list. By default, therefore, no relaying on the basis of a mail
5563 domain is permitted.
5564
5565 The third line defines a host list called &'relay_from_hosts'&. This list is
5566 used later in the configuration to permit relaying from any host or IP address
5567 that matches the list. The default contains just the IP address of the IPv4
5568 loopback interface, which means that processes on the local host are able to
5569 submit mail for relaying by sending it over TCP/IP to that interface. No other
5570 hosts are permitted to submit messages for relaying.
5571
5572 Just to be sure there's no misunderstanding: at this point in the configuration
5573 we aren't actually setting up any controls. We are just defining some domains
5574 and hosts that will be used in the controls that are specified later.
5575
5576 The next two configuration lines are genuine option settings:
5577 .code
5578 acl_smtp_rcpt = acl_check_rcpt
5579 acl_smtp_data = acl_check_data
5580 .endd
5581 These options specify &'Access Control Lists'& (ACLs) that are to be used
5582 during an incoming SMTP session for every recipient of a message (every RCPT
5583 command), and after the contents of the message have been received,
5584 respectively. The names of the lists are &'acl_check_rcpt'& and
5585 &'acl_check_data'&, and we will come to their definitions below, in the ACL
5586 section of the configuration. The RCPT ACL controls which recipients are
5587 accepted for an incoming message &-- if a configuration does not provide an ACL
5588 to check recipients, no SMTP mail can be accepted. The DATA ACL allows the
5589 contents of a message to be checked.
5590
5591 Two commented-out option settings are next:
5592 .code
5593 # av_scanner = clamd:/tmp/clamd
5594 # spamd_address = 127.0.0.1 783
5595 .endd
5596 These are example settings that can be used when Exim is compiled with the
5597 content-scanning extension. The first specifies the interface to the virus
5598 scanner, and the second specifies the interface to SpamAssassin. Further
5599 details are given in chapter &<<CHAPexiscan>>&.
5600
5601 Three more commented-out option settings follow:
5602 .code
5603 # tls_advertise_hosts = *
5604 # tls_certificate = /etc/ssl/exim.crt
5605 # tls_privatekey = /etc/ssl/exim.pem
5606 .endd
5607 These are example settings that can be used when Exim is compiled with
5608 support for TLS (aka SSL) as described in section &<<SECTinctlsssl>>&. The
5609 first one specifies the list of clients that are allowed to use TLS when
5610 connecting to this server; in this case the wildcard means all clients. The
5611 other options specify where Exim should find its TLS certificate and private
5612 key, which together prove the server's identity to any clients that connect.
5613 More details are given in chapter &<<CHAPTLS>>&.
5614
5615 Another two commented-out option settings follow:
5616 .code
5617 # daemon_smtp_ports = 25 : 465 : 587
5618 # tls_on_connect_ports = 465
5619 .endd
5620 .cindex "port" "465 and 587"
5621 .cindex "port" "for message submission"
5622 .cindex "message" "submission, ports for"
5623 .cindex "submissions protocol"
5624 .cindex "smtps protocol"
5625 .cindex "ssmtp protocol"
5626 .cindex "SMTP" "submissions protocol"
5627 .cindex "SMTP" "ssmtp protocol"
5628 .cindex "SMTP" "smtps protocol"
5629 These options provide better support for roaming users who wish to use this
5630 server for message submission. They are not much use unless you have turned on
5631 TLS (as described in the previous paragraph) and authentication (about which
5632 more in section &<<SECTdefconfauth>>&).
5633 Mail submission from mail clients (MUAs) should be separate from inbound mail
5634 to your domain (MX delivery) for various good reasons (eg, ability to impose
5635 much saner TLS protocol and ciphersuite requirements without unintended
5636 consequences).
5637 RFC 6409 (previously 4409) specifies use of port 587 for SMTP Submission,
5638 which uses STARTTLS, so this is the &"submission"& port.
5639 RFC 8314 specifies use of port 465 as the &"submissions"& protocol,
5640 which should be used in preference to 587.
5641 You should also consider deploying SRV records to help clients find
5642 these ports.
5643 Older names for &"submissions"& are &"smtps"& and &"ssmtp"&.
5644
5645 Two more commented-out options settings follow:
5646 .code
5647 # qualify_domain =
5648 # qualify_recipient =
5649 .endd
5650 The first of these specifies a domain that Exim uses when it constructs a
5651 complete email address from a local login name. This is often needed when Exim
5652 receives a message from a local process. If you do not set &%qualify_domain%&,
5653 the value of &%primary_hostname%& is used. If you set both of these options,
5654 you can have different qualification domains for sender and recipient
5655 addresses. If you set only the first one, its value is used in both cases.
5656
5657 .cindex "domain literal" "recognizing format"
5658 The following line must be uncommented if you want Exim to recognize
5659 addresses of the form &'user@[10.11.12.13]'& that is, with a &"domain literal"&
5660 (an IP address within square brackets) instead of a named domain.
5661 .code
5662 # allow_domain_literals
5663 .endd
5664 The RFCs still require this form, but many people think that in the modern
5665 Internet it makes little sense to permit mail to be sent to specific hosts by
5666 quoting their IP addresses. This ancient format has been used by people who
5667 try to abuse hosts by using them for unwanted relaying. However, some
5668 people believe there are circumstances (for example, messages addressed to
5669 &'postmaster'&) where domain literals are still useful.
5670
5671 The next configuration line is a kind of trigger guard:
5672 .code
5673 never_users = root
5674 .endd
5675 It specifies that no delivery must ever be run as the root user. The normal
5676 convention is to set up &'root'& as an alias for the system administrator. This
5677 setting is a guard against slips in the configuration.
5678 The list of users specified by &%never_users%& is not, however, the complete
5679 list; the build-time configuration in &_Local/Makefile_& has an option called
5680 FIXED_NEVER_USERS specifying a list that cannot be overridden. The
5681 contents of &%never_users%& are added to this list. By default
5682 FIXED_NEVER_USERS also specifies root.
5683
5684 When a remote host connects to Exim in order to send mail, the only information
5685 Exim has about the host's identity is its IP address. The next configuration
5686 line,
5687 .code
5688 host_lookup = *
5689 .endd
5690 specifies that Exim should do a reverse DNS lookup on all incoming connections,
5691 in order to get a host name. This improves the quality of the logging
5692 information, but if you feel it is too expensive, you can remove it entirely,
5693 or restrict the lookup to hosts on &"nearby"& networks.
5694 Note that it is not always possible to find a host name from an IP address,
5695 because not all DNS reverse zones are maintained, and sometimes DNS servers are
5696 unreachable.
5697
5698 The next two lines are concerned with &'ident'& callbacks, as defined by RFC
5699 1413 (hence their names):
5700 .code
5701 rfc1413_hosts = *
5702 rfc1413_query_timeout = 0s
5703 .endd
5704 These settings cause Exim to avoid ident callbacks for all incoming SMTP calls.
5705 Few hosts offer RFC1413 service these days; calls have to be
5706 terminated by a timeout and this needlessly delays the startup
5707 of an incoming SMTP connection.
5708 If you have hosts for which you trust RFC1413 and need this
5709 information, you can change this.
5710
5711 This line enables an efficiency SMTP option.  It is negotiated by clients
5712 and not expected to cause problems but can be disabled if needed.
5713 .code
5714 prdr_enable = true
5715 .endd
5716
5717 When Exim receives messages over SMTP connections, it expects all addresses to
5718 be fully qualified with a domain, as required by the SMTP definition. However,
5719 if you are running a server to which simple clients submit messages, you may
5720 find that they send unqualified addresses. The two commented-out options:
5721 .code
5722 # sender_unqualified_hosts =
5723 # recipient_unqualified_hosts =
5724 .endd
5725 show how you can specify hosts that are permitted to send unqualified sender
5726 and recipient addresses, respectively.
5727
5728 The &%log_selector%& option is used to increase the detail of logging
5729 over the default:
5730 .code
5731 log_selector = +smtp_protocol_error +smtp_syntax_error \
5732                +tls_certificate_verified
5733 .endd
5734
5735 The &%percent_hack_domains%& option is also commented out:
5736 .code
5737 # percent_hack_domains =
5738 .endd
5739 It provides a list of domains for which the &"percent hack"& is to operate.
5740 This is an almost obsolete form of explicit email routing. If you do not know
5741 anything about it, you can safely ignore this topic.
5742
5743 The next two settings in the main part of the default configuration are
5744 concerned with messages that have been &"frozen"& on Exim's queue. When a
5745 message is frozen, Exim no longer continues to try to deliver it. Freezing
5746 occurs when a bounce message encounters a permanent failure because the sender
5747 address of the original message that caused the bounce is invalid, so the
5748 bounce cannot be delivered. This is probably the most common case, but there
5749 are also other conditions that cause freezing, and frozen messages are not
5750 always bounce messages.
5751 .code
5752 ignore_bounce_errors_after = 2d
5753 timeout_frozen_after = 7d
5754 .endd
5755 The first of these options specifies that failing bounce messages are to be
5756 discarded after 2 days on the queue. The second specifies that any frozen
5757 message (whether a bounce message or not) is to be timed out (and discarded)
5758 after a week. In this configuration, the first setting ensures that no failing
5759 bounce message ever lasts a week.
5760
5761 Exim queues it's messages in a spool directory. If you expect to have
5762 large queues, you may consider using this option. It splits the spool
5763 directory into subdirectories to avoid file system degradation from
5764 many files in a single directory, resulting in better performance.
5765 Manual manipulation of queued messages becomes more complex (though fortunately
5766 not often needed).
5767 .code
5768 # split_spool_directory = true
5769 .endd
5770
5771 In an ideal world everybody follows the standards. For non-ASCII
5772 messages RFC 2047 is a standard, allowing a maximum line length of 76
5773 characters. Exim adheres that standard and won't process messages which
5774 violate this standard. (Even ${rfc2047:...} expansions will fail.)
5775 In particular, the Exim maintainers have had multiple reports of
5776 problems from Russian administrators of issues until they disable this
5777 check, because of some popular, yet buggy, mail composition software.
5778 .code
5779 # check_rfc2047_length = false
5780 .endd
5781
5782 If you need to be strictly RFC compliant you may wish to disable the
5783 8BITMIME advertisement. Use this, if you exchange mails with systems
5784 that are not 8-bit clean.
5785 .code
5786 # accept_8bitmime = false
5787 .endd
5788
5789 Libraries you use may depend on specific environment settings.  This
5790 imposes a security risk (e.g. PATH). There are two lists:
5791 &%keep_environment%& for the variables to import as they are, and
5792 &%add_environment%& for variables we want to set to a fixed value.
5793 Note that TZ is handled separately, by the $%timezone%$ runtime
5794 option and by the TIMEZONE_DEFAULT buildtime option.
5795 .code
5796 # keep_environment = ^LDAP
5797 # add_environment = PATH=/usr/bin::/bin
5798 .endd
5799
5800
5801 .section "ACL configuration" "SECID54"
5802 .cindex "default" "ACLs"
5803 .cindex "&ACL;" "default configuration"
5804 In the default configuration, the ACL section follows the main configuration.
5805 It starts with the line
5806 .code
5807 begin acl
5808 .endd
5809 and it contains the definitions of two ACLs, called &'acl_check_rcpt'& and
5810 &'acl_check_data'&, that were referenced in the settings of &%acl_smtp_rcpt%&
5811 and &%acl_smtp_data%& above.
5812
5813 .cindex "RCPT" "ACL for"
5814 The first ACL is used for every RCPT command in an incoming SMTP message. Each
5815 RCPT command specifies one of the message's recipients. The ACL statements
5816 are considered in order, until the recipient address is either accepted or
5817 rejected. The RCPT command is then accepted or rejected, according to the
5818 result of the ACL processing.
5819 .code
5820 acl_check_rcpt:
5821 .endd
5822 This line, consisting of a name terminated by a colon, marks the start of the
5823 ACL, and names it.
5824 .code
5825 accept  hosts = :
5826 .endd
5827 This ACL statement accepts the recipient if the sending host matches the list.
5828 But what does that strange list mean? It doesn't actually contain any host
5829 names or IP addresses. The presence of the colon puts an empty item in the
5830 list; Exim matches this only if the incoming message did not come from a remote
5831 host, because in that case, the remote hostname is empty. The colon is
5832 important. Without it, the list itself is empty, and can never match anything.
5833
5834 What this statement is doing is to accept unconditionally all recipients in
5835 messages that are submitted by SMTP from local processes using the standard
5836 input and output (that is, not using TCP/IP). A number of MUAs operate in this
5837 manner.
5838 .code
5839 deny    message       = Restricted characters in address
5840         domains       = +local_domains
5841         local_parts   = ^[.] : ^.*[@%!/|]
5842
5843 deny    message       = Restricted characters in address
5844         domains       = !+local_domains
5845         local_parts   = ^[./|] : ^.*[@%!] : ^.*/\\.\\./
5846 .endd
5847 These statements are concerned with local parts that contain any of the
5848 characters &"@"&, &"%"&, &"!"&, &"/"&, &"|"&, or dots in unusual places.
5849 Although these characters are entirely legal in local parts (in the case of
5850 &"@"& and leading dots, only if correctly quoted), they do not commonly occur
5851 in Internet mail addresses.
5852
5853 The first three have in the past been associated with explicitly routed
5854 addresses (percent is still sometimes used &-- see the &%percent_hack_domains%&
5855 option). Addresses containing these characters are regularly tried by spammers
5856 in an attempt to bypass relaying restrictions, and also by open relay testing
5857 programs. Unless you really need them it is safest to reject these characters
5858 at this early stage. This configuration is heavy-handed in rejecting these
5859 characters for all messages it accepts from remote hosts. This is a deliberate
5860 policy of being as safe as possible.
5861
5862 The first rule above is stricter, and is applied to messages that are addressed
5863 to one of the local domains handled by this host. This is implemented by the
5864 first condition, which restricts it to domains that are listed in the
5865 &'local_domains'& domain list. The &"+"& character is used to indicate a
5866 reference to a named list. In this configuration, there is just one domain in
5867 &'local_domains'&, but in general there may be many.
5868
5869 The second condition on the first statement uses two regular expressions to
5870 block local parts that begin with a dot or contain &"@"&, &"%"&, &"!"&, &"/"&,
5871 or &"|"&. If you have local accounts that include these characters, you will
5872 have to modify this rule.
5873
5874 Empty components (two dots in a row) are not valid in RFC 2822, but Exim
5875 allows them because they have been encountered in practice. (Consider the
5876 common convention of local parts constructed as
5877 &"&'first-initial.second-initial.family-name'&"& when applied to someone like
5878 the author of Exim, who has no second initial.) However, a local part starting
5879 with a dot or containing &"/../"& can cause trouble if it is used as part of a
5880 file name (for example, for a mailing list). This is also true for local parts
5881 that contain slashes. A pipe symbol can also be troublesome if the local part
5882 is incorporated unthinkingly into a shell command line.
5883
5884 The second rule above applies to all other domains, and is less strict. This
5885 allows your own users to send outgoing messages to sites that use slashes
5886 and vertical bars in their local parts. It blocks local parts that begin
5887 with a dot, slash, or vertical bar, but allows these characters within the
5888 local part. However, the sequence &"/../"& is barred. The use of &"@"&, &"%"&,
5889 and &"!"& is blocked, as before. The motivation here is to prevent your users
5890 (or your users' viruses) from mounting certain kinds of attack on remote sites.
5891 .code
5892 accept  local_parts   = postmaster
5893         domains       = +local_domains
5894 .endd
5895 This statement, which has two conditions, accepts an incoming address if the
5896 local part is &'postmaster'& and the domain is one of those listed in the
5897 &'local_domains'& domain list. The &"+"& character is used to indicate a
5898 reference to a named list. In this configuration, there is just one domain in
5899 &'local_domains'&, but in general there may be many.
5900
5901 The presence of this statement means that mail to postmaster is never blocked
5902 by any of the subsequent tests. This can be helpful while sorting out problems
5903 in cases where the subsequent tests are incorrectly denying access.
5904 .code
5905 require verify        = sender
5906 .endd
5907 This statement requires the sender address to be verified before any subsequent
5908 ACL statement can be used. If verification fails, the incoming recipient
5909 address is refused. Verification consists of trying to route the address, to
5910 see if a bounce message could be delivered to it. In the case of remote
5911 addresses, basic verification checks only the domain, but &'callouts'& can be
5912 used for more verification if required. Section &<<SECTaddressverification>>&
5913 discusses the details of address verification.
5914 .code
5915 accept  hosts         = +relay_from_hosts
5916         control       = submission
5917 .endd
5918 This statement accepts the address if the message is coming from one of the
5919 hosts that are defined as being allowed to relay through this host. Recipient
5920 verification is omitted here, because in many cases the clients are dumb MUAs
5921 that do not cope well with SMTP error responses. For the same reason, the
5922 second line specifies &"submission mode"& for messages that are accepted. This
5923 is described in detail in section &<<SECTsubmodnon>>&; it causes Exim to fix
5924 messages that are deficient in some way, for example, because they lack a
5925 &'Date:'& header line. If you are actually relaying out from MTAs, you should
5926 probably add recipient verification here, and disable submission mode.
5927 .code
5928 accept  authenticated = *
5929         control       = submission
5930 .endd
5931 This statement accepts the address if the client host has authenticated itself.
5932 Submission mode is again specified, on the grounds that such messages are most
5933 likely to come from MUAs. The default configuration does not define any
5934 authenticators, though it does include some nearly complete commented-out
5935 examples described in &<<SECTdefconfauth>>&. This means that no client can in
5936 fact authenticate until you complete the authenticator definitions.
5937 .code
5938 require message = relay not permitted
5939         domains = +local_domains : +relay_to_domains
5940 .endd
5941 This statement rejects the address if its domain is neither a local domain nor
5942 one of the domains for which this host is a relay.
5943 .code
5944 require verify = recipient
5945 .endd
5946 This statement requires the recipient address to be verified; if verification
5947 fails, the address is rejected.
5948 .code
5949 # deny    message     = rejected because $sender_host_address \
5950 #                       is in a black list at $dnslist_domain\n\
5951 #                       $dnslist_text
5952 #         dnslists    = black.list.example
5953 #
5954 # warn    dnslists    = black.list.example
5955 #         add_header  = X-Warning: $sender_host_address is in \
5956 #                       a black list at $dnslist_domain
5957 #         log_message = found in $dnslist_domain
5958 .endd
5959 These commented-out lines are examples of how you could configure Exim to check
5960 sending hosts against a DNS black list. The first statement rejects messages
5961 from blacklisted hosts, whereas the second just inserts a warning header
5962 line.
5963 .code
5964 # require verify = csa
5965 .endd
5966 This commented-out line is an example of how you could turn on client SMTP
5967 authorization (CSA) checking. Such checks do DNS lookups for special SRV
5968 records.
5969 .code
5970 accept
5971 .endd
5972 The final statement in the first ACL unconditionally accepts any recipient
5973 address that has successfully passed all the previous tests.
5974 .code
5975 acl_check_data:
5976 .endd
5977 This line marks the start of the second ACL, and names it. Most of the contents
5978 of this ACL are commented out:
5979 .code
5980 # deny    malware   = *
5981 #         message   = This message contains a virus \
5982 #                     ($malware_name).
5983 .endd
5984 These lines are examples of how to arrange for messages to be scanned for
5985 viruses when Exim has been compiled with the content-scanning extension, and a
5986 suitable virus scanner is installed. If the message is found to contain a
5987 virus, it is rejected with the given custom error message.
5988 .code
5989 # warn    spam      = nobody
5990 #         message   = X-Spam_score: $spam_score\n\
5991 #                     X-Spam_score_int: $spam_score_int\n\
5992 #                     X-Spam_bar: $spam_bar\n\
5993 #                     X-Spam_report: $spam_report
5994 .endd
5995 These lines are an example of how to arrange for messages to be scanned by
5996 SpamAssassin when Exim has been compiled with the content-scanning extension,
5997 and SpamAssassin has been installed. The SpamAssassin check is run with
5998 &`nobody`& as its user parameter, and the results are added to the message as a
5999 series of extra header line. In this case, the message is not rejected,
6000 whatever the spam score.
6001 .code
6002 accept
6003 .endd
6004 This final line in the DATA ACL accepts the message unconditionally.
6005
6006
6007 .section "Router configuration" "SECID55"
6008 .cindex "default" "routers"
6009 .cindex "routers" "default"
6010 The router configuration comes next in the default configuration, introduced
6011 by the line
6012 .code
6013 begin routers
6014 .endd
6015 Routers are the modules in Exim that make decisions about where to send
6016 messages. An address is passed to each router in turn, until it is either
6017 accepted, or failed. This means that the order in which you define the routers
6018 matters. Each router is fully described in its own chapter later in this
6019 manual. Here we give only brief overviews.
6020 .code
6021 # domain_literal:
6022 #   driver = ipliteral
6023 #   domains = !+local_domains
6024 #   transport = remote_smtp
6025 .endd
6026 .cindex "domain literal" "default router"
6027 This router is commented out because the majority of sites do not want to
6028 support domain literal addresses (those of the form &'user@[10.9.8.7]'&). If
6029 you uncomment this router, you also need to uncomment the setting of
6030 &%allow_domain_literals%& in the main part of the configuration.
6031 .code
6032 dnslookup:
6033   driver = dnslookup
6034   domains = ! +local_domains
6035   transport = remote_smtp
6036   ignore_target_hosts = 0.0.0.0 : 127.0.0.0/8
6037   no_more
6038 .endd
6039 The first uncommented router handles addresses that do not involve any local
6040 domains. This is specified by the line
6041 .code
6042 domains = ! +local_domains
6043 .endd
6044 The &%domains%& option lists the domains to which this router applies, but the
6045 exclamation mark is a negation sign, so the router is used only for domains
6046 that are not in the domain list called &'local_domains'& (which was defined at
6047 the start of the configuration). The plus sign before &'local_domains'&
6048 indicates that it is referring to a named list. Addresses in other domains are
6049 passed on to the following routers.
6050
6051 The name of the router driver is &(dnslookup)&,
6052 and is specified by the &%driver%& option. Do not be confused by the fact that
6053 the name of this router instance is the same as the name of the driver. The
6054 instance name is arbitrary, but the name set in the &%driver%& option must be
6055 one of the driver modules that is in the Exim binary.
6056
6057 The &(dnslookup)& router routes addresses by looking up their domains in the
6058 DNS in order to obtain a list of hosts to which the address is routed. If the
6059 router succeeds, the address is queued for the &(remote_smtp)& transport, as
6060 specified by the &%transport%& option. If the router does not find the domain
6061 in the DNS, no further routers are tried because of the &%no_more%& setting, so
6062 the address fails and is bounced.
6063
6064 The &%ignore_target_hosts%& option specifies a list of IP addresses that are to
6065 be entirely ignored. This option is present because a number of cases have been
6066 encountered where MX records in the DNS point to host names
6067 whose IP addresses are 0.0.0.0 or are in the 127 subnet (typically 127.0.0.1).
6068 Completely ignoring these IP addresses causes Exim to fail to route the
6069 email address, so it bounces. Otherwise, Exim would log a routing problem, and
6070 continue to try to deliver the message periodically until the address timed
6071 out.
6072 .code
6073 system_aliases:
6074   driver = redirect
6075   allow_fail
6076   allow_defer
6077   data = ${lookup{$local_part}lsearch{/etc/aliases}}
6078 # user = exim
6079   file_transport = address_file
6080   pipe_transport = address_pipe
6081 .endd
6082 Control reaches this and subsequent routers only for addresses in the local
6083 domains. This router checks to see whether the local part is defined as an
6084 alias in the &_/etc/aliases_& file, and if so, redirects it according to the
6085 data that it looks up from that file. If no data is found for the local part,
6086 the value of the &%data%& option is empty, causing the address to be passed to
6087 the next router.
6088
6089 &_/etc/aliases_& is a conventional name for the system aliases file that is
6090 often used. That is why it is referenced by from the default configuration
6091 file. However, you can change this by setting SYSTEM_ALIASES_FILE in
6092 &_Local/Makefile_& before building Exim.
6093 .code
6094 userforward:
6095   driver = redirect
6096   check_local_user
6097 # local_part_suffix = +* : -*
6098 # local_part_suffix_optional
6099   file = $home/.forward
6100 # allow_filter
6101   no_verify
6102   no_expn
6103   check_ancestor
6104   file_transport = address_file
6105   pipe_transport = address_pipe
6106   reply_transport = address_reply
6107 .endd
6108 This is the most complicated router in the default configuration. It is another
6109 redirection router, but this time it is looking for forwarding data set up by
6110 individual users. The &%check_local_user%& setting specifies a check that the
6111 local part of the address is the login name of a local user. If it is not, the
6112 router is skipped. The two commented options that follow &%check_local_user%&,
6113 namely:
6114 .code
6115 # local_part_suffix = +* : -*
6116 # local_part_suffix_optional
6117 .endd
6118 .vindex "&$local_part_suffix$&"
6119 show how you can specify the recognition of local part suffixes. If the first
6120 is uncommented, a suffix beginning with either a plus or a minus sign, followed
6121 by any sequence of characters, is removed from the local part and placed in the
6122 variable &$local_part_suffix$&. The second suffix option specifies that the
6123 presence of a suffix in the local part is optional. When a suffix is present,
6124 the check for a local login uses the local part with the suffix removed.
6125
6126 When a local user account is found, the file called &_.forward_& in the user's
6127 home directory is consulted. If it does not exist, or is empty, the router
6128 declines. Otherwise, the contents of &_.forward_& are interpreted as
6129 redirection data (see chapter &<<CHAPredirect>>& for more details).
6130
6131 .cindex "Sieve filter" "enabling in default router"
6132 Traditional &_.forward_& files contain just a list of addresses, pipes, or
6133 files. Exim supports this by default. However, if &%allow_filter%& is set (it
6134 is commented out by default), the contents of the file are interpreted as a set
6135 of Exim or Sieve filtering instructions, provided the file begins with &"#Exim
6136 filter"& or &"#Sieve filter"&, respectively. User filtering is discussed in the
6137 separate document entitled &'Exim's interfaces to mail filtering'&.
6138
6139 The &%no_verify%& and &%no_expn%& options mean that this router is skipped when
6140 verifying addresses, or when running as a consequence of an SMTP EXPN command.
6141 There are two reasons for doing this:
6142
6143 .olist
6144 Whether or not a local user has a &_.forward_& file is not really relevant when
6145 checking an address for validity; it makes sense not to waste resources doing
6146 unnecessary work.
6147 .next
6148 More importantly, when Exim is verifying addresses or handling an EXPN
6149 command during an SMTP session, it is running as the Exim user, not as root.
6150 The group is the Exim group, and no additional groups are set up.
6151 It may therefore not be possible for Exim to read users' &_.forward_& files at
6152 this time.
6153 .endlist
6154
6155 The setting of &%check_ancestor%& prevents the router from generating a new
6156 address that is the same as any previous address that was redirected. (This
6157 works round a problem concerning a bad interaction between aliasing and
6158 forwarding &-- see section &<<SECTredlocmai>>&).
6159
6160 The final three option settings specify the transports that are to be used when
6161 forwarding generates a direct delivery to a file, or to a pipe, or sets up an
6162 auto-reply, respectively. For example, if a &_.forward_& file contains
6163 .code
6164 a.nother@elsewhere.example, /home/spqr/archive
6165 .endd
6166 the delivery to &_/home/spqr/archive_& is done by running the &%address_file%&
6167 transport.
6168 .code
6169 localuser:
6170   driver = accept
6171   check_local_user
6172 # local_part_suffix = +* : -*
6173 # local_part_suffix_optional
6174   transport = local_delivery
6175 .endd
6176 The final router sets up delivery into local mailboxes, provided that the local
6177 part is the name of a local login, by accepting the address and assigning it to
6178 the &(local_delivery)& transport. Otherwise, we have reached the end of the
6179 routers, so the address is bounced. The commented suffix settings fulfil the
6180 same purpose as they do for the &(userforward)& router.
6181
6182
6183 .section "Transport configuration" "SECID56"
6184 .cindex "default" "transports"
6185 .cindex "transports" "default"
6186 Transports define mechanisms for actually delivering messages. They operate
6187 only when referenced from routers, so the order in which they are defined does
6188 not matter. The transports section of the configuration starts with
6189 .code
6190 begin transports
6191 .endd
6192 One remote transport and four local transports are defined.
6193 .code
6194 remote_smtp:
6195   driver = smtp
6196   hosts_try_prdr = *
6197 .endd
6198 This transport is used for delivering messages over SMTP connections.
6199 The list of remote hosts comes from the router.
6200 The &%hosts_try_prdr%& option enables an efficiency SMTP option.
6201 It is negotiated between client and server
6202 and not expected to cause problems but can be disabled if needed.
6203 All other options are defaulted.
6204 .code
6205 local_delivery:
6206   driver = appendfile
6207   file = /var/mail/$local_part
6208   delivery_date_add
6209   envelope_to_add
6210   return_path_add
6211 # group = mail
6212 # mode = 0660
6213 .endd
6214 This &(appendfile)& transport is used for local delivery to user mailboxes in
6215 traditional BSD mailbox format. By default it runs under the uid and gid of the
6216 local user, which requires the sticky bit to be set on the &_/var/mail_&
6217 directory. Some systems use the alternative approach of running mail deliveries
6218 under a particular group instead of using the sticky bit. The commented options
6219 show how this can be done.
6220
6221 Exim adds three headers to the message as it delivers it: &'Delivery-date:'&,
6222 &'Envelope-to:'& and &'Return-path:'&. This action is requested by the three
6223 similarly-named options above.
6224 .code
6225 address_pipe:
6226   driver = pipe
6227   return_output
6228 .endd
6229 This transport is used for handling deliveries to pipes that are generated by
6230 redirection (aliasing or users' &_.forward_& files). The &%return_output%&
6231 option specifies that any output on stdout or stderr generated by the pipe is to
6232 be returned to the sender.
6233 .code
6234 address_file:
6235   driver = appendfile
6236   delivery_date_add
6237   envelope_to_add
6238   return_path_add
6239 .endd
6240 This transport is used for handling deliveries to files that are generated by
6241 redirection. The name of the file is not specified in this instance of
6242 &(appendfile)&, because it comes from the &(redirect)& router.
6243 .code
6244 address_reply:
6245   driver = autoreply
6246 .endd
6247 This transport is used for handling automatic replies generated by users'
6248 filter files.
6249
6250
6251
6252 .section "Default retry rule" "SECID57"
6253 .cindex "retry" "default rule"
6254 .cindex "default" "retry rule"
6255 The retry section of the configuration file contains rules which affect the way
6256 Exim retries deliveries that cannot be completed at the first attempt. It is
6257 introduced by the line
6258 .code
6259 begin retry
6260 .endd
6261 In the default configuration, there is just one rule, which applies to all
6262 errors:
6263 .code
6264 *   *   F,2h,15m; G,16h,1h,1.5; F,4d,6h
6265 .endd
6266 This causes any temporarily failing address to be retried every 15 minutes for
6267 2 hours, then at intervals starting at one hour and increasing by a factor of
6268 1.5 until 16 hours have passed, then every 6 hours up to 4 days. If an address
6269 is not delivered after 4 days of temporary failure, it is bounced. The time is
6270 measured from first failure, not from the time the message was received.
6271
6272 If the retry section is removed from the configuration, or is empty (that is,
6273 if no retry rules are defined), Exim will not retry deliveries. This turns
6274 temporary errors into permanent errors.
6275
6276
6277 .section "Rewriting configuration" "SECID58"
6278 The rewriting section of the configuration, introduced by
6279 .code
6280 begin rewrite
6281 .endd
6282 contains rules for rewriting addresses in messages as they arrive. There are no
6283 rewriting rules in the default configuration file.
6284
6285
6286
6287 .section "Authenticators configuration" "SECTdefconfauth"
6288 .cindex "AUTH" "configuration"
6289 The authenticators section of the configuration, introduced by
6290 .code
6291 begin authenticators
6292 .endd
6293 defines mechanisms for the use of the SMTP AUTH command. The default
6294 configuration file contains two commented-out example authenticators
6295 which support plaintext username/password authentication using the
6296 standard PLAIN mechanism and the traditional but non-standard LOGIN
6297 mechanism, with Exim acting as the server. PLAIN and LOGIN are enough
6298 to support most MUA software.
6299
6300 The example PLAIN authenticator looks like this:
6301 .code
6302 #PLAIN:
6303 #  driver                  = plaintext
6304 #  server_set_id           = $auth2
6305 #  server_prompts          = :
6306 #  server_condition        = Authentication is not yet configured
6307 #  server_advertise_condition = ${if def:tls_in_cipher }
6308 .endd
6309 And the example LOGIN authenticator looks like this:
6310 .code
6311 #LOGIN:
6312 #  driver                  = plaintext
6313 #  server_set_id           = $auth1
6314 #  server_prompts          = <| Username: | Password:
6315 #  server_condition        = Authentication is not yet configured
6316 #  server_advertise_condition = ${if def:tls_in_cipher }
6317 .endd
6318
6319 The &%server_set_id%& option makes Exim remember the authenticated username
6320 in &$authenticated_id$&, which can be used later in ACLs or routers. The
6321 &%server_prompts%& option configures the &(plaintext)& authenticator so
6322 that it implements the details of the specific authentication mechanism,
6323 i.e. PLAIN or LOGIN. The &%server_advertise_condition%& setting controls
6324 when Exim offers authentication to clients; in the examples, this is only
6325 when TLS or SSL has been started, so to enable the authenticators you also
6326 need to add support for TLS as described in section &<<SECTdefconfmain>>&.
6327
6328 The &%server_condition%& setting defines how to verify that the username and
6329 password are correct. In the examples it just produces an error message.
6330 To make the authenticators work, you can use a string expansion
6331 expression like one of the examples in chapter &<<CHAPplaintext>>&.
6332
6333 Beware that the sequence of the parameters to PLAIN and LOGIN differ; the
6334 usercode and password are in different positions.
6335 Chapter &<<CHAPplaintext>>& covers both.
6336
6337 .ecindex IIDconfiwal
6338
6339
6340
6341 . ////////////////////////////////////////////////////////////////////////////
6342 . ////////////////////////////////////////////////////////////////////////////
6343
6344 .chapter "Regular expressions" "CHAPregexp"
6345
6346 .cindex "regular expressions" "library"
6347 .cindex "PCRE"
6348 Exim supports the use of regular expressions in many of its options. It
6349 uses the PCRE regular expression library; this provides regular expression
6350 matching that is compatible with Perl 5. The syntax and semantics of
6351 regular expressions is discussed in
6352 online Perl manpages, in
6353 many Perl reference books, and also in
6354 Jeffrey Friedl's &'Mastering Regular Expressions'&, which is published by
6355 O'Reilly (see &url(http://www.oreilly.com/catalog/regex2/)).
6356 . --- the http: URL here redirects to another page with the ISBN in the URL
6357 . --- where trying to use https: just redirects back to http:, so sticking
6358 . --- to the old URL for now.  2018-09-07.
6359
6360 The documentation for the syntax and semantics of the regular expressions that
6361 are supported by PCRE is included in the PCRE distribution, and no further
6362 description is included here. The PCRE functions are called from Exim using
6363 the default option settings (that is, with no PCRE options set), except that
6364 the PCRE_CASELESS option is set when the matching is required to be
6365 case-insensitive.
6366
6367 In most cases, when a regular expression is required in an Exim configuration,
6368 it has to start with a circumflex, in order to distinguish it from plain text
6369 or an &"ends with"& wildcard. In this example of a configuration setting, the
6370 second item in the colon-separated list is a regular expression.
6371 .code
6372 domains = a.b.c : ^\\d{3} : *.y.z : ...
6373 .endd
6374 The doubling of the backslash is required because of string expansion that
6375 precedes interpretation &-- see section &<<SECTlittext>>& for more discussion
6376 of this issue, and a way of avoiding the need for doubling backslashes. The
6377 regular expression that is eventually used in this example contains just one
6378 backslash. The circumflex is included in the regular expression, and has the
6379 normal effect of &"anchoring"& it to the start of the string that is being
6380 matched.
6381
6382 There are, however, two cases where a circumflex is not required for the
6383 recognition of a regular expression: these are the &%match%& condition in a
6384 string expansion, and the &%matches%& condition in an Exim filter file. In
6385 these cases, the relevant string is always treated as a regular expression; if
6386 it does not start with a circumflex, the expression is not anchored, and can
6387 match anywhere in the subject string.
6388
6389 In all cases, if you want a regular expression to match at the end of a string,
6390 you must code the $ metacharacter to indicate this. For example:
6391 .code
6392 domains = ^\\d{3}\\.example
6393 .endd
6394 matches the domain &'123.example'&, but it also matches &'123.example.com'&.
6395 You need to use:
6396 .code
6397 domains = ^\\d{3}\\.example\$
6398 .endd
6399 if you want &'example'& to be the top-level domain. The backslash before the
6400 $ is needed because string expansion also interprets dollar characters.
6401
6402
6403
6404 . ////////////////////////////////////////////////////////////////////////////
6405 . ////////////////////////////////////////////////////////////////////////////
6406
6407 .chapter "File and database lookups" "CHAPfdlookup"
6408 .scindex IIDfidalo1 "file" "lookups"
6409 .scindex IIDfidalo2 "database" "lookups"
6410 .cindex "lookup" "description of"
6411 Exim can be configured to look up data in files or databases as it processes
6412 messages. Two different kinds of syntax are used:
6413
6414 .olist
6415 A string that is to be expanded may contain explicit lookup requests. These
6416 cause parts of the string to be replaced by data that is obtained from the
6417 lookup. Lookups of this type are conditional expansion items. Different results
6418 can be defined for the cases of lookup success and failure. See chapter
6419 &<<CHAPexpand>>&, where string expansions are described in detail.
6420 The key for the lookup is specified as part of the string expansion.
6421 .next
6422 Lists of domains, hosts, and email addresses can contain lookup requests as a
6423 way of avoiding excessively long linear lists. In this case, the data that is
6424 returned by the lookup is often (but not always) discarded; whether the lookup
6425 succeeds or fails is what really counts. These kinds of list are described in
6426 chapter &<<CHAPdomhosaddlists>>&.
6427 The key for the lookup is given by the context in which the list is expanded.
6428 .endlist
6429
6430 String expansions, lists, and lookups interact with each other in such a way
6431 that there is no order in which to describe any one of them that does not
6432 involve references to the others. Each of these three chapters makes more sense
6433 if you have read the other two first. If you are reading this for the first
6434 time, be aware that some of it will make a lot more sense after you have read
6435 chapters &<<CHAPdomhosaddlists>>& and &<<CHAPexpand>>&.
6436
6437 .section "Examples of different lookup syntax" "SECID60"
6438 It is easy to confuse the two different kinds of lookup, especially as the
6439 lists that may contain the second kind are always expanded before being
6440 processed as lists. Therefore, they may also contain lookups of the first kind.
6441 Be careful to distinguish between the following two examples:
6442 .code
6443 domains = ${lookup{$sender_host_address}lsearch{/some/file}}
6444 domains = lsearch;/some/file
6445 .endd
6446 The first uses a string expansion, the result of which must be a domain list.
6447 No strings have been specified for a successful or a failing lookup; the
6448 defaults in this case are the looked-up data and an empty string, respectively.
6449 The expansion takes place before the string is processed as a list, and the
6450 file that is searched could contain lines like this:
6451 .code
6452 192.168.3.4: domain1:domain2:...
6453 192.168.1.9: domain3:domain4:...
6454 .endd
6455 When the lookup succeeds, the result of the expansion is a list of domains (and
6456 possibly other types of item that are allowed in domain lists).
6457
6458 In the second example, the lookup is a single item in a domain list. It causes
6459 Exim to use a lookup to see if the domain that is being processed can be found
6460 in the file. The file could contains lines like this:
6461 .code
6462 domain1:
6463 domain2:
6464 .endd
6465 Any data that follows the keys is not relevant when checking that the domain
6466 matches the list item.
6467
6468 It is possible, though no doubt confusing, to use both kinds of lookup at once.
6469 Consider a file containing lines like this:
6470 .code
6471 192.168.5.6: lsearch;/another/file
6472 .endd
6473 If the value of &$sender_host_address$& is 192.168.5.6, expansion of the
6474 first &%domains%& setting above generates the second setting, which therefore
6475 causes a second lookup to occur.
6476
6477 The rest of this chapter describes the different lookup types that are
6478 available. Any of them can be used in any part of the configuration where a
6479 lookup is permitted.
6480
6481
6482 .section "Lookup types" "SECID61"
6483 .cindex "lookup" "types of"
6484 .cindex "single-key lookup" "definition of"
6485 Two different types of data lookup are implemented:
6486
6487 .ilist
6488 The &'single-key'& type requires the specification of a file in which to look,
6489 and a single key to search for. The key must be a non-empty string for the
6490 lookup to succeed. The lookup type determines how the file is searched.
6491 .next
6492 .cindex "query-style lookup" "definition of"
6493 The &'query-style'& type accepts a generalized database query. No particular
6494 key value is assumed by Exim for query-style lookups. You can use whichever
6495 Exim variables you need to construct the database query.
6496 .endlist
6497
6498 The code for each lookup type is in a separate source file that is included in
6499 the binary of Exim only if the corresponding compile-time option is set. The
6500 default settings in &_src/EDITME_& are:
6501 .code
6502 LOOKUP_DBM=yes
6503 LOOKUP_LSEARCH=yes
6504 .endd
6505 which means that only linear searching and DBM lookups are included by default.
6506 For some types of lookup (e.g. SQL databases), you need to install appropriate
6507 libraries and header files before building Exim.
6508
6509
6510
6511
6512 .section "Single-key lookup types" "SECTsinglekeylookups"
6513 .cindex "lookup" "single-key types"
6514 .cindex "single-key lookup" "list of types"
6515 The following single-key lookup types are implemented:
6516
6517 .ilist
6518 .cindex "cdb" "description of"
6519 .cindex "lookup" "cdb"
6520 .cindex "binary zero" "in lookup key"
6521 &(cdb)&: The given file is searched as a Constant DataBase file, using the key
6522 string without a terminating binary zero. The cdb format is designed for
6523 indexed files that are read frequently and never updated, except by total
6524 re-creation. As such, it is particularly suitable for large files containing
6525 aliases or other indexed data referenced by an MTA. Information about cdb and
6526 tools for building the files can be found in several places:
6527 .display
6528 &url(https://cr.yp.to/cdb.html)
6529 &url(http://www.corpit.ru/mjt/tinycdb.html)
6530 &url(https://packages.debian.org/stable/utils/freecdb)
6531 &url(https://github.com/philpennock/cdbtools) (in Go)
6532 .endd
6533 . --- 2018-09-07: corpit.ru http:-only
6534 A cdb distribution is not needed in order to build Exim with cdb support,
6535 because the code for reading cdb files is included directly in Exim itself.
6536 However, no means of building or testing cdb files is provided with Exim, so
6537 you need to obtain a cdb distribution in order to do this.
6538 .next
6539 .cindex "DBM" "lookup type"
6540 .cindex "lookup" "dbm"
6541 .cindex "binary zero" "in lookup key"
6542 &(dbm)&: Calls to DBM library functions are used to extract data from the given
6543 DBM file by looking up the record with the given key. A terminating binary
6544 zero is included in the key that is passed to the DBM library. See section
6545 &<<SECTdb>>& for a discussion of DBM libraries.
6546
6547 .cindex "Berkeley DB library" "file format"
6548 For all versions of Berkeley DB, Exim uses the DB_HASH style of database
6549 when building DBM files using the &%exim_dbmbuild%& utility. However, when
6550 using Berkeley DB versions 3 or 4, it opens existing databases for reading with
6551 the DB_UNKNOWN option. This enables it to handle any of the types of database
6552 that the library supports, and can be useful for accessing DBM files created by
6553 other applications. (For earlier DB versions, DB_HASH is always used.)
6554 .next
6555 .cindex "lookup" "dbmjz"
6556 .cindex "lookup" "dbm &-- embedded NULs"
6557 .cindex "sasldb2"
6558 .cindex "dbmjz lookup type"
6559 &(dbmjz)&: This is the same as &(dbm)&, except that the lookup key is
6560 interpreted as an Exim list; the elements of the list are joined together with
6561 ASCII NUL characters to form the lookup key.  An example usage would be to
6562 authenticate incoming SMTP calls using the passwords from Cyrus SASL's
6563 &_/etc/sasldb2_& file with the &(gsasl)& authenticator or Exim's own
6564 &(cram_md5)& authenticator.
6565 .next
6566 .cindex "lookup" "dbmnz"
6567 .cindex "lookup" "dbm &-- terminating zero"
6568 .cindex "binary zero" "in lookup key"
6569 .cindex "Courier"
6570 .cindex "&_/etc/userdbshadow.dat_&"
6571 .cindex "dbmnz lookup type"
6572 &(dbmnz)&: This is the same as &(dbm)&, except that a terminating binary zero
6573 is not included in the key that is passed to the DBM library. You may need this
6574 if you want to look up data in files that are created by or shared with some
6575 other application that does not use terminating zeros. For example, you need to
6576 use &(dbmnz)& rather than &(dbm)& if you want to authenticate incoming SMTP
6577 calls using the passwords from Courier's &_/etc/userdbshadow.dat_& file. Exim's
6578 utility program for creating DBM files (&'exim_dbmbuild'&) includes the zeros
6579 by default, but has an option to omit them (see section &<<SECTdbmbuild>>&).
6580 .next
6581 .cindex "lookup" "dsearch"
6582 .cindex "dsearch lookup type"
6583 &(dsearch)&: The given file must be a directory; this is searched for an entry
6584 whose name is the key by calling the &[lstat()]& function. The key may not
6585 contain any forward slash characters. If &[lstat()]& succeeds, the result of
6586 the lookup is the name of the entry, which may be a file, directory,
6587 symbolic link, or any other kind of directory entry. An example of how this
6588 lookup can be used to support virtual domains is given in section
6589 &<<SECTvirtualdomains>>&.
6590 .next
6591 .cindex "lookup" "iplsearch"
6592 .cindex "iplsearch lookup type"
6593 &(iplsearch)&: The given file is a text file containing keys and data. A key is
6594 terminated by a colon or white space or the end of the line. The keys in the
6595 file must be IP addresses, or IP addresses with CIDR masks. Keys that involve
6596 IPv6 addresses must be enclosed in quotes to prevent the first internal colon
6597 being interpreted as a key terminator. For example:
6598 .code
6599 1.2.3.4:           data for 1.2.3.4
6600 192.168.0.0/16:    data for 192.168.0.0/16
6601 "abcd::cdab":      data for abcd::cdab
6602 "abcd:abcd::/32"   data for abcd:abcd::/32
6603 .endd
6604 The key for an &(iplsearch)& lookup must be an IP address (without a mask). The
6605 file is searched linearly, using the CIDR masks where present, until a matching
6606 key is found. The first key that matches is used; there is no attempt to find a
6607 &"best"& match. Apart from the way the keys are matched, the processing for
6608 &(iplsearch)& is the same as for &(lsearch)&.
6609
6610 &*Warning 1*&: Unlike most other single-key lookup types, a file of data for
6611 &(iplsearch)& can &'not'& be turned into a DBM or cdb file, because those
6612 lookup types support only literal keys.
6613
6614 &*Warning 2*&: In a host list, you must always use &(net-iplsearch)& so that
6615 the implicit key is the host's IP address rather than its name (see section
6616 &<<SECThoslispatsikey>>&).
6617 .next
6618 .new
6619 .cindex lookup json
6620 .cindex json "lookup type"
6621 .cindex JSON expansions
6622 &(json)&: The given file is a text file with a JSON structure.
6623 An element of the structure is extracted, defined by the search key.
6624 The key is a list of subelement selectors
6625 (colon-separated by default but changeable in the usual way)
6626 which are applied in turn to select smaller and smaller portions
6627 of the JSON structure.
6628 If a selector is numeric, it must apply to a JSON array; the (zero-based)
6629 nunbered array element is selected.
6630 Otherwise it must apply to a JSON object; the named element is selected.
6631 The final resulting object can be a simple JSOM type or a JSON object
6632 or array; for the latter two a string-representation os the JSON
6633 is returned.
6634 .wen
6635 .next
6636 .cindex "linear search"
6637 .cindex "lookup" "lsearch"
6638 .cindex "lsearch lookup type"
6639 .cindex "case sensitivity" "in lsearch lookup"
6640 &(lsearch)&: The given file is a text file that is searched linearly for a
6641 line beginning with the search key, terminated by a colon or white space or the
6642 end of the line. The search is case-insensitive; that is, upper and lower case
6643 letters are treated as the same. The first occurrence of the key that is found
6644 in the file is used.
6645
6646 White space between the key and the colon is permitted. The remainder of the
6647 line, with leading and trailing white space removed, is the data. This can be
6648 continued onto subsequent lines by starting them with any amount of white
6649 space, but only a single space character is included in the data at such a
6650 junction. If the data begins with a colon, the key must be terminated by a
6651 colon, for example:
6652 .code
6653 baduser:  :fail:
6654 .endd
6655 Empty lines and lines beginning with # are ignored, even if they occur in the
6656 middle of an item. This is the traditional textual format of alias files. Note
6657 that the keys in an &(lsearch)& file are literal strings. There is no
6658 wildcarding of any kind.
6659
6660 .cindex "lookup" "lsearch &-- colons in keys"
6661 .cindex "white space" "in lsearch key"
6662 In most &(lsearch)& files, keys are not required to contain colons or #
6663 characters, or white space. However, if you need this feature, it is available.
6664 If a key begins with a doublequote character, it is terminated only by a
6665 matching quote (or end of line), and the normal escaping rules apply to its
6666 contents (see section &<<SECTstrings>>&). An optional colon is permitted after
6667 quoted keys (exactly as for unquoted keys). There is no special handling of
6668 quotes for the data part of an &(lsearch)& line.
6669
6670 .next
6671 .cindex "NIS lookup type"
6672 .cindex "lookup" "NIS"
6673 .cindex "binary zero" "in lookup key"
6674 &(nis)&: The given file is the name of a NIS map, and a NIS lookup is done with
6675 the given key, without a terminating binary zero. There is a variant called
6676 &(nis0)& which does include the terminating binary zero in the key. This is
6677 reportedly needed for Sun-style alias files. Exim does not recognize NIS
6678 aliases; the full map names must be used.
6679
6680 .next
6681 .cindex "wildlsearch lookup type"
6682 .cindex "lookup" "wildlsearch"
6683 .cindex "nwildlsearch lookup type"
6684 .cindex "lookup" "nwildlsearch"
6685 &(wildlsearch)& or &(nwildlsearch)&: These search a file linearly, like
6686 &(lsearch)&, but instead of being interpreted as a literal string, each key in
6687 the file may be wildcarded. The difference between these two lookup types is
6688 that for &(wildlsearch)&, each key in the file is string-expanded before being
6689 used, whereas for &(nwildlsearch)&, no expansion takes place.
6690
6691 .cindex "case sensitivity" "in (n)wildlsearch lookup"
6692 Like &(lsearch)&, the testing is done case-insensitively. However, keys in the
6693 file that are regular expressions can be made case-sensitive by the use of
6694 &`(-i)`& within the pattern. The following forms of wildcard are recognized:
6695
6696 . ==== As this is a nested list, any displays it contains must be indented
6697 . ==== as otherwise they are too far to the left.
6698
6699 .olist
6700 The string may begin with an asterisk to mean &"ends with"&. For example:
6701 .code
6702     *.a.b.c       data for anything.a.b.c
6703     *fish         data for anythingfish
6704 .endd
6705 .next
6706 The string may begin with a circumflex to indicate a regular expression. For
6707 example, for &(wildlsearch)&:
6708 .code
6709     ^\N\d+\.a\.b\N    data for <digits>.a.b
6710 .endd
6711 Note the use of &`\N`& to disable expansion of the contents of the regular
6712 expression. If you are using &(nwildlsearch)&, where the keys are not
6713 string-expanded, the equivalent entry is:
6714 .code
6715     ^\d+\.a\.b        data for <digits>.a.b
6716 .endd
6717 The case-insensitive flag is set at the start of compiling the regular
6718 expression, but it can be turned off by using &`(-i)`& at an appropriate point.
6719 For example, to make the entire pattern case-sensitive:
6720 .code
6721     ^(?-i)\d+\.a\.b        data for <digits>.a.b
6722 .endd
6723
6724 If the regular expression contains white space or colon characters, you must
6725 either quote it (see &(lsearch)& above), or represent these characters in other
6726 ways. For example, &`\s`& can be used for white space and &`\x3A`& for a
6727 colon. This may be easier than quoting, because if you quote, you have to
6728 escape all the backslashes inside the quotes.
6729
6730 &*Note*&: It is not possible to capture substrings in a regular expression
6731 match for later use, because the results of all lookups are cached. If a lookup
6732 is repeated, the result is taken from the cache, and no actual pattern matching
6733 takes place. The values of all the numeric variables are unset after a
6734 &((n)wildlsearch)& match.
6735
6736 .next
6737 Although I cannot see it being of much use, the general matching function that
6738 is used to implement &((n)wildlsearch)& means that the string may begin with a
6739 lookup name terminated by a semicolon, and followed by lookup data. For
6740 example:
6741 .code
6742     cdb;/some/file  data for keys that match the file
6743 .endd
6744 The data that is obtained from the nested lookup is discarded.
6745 .endlist olist
6746
6747 Keys that do not match any of these patterns are interpreted literally. The
6748 continuation rules for the data are the same as for &(lsearch)&, and keys may
6749 be followed by optional colons.
6750
6751 &*Warning*&: Unlike most other single-key lookup types, a file of data for
6752 &((n)wildlsearch)& can &'not'& be turned into a DBM or cdb file, because those
6753 lookup types support only literal keys.
6754
6755 .next
6756 .cindex "lookup" "spf"
6757 If Exim is built with SPF support, manual lookups can be done
6758 (as opposed to the standard ACL condition method.
6759 For details see section &<<SECSPF>>&.
6760 .endlist ilist
6761
6762
6763 .section "Query-style lookup types" "SECTquerystylelookups"
6764 .cindex "lookup" "query-style types"
6765 .cindex "query-style lookup" "list of types"
6766 The supported query-style lookup types are listed below. Further details about
6767 many of them are given in later sections.
6768
6769 .ilist
6770 .cindex "DNS" "as a lookup type"
6771 .cindex "lookup" "DNS"
6772 &(dnsdb)&: This does a DNS search for one or more records whose domain names
6773 are given in the supplied query. The resulting data is the contents of the
6774 records. See section &<<SECTdnsdb>>&.
6775 .next
6776 .cindex "InterBase lookup type"
6777 .cindex "lookup" "InterBase"
6778 &(ibase)&: This does a lookup in an InterBase database.
6779 .next
6780 .cindex "LDAP" "lookup type"
6781 .cindex "lookup" "LDAP"
6782 &(ldap)&: This does an LDAP lookup using a query in the form of a URL, and
6783 returns attributes from a single entry. There is a variant called &(ldapm)&
6784 that permits values from multiple entries to be returned. A third variant
6785 called &(ldapdn)& returns the Distinguished Name of a single entry instead of
6786 any attribute values. See section &<<SECTldap>>&.
6787 .next
6788 .cindex "MySQL" "lookup type"
6789 .cindex "lookup" "MySQL"
6790 &(mysql)&: The format of the query is an SQL statement that is passed to a
6791 MySQL database. See section &<<SECTsql>>&.
6792 .next
6793 .cindex "NIS+ lookup type"
6794 .cindex "lookup" "NIS+"
6795 &(nisplus)&: This does a NIS+ lookup using a query that can specify the name of
6796 the field to be returned. See section &<<SECTnisplus>>&.
6797 .next
6798 .cindex "Oracle" "lookup type"
6799 .cindex "lookup" "Oracle"
6800 &(oracle)&: The format of the query is an SQL statement that is passed to an
6801 Oracle database. See section &<<SECTsql>>&.
6802 .next
6803 .cindex "lookup" "passwd"
6804 .cindex "passwd lookup type"
6805 .cindex "&_/etc/passwd_&"
6806 &(passwd)& is a query-style lookup with queries that are just user names. The
6807 lookup calls &[getpwnam()]& to interrogate the system password data, and on
6808 success, the result string is the same as you would get from an &(lsearch)&
6809 lookup on a traditional &_/etc/passwd file_&, though with &`*`& for the
6810 password value. For example:
6811 .code
6812 *:42:42:King Rat:/home/kr:/bin/bash
6813 .endd
6814 .next
6815 .cindex "PostgreSQL lookup type"
6816 .cindex "lookup" "PostgreSQL"
6817 &(pgsql)&: The format of the query is an SQL statement that is passed to a
6818 PostgreSQL database. See section &<<SECTsql>>&.
6819
6820 .next
6821 .cindex "Redis lookup type"
6822 .cindex lookup Redis
6823 &(redis)&: The format of the query is either a simple get or simple set,
6824 passed to a Redis database. See section &<<SECTsql>>&.
6825
6826 .next
6827 .cindex "sqlite lookup type"
6828 .cindex "lookup" "sqlite"
6829 &(sqlite)&: The format of the query is a file name followed by an SQL statement
6830 that is passed to an SQLite database. See section &<<SECTsqlite>>&.
6831
6832 .next
6833 &(testdb)&: This is a lookup type that is used for testing Exim. It is
6834 not likely to be useful in normal operation.
6835 .next
6836 .cindex "whoson lookup type"
6837 .cindex "lookup" "whoson"
6838 . --- still http:-only, 2018-09-07
6839 &(whoson)&: &'Whoson'& (&url(http://whoson.sourceforge.net)) is a protocol that
6840 allows a server to check whether a particular (dynamically allocated) IP
6841 address is currently allocated to a known (trusted) user and, optionally, to
6842 obtain the identity of the said user. For SMTP servers, &'Whoson'& was popular
6843 at one time for &"POP before SMTP"& authentication, but that approach has been
6844 superseded by SMTP authentication. In Exim, &'Whoson'& can be used to implement
6845 &"POP before SMTP"& checking using ACL statements such as
6846 .code
6847 require condition = \
6848   ${lookup whoson {$sender_host_address}{yes}{no}}
6849 .endd
6850 The query consists of a single IP address. The value returned is the name of
6851 the authenticated user, which is stored in the variable &$value$&. However, in
6852 this example, the data in &$value$& is not used; the result of the lookup is
6853 one of the fixed strings &"yes"& or &"no"&.
6854 .endlist
6855
6856
6857
6858 .section "Temporary errors in lookups" "SECID63"
6859 .cindex "lookup" "temporary error in"
6860 Lookup functions can return temporary error codes if the lookup cannot be
6861 completed. For example, an SQL or LDAP database might be unavailable. For this
6862 reason, it is not advisable to use a lookup that might do this for critical
6863 options such as a list of local domains.
6864
6865 When a lookup cannot be completed in a router or transport, delivery
6866 of the message (to the relevant address) is deferred, as for any other
6867 temporary error. In other circumstances Exim may assume the lookup has failed,
6868 or may give up altogether.
6869
6870
6871
6872 .section "Default values in single-key lookups" "SECTdefaultvaluelookups"
6873 .cindex "wildcard lookups"
6874 .cindex "lookup" "default values"
6875 .cindex "lookup" "wildcard"
6876 .cindex "lookup" "* added to type"
6877 .cindex "default" "in single-key lookups"
6878 In this context, a &"default value"& is a value specified by the administrator
6879 that is to be used if a lookup fails.
6880
6881 &*Note:*& This section applies only to single-key lookups. For query-style
6882 lookups, the facilities of the query language must be used. An attempt to
6883 specify a default for a query-style lookup provokes an error.
6884
6885 If &"*"& is added to a single-key lookup type (for example, &%lsearch*%&)
6886 and the initial lookup fails, the key &"*"& is looked up in the file to
6887 provide a default value. See also the section on partial matching below.
6888
6889 .cindex "*@ with single-key lookup"
6890 .cindex "lookup" "*@ added to type"
6891 .cindex "alias file" "per-domain default"
6892 Alternatively, if &"*@"& is added to a single-key lookup type (for example
6893 &%dbm*@%&) then, if the initial lookup fails and the key contains an @
6894 character, a second lookup is done with everything before the last @ replaced
6895 by *. This makes it possible to provide per-domain defaults in alias files
6896 that include the domains in the keys. If the second lookup fails (or doesn't
6897 take place because there is no @ in the key), &"*"& is looked up.
6898 For example, a &(redirect)& router might contain:
6899 .code
6900 data = ${lookup{$local_part@$domain}lsearch*@{/etc/mix-aliases}}
6901 .endd
6902 Suppose the address that is being processed is &'jane@eyre.example'&. Exim
6903 looks up these keys, in this order:
6904 .code
6905 jane@eyre.example
6906 *@eyre.example
6907 *
6908 .endd
6909 The data is taken from whichever key it finds first. &*Note*&: In an
6910 &(lsearch)& file, this does not mean the first of these keys in the file. A
6911 complete scan is done for each key, and only if it is not found at all does
6912 Exim move on to try the next key.
6913
6914
6915
6916 .section "Partial matching in single-key lookups" "SECTpartiallookup"
6917 .cindex "partial matching"
6918 .cindex "wildcard lookups"
6919 .cindex "lookup" "partial matching"
6920 .cindex "lookup" "wildcard"
6921 .cindex "asterisk" "in search type"
6922 The normal operation of a single-key lookup is to search the file for an exact
6923 match with the given key. However, in a number of situations where domains are
6924 being looked up, it is useful to be able to do partial matching. In this case,
6925 information in the file that has a key starting with &"*."& is matched by any
6926 domain that ends with the components that follow the full stop. For example, if
6927 a key in a DBM file is
6928 .code
6929 *.dates.fict.example
6930 .endd
6931 then when partial matching is enabled this is matched by (amongst others)
6932 &'2001.dates.fict.example'& and &'1984.dates.fict.example'&. It is also matched
6933 by &'dates.fict.example'&, if that does not appear as a separate key in the
6934 file.
6935
6936 &*Note*&: Partial matching is not available for query-style lookups. It is
6937 also not available for any lookup items in address lists (see section
6938 &<<SECTaddresslist>>&).
6939
6940 Partial matching is implemented by doing a series of separate lookups using
6941 keys constructed by modifying the original subject key. This means that it can
6942 be used with any of the single-key lookup types, provided that
6943 partial matching keys
6944 beginning with a special prefix (default &"*."&) are included in the data file.
6945 Keys in the file that do not begin with the prefix are matched only by
6946 unmodified subject keys when partial matching is in use.
6947
6948 Partial matching is requested by adding the string &"partial-"& to the front of
6949 the name of a single-key lookup type, for example, &%partial-dbm%&. When this
6950 is done, the subject key is first looked up unmodified; if that fails, &"*."&
6951 is added at the start of the subject key, and it is looked up again. If that
6952 fails, further lookups are tried with dot-separated components removed from the
6953 start of the subject key, one-by-one, and &"*."& added on the front of what
6954 remains.
6955
6956 A minimum number of two non-* components are required. This can be adjusted
6957 by including a number before the hyphen in the search type. For example,
6958 &%partial3-lsearch%& specifies a minimum of three non-* components in the
6959 modified keys. Omitting the number is equivalent to &"partial2-"&. If the
6960 subject key is &'2250.dates.fict.example'& then the following keys are looked
6961 up when the minimum number of non-* components is two:
6962 .code
6963 2250.dates.fict.example
6964 *.2250.dates.fict.example
6965 *.dates.fict.example
6966 *.fict.example
6967 .endd
6968 As soon as one key in the sequence is successfully looked up, the lookup
6969 finishes.
6970
6971 .cindex "lookup" "partial matching &-- changing prefix"
6972 .cindex "prefix" "for partial matching"
6973 The use of &"*."& as the partial matching prefix is a default that can be
6974 changed. The motivation for this feature is to allow Exim to operate with file
6975 formats that are used by other MTAs. A different prefix can be supplied in
6976 parentheses instead of the hyphen after &"partial"&. For example:
6977 .code
6978 domains = partial(.)lsearch;/some/file
6979 .endd
6980 In this example, if the domain is &'a.b.c'&, the sequence of lookups is
6981 &`a.b.c`&, &`.a.b.c`&, and &`.b.c`& (the default minimum of 2 non-wild
6982 components is unchanged). The prefix may consist of any punctuation characters
6983 other than a closing parenthesis. It may be empty, for example:
6984 .code
6985 domains = partial1()cdb;/some/file
6986 .endd
6987 For this example, if the domain is &'a.b.c'&, the sequence of lookups is
6988 &`a.b.c`&, &`b.c`&, and &`c`&.
6989
6990 If &"partial0"& is specified, what happens at the end (when the lookup with
6991 just one non-wild component has failed, and the original key is shortened right
6992 down to the null string) depends on the prefix:
6993
6994 .ilist
6995 If the prefix has zero length, the whole lookup fails.
6996 .next
6997 If the prefix has length 1, a lookup for just the prefix is done. For
6998 example, the final lookup for &"partial0(.)"& is for &`.`& alone.
6999 .next
7000 Otherwise, if the prefix ends in a dot, the dot is removed, and the
7001 remainder is looked up. With the default prefix, therefore, the final lookup is
7002 for &"*"& on its own.
7003 .next
7004 Otherwise, the whole prefix is looked up.
7005 .endlist
7006
7007
7008 If the search type ends in &"*"& or &"*@"& (see section
7009 &<<SECTdefaultvaluelookups>>& above), the search for an ultimate default that
7010 this implies happens after all partial lookups have failed. If &"partial0"& is
7011 specified, adding &"*"& to the search type has no effect with the default
7012 prefix, because the &"*"& key is already included in the sequence of partial
7013 lookups. However, there might be a use for lookup types such as
7014 &"partial0(.)lsearch*"&.
7015
7016 The use of &"*"& in lookup partial matching differs from its use as a wildcard
7017 in domain lists and the like. Partial matching works only in terms of
7018 dot-separated components; a key such as &`*fict.example`&
7019 in a database file is useless, because the asterisk in a partial matching
7020 subject key is always followed by a dot.
7021
7022
7023
7024
7025 .section "Lookup caching" "SECID64"
7026 .cindex "lookup" "caching"
7027 .cindex "caching" "lookup data"
7028 Exim caches all lookup results in order to avoid needless repetition of
7029 lookups. However, because (apart from the daemon) Exim operates as a collection
7030 of independent, short-lived processes, this caching applies only within a
7031 single Exim process. There is no inter-process lookup caching facility.
7032
7033 For single-key lookups, Exim keeps the relevant files open in case there is
7034 another lookup that needs them. In some types of configuration this can lead to
7035 many files being kept open for messages with many recipients. To avoid hitting
7036 the operating system limit on the number of simultaneously open files, Exim
7037 closes the least recently used file when it needs to open more files than its
7038 own internal limit, which can be changed via the &%lookup_open_max%& option.
7039
7040 The single-key lookup files are closed and the lookup caches are flushed at
7041 strategic points during delivery &-- for example, after all routing is
7042 complete.
7043
7044
7045
7046
7047 .section "Quoting lookup data" "SECID65"
7048 .cindex "lookup" "quoting"
7049 .cindex "quoting" "in lookups"
7050 When data from an incoming message is included in a query-style lookup, there
7051 is the possibility of special characters in the data messing up the syntax of
7052 the query. For example, a NIS+ query that contains
7053 .code
7054 [name=$local_part]
7055 .endd
7056 will be broken if the local part happens to contain a closing square bracket.
7057 For NIS+, data can be enclosed in double quotes like this:
7058 .code
7059 [name="$local_part"]
7060 .endd
7061 but this still leaves the problem of a double quote in the data. The rule for
7062 NIS+ is that double quotes must be doubled. Other lookup types have different
7063 rules, and to cope with the differing requirements, an expansion operator
7064 of the following form is provided:
7065 .code
7066 ${quote_<lookup-type>:<string>}
7067 .endd
7068 For example, the safest way to write the NIS+ query is
7069 .code
7070 [name="${quote_nisplus:$local_part}"]
7071 .endd
7072 See chapter &<<CHAPexpand>>& for full coverage of string expansions. The quote
7073 operator can be used for all lookup types, but has no effect for single-key
7074 lookups, since no quoting is ever needed in their key strings.
7075
7076
7077
7078
7079 .section "More about dnsdb" "SECTdnsdb"
7080 .cindex "dnsdb lookup"
7081 .cindex "lookup" "dnsdb"
7082 .cindex "DNS" "as a lookup type"
7083 The &(dnsdb)& lookup type uses the DNS as its database. A simple query consists
7084 of a record type and a domain name, separated by an equals sign. For example,
7085 an expansion string could contain:
7086 .code
7087 ${lookup dnsdb{mx=a.b.example}{$value}fail}
7088 .endd
7089 If the lookup succeeds, the result is placed in &$value$&, which in this case
7090 is used on its own as the result. If the lookup does not succeed, the
7091 &`fail`& keyword causes a &'forced expansion failure'& &-- see section
7092 &<<SECTforexpfai>>& for an explanation of what this means.
7093
7094 The supported DNS record types are A, CNAME, MX, NS, PTR, SOA, SPF, SRV, TLSA
7095 and TXT, and, when Exim is compiled with IPv6 support, AAAA.
7096 If no type is given, TXT is assumed.
7097
7098 For any record type, if multiple records are found, the data is returned as a
7099 concatenation, with newline as the default separator. The order, of course,
7100 depends on the DNS resolver. You can specify a different separator character
7101 between multiple records by putting a right angle-bracket followed immediately
7102 by the new separator at the start of the query. For example:
7103 .code
7104 ${lookup dnsdb{>: a=host1.example}}
7105 .endd
7106 It is permitted to specify a space as the separator character. Further
7107 white space is ignored.
7108 For lookup types that return multiple fields per record,
7109 an alternate field separator can be specified using a comma after the main
7110 separator character, followed immediately by the field separator.
7111
7112 .cindex "PTR record" "in &(dnsdb)& lookup"
7113 When the type is PTR,
7114 the data can be an IP address, written as normal; inversion and the addition of
7115 &%in-addr.arpa%& or &%ip6.arpa%& happens automatically. For example:
7116 .code
7117 ${lookup dnsdb{ptr=192.168.4.5}{$value}fail}
7118 .endd
7119 If the data for a PTR record is not a syntactically valid IP address, it is not
7120 altered and nothing is added.
7121
7122 .cindex "MX record" "in &(dnsdb)& lookup"
7123 .cindex "SRV record" "in &(dnsdb)& lookup"
7124 For an MX lookup, both the preference value and the host name are returned for
7125 each record, separated by a space. For an SRV lookup, the priority, weight,
7126 port, and host name are returned for each record, separated by spaces.
7127 The field separator can be modified as above.
7128
7129 .cindex "TXT record" "in &(dnsdb)& lookup"
7130 .cindex "SPF record" "in &(dnsdb)& lookup"
7131 For TXT records with multiple items of data, only the first item is returned,
7132 unless a field separator is specified.
7133 To concatenate items without a separator, use a semicolon instead.
7134 For SPF records the
7135 default behaviour is to concatenate multiple items without using a separator.
7136 .code
7137 ${lookup dnsdb{>\n,: txt=a.b.example}}
7138 ${lookup dnsdb{>\n; txt=a.b.example}}
7139 ${lookup dnsdb{spf=example.org}}
7140 .endd
7141 It is permitted to specify a space as the separator character. Further
7142 white space is ignored.
7143
7144 .cindex "SOA record" "in &(dnsdb)& lookup"
7145 For an SOA lookup, while no result is obtained the lookup is redone with
7146 successively more leading components dropped from the given domain.
7147 Only the primary-nameserver field is returned unless a field separator is
7148 specified.
7149 .code
7150 ${lookup dnsdb{>:,; soa=a.b.example.com}}
7151 .endd
7152
7153 .section "Dnsdb lookup modifiers" "SECTdnsdb_mod"
7154 .cindex "dnsdb modifiers"
7155 .cindex "modifiers" "dnsdb"
7156 .cindex "options" "dnsdb"
7157 Modifiers for &(dnsdb)& lookups are given by optional keywords,
7158 each followed by a comma,
7159 that may appear before the record type.
7160
7161 The &(dnsdb)& lookup fails only if all the DNS lookups fail. If there is a
7162 temporary DNS error for any of them, the behaviour is controlled by
7163 a defer-option modifier.
7164 The possible keywords are
7165 &"defer_strict"&, &"defer_never"&, and &"defer_lax"&.
7166 With &"strict"& behaviour, any temporary DNS error causes the
7167 whole lookup to defer. With &"never"& behaviour, a temporary DNS error is
7168 ignored, and the behaviour is as if the DNS lookup failed to find anything.
7169 With &"lax"& behaviour, all the queries are attempted, but a temporary DNS
7170 error causes the whole lookup to defer only if none of the other lookups
7171 succeed. The default is &"lax"&, so the following lookups are equivalent:
7172 .code
7173 ${lookup dnsdb{defer_lax,a=one.host.com:two.host.com}}
7174 ${lookup dnsdb{a=one.host.com:two.host.com}}
7175 .endd
7176 Thus, in the default case, as long as at least one of the DNS lookups
7177 yields some data, the lookup succeeds.
7178
7179 .cindex "DNSSEC" "dns lookup"
7180 Use of &(DNSSEC)& is controlled by a dnssec modifier.
7181 The possible keywords are
7182 &"dnssec_strict"&, &"dnssec_lax"&, and &"dnssec_never"&.
7183 With &"strict"& or &"lax"& DNSSEC information is requested
7184 with the lookup.
7185 With &"strict"& a response from the DNS resolver that
7186 is not labelled as authenticated data
7187 is treated as equivalent to a temporary DNS error.
7188 The default is &"never"&.
7189
7190 See also the &$lookup_dnssec_authenticated$& variable.
7191
7192 .cindex timeout "dns lookup"
7193 .cindex "DNS" timeout
7194 Timeout for the dnsdb lookup can be controlled by a retrans modifier.
7195 The form is &"retrans_VAL"& where VAL is an Exim time specification
7196 (e.g. &"5s"&).
7197 The default value is set by the main configuration option &%dns_retrans%&.
7198
7199 Retries for the dnsdb lookup can be controlled by a retry modifier.
7200 The form if &"retry_VAL"& where VAL is an integer.
7201 The default count is set by the main configuration option &%dns_retry%&.
7202
7203 .cindex caching "of dns lookup"
7204 .cindex TTL "of dns lookup"
7205 .cindex DNS TTL
7206 Dnsdb lookup results are cached within a single process (and its children).
7207 The cache entry lifetime is limited to the smallest time-to-live (TTL)
7208 value of the set of returned DNS records.
7209
7210
7211 .section "Pseudo dnsdb record types" "SECID66"
7212 .cindex "MX record" "in &(dnsdb)& lookup"
7213 By default, both the preference value and the host name are returned for
7214 each MX record, separated by a space. If you want only host names, you can use
7215 the pseudo-type MXH:
7216 .code
7217 ${lookup dnsdb{mxh=a.b.example}}
7218 .endd
7219 In this case, the preference values are omitted, and just the host names are
7220 returned.
7221
7222 .cindex "name server for enclosing domain"
7223 Another pseudo-type is ZNS (for &"zone NS"&). It performs a lookup for NS
7224 records on the given domain, but if none are found, it removes the first
7225 component of the domain name, and tries again. This process continues until NS
7226 records are found or there are no more components left (or there is a DNS
7227 error). In other words, it may return the name servers for a top-level domain,
7228 but it never returns the root name servers. If there are no NS records for the
7229 top-level domain, the lookup fails. Consider these examples:
7230 .code
7231 ${lookup dnsdb{zns=xxx.quercite.com}}
7232 ${lookup dnsdb{zns=xxx.edu}}
7233 .endd
7234 Assuming that in each case there are no NS records for the full domain name,
7235 the first returns the name servers for &%quercite.com%&, and the second returns
7236 the name servers for &%edu%&.
7237
7238 You should be careful about how you use this lookup because, unless the
7239 top-level domain does not exist, the lookup always returns some host names. The
7240 sort of use to which this might be put is for seeing if the name servers for a
7241 given domain are on a blacklist. You can probably assume that the name servers
7242 for the high-level domains such as &%com%& or &%co.uk%& are not going to be on
7243 such a list.
7244
7245 .cindex "CSA" "in &(dnsdb)& lookup"
7246 A third pseudo-type is CSA (Client SMTP Authorization). This looks up SRV
7247 records according to the CSA rules, which are described in section
7248 &<<SECTverifyCSA>>&. Although &(dnsdb)& supports SRV lookups directly, this is
7249 not sufficient because of the extra parent domain search behaviour of CSA. The
7250 result of a successful lookup such as:
7251 .code
7252 ${lookup dnsdb {csa=$sender_helo_name}}
7253 .endd
7254 has two space-separated fields: an authorization code and a target host name.
7255 The authorization code can be &"Y"& for yes, &"N"& for no, &"X"& for explicit
7256 authorization required but absent, or &"?"& for unknown.
7257
7258 .cindex "A+" "in &(dnsdb)& lookup"
7259 The pseudo-type A+ performs an AAAA
7260 and then an A lookup.  All results are returned; defer processing
7261 (see below) is handled separately for each lookup.  Example:
7262 .code
7263 ${lookup dnsdb {>; a+=$sender_helo_name}}
7264 .endd
7265
7266
7267 .section "Multiple dnsdb lookups" "SECID67"
7268 In the previous sections, &(dnsdb)& lookups for a single domain are described.
7269 However, you can specify a list of domains or IP addresses in a single
7270 &(dnsdb)& lookup. The list is specified in the normal Exim way, with colon as
7271 the default separator, but with the ability to change this. For example:
7272 .code
7273 ${lookup dnsdb{one.domain.com:two.domain.com}}
7274 ${lookup dnsdb{a=one.host.com:two.host.com}}
7275 ${lookup dnsdb{ptr = <; 1.2.3.4 ; 4.5.6.8}}
7276 .endd
7277 In order to retain backwards compatibility, there is one special case: if
7278 the lookup type is PTR and no change of separator is specified, Exim looks
7279 to see if the rest of the string is precisely one IPv6 address. In this
7280 case, it does not treat it as a list.
7281
7282 The data from each lookup is concatenated, with newline separators by default,
7283 in the same way that multiple DNS records for a single item are handled. A
7284 different separator can be specified, as described above.
7285
7286
7287
7288
7289 .section "More about LDAP" "SECTldap"
7290 .cindex "LDAP" "lookup, more about"
7291 .cindex "lookup" "LDAP"
7292 .cindex "Solaris" "LDAP"
7293 The original LDAP implementation came from the University of Michigan; this has
7294 become &"Open LDAP"&, and there are now two different releases. Another
7295 implementation comes from Netscape, and Solaris 7 and subsequent releases
7296 contain inbuilt LDAP support. Unfortunately, though these are all compatible at
7297 the lookup function level, their error handling is different. For this reason
7298 it is necessary to set a compile-time variable when building Exim with LDAP, to
7299 indicate which LDAP library is in use. One of the following should appear in
7300 your &_Local/Makefile_&:
7301 .code
7302 LDAP_LIB_TYPE=UMICHIGAN
7303 LDAP_LIB_TYPE=OPENLDAP1
7304 LDAP_LIB_TYPE=OPENLDAP2
7305 LDAP_LIB_TYPE=NETSCAPE
7306 LDAP_LIB_TYPE=SOLARIS
7307 .endd
7308 If LDAP_LIB_TYPE is not set, Exim assumes &`OPENLDAP1`&, which has the
7309 same interface as the University of Michigan version.
7310
7311 There are three LDAP lookup types in Exim. These behave slightly differently in
7312 the way they handle the results of a query:
7313
7314 .ilist
7315 &(ldap)& requires the result to contain just one entry; if there are more, it
7316 gives an error.
7317 .next
7318 &(ldapdn)& also requires the result to contain just one entry, but it is the
7319 Distinguished Name that is returned rather than any attribute values.
7320 .next
7321 &(ldapm)& permits the result to contain more than one entry; the attributes
7322 from all of them are returned.
7323 .endlist
7324
7325
7326 For &(ldap)& and &(ldapm)&, if a query finds only entries with no attributes,
7327 Exim behaves as if the entry did not exist, and the lookup fails. The format of
7328 the data returned by a successful lookup is described in the next section.
7329 First we explain how LDAP queries are coded.
7330
7331
7332 .section "Format of LDAP queries" "SECTforldaque"
7333 .cindex "LDAP" "query format"
7334 An LDAP query takes the form of a URL as defined in RFC 2255. For example, in
7335 the configuration of a &(redirect)& router one might have this setting:
7336 .code
7337 data = ${lookup ldap \
7338   {ldap:///cn=$local_part,o=University%20of%20Cambridge,\
7339   c=UK?mailbox?base?}}
7340 .endd
7341 .cindex "LDAP" "with TLS"
7342 The URL may begin with &`ldap`& or &`ldaps`& if your LDAP library supports
7343 secure (encrypted) LDAP connections. The second of these ensures that an
7344 encrypted TLS connection is used.
7345
7346 With sufficiently modern LDAP libraries, Exim supports forcing TLS over regular
7347 LDAP connections, rather than the SSL-on-connect &`ldaps`&.
7348 See the &%ldap_start_tls%& option.
7349
7350 Starting with Exim 4.83, the initialization of LDAP with TLS is more tightly
7351 controlled. Every part of the TLS configuration can be configured by settings in
7352 &_exim.conf_&. Depending on the version of the client libraries installed on
7353 your system, some of the initialization may have required setting options in
7354 &_/etc/ldap.conf_& or &_~/.ldaprc_& to get TLS working with self-signed
7355 certificates. This revealed a nuance where the current UID that exim was
7356 running as could affect which config files it read. With Exim 4.83, these
7357 methods become optional, only taking effect if not specifically set in
7358 &_exim.conf_&.
7359
7360
7361 .section "LDAP quoting" "SECID68"
7362 .cindex "LDAP" "quoting"
7363 Two levels of quoting are required in LDAP queries, the first for LDAP itself
7364 and the second because the LDAP query is represented as a URL. Furthermore,
7365 within an LDAP query, two different kinds of quoting are required. For this
7366 reason, there are two different LDAP-specific quoting operators.
7367
7368 The &%quote_ldap%& operator is designed for use on strings that are part of
7369 filter specifications. Conceptually, it first does the following conversions on
7370 the string:
7371 .code
7372 *   =>   \2A
7373 (   =>   \28
7374 )   =>   \29
7375 \   =>   \5C
7376 .endd
7377 in accordance with RFC 2254. The resulting string is then quoted according
7378 to the rules for URLs, that is, all non-alphanumeric characters except
7379 .code
7380 ! $ ' - . _ ( ) * +
7381 .endd
7382 are converted to their hex values, preceded by a percent sign. For example:
7383 .code
7384 ${quote_ldap: a(bc)*, a<yz>; }
7385 .endd
7386 yields
7387 .code
7388 %20a%5C28bc%5C29%5C2A%2C%20a%3Cyz%3E%3B%20
7389 .endd
7390 Removing the URL quoting, this is (with a leading and a trailing space):
7391 .code
7392 a\28bc\29\2A, a<yz>;
7393 .endd
7394 The &%quote_ldap_dn%& operator is designed for use on strings that are part of
7395 base DN specifications in queries. Conceptually, it first converts the string
7396 by inserting a backslash in front of any of the following characters:
7397 .code
7398 , + " \ < > ;
7399 .endd
7400 It also inserts a backslash before any leading spaces or # characters, and
7401 before any trailing spaces. (These rules are in RFC 2253.) The resulting string
7402 is then quoted according to the rules for URLs. For example:
7403 .code
7404 ${quote_ldap_dn: a(bc)*, a<yz>; }
7405 .endd
7406 yields
7407 .code
7408 %5C%20a(bc)*%5C%2C%20a%5C%3Cyz%5C%3E%5C%3B%5C%20
7409 .endd
7410 Removing the URL quoting, this is (with a trailing space):
7411 .code
7412 \ a(bc)*\, a\<yz\>\;\
7413 .endd
7414 There are some further comments about quoting in the section on LDAP
7415 authentication below.
7416
7417
7418 .section "LDAP connections" "SECID69"
7419 .cindex "LDAP" "connections"
7420 The connection to an LDAP server may either be over TCP/IP, or, when OpenLDAP
7421 is in use, via a Unix domain socket. The example given above does not specify
7422 an LDAP server. A server that is reached by TCP/IP can be specified in a query
7423 by starting it with
7424 .code
7425 ldap://<hostname>:<port>/...
7426 .endd
7427 If the port (and preceding colon) are omitted, the standard LDAP port (389) is
7428 used. When no server is specified in a query, a list of default servers is
7429 taken from the &%ldap_default_servers%& configuration option. This supplies a
7430 colon-separated list of servers which are tried in turn until one successfully
7431 handles a query, or there is a serious error. Successful handling either
7432 returns the requested data, or indicates that it does not exist. Serious errors
7433 are syntactical, or multiple values when only a single value is expected.
7434 Errors which cause the next server to be tried are connection failures, bind
7435 failures, and timeouts.
7436
7437 For each server name in the list, a port number can be given. The standard way
7438 of specifying a host and port is to use a colon separator (RFC 1738). Because
7439 &%ldap_default_servers%& is a colon-separated list, such colons have to be
7440 doubled. For example
7441 .code
7442 ldap_default_servers = ldap1.example.com::145:ldap2.example.com
7443 .endd
7444 If &%ldap_default_servers%& is unset, a URL with no server name is passed
7445 to the LDAP library with no server name, and the library's default (normally
7446 the local host) is used.
7447
7448 If you are using the OpenLDAP library, you can connect to an LDAP server using
7449 a Unix domain socket instead of a TCP/IP connection. This is specified by using
7450 &`ldapi`& instead of &`ldap`& in LDAP queries. What follows here applies only
7451 to OpenLDAP. If Exim is compiled with a different LDAP library, this feature is
7452 not available.
7453
7454 For this type of connection, instead of a host name for the server, a pathname
7455 for the socket is required, and the port number is not relevant. The pathname
7456 can be specified either as an item in &%ldap_default_servers%&, or inline in
7457 the query. In the former case, you can have settings such as
7458 .code
7459 ldap_default_servers = /tmp/ldap.sock : backup.ldap.your.domain
7460 .endd
7461 When the pathname is given in the query, you have to escape the slashes as
7462 &`%2F`& to fit in with the LDAP URL syntax. For example:
7463 .code
7464 ${lookup ldap {ldapi://%2Ftmp%2Fldap.sock/o=...
7465 .endd
7466 When Exim processes an LDAP lookup and finds that the &"hostname"& is really
7467 a pathname, it uses the Unix domain socket code, even if the query actually
7468 specifies &`ldap`& or &`ldaps`&. In particular, no encryption is used for a
7469 socket connection. This behaviour means that you can use a setting of
7470 &%ldap_default_servers%& such as in the example above with traditional &`ldap`&
7471 or &`ldaps`& queries, and it will work. First, Exim tries a connection via
7472 the Unix domain socket; if that fails, it tries a TCP/IP connection to the
7473 backup host.
7474
7475 If an explicit &`ldapi`& type is given in a query when a host name is
7476 specified, an error is diagnosed. However, if there are more items in
7477 &%ldap_default_servers%&, they are tried. In other words:
7478
7479 .ilist
7480 Using a pathname with &`ldap`& or &`ldaps`& forces the use of the Unix domain
7481 interface.
7482 .next
7483 Using &`ldapi`& with a host name causes an error.
7484 .endlist
7485
7486
7487 Using &`ldapi`& with no host or path in the query, and no setting of
7488 &%ldap_default_servers%&, does whatever the library does by default.
7489
7490
7491
7492 .section "LDAP authentication and control information" "SECID70"
7493 .cindex "LDAP" "authentication"
7494 The LDAP URL syntax provides no way of passing authentication and other control
7495 information to the server. To make this possible, the URL in an LDAP query may
7496 be preceded by any number of <&'name'&>=<&'value'&> settings, separated by
7497 spaces. If a value contains spaces it must be enclosed in double quotes, and
7498 when double quotes are used, backslash is interpreted in the usual way inside
7499 them. The following names are recognized:
7500 .display
7501 &`DEREFERENCE`&  set the dereferencing parameter
7502 &`NETTIME    `&  set a timeout for a network operation
7503 &`USER       `&  set the DN, for authenticating the LDAP bind
7504 &`PASS       `&  set the password, likewise
7505 &`REFERRALS  `&  set the referrals parameter
7506 &`SERVERS    `&  set alternate server list for this query only
7507 &`SIZE       `&  set the limit for the number of entries returned
7508 &`TIME       `&  set the maximum waiting time for a query
7509 .endd
7510 The value of the DEREFERENCE parameter must be one of the words &"never"&,
7511 &"searching"&, &"finding"&, or &"always"&. The value of the REFERRALS parameter
7512 must be &"follow"& (the default) or &"nofollow"&. The latter stops the LDAP
7513 library from trying to follow referrals issued by the LDAP server.
7514
7515 .cindex LDAP timeout
7516 .cindex timeout "LDAP lookup"
7517 The name CONNECT is an obsolete name for NETTIME, retained for
7518 backwards compatibility. This timeout (specified as a number of seconds) is
7519 enforced from the client end for operations that can be carried out over a
7520 network. Specifically, it applies to network connections and calls to the
7521 &'ldap_result()'& function. If the value is greater than zero, it is used if
7522 LDAP_OPT_NETWORK_TIMEOUT is defined in the LDAP headers (OpenLDAP), or
7523 if LDAP_X_OPT_CONNECT_TIMEOUT is defined in the LDAP headers (Netscape
7524 SDK 4.1). A value of zero forces an explicit setting of &"no timeout"& for
7525 Netscape SDK; for OpenLDAP no action is taken.
7526
7527 The TIME parameter (also a number of seconds) is passed to the server to
7528 set a server-side limit on the time taken to complete a search.
7529
7530 The SERVERS parameter allows you to specify an alternate list of ldap servers
7531 to use for an individual lookup.  The global &%ldap_default_servers%& option provides a
7532 default list of ldap servers, and a single lookup can specify a single ldap
7533 server to use.  But when you need to do a lookup with a list of servers that is
7534 different than the default list (maybe different order, maybe a completely
7535 different set of servers), the SERVERS parameter allows you to specify this
7536 alternate list (colon-separated).
7537
7538 Here is an example of an LDAP query in an Exim lookup that uses some of these
7539 values. This is a single line, folded to fit on the page:
7540 .code
7541 ${lookup ldap
7542   {user="cn=manager,o=University of Cambridge,c=UK" pass=secret
7543   ldap:///o=University%20of%20Cambridge,c=UK?sn?sub?(cn=foo)}
7544   {$value}fail}
7545 .endd
7546 The encoding of spaces as &`%20`& is a URL thing which should not be done for
7547 any of the auxiliary data. Exim configuration settings that include lookups
7548 which contain password information should be preceded by &"hide"& to prevent
7549 non-admin users from using the &%-bP%& option to see their values.
7550
7551 The auxiliary data items may be given in any order. The default is no
7552 connection timeout (the system timeout is used), no user or password, no limit
7553 on the number of entries returned, and no time limit on queries.
7554
7555 When a DN is quoted in the USER= setting for LDAP authentication, Exim
7556 removes any URL quoting that it may contain before passing it LDAP. Apparently
7557 some libraries do this for themselves, but some do not. Removing the URL
7558 quoting has two advantages:
7559
7560 .ilist
7561 It makes it possible to use the same &%quote_ldap_dn%& expansion for USER=
7562 DNs as with DNs inside actual queries.
7563 .next
7564 It permits spaces inside USER= DNs.
7565 .endlist
7566
7567 For example, a setting such as
7568 .code
7569 USER=cn=${quote_ldap_dn:$1}
7570 .endd
7571 should work even if &$1$& contains spaces.
7572
7573 Expanded data for the PASS= value should be quoted using the &%quote%&
7574 expansion operator, rather than the LDAP quote operators. The only reason this
7575 field needs quoting is to ensure that it conforms to the Exim syntax, which
7576 does not allow unquoted spaces. For example:
7577 .code
7578 PASS=${quote:$3}
7579 .endd
7580 The LDAP authentication mechanism can be used to check passwords as part of
7581 SMTP authentication. See the &%ldapauth%& expansion string condition in chapter
7582 &<<CHAPexpand>>&.
7583
7584
7585
7586 .section "Format of data returned by LDAP" "SECID71"
7587 .cindex "LDAP" "returned data formats"
7588 The &(ldapdn)& lookup type returns the Distinguished Name from a single entry
7589 as a sequence of values, for example
7590 .code
7591 cn=manager,o=University of Cambridge,c=UK
7592 .endd
7593 The &(ldap)& lookup type generates an error if more than one entry matches the
7594 search filter, whereas &(ldapm)& permits this case, and inserts a newline in
7595 the result between the data from different entries. It is possible for multiple
7596 values to be returned for both &(ldap)& and &(ldapm)&, but in the former case
7597 you know that whatever values are returned all came from a single entry in the
7598 directory.
7599
7600 In the common case where you specify a single attribute in your LDAP query, the
7601 result is not quoted, and does not contain the attribute name. If the attribute
7602 has multiple values, they are separated by commas. Any comma that is
7603 part of an attribute's value is doubled.
7604
7605 If you specify multiple attributes, the result contains space-separated, quoted
7606 strings, each preceded by the attribute name and an equals sign. Within the
7607 quotes, the quote character, backslash, and newline are escaped with
7608 backslashes, and commas are used to separate multiple values for the attribute.
7609 Any commas in attribute values are doubled
7610 (permitting treatment of the values as a comma-separated list).
7611 Apart from the escaping, the string within quotes takes the same form as the
7612 output when a single attribute is requested. Specifying no attributes is the
7613 same as specifying all of an entry's attributes.
7614
7615 Here are some examples of the output format. The first line of each pair is an
7616 LDAP query, and the second is the data that is returned. The attribute called
7617 &%attr1%& has two values, one of them with an embedded comma, whereas
7618 &%attr2%& has only one value. Both attributes are derived from &%attr%&
7619 (they have SUP &%attr%& in their schema definitions).
7620
7621 .code
7622 ldap:///o=base?attr1?sub?(uid=fred)
7623 value1.1,value1,,2
7624
7625 ldap:///o=base?attr2?sub?(uid=fred)
7626 value two
7627
7628 ldap:///o=base?attr?sub?(uid=fred)
7629 value1.1,value1,,2,value two
7630
7631 ldap:///o=base?attr1,attr2?sub?(uid=fred)
7632 attr1="value1.1,value1,,2" attr2="value two"
7633
7634 ldap:///o=base??sub?(uid=fred)
7635 objectClass="top" attr1="value1.1,value1,,2" attr2="value two"
7636 .endd
7637 You can
7638 make use of Exim's &%-be%& option to run expansion tests and thereby check the
7639 results of LDAP lookups.
7640 The &%extract%& operator in string expansions can be used to pick out
7641 individual fields from data that consists of &'key'&=&'value'& pairs.
7642 The &%listextract%& operator should be used to pick out individual values
7643 of attributes, even when only a single value is expected.
7644 The doubling of embedded commas allows you to use the returned data as a
7645 comma separated list (using the "<," syntax for changing the input list separator).
7646
7647
7648
7649
7650 .section "More about NIS+" "SECTnisplus"
7651 .cindex "NIS+ lookup type"
7652 .cindex "lookup" "NIS+"
7653 NIS+ queries consist of a NIS+ &'indexed name'& followed by an optional colon
7654 and field name. If this is given, the result of a successful query is the
7655 contents of the named field; otherwise the result consists of a concatenation
7656 of &'field-name=field-value'& pairs, separated by spaces. Empty values and
7657 values containing spaces are quoted. For example, the query
7658 .code
7659 [name=mg1456],passwd.org_dir
7660 .endd
7661 might return the string
7662 .code
7663 name=mg1456 passwd="" uid=999 gid=999 gcos="Martin Guerre"
7664 home=/home/mg1456 shell=/bin/bash shadow=""
7665 .endd
7666 (split over two lines here to fit on the page), whereas
7667 .code
7668 [name=mg1456],passwd.org_dir:gcos
7669 .endd
7670 would just return
7671 .code
7672 Martin Guerre
7673 .endd
7674 with no quotes. A NIS+ lookup fails if NIS+ returns more than one table entry
7675 for the given indexed key. The effect of the &%quote_nisplus%& expansion
7676 operator is to double any quote characters within the text.
7677
7678
7679
7680 .section "SQL lookups" "SECTsql"
7681 .cindex "SQL lookup types"
7682 .cindex "MySQL" "lookup type"
7683 .cindex "PostgreSQL lookup type"
7684 .cindex "lookup" "MySQL"
7685 .cindex "lookup" "PostgreSQL"
7686 .cindex "Oracle" "lookup type"
7687 .cindex "lookup" "Oracle"
7688 .cindex "InterBase lookup type"
7689 .cindex "lookup" "InterBase"
7690 .cindex "Redis lookup type"
7691 .cindex lookup Redis
7692 Exim can support lookups in InterBase, MySQL, Oracle, PostgreSQL, Redis,
7693 and SQLite
7694 databases. Queries for these databases contain SQL statements, so an example
7695 might be
7696 .code
7697 ${lookup mysql{select mailbox from users where id='userx'}\
7698   {$value}fail}
7699 .endd
7700 If the result of the query contains more than one field, the data for each
7701 field in the row is returned, preceded by its name, so the result of
7702 .code
7703 ${lookup pgsql{select home,name from users where id='userx'}\
7704   {$value}}
7705 .endd
7706 might be
7707 .code
7708 home=/home/userx name="Mister X"
7709 .endd
7710 Empty values and values containing spaces are double quoted, with embedded
7711 quotes escaped by a backslash. If the result of the query contains just one
7712 field, the value is passed back verbatim, without a field name, for example:
7713 .code
7714 Mister X
7715 .endd
7716 If the result of the query yields more than one row, it is all concatenated,
7717 with a newline between the data for each row.
7718
7719
7720 .section "More about MySQL, PostgreSQL, Oracle, InterBase, and Redis" "SECID72"
7721 .cindex "MySQL" "lookup type"
7722 .cindex "PostgreSQL lookup type"
7723 .cindex "lookup" "MySQL"
7724 .cindex "lookup" "PostgreSQL"
7725 .cindex "Oracle" "lookup type"
7726 .cindex "lookup" "Oracle"
7727 .cindex "InterBase lookup type"
7728 .cindex "lookup" "InterBase"
7729 .cindex "Redis lookup type"
7730 .cindex lookup Redis
7731 If any MySQL, PostgreSQL, Oracle, InterBase or Redis lookups are used, the
7732 &%mysql_servers%&, &%pgsql_servers%&, &%oracle_servers%&, &%ibase_servers%&,
7733 or &%redis_servers%&
7734 option (as appropriate) must be set to a colon-separated list of server
7735 information.
7736 (For MySQL and PostgreSQL, the global option need not be set if all
7737 queries contain their own server information &-- see section
7738 &<<SECTspeserque>>&.)
7739 For all but Redis
7740 each item in the list is a slash-separated list of four
7741 items: host name, database name, user name, and password. In the case of
7742 Oracle, the host name field is used for the &"service name"&, and the database
7743 name field is not used and should be empty. For example:
7744 .code
7745 hide oracle_servers = oracle.plc.example//userx/abcdwxyz
7746 .endd
7747 Because password data is sensitive, you should always precede the setting with
7748 &"hide"&, to prevent non-admin users from obtaining the setting via the &%-bP%&
7749 option. Here is an example where two MySQL servers are listed:
7750 .code
7751 hide mysql_servers = localhost/users/root/secret:\
7752                      otherhost/users/root/othersecret
7753 .endd
7754 For MySQL and PostgreSQL, a host may be specified as <&'name'&>:<&'port'&> but
7755 because this is a colon-separated list, the colon has to be doubled. For each
7756 query, these parameter groups are tried in order until a connection is made and
7757 a query is successfully processed. The result of a query may be that no data is
7758 found, but that is still a successful query. In other words, the list of
7759 servers provides a backup facility, not a list of different places to look.
7760
7761 For Redis the global option need not be specified if all queries contain their
7762 own server information &-- see section &<<SECTspeserque>>&.
7763 If specified, the option must be set to a colon-separated list of server
7764 information.
7765 Each item in the list is a slash-separated list of three items:
7766 host, database number, and password.
7767 .olist
7768 The host is required and may be either an IPv4 address and optional
7769 port number (separated by a colon, which needs doubling due to the
7770 higher-level list), or a Unix socket pathname enclosed in parentheses
7771 .next
7772 The database number is optional; if present that number is selected in the backend
7773 .next
7774 The password is optional; if present it is used to authenticate to the backend
7775 .endlist
7776
7777 The &%quote_mysql%&, &%quote_pgsql%&, and &%quote_oracle%& expansion operators
7778 convert newline, tab, carriage return, and backspace to \n, \t, \r, and \b
7779 respectively, and the characters single-quote, double-quote, and backslash
7780 itself are escaped with backslashes.
7781
7782 The &%quote_redis%& expansion operator
7783 escapes whitespace and backslash characters with a backslash.
7784
7785 .section "Specifying the server in the query" "SECTspeserque"
7786 For MySQL, PostgreSQL and Redis lookups (but not currently for Oracle and InterBase),
7787 it is possible to specify a list of servers with an individual query. This is
7788 done by starting the query with
7789 .display
7790 &`servers=`&&'server1:server2:server3:...'&&`;`&
7791 .endd
7792 Each item in the list may take one of two forms:
7793 .olist
7794 If it contains no slashes it is assumed to be just a host name. The appropriate
7795 global option (&%mysql_servers%& or &%pgsql_servers%&) is searched for a host
7796 of the same name, and the remaining parameters (database, user, password) are
7797 taken from there.
7798 .next
7799 If it contains any slashes, it is taken as a complete parameter set.
7800 .endlist
7801 The list of servers is used in exactly the same way as the global list.
7802 Once a connection to a server has happened and a query has been
7803 successfully executed, processing of the lookup ceases.
7804
7805 This feature is intended for use in master/slave situations where updates
7806 are occurring and you want to update the master rather than a slave. If the
7807 master is in the list as a backup for reading, you might have a global setting
7808 like this:
7809 .code
7810 mysql_servers = slave1/db/name/pw:\
7811                 slave2/db/name/pw:\
7812                 master/db/name/pw
7813 .endd
7814 In an updating lookup, you could then write:
7815 .code
7816 ${lookup mysql{servers=master; UPDATE ...} }
7817 .endd
7818 That query would then be sent only to the master server. If, on the other hand,
7819 the master is not to be used for reading, and so is not present in the global
7820 option, you can still update it by a query of this form:
7821 .code
7822 ${lookup pgsql{servers=master/db/name/pw; UPDATE ...} }
7823 .endd
7824
7825
7826 .section "Special MySQL features" "SECID73"
7827 For MySQL, an empty host name or the use of &"localhost"& in &%mysql_servers%&
7828 causes a connection to the server on the local host by means of a Unix domain
7829 socket. An alternate socket can be specified in parentheses.
7830 An option group name for MySQL option files can be specified in square brackets;
7831 the default value is &"exim"&.
7832 The full syntax of each item in &%mysql_servers%& is:
7833 .display
7834 <&'hostname'&>::<&'port'&>(<&'socket name'&>)[<&'option group'&>]/&&&
7835   <&'database'&>/<&'user'&>/<&'password'&>
7836 .endd
7837 Any of the four sub-parts of the first field can be omitted. For normal use on
7838 the local host it can be left blank or set to just &"localhost"&.
7839
7840 No database need be supplied &-- but if it is absent here, it must be given in
7841 the queries.
7842
7843 If a MySQL query is issued that does not request any data (an insert, update,
7844 or delete command), the result of the lookup is the number of rows affected.
7845
7846 &*Warning*&: This can be misleading. If an update does not actually change
7847 anything (for example, setting a field to the value it already has), the result
7848 is zero because no rows are affected.
7849
7850
7851 .section "Special PostgreSQL features" "SECID74"
7852 PostgreSQL lookups can also use Unix domain socket connections to the database.
7853 This is usually faster and costs less CPU time than a TCP/IP connection.
7854 However it can be used only if the mail server runs on the same machine as the
7855 database server. A configuration line for PostgreSQL via Unix domain sockets
7856 looks like this:
7857 .code
7858 hide pgsql_servers = (/tmp/.s.PGSQL.5432)/db/user/password : ...
7859 .endd
7860 In other words, instead of supplying a host name, a path to the socket is
7861 given. The path name is enclosed in parentheses so that its slashes aren't
7862 visually confused with the delimiters for the other server parameters.
7863
7864 If a PostgreSQL query is issued that does not request any data (an insert,
7865 update, or delete command), the result of the lookup is the number of rows
7866 affected.
7867
7868 .section "More about SQLite" "SECTsqlite"
7869 .cindex "lookup" "SQLite"
7870 .cindex "sqlite lookup type"
7871 SQLite is different to the other SQL lookups because a file name is required in
7872 addition to the SQL query. An SQLite database is a single file, and there is no
7873 daemon as in the other SQL databases. The interface to Exim requires the name
7874 of the file, as an absolute path, to be given at the start of the query. It is
7875 separated from the query by white space. This means that the path name cannot
7876 contain white space. Here is a lookup expansion example:
7877 .code
7878 ${lookup sqlite {/some/thing/sqlitedb \
7879   select name from aliases where id='userx';}}
7880 .endd
7881 In a list, the syntax is similar. For example:
7882 .code
7883 domainlist relay_to_domains = sqlite;/some/thing/sqlitedb \
7884    select * from relays where ip='$sender_host_address';
7885 .endd
7886 The only character affected by the &%quote_sqlite%& operator is a single
7887 quote, which it doubles.
7888
7889 .cindex timeout SQLite
7890 .cindex sqlite "lookup timeout"
7891 The SQLite library handles multiple simultaneous accesses to the database
7892 internally. Multiple readers are permitted, but only one process can
7893 update at once. Attempts to access the database while it is being updated
7894 are rejected after a timeout period, during which the SQLite library
7895 waits for the lock to be released. In Exim, the default timeout is set
7896 to 5 seconds, but it can be changed by means of the &%sqlite_lock_timeout%&
7897 option.
7898
7899 .section "More about Redis" "SECTredis"
7900 .cindex "lookup" "Redis"
7901 .cindex "redis lookup type"
7902 Redis is a non-SQL database. Commands are simple get and set.
7903 Examples:
7904 .code
7905 ${lookup redis{set keyname ${quote_redis:objvalue plus}}}
7906 ${lookup redis{get keyname}}
7907 .endd
7908
7909 As of release 4.91, "lightweight" support for Redis Cluster is available.
7910 Requires &%redis_servers%& list to contain all the servers in the cluster, all
7911 of which must be reachable from the running exim instance. If the cluster has
7912 master/slave replication, the list must contain all the master and slave
7913 servers.
7914
7915 When the Redis Cluster returns a "MOVED" response to a query, Exim does not
7916 immediately follow the redirection but treats the response as a DEFER, moving on
7917 to the next server in the &%redis_servers%& list until the correct server is
7918 reached.
7919
7920 .ecindex IIDfidalo1
7921 .ecindex IIDfidalo2
7922
7923
7924 . ////////////////////////////////////////////////////////////////////////////
7925 . ////////////////////////////////////////////////////////////////////////////
7926
7927 .chapter "Domain, host, address, and local part lists" &&&
7928          "CHAPdomhosaddlists" &&&
7929          "Domain, host, and address lists"
7930 .scindex IIDdohoadli "lists of domains; hosts; etc."
7931 A number of Exim configuration options contain lists of domains, hosts,
7932 email addresses, or local parts. For example, the &%hold_domains%& option
7933 contains a list of domains whose delivery is currently suspended. These lists
7934 are also used as data in ACL statements (see chapter &<<CHAPACL>>&), and as
7935 arguments to expansion conditions such as &%match_domain%&.
7936
7937 Each item in one of these lists is a pattern to be matched against a domain,
7938 host, email address, or local part, respectively. In the sections below, the
7939 different types of pattern for each case are described, but first we cover some
7940 general facilities that apply to all four kinds of list.
7941
7942 Note that other parts of Exim use a &'string list'& which does not
7943 support all the complexity available in
7944 domain, host, address and local part lists.
7945
7946
7947
7948 .section "Expansion of lists" "SECTlistexpand"
7949 .cindex "expansion" "of lists"
7950 Each list is expanded as a single string before it is used.
7951
7952 &'Exception: the router headers_remove option, where list-item
7953 splitting is done before string-expansion.'&
7954
7955 The result of
7956 expansion must be a list, possibly containing empty items, which is split up
7957 into separate items for matching. By default, colon is the separator character,
7958 but this can be varied if necessary. See sections &<<SECTlistconstruct>>& and
7959 &<<SECTempitelis>>& for details of the list syntax; the second of these
7960 discusses the way to specify empty list items.
7961
7962
7963 If the string expansion is forced to fail, Exim behaves as if the item it is
7964 testing (domain, host, address, or local part) is not in the list. Other
7965 expansion failures cause temporary errors.
7966
7967 If an item in a list is a regular expression, backslashes, dollars and possibly
7968 other special characters in the expression must be protected against
7969 misinterpretation by the string expander. The easiest way to do this is to use
7970 the &`\N`& expansion feature to indicate that the contents of the regular
7971 expression should not be expanded. For example, in an ACL you might have:
7972 .code
7973 deny senders = \N^\d{8}\w@.*\.baddomain\.example$\N : \
7974                ${lookup{$domain}lsearch{/badsenders/bydomain}}
7975 .endd
7976 The first item is a regular expression that is protected from expansion by
7977 &`\N`&, whereas the second uses the expansion to obtain a list of unwanted
7978 senders based on the receiving domain.
7979
7980
7981
7982
7983 .section "Negated items in lists" "SECID76"
7984 .cindex "list" "negation"
7985 .cindex "negation" "in lists"
7986 Items in a list may be positive or negative. Negative items are indicated by a
7987 leading exclamation mark, which may be followed by optional white space. A list
7988 defines a set of items (domains, etc). When Exim processes one of these lists,
7989 it is trying to find out whether a domain, host, address, or local part
7990 (respectively) is in the set that is defined by the list. It works like this:
7991
7992 The list is scanned from left to right. If a positive item is matched, the
7993 subject that is being checked is in the set; if a negative item is matched, the
7994 subject is not in the set. If the end of the list is reached without the
7995 subject having matched any of the patterns, it is in the set if the last item
7996 was a negative one, but not if it was a positive one. For example, the list in
7997 .code
7998 domainlist relay_to_domains = !a.b.c : *.b.c
7999 .endd
8000 matches any domain ending in &'.b.c'& except for &'a.b.c'&. Domains that match
8001 neither &'a.b.c'& nor &'*.b.c'& do not match, because the last item in the
8002 list is positive. However, if the setting were
8003 .code
8004 domainlist relay_to_domains = !a.b.c
8005 .endd
8006 then all domains other than &'a.b.c'& would match because the last item in the
8007 list is negative. In other words, a list that ends with a negative item behaves
8008 as if it had an extra item &`:*`& on the end.
8009
8010 Another way of thinking about positive and negative items in lists is to read
8011 the connector as &"or"& after a positive item and as &"and"& after a negative
8012 item.
8013
8014
8015
8016 .section "File names in lists" "SECTfilnamlis"
8017 .cindex "list" "file name in"
8018 If an item in a domain, host, address, or local part list is an absolute file
8019 name (beginning with a slash character), each line of the file is read and
8020 processed as if it were an independent item in the list, except that further
8021 file names are not allowed,
8022 and no expansion of the data from the file takes place.
8023 Empty lines in the file are ignored, and the file may also contain comment
8024 lines:
8025
8026 .ilist
8027 For domain and host lists, if a # character appears anywhere in a line of the
8028 file, it and all following characters are ignored.
8029 .next
8030 Because local parts may legitimately contain # characters, a comment in an
8031 address list or local part list file is recognized only if # is preceded by
8032 white space or the start of the line. For example:
8033 .code
8034 not#comment@x.y.z   # but this is a comment
8035 .endd
8036 .endlist
8037
8038 Putting a file name in a list has the same effect as inserting each line of the
8039 file as an item in the list (blank lines and comments excepted). However, there
8040 is one important difference: the file is read each time the list is processed,
8041 so if its contents vary over time, Exim's behaviour changes.
8042
8043 If a file name is preceded by an exclamation mark, the sense of any match
8044 within the file is inverted. For example, if
8045 .code
8046 hold_domains = !/etc/nohold-domains
8047 .endd
8048 and the file contains the lines
8049 .code
8050 !a.b.c
8051 *.b.c
8052 .endd
8053 then &'a.b.c'& is in the set of domains defined by &%hold_domains%&, whereas
8054 any domain matching &`*.b.c`& is not.
8055
8056
8057
8058 .section "An lsearch file is not an out-of-line list" "SECID77"
8059 As will be described in the sections that follow, lookups can be used in lists
8060 to provide indexed methods of checking list membership. There has been some
8061 confusion about the way &(lsearch)& lookups work in lists. Because
8062 an &(lsearch)& file contains plain text and is scanned sequentially, it is
8063 sometimes thought that it is allowed to contain wild cards and other kinds of
8064 non-constant pattern. This is not the case. The keys in an &(lsearch)& file are
8065 always fixed strings, just as for any other single-key lookup type.
8066
8067 If you want to use a file to contain wild-card patterns that form part of a
8068 list, just give the file name on its own, without a search type, as described
8069 in the previous section. You could also use the &(wildlsearch)& or
8070 &(nwildlsearch)&, but there is no advantage in doing this.
8071
8072
8073
8074
8075 .section "Named lists" "SECTnamedlists"
8076 .cindex "named lists"
8077 .cindex "list" "named"
8078 A list of domains, hosts, email addresses, or local parts can be given a name
8079 which is then used to refer to the list elsewhere in the configuration. This is
8080 particularly convenient if the same list is required in several different
8081 places. It also allows lists to be given meaningful names, which can improve
8082 the readability of the configuration. For example, it is conventional to define
8083 a domain list called &'local_domains'& for all the domains that are handled
8084 locally on a host, using a configuration line such as
8085 .code
8086 domainlist local_domains = localhost:my.dom.example
8087 .endd
8088 Named lists are referenced by giving their name preceded by a plus sign, so,
8089 for example, a router that is intended to handle local domains would be
8090 configured with the line
8091 .code
8092 domains = +local_domains
8093 .endd
8094 The first router in a configuration is often one that handles all domains
8095 except the local ones, using a configuration with a negated item like this:
8096 .code
8097 dnslookup:
8098   driver = dnslookup
8099   domains = ! +local_domains
8100   transport = remote_smtp
8101   no_more
8102 .endd
8103 The four kinds of named list are created by configuration lines starting with
8104 the words &%domainlist%&, &%hostlist%&, &%addresslist%&, or &%localpartlist%&,
8105 respectively. Then there follows the name that you are defining, followed by an
8106 equals sign and the list itself. For example:
8107 .code
8108 hostlist    relay_from_hosts = 192.168.23.0/24 : my.friend.example
8109 addresslist bad_senders = cdb;/etc/badsenders
8110 .endd
8111 A named list may refer to other named lists:
8112 .code
8113 domainlist  dom1 = first.example : second.example
8114 domainlist  dom2 = +dom1 : third.example
8115 domainlist  dom3 = fourth.example : +dom2 : fifth.example
8116 .endd
8117 &*Warning*&: If the last item in a referenced list is a negative one, the
8118 effect may not be what you intended, because the negation does not propagate
8119 out to the higher level. For example, consider:
8120 .code
8121 domainlist  dom1 = !a.b
8122 domainlist  dom2 = +dom1 : *.b
8123 .endd
8124 The second list specifies &"either in the &%dom1%& list or &'*.b'&"&. The first
8125 list specifies just &"not &'a.b'&"&, so the domain &'x.y'& matches it. That
8126 means it matches the second list as well. The effect is not the same as
8127 .code
8128 domainlist  dom2 = !a.b : *.b
8129 .endd
8130 where &'x.y'& does not match. It's best to avoid negation altogether in
8131 referenced lists if you can.
8132
8133 Named lists may have a performance advantage. When Exim is routing an
8134 address or checking an incoming message, it caches the result of tests on named
8135 lists. So, if you have a setting such as
8136 .code
8137 domains = +local_domains
8138 .endd
8139 on several of your routers
8140 or in several ACL statements,
8141 the actual test is done only for the first one. However, the caching works only
8142 if there are no expansions within the list itself or any sublists that it
8143 references. In other words, caching happens only for lists that are known to be
8144 the same each time they are referenced.
8145
8146 By default, there may be up to 16 named lists of each type. This limit can be
8147 extended by changing a compile-time variable. The use of domain and host lists
8148 is recommended for concepts such as local domains, relay domains, and relay
8149 hosts. The default configuration is set up like this.
8150
8151
8152
8153 .section "Named lists compared with macros" "SECID78"
8154 .cindex "list" "named compared with macro"
8155 .cindex "macro" "compared with named list"
8156 At first sight, named lists might seem to be no different from macros in the
8157 configuration file. However, macros are just textual substitutions. If you
8158 write
8159 .code
8160 ALIST = host1 : host2
8161 auth_advertise_hosts = !ALIST
8162 .endd
8163 it probably won't do what you want, because that is exactly the same as
8164 .code
8165 auth_advertise_hosts = !host1 : host2
8166 .endd
8167 Notice that the second host name is not negated. However, if you use a host
8168 list, and write
8169 .code
8170 hostlist alist = host1 : host2
8171 auth_advertise_hosts = ! +alist
8172 .endd
8173 the negation applies to the whole list, and so that is equivalent to
8174 .code
8175 auth_advertise_hosts = !host1 : !host2
8176 .endd
8177
8178
8179 .section "Named list caching" "SECID79"
8180 .cindex "list" "caching of named"
8181 .cindex "caching" "named lists"
8182 While processing a message, Exim caches the result of checking a named list if
8183 it is sure that the list is the same each time. In practice, this means that
8184 the cache operates only if the list contains no $ characters, which guarantees
8185 that it will not change when it is expanded. Sometimes, however, you may have
8186 an expanded list that you know will be the same each time within a given
8187 message. For example:
8188 .code
8189 domainlist special_domains = \
8190            ${lookup{$sender_host_address}cdb{/some/file}}
8191 .endd
8192 This provides a list of domains that depends only on the sending host's IP
8193 address. If this domain list is referenced a number of times (for example,
8194 in several ACL lines, or in several routers) the result of the check is not
8195 cached by default, because Exim does not know that it is going to be the
8196 same list each time.
8197
8198 By appending &`_cache`& to &`domainlist`& you can tell Exim to go ahead and
8199 cache the result anyway. For example:
8200 .code
8201 domainlist_cache special_domains = ${lookup{...
8202 .endd
8203 If you do this, you should be absolutely sure that caching is going to do
8204 the right thing in all cases. When in doubt, leave it out.
8205
8206
8207
8208 .section "Domain lists" "SECTdomainlist"
8209 .cindex "domain list" "patterns for"
8210 .cindex "list" "domain list"
8211 Domain lists contain patterns that are to be matched against a mail domain.
8212 The following types of item may appear in domain lists:
8213
8214 .ilist
8215 .cindex "primary host name"
8216 .cindex "host name" "matched in domain list"
8217 .oindex "&%primary_hostname%&"
8218 .cindex "domain list" "matching primary host name"
8219 .cindex "@ in a domain list"
8220 If a pattern consists of a single @ character, it matches the local host name,
8221 as set by the &%primary_hostname%& option (or defaulted). This makes it
8222 possible to use the same configuration file on several different hosts that
8223 differ only in their names.
8224 .next
8225 .cindex "@[] in a domain list"
8226 .cindex "domain list" "matching local IP interfaces"
8227 .cindex "domain literal"
8228 If a pattern consists of the string &`@[]`& it matches an IP address enclosed
8229 in square brackets (as in an email address that contains a domain literal), but
8230 only if that IP address is recognized as local for email routing purposes. The
8231 &%local_interfaces%& and &%extra_local_interfaces%& options can be used to
8232 control which of a host's several IP addresses are treated as local.
8233 In today's Internet, the use of domain literals is controversial.
8234 .next
8235 .cindex "@mx_any"
8236 .cindex "@mx_primary"
8237 .cindex "@mx_secondary"
8238 .cindex "domain list" "matching MX pointers to local host"
8239 If a pattern consists of the string &`@mx_any`& it matches any domain that
8240 has an MX record pointing to the local host or to any host that is listed in
8241 .oindex "&%hosts_treat_as_local%&"
8242 &%hosts_treat_as_local%&. The items &`@mx_primary`& and &`@mx_secondary`&
8243 are similar, except that the first matches only when a primary MX target is the
8244 local host, and the second only when no primary MX target is the local host,
8245 but a secondary MX target is. &"Primary"& means an MX record with the lowest
8246 preference value &-- there may of course be more than one of them.
8247
8248 The MX lookup that takes place when matching a pattern of this type is
8249 performed with the resolver options for widening names turned off. Thus, for
8250 example, a single-component domain will &'not'& be expanded by adding the
8251 resolver's default domain. See the &%qualify_single%& and &%search_parents%&
8252 options of the &(dnslookup)& router for a discussion of domain widening.
8253
8254 Sometimes you may want to ignore certain IP addresses when using one of these
8255 patterns. You can specify this by following the pattern with &`/ignore=`&<&'ip
8256 list'&>, where <&'ip list'&> is a list of IP addresses. These addresses are
8257 ignored when processing the pattern (compare the &%ignore_target_hosts%& option
8258 on a router). For example:
8259 .code
8260 domains = @mx_any/ignore=127.0.0.1
8261 .endd
8262 This example matches any domain that has an MX record pointing to one of
8263 the local host's IP addresses other than 127.0.0.1.
8264
8265 The list of IP addresses is in fact processed by the same code that processes
8266 host lists, so it may contain CIDR-coded network specifications and it may also
8267 contain negative items.
8268
8269 Because the list of IP addresses is a sublist within a domain list, you have to
8270 be careful about delimiters if there is more than one address. Like any other
8271 list, the default delimiter can be changed. Thus, you might have:
8272 .code
8273 domains = @mx_any/ignore=<;127.0.0.1;0.0.0.0 : \
8274           an.other.domain : ...
8275 .endd
8276 so that the sublist uses semicolons for delimiters. When IPv6 addresses are
8277 involved, it is easiest to change the delimiter for the main list as well:
8278 .code
8279 domains = <? @mx_any/ignore=<;127.0.0.1;::1 ? \
8280           an.other.domain ? ...
8281 .endd
8282 .next
8283 .cindex "asterisk" "in domain list"
8284 .cindex "domain list" "asterisk in"
8285 .cindex "domain list" "matching &""ends with""&"
8286 If a pattern starts with an asterisk, the remaining characters of the pattern
8287 are compared with the terminating characters of the domain. The use of &"*"& in
8288 domain lists differs from its use in partial matching lookups. In a domain
8289 list, the character following the asterisk need not be a dot, whereas partial
8290 matching works only in terms of dot-separated components. For example, a domain
8291 list item such as &`*key.ex`& matches &'donkey.ex'& as well as
8292 &'cipher.key.ex'&.
8293
8294 .next
8295 .cindex "regular expressions" "in domain list"
8296 .cindex "domain list" "matching regular expression"
8297 If a pattern starts with a circumflex character, it is treated as a regular
8298 expression, and matched against the domain using a regular expression matching
8299 function. The circumflex is treated as part of the regular expression.
8300 Email domains are case-independent, so this regular expression match is by
8301 default case-independent, but you can make it case-dependent by starting it
8302 with &`(?-i)`&. References to descriptions of the syntax of regular expressions
8303 are given in chapter &<<CHAPregexp>>&.
8304
8305 &*Warning*&: Because domain lists are expanded before being processed, you
8306 must escape any backslash and dollar characters in the regular expression, or
8307 use the special &`\N`& sequence (see chapter &<<CHAPexpand>>&) to specify that
8308 it is not to be expanded (unless you really do want to build a regular
8309 expression by expansion, of course).
8310 .next
8311 .cindex "lookup" "in domain list"
8312 .cindex "domain list" "matching by lookup"
8313 If a pattern starts with the name of a single-key lookup type followed by a
8314 semicolon (for example, &"dbm;"& or &"lsearch;"&), the remainder of the pattern
8315 must be a file name in a suitable format for the lookup type. For example, for
8316 &"cdb;"& it must be an absolute path:
8317 .code
8318 domains = cdb;/etc/mail/local_domains.cdb
8319 .endd
8320 The appropriate type of lookup is done on the file using the domain name as the
8321 key. In most cases, the data that is looked up is not used; Exim is interested
8322 only in whether or not the key is present in the file. However, when a lookup
8323 is used for the &%domains%& option on a router
8324 or a &%domains%& condition in an ACL statement, the data is preserved in the
8325 &$domain_data$& variable and can be referred to in other router options or
8326 other statements in the same ACL.
8327
8328 .next
8329 Any of the single-key lookup type names may be preceded by
8330 &`partial`&<&'n'&>&`-`&, where the <&'n'&> is optional, for example,
8331 .code
8332 domains = partial-dbm;/partial/domains
8333 .endd
8334 This causes partial matching logic to be invoked; a description of how this
8335 works is given in section &<<SECTpartiallookup>>&.
8336
8337 .next
8338 .cindex "asterisk" "in lookup type"
8339 Any of the single-key lookup types may be followed by an asterisk. This causes
8340 a default lookup for a key consisting of a single asterisk to be done if the
8341 original lookup fails. This is not a useful feature when using a domain list to
8342 select particular domains (because any domain would match), but it might have
8343 value if the result of the lookup is being used via the &$domain_data$&
8344 expansion variable.
8345 .next
8346 If the pattern starts with the name of a query-style lookup type followed by a
8347 semicolon (for example, &"nisplus;"& or &"ldap;"&), the remainder of the
8348 pattern must be an appropriate query for the lookup type, as described in
8349 chapter &<<CHAPfdlookup>>&. For example:
8350 .code
8351 hold_domains = mysql;select domain from holdlist \
8352   where domain = '${quote_mysql:$domain}';
8353 .endd
8354 In most cases, the data that is looked up is not used (so for an SQL query, for
8355 example, it doesn't matter what field you select). Exim is interested only in
8356 whether or not the query succeeds. However, when a lookup is used for the
8357 &%domains%& option on a router, the data is preserved in the &$domain_data$&
8358 variable and can be referred to in other options.
8359 .next
8360 .cindex "domain list" "matching literal domain name"
8361 If none of the above cases apply, a caseless textual comparison is made
8362 between the pattern and the domain.
8363 .endlist
8364
8365 Here is an example that uses several different kinds of pattern:
8366 .code
8367 domainlist funny_domains = \
8368   @ : \
8369   lib.unseen.edu : \
8370   *.foundation.fict.example : \
8371   \N^[1-2]\d{3}\.fict\.example$\N : \
8372   partial-dbm;/opt/data/penguin/book : \
8373   nis;domains.byname : \
8374   nisplus;[name=$domain,status=local],domains.org_dir
8375 .endd
8376 There are obvious processing trade-offs among the various matching modes. Using
8377 an asterisk is faster than a regular expression, and listing a few names
8378 explicitly probably is too. The use of a file or database lookup is expensive,
8379 but may be the only option if hundreds of names are required. Because the
8380 patterns are tested in order, it makes sense to put the most commonly matched
8381 patterns earlier.
8382
8383
8384
8385 .section "Host lists" "SECThostlist"
8386 .cindex "host list" "patterns in"
8387 .cindex "list" "host list"
8388 Host lists are used to control what remote hosts are allowed to do. For
8389 example, some hosts may be allowed to use the local host as a relay, and some
8390 may be permitted to use the SMTP ETRN command. Hosts can be identified in
8391 two different ways, by name or by IP address. In a host list, some types of
8392 pattern are matched to a host name, and some are matched to an IP address.
8393 You need to be particularly careful with this when single-key lookups are
8394 involved, to ensure that the right value is being used as the key.
8395
8396
8397 .section "Special host list patterns" "SECID80"
8398 .cindex "empty item in hosts list"
8399 .cindex "host list" "empty string in"
8400 If a host list item is the empty string, it matches only when no remote host is
8401 involved. This is the case when a message is being received from a local
8402 process using SMTP on the standard input, that is, when a TCP/IP connection is
8403 not used.
8404
8405 .cindex "asterisk" "in host list"
8406 The special pattern &"*"& in a host list matches any host or no host. Neither
8407 the IP address nor the name is actually inspected.
8408
8409
8410
8411 .section "Host list patterns that match by IP address" "SECThoslispatip"
8412 .cindex "host list" "matching IP addresses"
8413 If an IPv4 host calls an IPv6 host and the call is accepted on an IPv6 socket,
8414 the incoming address actually appears in the IPv6 host as
8415 &`::ffff:`&<&'v4address'&>. When such an address is tested against a host
8416 list, it is converted into a traditional IPv4 address first. (Not all operating
8417 systems accept IPv4 calls on IPv6 sockets, as there have been some security
8418 concerns.)
8419
8420 The following types of pattern in a host list check the remote host by
8421 inspecting its IP address:
8422
8423 .ilist
8424 If the pattern is a plain domain name (not a regular expression, not starting
8425 with *, not a lookup of any kind), Exim calls the operating system function
8426 to find the associated IP address(es). Exim uses the newer
8427 &[getipnodebyname()]& function when available, otherwise &[gethostbyname()]&.
8428 This typically causes a forward DNS lookup of the name. The result is compared
8429 with the IP address of the subject host.
8430
8431 If there is a temporary problem (such as a DNS timeout) with the host name
8432 lookup, a temporary error occurs. For example, if the list is being used in an
8433 ACL condition, the ACL gives a &"defer"& response, usually leading to a
8434 temporary SMTP error code. If no IP address can be found for the host name,
8435 what happens is described in section &<<SECTbehipnot>>& below.
8436
8437 .next
8438 .cindex "@ in a host list"
8439 If the pattern is &"@"&, the primary host name is substituted and used as a
8440 domain name, as just described.
8441
8442 .next
8443 If the pattern is an IP address, it is matched against the IP address of the
8444 subject host. IPv4 addresses are given in the normal &"dotted-quad"& notation.
8445 IPv6 addresses can be given in colon-separated format, but the colons have to
8446 be doubled so as not to be taken as item separators when the default list
8447 separator is used. IPv6 addresses are recognized even when Exim is compiled
8448 without IPv6 support. This means that if they appear in a host list on an
8449 IPv4-only host, Exim will not treat them as host names. They are just addresses
8450 that can never match a client host.
8451
8452 .next
8453 .cindex "@[] in a host list"
8454 If the pattern is &"@[]"&, it matches the IP address of any IP interface on
8455 the local host. For example, if the local host is an IPv4 host with one
8456 interface address 10.45.23.56, these two ACL statements have the same effect:
8457 .code
8458 accept hosts = 127.0.0.1 : 10.45.23.56
8459 accept hosts = @[]
8460 .endd
8461 .next
8462 .cindex "CIDR notation"
8463 If the pattern is an IP address followed by a slash and a mask length (for
8464 example 10.11.42.0/24), it is matched against the IP address of the subject
8465 host under the given mask. This allows, an entire network of hosts to be
8466 included (or excluded) by a single item. The mask uses CIDR notation; it
8467 specifies the number of address bits that must match, starting from the most
8468 significant end of the address.
8469
8470 &*Note*&: The mask is &'not'& a count of addresses, nor is it the high number
8471 of a range of addresses. It is the number of bits in the network portion of the
8472 address. The above example specifies a 24-bit netmask, so it matches all 256
8473 addresses in the 10.11.42.0 network. An item such as
8474 .code
8475 192.168.23.236/31
8476 .endd
8477 matches just two addresses, 192.168.23.236 and 192.168.23.237. A mask value of
8478 32 for an IPv4 address is the same as no mask at all; just a single address
8479 matches.
8480
8481 Here is another example which shows an IPv4 and an IPv6 network:
8482 .code
8483 recipient_unqualified_hosts = 192.168.0.0/16: \
8484                               3ffe::ffff::836f::::/48
8485 .endd
8486 The doubling of list separator characters applies only when these items
8487 appear inline in a host list. It is not required when indirecting via a file.
8488 For example:
8489 .code
8490 recipient_unqualified_hosts = /opt/exim/unqualnets
8491 .endd
8492 could make use of a file containing
8493 .code
8494 172.16.0.0/12
8495 3ffe:ffff:836f::/48
8496 .endd
8497 to have exactly the same effect as the previous example. When listing IPv6
8498 addresses inline, it is usually more convenient to use the facility for
8499 changing separator characters. This list contains the same two networks:
8500 .code
8501 recipient_unqualified_hosts = <; 172.16.0.0/12; \
8502                                  3ffe:ffff:836f::/48
8503 .endd
8504 The separator is changed to semicolon by the leading &"<;"& at the start of the
8505 list.
8506 .endlist
8507
8508
8509
8510 .section "Host list patterns for single-key lookups by host address" &&&
8511          "SECThoslispatsikey"
8512 .cindex "host list" "lookup of IP address"
8513 When a host is to be identified by a single-key lookup of its complete IP
8514 address, the pattern takes this form:
8515 .display
8516 &`net-<`&&'single-key-search-type'&&`>;<`&&'search-data'&&`>`&
8517 .endd
8518 For example:
8519 .code
8520 hosts_lookup = net-cdb;/hosts-by-ip.db
8521 .endd
8522 The text form of the IP address of the subject host is used as the lookup key.
8523 IPv6 addresses are converted to an unabbreviated form, using lower case
8524 letters, with dots as separators because colon is the key terminator in
8525 &(lsearch)& files. [Colons can in fact be used in keys in &(lsearch)& files by
8526 quoting the keys, but this is a facility that was added later.] The data
8527 returned by the lookup is not used.
8528
8529 .cindex "IP address" "masking"
8530 .cindex "host list" "masked IP address"
8531 Single-key lookups can also be performed using masked IP addresses, using
8532 patterns of this form:
8533 .display
8534 &`net<`&&'number'&&`>-<`&&'single-key-search-type'&&`>;<`&&'search-data'&&`>`&
8535 .endd
8536 For example:
8537 .code
8538 net24-dbm;/networks.db
8539 .endd
8540 The IP address of the subject host is masked using <&'number'&> as the mask
8541 length. A textual string is constructed from the masked value, followed by the
8542 mask, and this is used as the lookup key. For example, if the host's IP address
8543 is 192.168.34.6, the key that is looked up for the above example is
8544 &"192.168.34.0/24"&.
8545
8546 When an IPv6 address is converted to a string, dots are normally used instead
8547 of colons, so that keys in &(lsearch)& files need not contain colons (which
8548 terminate &(lsearch)& keys). This was implemented some time before the ability
8549 to quote keys was made available in &(lsearch)& files. However, the more
8550 recently implemented &(iplsearch)& files do require colons in IPv6 keys
8551 (notated using the quoting facility) so as to distinguish them from IPv4 keys.
8552 For this reason, when the lookup type is &(iplsearch)&, IPv6 addresses are
8553 converted using colons and not dots. In all cases, full, unabbreviated IPv6
8554 addresses are always used.
8555
8556 Ideally, it would be nice to tidy up this anomalous situation by changing to
8557 colons in all cases, given that quoting is now available for &(lsearch)&.
8558 However, this would be an incompatible change that might break some existing
8559 configurations.
8560
8561 &*Warning*&: Specifying &%net32-%& (for an IPv4 address) or &%net128-%& (for an
8562 IPv6 address) is not the same as specifying just &%net-%& without a number. In
8563 the former case the key strings include the mask value, whereas in the latter
8564 case the IP address is used on its own.
8565
8566
8567
8568 .section "Host list patterns that match by host name" "SECThoslispatnam"
8569 .cindex "host" "lookup failures"
8570 .cindex "unknown host name"
8571 .cindex "host list" "matching host name"
8572 There are several types of pattern that require Exim to know the name of the
8573 remote host. These are either wildcard patterns or lookups by name. (If a
8574 complete hostname is given without any wildcarding, it is used to find an IP
8575 address to match against, as described in section &<<SECThoslispatip>>&
8576 above.)
8577
8578 If the remote host name is not already known when Exim encounters one of these
8579 patterns, it has to be found from the IP address.
8580 Although many sites on the Internet are conscientious about maintaining reverse
8581 DNS data for their hosts, there are also many that do not do this.
8582 Consequently, a name cannot always be found, and this may lead to unwanted
8583 effects. Take care when configuring host lists with wildcarded name patterns.
8584 Consider what will happen if a name cannot be found.
8585
8586 Because of the problems of determining host names from IP addresses, matching
8587 against host names is not as common as matching against IP addresses.
8588
8589 By default, in order to find a host name, Exim first does a reverse DNS lookup;
8590 if no name is found in the DNS, the system function (&[gethostbyaddr()]& or
8591 &[getipnodebyaddr()]& if available) is tried. The order in which these lookups
8592 are done can be changed by setting the &%host_lookup_order%& option. For
8593 security, once Exim has found one or more names, it looks up the IP addresses
8594 for these names and compares them with the IP address that it started with.
8595 Only those names whose IP addresses match are accepted. Any other names are
8596 discarded. If no names are left, Exim behaves as if the host name cannot be
8597 found. In the most common case there is only one name and one IP address.
8598
8599 There are some options that control what happens if a host name cannot be
8600 found. These are described in section &<<SECTbehipnot>>& below.
8601
8602 .cindex "host" "alias for"
8603 .cindex "alias for host"
8604 As a result of aliasing, hosts may have more than one name. When processing any
8605 of the following types of pattern, all the host's names are checked:
8606
8607 .ilist
8608 .cindex "asterisk" "in host list"
8609 If a pattern starts with &"*"& the remainder of the item must match the end of
8610 the host name. For example, &`*.b.c`& matches all hosts whose names end in
8611 &'.b.c'&. This special simple form is provided because this is a very common
8612 requirement. Other kinds of wildcarding require the use of a regular
8613 expression.
8614 .next
8615 .cindex "regular expressions" "in host list"
8616 .cindex "host list" "regular expression in"
8617 If the item starts with &"^"& it is taken to be a regular expression which is
8618 matched against the host name. Host names are case-independent, so this regular
8619 expression match is by default case-independent, but you can make it
8620 case-dependent by starting it with &`(?-i)`&. References to descriptions of the
8621 syntax of regular expressions are given in chapter &<<CHAPregexp>>&. For
8622 example,
8623 .code
8624 ^(a|b)\.c\.d$
8625 .endd
8626 is a regular expression that matches either of the two hosts &'a.c.d'& or
8627 &'b.c.d'&. When a regular expression is used in a host list, you must take care
8628 that backslash and dollar characters are not misinterpreted as part of the
8629 string expansion. The simplest way to do this is to use &`\N`& to mark that
8630 part of the string as non-expandable. For example:
8631 .code
8632 sender_unqualified_hosts = \N^(a|b)\.c\.d$\N : ....
8633 .endd
8634 &*Warning*&: If you want to match a complete host name, you must include the
8635 &`$`& terminating metacharacter in the regular expression, as in the above
8636 example. Without it, a match at the start of the host name is all that is
8637 required.
8638 .endlist
8639
8640
8641
8642
8643 .section "Behaviour when an IP address or name cannot be found" "SECTbehipnot"
8644 .cindex "host" "lookup failures, permanent"
8645 While processing a host list, Exim may need to look up an IP address from a
8646 name (see section &<<SECThoslispatip>>&), or it may need to look up a host name
8647 from an IP address (see section &<<SECThoslispatnam>>&). In either case, the
8648 behaviour when it fails to find the information it is seeking is the same.
8649
8650 &*Note*&: This section applies to permanent lookup failures. It does &'not'&
8651 apply to temporary DNS errors, whose handling is described in the next section.
8652
8653 .cindex "&`+include_unknown`&"
8654 .cindex "&`+ignore_unknown`&"
8655 Exim parses a host list from left to right. If it encounters a permanent
8656 lookup failure in any item in the host list before it has found a match,
8657 Exim treats it as a failure and the default behavior is as if the host
8658 does not match the list. This may not always be what you want to happen.
8659 To change Exim's behaviour, the special items &`+include_unknown`& or
8660 &`+ignore_unknown`& may appear in the list (at top level &-- they are
8661 not recognized in an indirected file).
8662
8663 .ilist
8664 If any item that follows &`+include_unknown`& requires information that
8665 cannot found, Exim behaves as if the host does match the list. For example,
8666 .code
8667 host_reject_connection = +include_unknown:*.enemy.ex
8668 .endd
8669 rejects connections from any host whose name matches &`*.enemy.ex`&, and also
8670 any hosts whose name it cannot find.
8671
8672 .next
8673 If any item that follows &`+ignore_unknown`& requires information that cannot
8674 be found, Exim ignores that item and proceeds to the rest of the list. For
8675 example:
8676 .code
8677 accept hosts = +ignore_unknown : friend.example : \
8678                192.168.4.5
8679 .endd
8680 accepts from any host whose name is &'friend.example'& and from 192.168.4.5,
8681 whether or not its host name can be found. Without &`+ignore_unknown`&, if no
8682 name can be found for 192.168.4.5, it is rejected.
8683 .endlist
8684
8685 Both &`+include_unknown`& and &`+ignore_unknown`& may appear in the same
8686 list. The effect of each one lasts until the next, or until the end of the
8687 list.
8688
8689 .section "Mixing wildcarded host names and addresses in host lists" &&&
8690          "SECTmixwilhos"
8691 .cindex "host list" "mixing names and addresses in"
8692
8693 This section explains the host/ip processing logic with the same concepts
8694 as the previous section, but specifically addresses what happens when a
8695 wildcarded hostname is one of the items in the hostlist.
8696
8697 .ilist
8698 If you have name lookups or wildcarded host names and
8699 IP addresses in the same host list, you should normally put the IP
8700 addresses first. For example, in an ACL you could have:
8701 .code
8702 accept hosts = 10.9.8.7 : *.friend.example
8703 .endd
8704 The reason you normally would order it this way lies in the
8705 left-to-right way that Exim processes lists.  It can test IP addresses
8706 without doing any DNS lookups, but when it reaches an item that requires
8707 a host name, it fails if it cannot find a host name to compare with the
8708 pattern. If the above list is given in the opposite order, the
8709 &%accept%& statement fails for a host whose name cannot be found, even
8710 if its IP address is 10.9.8.7.
8711
8712 .next
8713 If you really do want to do the name check first, and still recognize the IP
8714 address, you can rewrite the ACL like this:
8715 .code
8716 accept hosts = *.friend.example
8717 accept hosts = 10.9.8.7
8718 .endd
8719 If the first &%accept%& fails, Exim goes on to try the second one. See chapter
8720 &<<CHAPACL>>& for details of ACLs. Alternatively, you can use
8721 &`+ignore_unknown`&, which was discussed in depth in the first example in
8722 this section.
8723 .endlist
8724
8725
8726 .section "Temporary DNS errors when looking up host information" &&&
8727          "SECTtemdnserr"
8728 .cindex "host" "lookup failures, temporary"
8729 .cindex "&`+include_defer`&"
8730 .cindex "&`+ignore_defer`&"
8731 A temporary DNS lookup failure normally causes a defer action (except when
8732 &%dns_again_means_nonexist%& converts it into a permanent error). However,
8733 host lists can include &`+ignore_defer`& and &`+include_defer`&, analogous to
8734 &`+ignore_unknown`& and &`+include_unknown`&, as described in the previous
8735 section. These options should be used with care, probably only in non-critical
8736 host lists such as whitelists.
8737
8738
8739
8740 .section "Host list patterns for single-key lookups by host name" &&&
8741          "SECThoslispatnamsk"
8742 .cindex "unknown host name"
8743 .cindex "host list" "matching host name"
8744 If a pattern is of the form
8745 .display
8746 <&'single-key-search-type'&>;<&'search-data'&>
8747 .endd
8748 for example
8749 .code
8750 dbm;/host/accept/list
8751 .endd
8752 a single-key lookup is performed, using the host name as its key. If the
8753 lookup succeeds, the host matches the item. The actual data that is looked up
8754 is not used.
8755
8756 &*Reminder*&: With this kind of pattern, you must have host &'names'& as
8757 keys in the file, not IP addresses. If you want to do lookups based on IP
8758 addresses, you must precede the search type with &"net-"& (see section
8759 &<<SECThoslispatsikey>>&). There is, however, no reason why you could not use
8760 two items in the same list, one doing an address lookup and one doing a name
8761 lookup, both using the same file.
8762
8763
8764
8765 .section "Host list patterns for query-style lookups" "SECID81"
8766 If a pattern is of the form
8767 .display
8768 <&'query-style-search-type'&>;<&'query'&>
8769 .endd
8770 the query is obeyed, and if it succeeds, the host matches the item. The actual
8771 data that is looked up is not used. The variables &$sender_host_address$& and
8772 &$sender_host_name$& can be used in the query. For example:
8773 .code
8774 hosts_lookup = pgsql;\
8775   select ip from hostlist where ip='$sender_host_address'
8776 .endd
8777 The value of &$sender_host_address$& for an IPv6 address contains colons. You
8778 can use the &%sg%& expansion item to change this if you need to. If you want to
8779 use masked IP addresses in database queries, you can use the &%mask%& expansion
8780 operator.
8781
8782 If the query contains a reference to &$sender_host_name$&, Exim automatically
8783 looks up the host name if it has not already done so. (See section
8784 &<<SECThoslispatnam>>& for comments on finding host names.)
8785
8786 Historical note: prior to release 4.30, Exim would always attempt to find a
8787 host name before running the query, unless the search type was preceded by
8788 &`net-`&. This is no longer the case. For backwards compatibility, &`net-`& is
8789 still recognized for query-style lookups, but its presence or absence has no
8790 effect. (Of course, for single-key lookups, &`net-`& &'is'& important.
8791 See section &<<SECThoslispatsikey>>&.)
8792
8793
8794
8795
8796
8797 .section "Address lists" "SECTaddresslist"
8798 .cindex "list" "address list"
8799 .cindex "address list" "empty item"
8800 .cindex "address list" "patterns"
8801 Address lists contain patterns that are matched against mail addresses. There
8802 is one special case to be considered: the sender address of a bounce message is
8803 always empty. You can test for this by providing an empty item in an address
8804 list. For example, you can set up a router to process bounce messages by
8805 using this option setting:
8806 .code
8807 senders = :
8808 .endd
8809 The presence of the colon creates an empty item. If you do not provide any
8810 data, the list is empty and matches nothing. The empty sender can also be
8811 detected by a regular expression that matches an empty string,
8812 and by a query-style lookup that succeeds when &$sender_address$& is empty.
8813
8814 Non-empty items in an address list can be straightforward email addresses. For
8815 example:
8816 .code
8817 senders = jbc@askone.example : hs@anacreon.example
8818 .endd
8819 A certain amount of wildcarding is permitted. If a pattern contains an @
8820 character, but is not a regular expression and does not begin with a
8821 semicolon-terminated lookup type (described below), the local part of the
8822 subject address is compared with the local part of the pattern, which may start
8823 with an asterisk. If the local parts match, the domain is checked in exactly
8824 the same way as for a pattern in a domain list. For example, the domain can be
8825 wildcarded, refer to a named list, or be a lookup:
8826 .code
8827 deny senders = *@*.spamming.site:\
8828                *@+hostile_domains:\
8829                bozo@partial-lsearch;/list/of/dodgy/sites:\
8830                *@dbm;/bad/domains.db
8831 .endd
8832 .cindex "local part" "starting with !"
8833 .cindex "address list" "local part starting with !"
8834 If a local part that begins with an exclamation mark is required, it has to be
8835 specified using a regular expression, because otherwise the exclamation mark is
8836 treated as a sign of negation, as is standard in lists.
8837
8838 If a non-empty pattern that is not a regular expression or a lookup does not
8839 contain an @ character, it is matched against the domain part of the subject
8840 address. The only two formats that are recognized this way are a literal
8841 domain, or a domain pattern that starts with *. In both these cases, the effect
8842 is the same as if &`*@`& preceded the pattern. For example:
8843 .code
8844 deny senders = enemy.domain : *.enemy.domain
8845 .endd
8846
8847 The following kinds of more complicated address list pattern can match any
8848 address, including the empty address that is characteristic of bounce message
8849 senders:
8850
8851 .ilist
8852 .cindex "regular expressions" "in address list"
8853 .cindex "address list" "regular expression in"
8854 If (after expansion) a pattern starts with &"^"&, a regular expression match is
8855 done against the complete address, with the pattern as the regular expression.
8856 You must take care that backslash and dollar characters are not misinterpreted
8857 as part of the string expansion. The simplest way to do this is to use &`\N`&
8858 to mark that part of the string as non-expandable. For example:
8859 .code
8860 deny senders = \N^.*this.*@example\.com$\N : \
8861                \N^\d{8}.+@spamhaus.example$\N : ...
8862 .endd
8863 The &`\N`& sequences are removed by the expansion, so these items do indeed
8864 start with &"^"& by the time they are being interpreted as address patterns.
8865
8866 .next
8867 .cindex "address list" "lookup for complete address"
8868 Complete addresses can be looked up by using a pattern that starts with a
8869 lookup type terminated by a semicolon, followed by the data for the lookup. For
8870 example:
8871 .code
8872 deny senders = cdb;/etc/blocked.senders : \
8873   mysql;select address from blocked where \
8874   address='${quote_mysql:$sender_address}'
8875 .endd
8876 Both query-style and single-key lookup types can be used. For a single-key
8877 lookup type, Exim uses the complete address as the key. However, empty keys are
8878 not supported for single-key lookups, so a match against the empty address
8879 always fails. This restriction does not apply to query-style lookups.
8880
8881 Partial matching for single-key lookups (section &<<SECTpartiallookup>>&)
8882 cannot be used, and is ignored if specified, with an entry being written to the
8883 panic log.
8884 .cindex "*@ with single-key lookup"
8885 However, you can configure lookup defaults, as described in section
8886 &<<SECTdefaultvaluelookups>>&, but this is useful only for the &"*@"& type of
8887 default. For example, with this lookup:
8888 .code
8889 accept senders = lsearch*@;/some/file
8890 .endd
8891 the file could contains lines like this:
8892 .code
8893 user1@domain1.example
8894 *@domain2.example
8895 .endd
8896 and for the sender address &'nimrod@jaeger.example'&, the sequence of keys
8897 that are tried is:
8898 .code
8899 nimrod@jaeger.example
8900 *@jaeger.example
8901 *
8902 .endd
8903 &*Warning 1*&: Do not include a line keyed by &"*"& in the file, because that
8904 would mean that every address matches, thus rendering the test useless.
8905
8906 &*Warning 2*&: Do not confuse these two kinds of item:
8907 .code
8908 deny recipients = dbm*@;/some/file
8909 deny recipients = *@dbm;/some/file
8910 .endd
8911 The first does a whole address lookup, with defaulting, as just described,
8912 because it starts with a lookup type. The second matches the local part and
8913 domain independently, as described in a bullet point below.
8914 .endlist
8915
8916
8917 The following kinds of address list pattern can match only non-empty addresses.
8918 If the subject address is empty, a match against any of these pattern types
8919 always fails.
8920
8921
8922 .ilist
8923 .cindex "@@ with single-key lookup"
8924 .cindex "address list" "@@ lookup type"
8925 .cindex "address list" "split local part and domain"
8926 If a pattern starts with &"@@"& followed by a single-key lookup item
8927 (for example, &`@@lsearch;/some/file`&), the address that is being checked is
8928 split into a local part and a domain. The domain is looked up in the file. If
8929 it is not found, there is no match. If it is found, the data that is looked up
8930 from the file is treated as a colon-separated list of local part patterns, each
8931 of which is matched against the subject local part in turn.
8932
8933 .cindex "asterisk" "in address list"
8934 The lookup may be a partial one, and/or one involving a search for a default
8935 keyed by &"*"& (see section &<<SECTdefaultvaluelookups>>&). The local part
8936 patterns that are looked up can be regular expressions or begin with &"*"&, or
8937 even be further lookups. They may also be independently negated. For example,
8938 with
8939 .code
8940 deny senders = @@dbm;/etc/reject-by-domain
8941 .endd
8942 the data from which the DBM file is built could contain lines like
8943 .code
8944 baddomain.com:  !postmaster : *
8945 .endd
8946 to reject all senders except &%postmaster%& from that domain.
8947
8948 .cindex "local part" "starting with !"
8949 If a local part that actually begins with an exclamation mark is required, it
8950 has to be specified using a regular expression. In &(lsearch)& files, an entry
8951 may be split over several lines by indenting the second and subsequent lines,
8952 but the separating colon must still be included at line breaks. White space
8953 surrounding the colons is ignored. For example:
8954 .code
8955 aol.com:  spammer1 : spammer2 : ^[0-9]+$ :
8956   spammer3 : spammer4
8957 .endd
8958 As in all colon-separated lists in Exim, a colon can be included in an item by
8959 doubling.
8960
8961 If the last item in the list starts with a right angle-bracket, the remainder
8962 of the item is taken as a new key to look up in order to obtain a continuation
8963 list of local parts. The new key can be any sequence of characters. Thus one
8964 might have entries like
8965 .code
8966 aol.com: spammer1 : spammer 2 : >*
8967 xyz.com: spammer3 : >*
8968 *:       ^\d{8}$
8969 .endd
8970 in a file that was searched with &%@@dbm*%&, to specify a match for 8-digit
8971 local parts for all domains, in addition to the specific local parts listed for
8972 each domain. Of course, using this feature costs another lookup each time a
8973 chain is followed, but the effort needed to maintain the data is reduced.
8974
8975 .cindex "loop" "in lookups"
8976 It is possible to construct loops using this facility, and in order to catch
8977 them, the chains may be no more than fifty items long.
8978
8979 .next
8980 The @@<&'lookup'&> style of item can also be used with a query-style
8981 lookup, but in this case, the chaining facility is not available. The lookup
8982 can only return a single list of local parts.
8983 .endlist
8984
8985 &*Warning*&: There is an important difference between the address list items
8986 in these two examples:
8987 .code
8988 senders = +my_list
8989 senders = *@+my_list
8990 .endd
8991 In the first one, &`my_list`& is a named address list, whereas in the second
8992 example it is a named domain list.
8993
8994
8995
8996
8997 .section "Case of letters in address lists" "SECTcasletadd"
8998 .cindex "case of local parts"
8999 .cindex "address list" "case forcing"
9000 .cindex "case forcing in address lists"
9001 Domains in email addresses are always handled caselessly, but for local parts
9002 case may be significant on some systems (see &%caseful_local_part%& for how
9003 Exim deals with this when routing addresses). However, RFC 2505 (&'Anti-Spam
9004 Recommendations for SMTP MTAs'&) suggests that matching of addresses to
9005 blocking lists should be done in a case-independent manner. Since most address
9006 lists in Exim are used for this kind of control, Exim attempts to do this by
9007 default.
9008
9009 The domain portion of an address is always lowercased before matching it to an
9010 address list. The local part is lowercased by default, and any string
9011 comparisons that take place are done caselessly. This means that the data in
9012 the address list itself, in files included as plain file names, and in any file
9013 that is looked up using the &"@@"& mechanism, can be in any case. However, the
9014 keys in files that are looked up by a search type other than &(lsearch)& (which
9015 works caselessly) must be in lower case, because these lookups are not
9016 case-independent.
9017
9018 .cindex "&`+caseful`&"
9019 To allow for the possibility of caseful address list matching, if an item in
9020 an address list is the string &"+caseful"&, the original case of the local
9021 part is restored for any comparisons that follow, and string comparisons are no
9022 longer case-independent. This does not affect the domain, which remains in
9023 lower case. However, although independent matches on the domain alone are still
9024 performed caselessly, regular expressions that match against an entire address
9025 become case-sensitive after &"+caseful"& has been seen.
9026
9027
9028
9029 .section "Local part lists" "SECTlocparlis"
9030 .cindex "list" "local part list"
9031 .cindex "local part" "list"
9032 Case-sensitivity in local part lists is handled in the same way as for address
9033 lists, as just described. The &"+caseful"& item can be used if required. In a
9034 setting of the &%local_parts%& option in a router with &%caseful_local_part%&
9035 set false, the subject is lowercased and the matching is initially
9036 case-insensitive. In this case, &"+caseful"& will restore case-sensitive
9037 matching in the local part list, but not elsewhere in the router. If
9038 &%caseful_local_part%& is set true in a router, matching in the &%local_parts%&
9039 option is case-sensitive from the start.
9040
9041 If a local part list is indirected to a file (see section &<<SECTfilnamlis>>&),
9042 comments are handled in the same way as address lists &-- they are recognized
9043 only if the # is preceded by white space or the start of the line.
9044 Otherwise, local part lists are matched in the same way as domain lists, except
9045 that the special items that refer to the local host (&`@`&, &`@[]`&,
9046 &`@mx_any`&, &`@mx_primary`&, and &`@mx_secondary`&) are not recognized.
9047 Refer to section &<<SECTdomainlist>>& for details of the other available item
9048 types.
9049 .ecindex IIDdohoadli
9050
9051
9052
9053
9054 . ////////////////////////////////////////////////////////////////////////////
9055 . ////////////////////////////////////////////////////////////////////////////
9056
9057 .chapter "String expansions" "CHAPexpand"
9058 .scindex IIDstrexp "expansion" "of strings"
9059 Many strings in Exim's run time configuration are expanded before use. Some of
9060 them are expanded every time they are used; others are expanded only once.
9061
9062 When a string is being expanded it is copied verbatim from left to right except
9063 when a dollar or backslash character is encountered. A dollar specifies the
9064 start of a portion of the string that is interpreted and replaced as described
9065 below in section &<<SECTexpansionitems>>& onwards. Backslash is used as an
9066 escape character, as described in the following section.
9067
9068 Whether a string is expanded depends upon the context.  Usually this is solely
9069 dependent upon the option for which a value is sought; in this documentation,
9070 options for which string expansion is performed are marked with &dagger; after
9071 the data type.  ACL rules always expand strings.  A couple of expansion
9072 conditions do not expand some of the brace-delimited branches, for security
9073 reasons.
9074
9075
9076
9077 .section "Literal text in expanded strings" "SECTlittext"
9078 .cindex "expansion" "including literal text"
9079 An uninterpreted dollar can be included in an expanded string by putting a
9080 backslash in front of it. A backslash can be used to prevent any special
9081 character being treated specially in an expansion, including backslash itself.
9082 If the string appears in quotes in the configuration file, two backslashes are
9083 required because the quotes themselves cause interpretation of backslashes when
9084 the string is read in (see section &<<SECTstrings>>&).
9085
9086 .cindex "expansion" "non-expandable substrings"
9087 A portion of the string can specified as non-expandable by placing it between
9088 two occurrences of &`\N`&. This is particularly useful for protecting regular
9089 expressions, which often contain backslashes and dollar signs. For example:
9090 .code
9091 deny senders = \N^\d{8}[a-z]@some\.site\.example$\N
9092 .endd
9093 On encountering the first &`\N`&, the expander copies subsequent characters
9094 without interpretation until it reaches the next &`\N`& or the end of the
9095 string.
9096
9097
9098
9099 .section "Character escape sequences in expanded strings" "SECID82"
9100 .cindex "expansion" "escape sequences"
9101 A backslash followed by one of the letters &"n"&, &"r"&, or &"t"& in an
9102 expanded string is recognized as an escape sequence for the character newline,
9103 carriage return, or tab, respectively. A backslash followed by up to three
9104 octal digits is recognized as an octal encoding for a single character, and a
9105 backslash followed by &"x"& and up to two hexadecimal digits is a hexadecimal
9106 encoding.
9107
9108 These escape sequences are also recognized in quoted strings when they are read
9109 in. Their interpretation in expansions as well is useful for unquoted strings,
9110 and for other cases such as looked-up strings that are then expanded.
9111
9112
9113 .section "Testing string expansions" "SECID83"
9114 .cindex "expansion" "testing"
9115 .cindex "testing" "string expansion"
9116 .oindex "&%-be%&"
9117 Many expansions can be tested by calling Exim with the &%-be%& option. This
9118 takes the command arguments, or lines from the standard input if there are no
9119 arguments, runs them through the string expansion code, and writes the results
9120 to the standard output. Variables based on configuration values are set up, but
9121 since no message is being processed, variables such as &$local_part$& have no
9122 value. Nevertheless the &%-be%& option can be useful for checking out file and
9123 database lookups, and the use of expansion operators such as &%sg%&, &%substr%&
9124 and &%nhash%&.
9125
9126 Exim gives up its root privilege when it is called with the &%-be%& option, and
9127 instead runs under the uid and gid it was called with, to prevent users from
9128 using &%-be%& for reading files to which they do not have access.
9129
9130 .oindex "&%-bem%&"
9131 If you want to test expansions that include variables whose values are taken
9132 from a message, there are two other options that can be used. The &%-bem%&
9133 option is like &%-be%& except that it is followed by a file name. The file is
9134 read as a message before doing the test expansions. For example:
9135 .code
9136 exim -bem /tmp/test.message '$h_subject:'
9137 .endd
9138 The &%-Mset%& option is used in conjunction with &%-be%& and is followed by an
9139 Exim message identifier. For example:
9140 .code
9141 exim -be -Mset 1GrA8W-0004WS-LQ '$recipients'
9142 .endd
9143 This loads the message from Exim's spool before doing the test expansions, and
9144 is therefore restricted to admin users.
9145
9146
9147 .section "Forced expansion failure" "SECTforexpfai"
9148 .cindex "expansion" "forced failure"
9149 A number of expansions that are described in the following section have
9150 alternative &"true"& and &"false"& substrings, enclosed in brace characters
9151 (which are sometimes called &"curly brackets"&). Which of the two strings is
9152 used depends on some condition that is evaluated as part of the expansion. If,
9153 instead of a &"false"& substring, the word &"fail"& is used (not in braces),
9154 the entire string expansion fails in a way that can be detected by the code
9155 that requested the expansion. This is called &"forced expansion failure"&, and
9156 its consequences depend on the circumstances. In some cases it is no different
9157 from any other expansion failure, but in others a different action may be
9158 taken. Such variations are mentioned in the documentation of the option that is
9159 being expanded.
9160
9161
9162
9163
9164 .section "Expansion items" "SECTexpansionitems"
9165 The following items are recognized in expanded strings. White space may be used
9166 between sub-items that are keywords or substrings enclosed in braces inside an
9167 outer set of braces, to improve readability. &*Warning*&: Within braces,
9168 white space is significant.
9169
9170 .vlist
9171 .vitem &*$*&<&'variable&~name'&>&~or&~&*${*&<&'variable&~name'&>&*}*&
9172 .cindex "expansion" "variables"
9173 Substitute the contents of the named variable, for example:
9174 .code
9175 $local_part
9176 ${domain}
9177 .endd
9178 The second form can be used to separate the name from subsequent alphanumeric
9179 characters. This form (using braces) is available only for variables; it does
9180 &'not'& apply to message headers. The names of the variables are given in
9181 section &<<SECTexpvar>>& below. If the name of a non-existent variable is
9182 given, the expansion fails.
9183
9184 .vitem &*${*&<&'op'&>&*:*&<&'string'&>&*}*&
9185 .cindex "expansion" "operators"
9186 The string is first itself expanded, and then the operation specified by
9187 <&'op'&> is applied to it. For example:
9188 .code
9189 ${lc:$local_part}
9190 .endd
9191 The string starts with the first character after the colon, which may be
9192 leading white space. A list of operators is given in section &<<SECTexpop>>&
9193 below. The operator notation is used for simple expansion items that have just
9194 one argument, because it reduces the number of braces and therefore makes the
9195 string easier to understand.
9196
9197 .vitem &*$bheader_*&<&'header&~name'&>&*:*&&~or&~&*$bh_*&<&'header&~name'&>&*:*&
9198 This item inserts &"basic"& header lines. It is described with the &%header%&
9199 expansion item below.
9200
9201
9202 .vitem "&*${acl{*&<&'name'&>&*}{*&<&'arg'&>&*}...}*&"
9203 .cindex "expansion" "calling an acl"
9204 .cindex "&%acl%&" "call from expansion"
9205 The name and zero to nine argument strings are first expanded separately.  The expanded
9206 arguments are assigned to the variables &$acl_arg1$& to &$acl_arg9$& in order.
9207 Any unused are made empty.  The variable &$acl_narg$& is set to the number of
9208 arguments.  The named ACL (see chapter &<<CHAPACL>>&) is called
9209 and may use the variables; if another acl expansion is used the values
9210 are restored after it returns.  If the ACL sets
9211 a value using a "message =" modifier and returns accept or deny, the value becomes
9212 the result of the expansion.
9213 If no message is set and the ACL returns accept or deny
9214 the expansion result is an empty string.
9215 If the ACL returns defer the result is a forced-fail.  Otherwise the expansion fails.
9216
9217
9218 .vitem "&*${authresults{*&<&'authserv-id'&>&*}}*&"
9219 .cindex authentication "results header"
9220 .cindex headers "authentication-results:"
9221 .cindex authentication "expansion item"
9222 This item returns a string suitable for insertion as an
9223 &'Authentication-Results"'&
9224 header line.
9225 The given <&'authserv-id'&> is included in the result; typically this
9226 will be a domain name identifying the system performing the authentications.
9227 Methods that might be present in the result include:
9228 .code
9229 none
9230 iprev
9231 auth
9232 spf
9233 dkim
9234 .endd
9235
9236 Example use (as an ACL modifier):
9237 .code
9238       add_header = :at_start:${authresults {$primary_hostname}}
9239 .endd
9240 This is safe even if no authentication results are available.
9241
9242
9243 .vitem "&*${certextract{*&<&'field'&>&*}{*&<&'certificate'&>&*}&&&
9244        {*&<&'string2'&>&*}{*&<&'string3'&>&*}}*&"
9245 .cindex "expansion" "extracting certificate fields"
9246 .cindex "&%certextract%&" "certificate fields"
9247 .cindex "certificate" "extracting fields"
9248 The <&'certificate'&> must be a variable of type certificate.
9249 The field name is expanded and used to retrieve the relevant field from
9250 the certificate.  Supported fields are:
9251 .display
9252 &`version        `&
9253 &`serial_number  `&
9254 &`subject        `& RFC4514 DN
9255 &`issuer         `& RFC4514 DN
9256 &`notbefore      `& time
9257 &`notafter       `& time
9258 &`sig_algorithm  `&
9259 &`signature      `&
9260 &`subj_altname   `& tagged list
9261 &`ocsp_uri       `& list
9262 &`crl_uri        `& list
9263 .endd
9264 If the field is found,
9265 <&'string2'&> is expanded, and replaces the whole item;
9266 otherwise <&'string3'&> is used. During the expansion of <&'string2'&> the
9267 variable &$value$& contains the value that has been extracted. Afterwards, it
9268 is restored to any previous value it might have had.
9269
9270 If {<&'string3'&>} is omitted, the item is replaced by an empty string if the
9271 key is not found. If {<&'string2'&>} is also omitted, the value that was
9272 extracted is used.
9273
9274 Some field names take optional modifiers, appended and separated by commas.
9275
9276 The field selectors marked as "RFC4514" above
9277 output a Distinguished Name string which is
9278 not quite
9279 parseable by Exim as a comma-separated tagged list
9280 (the exceptions being elements containing commas).
9281 RDN elements of a single type may be selected by
9282 a modifier of the type label; if so the expansion
9283 result is a list (newline-separated by default).
9284 The separator may be changed by another modifier of
9285 a right angle-bracket followed immediately by the new separator.
9286 Recognised RDN type labels include "CN", "O", "OU" and "DC".
9287
9288 The field selectors marked as "time" above
9289 take an optional modifier of "int"
9290 for which the result is the number of seconds since epoch.
9291 Otherwise the result is a human-readable string
9292 in the timezone selected by the main "timezone" option.
9293
9294 The field selectors marked as "list" above return a list,
9295 newline-separated by default,
9296 (embedded separator characters in elements are doubled).
9297 The separator may be changed by a modifier of
9298 a right angle-bracket followed immediately by the new separator.
9299
9300 The field selectors marked as "tagged" above
9301 prefix each list element with a type string and an equals sign.
9302 Elements of only one type may be selected by a modifier
9303 which is one of "dns", "uri" or "mail";
9304 if so the element tags are omitted.
9305
9306 If not otherwise noted field values are presented in human-readable form.
9307
9308 .vitem "&*${dlfunc{*&<&'file'&>&*}{*&<&'function'&>&*}{*&<&'arg'&>&*}&&&
9309        {*&<&'arg'&>&*}...}*&"
9310 .cindex &%dlfunc%&
9311 This expansion dynamically loads and then calls a locally-written C function.
9312 This functionality is available only if Exim is compiled with
9313 .code
9314 EXPAND_DLFUNC=yes
9315 .endd
9316 set in &_Local/Makefile_&. Once loaded, Exim remembers the dynamically loaded
9317 object so that it doesn't reload the same object file in the same Exim process
9318 (but of course Exim does start new processes frequently).
9319
9320 There may be from zero to eight arguments to the function. When compiling
9321 a local function that is to be called in this way, &_local_scan.h_& should be
9322 included. The Exim variables and functions that are defined by that API
9323 are also available for dynamically loaded functions. The function itself
9324 must have the following type:
9325 .code
9326 int dlfunction(uschar **yield, int argc, uschar *argv[])
9327 .endd
9328 Where &`uschar`& is a typedef for &`unsigned char`& in &_local_scan.h_&. The
9329 function should return one of the following values:
9330
9331 &`OK`&: Success. The string that is placed in the variable &'yield'& is put
9332 into the expanded string that is being built.
9333
9334 &`FAIL`&: A non-forced expansion failure occurs, with the error message taken
9335 from &'yield'&, if it is set.
9336
9337 &`FAIL_FORCED`&: A forced expansion failure occurs, with the error message
9338 taken from &'yield'& if it is set.
9339
9340 &`ERROR`&: Same as &`FAIL`&, except that a panic log entry is written.
9341
9342 When compiling a function that is to be used in this way with gcc,
9343 you need to add &%-shared%& to the gcc command. Also, in the Exim build-time
9344 configuration, you must add &%-export-dynamic%& to EXTRALIBS.
9345
9346
9347 .vitem "&*${env{*&<&'key'&>&*}{*&<&'string1'&>&*}{*&<&'string2'&>&*}}*&"
9348 .cindex "expansion" "extracting value from environment"
9349 .cindex "environment" "values from"
9350 The key is first expanded separately, and leading and trailing white space
9351 removed.
9352 This is then searched for as a name in the environment.
9353 If a variable is found then its value is placed in &$value$&
9354 and <&'string1'&> is expanded, otherwise <&'string2'&> is expanded.
9355
9356 Instead of {<&'string2'&>} the word &"fail"& (not in curly brackets) can
9357 appear, for example:
9358 .code
9359 ${env{USER}{$value} fail }
9360 .endd
9361 This forces an expansion failure (see section &<<SECTforexpfai>>&);
9362 {<&'string1'&>} must be present for &"fail"& to be recognized.
9363
9364 If {<&'string2'&>} is omitted an empty string is substituted on
9365 search failure.
9366 If {<&'string1'&>} is omitted the search result is substituted on
9367 search success.
9368
9369 The environment is adjusted by the &%keep_environment%& and
9370 &%add_environment%& main section options.
9371
9372
9373 .vitem "&*${extract{*&<&'key'&>&*}{*&<&'string1'&>&*}{*&<&'string2'&>&*}&&&
9374        {*&<&'string3'&>&*}}*&"
9375 .cindex "expansion" "extracting substrings by key"
9376 .cindex "&%extract%&" "substrings by key"
9377 The key and <&'string1'&> are first expanded separately. Leading and trailing
9378 white space is removed from the key (but not from any of the strings). The key
9379 must not be empty and must not consist entirely of digits.
9380 The expanded <&'string1'&> must be of the form:
9381 .display
9382 <&'key1'&> = <&'value1'&>  <&'key2'&> = <&'value2'&> ...
9383 .endd
9384 .vindex "&$value$&"
9385 where the equals signs and spaces (but not both) are optional. If any of the
9386 values contain white space, they must be enclosed in double quotes, and any
9387 values that are enclosed in double quotes are subject to escape processing as
9388 described in section &<<SECTstrings>>&. The expanded <&'string1'&> is searched
9389 for the value that corresponds to the key. The search is case-insensitive. If
9390 the key is found, <&'string2'&> is expanded, and replaces the whole item;
9391 otherwise <&'string3'&> is used. During the expansion of <&'string2'&> the
9392 variable &$value$& contains the value that has been extracted. Afterwards, it
9393 is restored to any previous value it might have had.
9394
9395 If {<&'string3'&>} is omitted, the item is replaced by an empty string if the
9396 key is not found. If {<&'string2'&>} is also omitted, the value that was
9397 extracted is used. Thus, for example, these two expansions are identical, and
9398 yield &"2001"&:
9399 .code
9400 ${extract{gid}{uid=1984 gid=2001}}
9401 ${extract{gid}{uid=1984 gid=2001}{$value}}
9402 .endd
9403 Instead of {<&'string3'&>} the word &"fail"& (not in curly brackets) can
9404 appear, for example:
9405 .code
9406 ${extract{Z}{A=... B=...}{$value} fail }
9407 .endd
9408 This forces an expansion failure (see section &<<SECTforexpfai>>&);
9409 {<&'string2'&>} must be present for &"fail"& to be recognized.
9410
9411 .new
9412 .vitem "&*${extract json{*&<&'key'&>&*}{*&<&'string1'&>&*}{*&<&'string2'&>&*}&&&
9413        {*&<&'string3'&>&*}}*&"
9414 .cindex "expansion" "extracting from JSON object"
9415 .cindex JSON expansions
9416 The key and <&'string1'&> are first expanded separately. Leading and trailing
9417 white space is removed from the key (but not from any of the strings). The key
9418 must not be empty and must not consist entirely of digits.
9419 The expanded <&'string1'&> must be of the form:
9420 .display
9421 { <&'"key1"'&> : <&'value1'&> ,  <&'"key2"'&> , <&'value2'&> ... }
9422 .endd
9423 .vindex "&$value$&"
9424 The braces, commas and colons, and the quoting of the member name are required;
9425 the spaces are optional.
9426 Matching of the key against the member names is done case-sensitively.
9427 . XXX should be a UTF-8 compare
9428
9429 The results of matching are handled as above.
9430 .wen
9431
9432
9433 .vitem "&*${extract{*&<&'number'&>&*}{*&<&'separators'&>&*}&&&
9434         {*&<&'string1'&>&*}{*&<&'string2'&>&*}{*&<&'string3'&>&*}}*&"
9435 .cindex "expansion" "extracting substrings by number"
9436 .cindex "&%extract%&" "substrings by number"
9437 The <&'number'&> argument must consist entirely of decimal digits,
9438 apart from leading and trailing white space, which is ignored.
9439 This is what distinguishes this form of &%extract%& from the previous kind. It
9440 behaves in the same way, except that, instead of extracting a named field, it
9441 extracts from <&'string1'&> the field whose number is given as the first
9442 argument. You can use &$value$& in <&'string2'&> or &`fail`& instead of
9443 <&'string3'&> as before.
9444
9445 The fields in the string are separated by any one of the characters in the
9446 separator string. These may include space or tab characters.
9447 The first field is numbered one. If the number is negative, the fields are
9448 counted from the end of the string, with the rightmost one numbered -1. If the
9449 number given is zero, the entire string is returned. If the modulus of the
9450 number is greater than the number of fields in the string, the result is the
9451 expansion of <&'string3'&>, or the empty string if <&'string3'&> is not
9452 provided. For example:
9453 .code
9454 ${extract{2}{:}{x:42:99:& Mailer::/bin/bash}}
9455 .endd
9456 yields &"42"&, and
9457 .code
9458 ${extract{-4}{:}{x:42:99:& Mailer::/bin/bash}}
9459 .endd
9460 yields &"99"&. Two successive separators mean that the field between them is
9461 empty (for example, the fifth field above).
9462
9463
9464 .new
9465 .vitem "&*${extract json{*&<&'number'&>&*}}&&&
9466         {*&<&'string1'&>&*}{*&<&'string2'&>&*}{*&<&'string3'&>&*}}*&"
9467 .cindex "expansion" "extracting from JSON array"
9468 .cindex JSON expansions
9469 The <&'number'&> argument must consist entirely of decimal digits,
9470 apart from leading and trailing white space, which is ignored.
9471
9472 Field selection and result handling is as above;
9473 there is no choice of field separator.
9474 .wen
9475
9476
9477 .vitem &*${filter{*&<&'string'&>&*}{*&<&'condition'&>&*}}*&
9478 .cindex "list" "selecting by condition"
9479 .cindex "expansion" "selecting from list by condition"
9480 .vindex "&$item$&"
9481 After expansion, <&'string'&> is interpreted as a list, colon-separated by
9482 default, but the separator can be changed in the usual way. For each item
9483 in this list, its value is place in &$item$&, and then the condition is
9484 evaluated. If the condition is true, &$item$& is added to the output as an
9485 item in a new list; if the condition is false, the item is discarded. The
9486 separator used for the output list is the same as the one used for the
9487 input, but a separator setting is not included in the output. For example:
9488 .code
9489 ${filter{a:b:c}{!eq{$item}{b}}}
9490 .endd
9491 yields &`a:c`&. At the end of the expansion, the value of &$item$& is restored
9492 to what it was before. See also the &*map*& and &*reduce*& expansion items.
9493
9494
9495 .vitem &*${hash{*&<&'string1'&>&*}{*&<&'string2'&>&*}{*&<&'string3'&>&*}}*&
9496 .cindex "hash function" "textual"
9497 .cindex "expansion" "textual hash"
9498 This is a textual hashing function, and was the first to be implemented in
9499 early versions of Exim. In current releases, there are other hashing functions
9500 (numeric, MD5, and SHA-1), which are described below.
9501
9502 The first two strings, after expansion, must be numbers. Call them <&'m'&> and
9503 <&'n'&>. If you are using fixed values for these numbers, that is, if
9504 <&'string1'&> and <&'string2'&> do not change when they are expanded, you can
9505 use the simpler operator notation that avoids some of the braces:
9506 .code
9507 ${hash_<n>_<m>:<string>}
9508 .endd
9509 The second number is optional (in both notations). If <&'n'&> is greater than
9510 or equal to the length of the string, the expansion item returns the string.
9511 Otherwise it computes a new string of length <&'n'&> by applying a hashing
9512 function to the string. The new string consists of characters taken from the
9513 first <&'m'&> characters of the string
9514 .code
9515 abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQWRSTUVWXYZ0123456789
9516 .endd
9517 If <&'m'&> is not present the value 26 is used, so that only lower case
9518 letters appear. For example:
9519 .display
9520 &`$hash{3}{monty}}           `&   yields  &`jmg`&
9521 &`$hash{5}{monty}}           `&   yields  &`monty`&
9522 &`$hash{4}{62}{monty python}}`&   yields  &`fbWx`&
9523 .endd
9524
9525 .vitem "&*$header_*&<&'header&~name'&>&*:*&&~or&~&&&
9526         &*$h_*&<&'header&~name'&>&*:*&" &&&
9527        "&*$bheader_*&<&'header&~name'&>&*:*&&~or&~&&&
9528         &*$bh_*&<&'header&~name'&>&*:*&" &&&
9529        "&*$lheader_*&<&'header&~name'&>&*:*&&~or&~&&&
9530         &*$lh_*&<&'header&~name'&>&*:*&"
9531        "&*$rheader_*&<&'header&~name'&>&*:*&&~or&~&&&
9532         &*$rh_*&<&'header&~name'&>&*:*&"
9533 .cindex "expansion" "header insertion"
9534 .vindex "&$header_$&"
9535 .vindex "&$bheader_$&"
9536 .vindex "&$lheader_$&"
9537 .vindex "&$rheader_$&"
9538 .cindex "header lines" "in expansion strings"
9539 .cindex "header lines" "character sets"
9540 .cindex "header lines" "decoding"
9541 Substitute the contents of the named message header line, for example
9542 .code
9543 $header_reply-to:
9544 .endd
9545 The newline that terminates a header line is not included in the expansion, but
9546 internal newlines (caused by splitting the header line over several physical
9547 lines) may be present.
9548
9549 The difference between the four pairs of expansions is in the way
9550 the data in the header line is interpreted.
9551
9552 .ilist
9553 .cindex "white space" "in header lines"
9554 &%rheader%& gives the original &"raw"& content of the header line, with no
9555 processing at all, and without the removal of leading and trailing white space.
9556
9557 .next
9558 .cindex "list" "of header lines"
9559 &%lheader%& gives a colon-separated list, one element per header when there
9560 are multiple headers with a given name.
9561 Any embedded colon characters within an element are doubled, so normal Exim
9562 list-processing facilities can be used.
9563 The terminating newline of each element is removed; in other respects
9564 the content is &"raw"&.
9565
9566 .next
9567 .cindex "base64 encoding" "in header lines"
9568 &%bheader%& removes leading and trailing white space, and then decodes base64
9569 or quoted-printable MIME &"words"& within the header text, but does no
9570 character set translation. If decoding of what looks superficially like a MIME
9571 &"word"& fails, the raw string is returned. If decoding
9572 .cindex "binary zero" "in header line"
9573 produces a binary zero character, it is replaced by a question mark &-- this is
9574 what Exim does for binary zeros that are actually received in header lines.
9575
9576 .next
9577 &%header%& tries to translate the string as decoded by &%bheader%& to a
9578 standard character set. This is an attempt to produce the same string as would
9579 be displayed on a user's MUA. If translation fails, the &%bheader%& string is
9580 returned. Translation is attempted only on operating systems that support the
9581 &[iconv()]& function. This is indicated by the compile-time macro HAVE_ICONV in
9582 a system Makefile or in &_Local/Makefile_&.
9583 .endlist ilist
9584
9585 In a filter file, the target character set for &%header%& can be specified by a
9586 command of the following form:
9587 .code
9588 headers charset "UTF-8"
9589 .endd
9590 This command affects all references to &$h_$& (or &$header_$&) expansions in
9591 subsequently obeyed filter commands. In the absence of this command, the target
9592 character set in a filter is taken from the setting of the &%headers_charset%&
9593 option in the runtime configuration. The value of this option defaults to the
9594 value of HEADERS_CHARSET in &_Local/Makefile_&. The ultimate default is
9595 ISO-8859-1.
9596
9597 Header names follow the syntax of RFC 2822, which states that they may contain
9598 any printing characters except space and colon. Consequently, curly brackets
9599 &'do not'& terminate header names, and should not be used to enclose them as
9600 if they were variables. Attempting to do so causes a syntax error.
9601
9602 Only header lines that are common to all copies of a message are visible to
9603 this mechanism. These are the original header lines that are received with the
9604 message, and any that are added by an ACL statement or by a system
9605 filter. Header lines that are added to a particular copy of a message by a
9606 router or transport are not accessible.
9607
9608 For incoming SMTP messages, no header lines are visible in
9609 ACLs that are obeyed before the data phase completes,
9610 because the header structure is not set up until the message is received.
9611 They are visible in DKIM, PRDR and DATA ACLs.
9612 Header lines that are added in a RCPT ACL (for example)
9613 are saved until the message's incoming header lines are available, at which
9614 point they are added.
9615 When any of the above ACLs ar
9616 running, however, header lines added by earlier ACLs are visible.
9617
9618 Upper case and lower case letters are synonymous in header names. If the
9619 following character is white space, the terminating colon may be omitted, but
9620 this is not recommended, because you may then forget it when it is needed. When
9621 white space terminates the header name, this white space is included in the
9622 expanded string.  If the message does not contain the given header, the
9623 expansion item is replaced by an empty string. (See the &%def%& condition in
9624 section &<<SECTexpcond>>& for a means of testing for the existence of a
9625 header.)
9626
9627 If there is more than one header with the same name, they are all concatenated
9628 to form the substitution string, up to a maximum length of 64K. Unless
9629 &%rheader%& is being used, leading and trailing white space is removed from
9630 each header before concatenation, and a completely empty header is ignored. A
9631 newline character is then inserted between non-empty headers, but there is no
9632 newline at the very end. For the &%header%& and &%bheader%& expansion, for
9633 those headers that contain lists of addresses, a comma is also inserted at the
9634 junctions between headers. This does not happen for the &%rheader%& expansion.
9635
9636
9637 .vitem &*${hmac{*&<&'hashname'&>&*}{*&<&'secret'&>&*}{*&<&'string'&>&*}}*&
9638 .cindex "expansion" "hmac hashing"
9639 .cindex &%hmac%&
9640 This function uses cryptographic hashing (either MD5 or SHA-1) to convert a
9641 shared secret and some text into a message authentication code, as specified in
9642 RFC 2104. This differs from &`${md5:secret_text...}`& or
9643 &`${sha1:secret_text...}`& in that the hmac step adds a signature to the
9644 cryptographic hash, allowing for authentication that is not possible with MD5
9645 or SHA-1 alone. The hash name must expand to either &`md5`& or &`sha1`& at
9646 present. For example:
9647 .code
9648 ${hmac{md5}{somesecret}{$primary_hostname $tod_log}}
9649 .endd
9650 For the hostname &'mail.example.com'& and time 2002-10-17 11:30:59, this
9651 produces:
9652 .code
9653 dd97e3ba5d1a61b5006108f8c8252953
9654 .endd
9655 As an example of how this might be used, you might put in the main part of
9656 an Exim configuration:
9657 .code
9658 SPAMSCAN_SECRET=cohgheeLei2thahw
9659 .endd
9660 In a router or a transport you could then have:
9661 .code
9662 headers_add = \
9663   X-Spam-Scanned: ${primary_hostname} ${message_exim_id} \
9664   ${hmac{md5}{SPAMSCAN_SECRET}\
9665   {${primary_hostname},${message_exim_id},$h_message-id:}}
9666 .endd
9667 Then given a message, you can check where it was scanned by looking at the
9668 &'X-Spam-Scanned:'& header line. If you know the secret, you can check that
9669 this header line is authentic by recomputing the authentication code from the
9670 host name, message ID and the &'Message-id:'& header line. This can be done
9671 using Exim's &%-be%& option, or by other means, for example by using the
9672 &'hmac_md5_hex()'& function in Perl.
9673
9674
9675 .vitem &*${if&~*&<&'condition'&>&*&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}}*&
9676 .cindex "expansion" "conditional"
9677 .cindex "&%if%&, expansion item"
9678 If <&'condition'&> is true, <&'string1'&> is expanded and replaces the whole
9679 item; otherwise <&'string2'&> is used. The available conditions are described
9680 in section &<<SECTexpcond>>& below. For example:
9681 .code
9682 ${if eq {$local_part}{postmaster} {yes}{no} }
9683 .endd
9684 The second string need not be present; if it is not and the condition is not
9685 true, the item is replaced with nothing. Alternatively, the word &"fail"& may
9686 be present instead of the second string (without any curly brackets). In this
9687 case, the expansion is forced to fail if the condition is not true (see section
9688 &<<SECTforexpfai>>&).
9689
9690 If both strings are omitted, the result is the string &`true`& if the condition
9691 is true, and the empty string if the condition is false. This makes it less
9692 cumbersome to write custom ACL and router conditions. For example, instead of
9693 .code
9694 condition = ${if >{$acl_m4}{3}{true}{false}}
9695 .endd
9696 you can use
9697 .code
9698 condition = ${if >{$acl_m4}{3}}
9699 .endd
9700
9701
9702
9703 .vitem &*${imapfolder{*&<&'foldername'&>&*}}*&
9704 .cindex expansion "imap folder"
9705 .cindex "&%imapfolder%& expansion item"
9706 This item converts a (possibly multilevel, or with non-ASCII characters)
9707 folder specification to a Maildir name for filesystem use.
9708 For information on internationalisation support see &<<SECTi18nMDA>>&.
9709
9710
9711
9712 .vitem &*${length{*&<&'string1'&>&*}{*&<&'string2'&>&*}}*&
9713 .cindex "expansion" "string truncation"
9714 .cindex "&%length%& expansion item"
9715 The &%length%& item is used to extract the initial portion of a string. Both
9716 strings are expanded, and the first one must yield a number, <&'n'&>, say. If
9717 you are using a fixed value for the number, that is, if <&'string1'&> does not
9718 change when expanded, you can use the simpler operator notation that avoids
9719 some of the braces:
9720 .code
9721 ${length_<n>:<string>}
9722 .endd
9723 The result of this item is either the first <&'n'&> bytes or the whole
9724 of <&'string2'&>, whichever is the shorter. Do not confuse &%length%& with
9725 &%strlen%&, which gives the length of a string.
9726 All measurement is done in bytes and is not UTF-8 aware.
9727
9728
9729 .vitem "&*${listextract{*&<&'number'&>&*}&&&
9730         {*&<&'string1'&>&*}{*&<&'string2'&>&*}{*&<&'string3'&>&*}}*&"
9731 .cindex "expansion" "extracting list elements by number"
9732 .cindex "&%listextract%&" "extract list elements by number"
9733 .cindex "list" "extracting elements by number"
9734 The <&'number'&> argument must consist entirely of decimal digits,
9735 apart from an optional leading minus,
9736 and leading and trailing white space (which is ignored).
9737
9738 After expansion, <&'string1'&> is interpreted as a list, colon-separated by
9739 default, but the separator can be changed in the usual way.
9740
9741 The first field of the list is numbered one.
9742 If the number is negative, the fields are
9743 counted from the end of the list, with the rightmost one numbered -1.
9744 The numbered element of the list is extracted and placed in &$value$&,
9745 then <&'string2'&> is expanded as the result.
9746
9747 If the modulus of the
9748 number is zero or greater than the number of fields in the string,
9749 the result is the expansion of <&'string3'&>.
9750
9751 For example:
9752 .code
9753 ${listextract{2}{x:42:99}}
9754 .endd
9755 yields &"42"&, and
9756 .code
9757 ${listextract{-3}{<, x,42,99,& Mailer,,/bin/bash}{result: $value}}
9758 .endd
9759 yields &"result: 42"&.
9760
9761 If {<&'string3'&>} is omitted, an empty string is used for string3.
9762 If {<&'string2'&>} is also omitted, the value that was
9763 extracted is used.
9764 You can use &`fail`& instead of {<&'string3'&>} as in a string extract.
9765
9766
9767 .vitem "&*${lookup{*&<&'key'&>&*}&~*&<&'search&~type'&>&*&~&&&
9768         {*&<&'file'&>&*}&~{*&<&'string1'&>&*}&~{*&<&'string2'&>&*}}*&"
9769 This is the first of one of two different types of lookup item, which are both
9770 described in the next item.
9771
9772 .vitem "&*${lookup&~*&<&'search&~type'&>&*&~{*&<&'query'&>&*}&~&&&
9773         {*&<&'string1'&>&*}&~{*&<&'string2'&>&*}}*&"
9774 .cindex "expansion" "lookup in"
9775 .cindex "file" "lookups"
9776 .cindex "lookup" "in expanded string"
9777 The two forms of lookup item specify data lookups in files and databases, as
9778 discussed in chapter &<<CHAPfdlookup>>&. The first form is used for single-key
9779 lookups, and the second is used for query-style lookups. The <&'key'&>,
9780 <&'file'&>, and <&'query'&> strings are expanded before use.
9781
9782 If there is any white space in a lookup item which is part of a filter command,
9783 a retry or rewrite rule, a routing rule for the &(manualroute)& router, or any
9784 other place where white space is significant, the lookup item must be enclosed
9785 in double quotes. The use of data lookups in users' filter files may be locked
9786 out by the system administrator.
9787
9788 .vindex "&$value$&"
9789 If the lookup succeeds, <&'string1'&> is expanded and replaces the entire item.
9790 During its expansion, the variable &$value$& contains the data returned by the
9791 lookup. Afterwards it reverts to the value it had previously (at the outer
9792 level it is empty). If the lookup fails, <&'string2'&> is expanded and replaces
9793 the entire item. If {<&'string2'&>} is omitted, the replacement is the empty
9794 string on failure. If <&'string2'&> is provided, it can itself be a nested
9795 lookup, thus providing a mechanism for looking up a default value when the
9796 original lookup fails.
9797
9798 If a nested lookup is used as part of <&'string1'&>, &$value$& contains the
9799 data for the outer lookup while the parameters of the second lookup are
9800 expanded, and also while <&'string2'&> of the second lookup is expanded, should
9801 the second lookup fail. Instead of {<&'string2'&>} the word &"fail"& can
9802 appear, and in this case, if the lookup fails, the entire expansion is forced
9803 to fail (see section &<<SECTforexpfai>>&). If both {<&'string1'&>} and
9804 {<&'string2'&>} are omitted, the result is the looked up value in the case of a
9805 successful lookup, and nothing in the case of failure.
9806
9807 For single-key lookups, the string &"partial"& is permitted to precede the
9808 search type in order to do partial matching, and * or *@ may follow a search
9809 type to request default lookups if the key does not match (see sections
9810 &<<SECTdefaultvaluelookups>>& and &<<SECTpartiallookup>>& for details).
9811
9812 .cindex "numerical variables (&$1$& &$2$& etc)" "in lookup expansion"
9813 If a partial search is used, the variables &$1$& and &$2$& contain the wild
9814 and non-wild parts of the key during the expansion of the replacement text.
9815 They return to their previous values at the end of the lookup item.
9816
9817 This example looks up the postmaster alias in the conventional alias file:
9818 .code
9819 ${lookup {postmaster} lsearch {/etc/aliases} {$value}}
9820 .endd
9821 This example uses NIS+ to look up the full name of the user corresponding to
9822 the local part of an address, forcing the expansion to fail if it is not found:
9823 .code
9824 ${lookup nisplus {[name=$local_part],passwd.org_dir:gcos} \
9825   {$value}fail}
9826 .endd
9827
9828
9829 .vitem &*${map{*&<&'string1'&>&*}{*&<&'string2'&>&*}}*&
9830 .cindex "expansion" "list creation"
9831 .vindex "&$item$&"
9832 After expansion, <&'string1'&> is interpreted as a list, colon-separated by
9833 default, but the separator can be changed in the usual way. For each item
9834 in this list, its value is place in &$item$&, and then <&'string2'&> is
9835 expanded and added to the output as an item in a new list. The separator used
9836 for the output list is the same as the one used for the input, but a separator
9837 setting is not included in the output. For example:
9838 .code
9839 ${map{a:b:c}{[$item]}} ${map{<- x-y-z}{($item)}}
9840 .endd
9841 expands to &`[a]:[b]:[c] (x)-(y)-(z)`&. At the end of the expansion, the
9842 value of &$item$& is restored to what it was before. See also the &*filter*&
9843 and &*reduce*& expansion items.
9844
9845 .vitem &*${nhash{*&<&'string1'&>&*}{*&<&'string2'&>&*}{*&<&'string3'&>&*}}*&
9846 .cindex "expansion" "numeric hash"
9847 .cindex "hash function" "numeric"
9848 The three strings are expanded; the first two must yield numbers. Call them
9849 <&'n'&> and <&'m'&>. If you are using fixed values for these numbers, that is,
9850 if <&'string1'&> and <&'string2'&> do not change when they are expanded, you
9851 can use the simpler operator notation that avoids some of the braces:
9852 .code
9853 ${nhash_<n>_<m>:<string>}
9854 .endd
9855 The second number is optional (in both notations). If there is only one number,
9856 the result is a number in the range 0&--<&'n'&>-1. Otherwise, the string is
9857 processed by a div/mod hash function that returns two numbers, separated by a
9858 slash, in the ranges 0 to <&'n'&>-1 and 0 to <&'m'&>-1, respectively. For
9859 example,
9860 .code
9861 ${nhash{8}{64}{supercalifragilisticexpialidocious}}
9862 .endd
9863 returns the string &"6/33"&.
9864
9865
9866
9867 .vitem &*${perl{*&<&'subroutine'&>&*}{*&<&'arg'&>&*}{*&<&'arg'&>&*}...}*&
9868 .cindex "Perl" "use in expanded string"
9869 .cindex "expansion" "calling Perl from"
9870 This item is available only if Exim has been built to include an embedded Perl
9871 interpreter. The subroutine name and the arguments are first separately
9872 expanded, and then the Perl subroutine is called with those arguments. No
9873 additional arguments need be given; the maximum number permitted, including the
9874 name of the subroutine, is nine.
9875
9876 The return value of the subroutine is inserted into the expanded string, unless
9877 the return value is &%undef%&. In that case, the expansion fails in the same
9878 way as an explicit &"fail"& on a lookup item. The return value is a scalar.
9879 Whatever you return is evaluated in a scalar context. For example, if you
9880 return the name of a Perl vector, the return value is the size of the vector,
9881 not its contents.
9882
9883 If the subroutine exits by calling Perl's &%die%& function, the expansion fails
9884 with the error message that was passed to &%die%&. More details of the embedded
9885 Perl facility are given in chapter &<<CHAPperl>>&.
9886
9887 The &(redirect)& router has an option called &%forbid_filter_perl%& which locks
9888 out the use of this expansion item in filter files.
9889
9890
9891 .vitem &*${prvs{*&<&'address'&>&*}{*&<&'secret'&>&*}{*&<&'keynumber'&>&*}}*&
9892 .cindex "&%prvs%& expansion item"
9893 The first argument is a complete email address and the second is secret
9894 keystring. The third argument, specifying a key number, is optional. If absent,
9895 it defaults to 0. The result of the expansion is a prvs-signed email address,
9896 to be typically used with the &%return_path%& option on an &(smtp)& transport
9897 as part of a bounce address tag validation (BATV) scheme. For more discussion
9898 and an example, see section &<<SECTverifyPRVS>>&.
9899
9900 .vitem "&*${prvscheck{*&<&'address'&>&*}{*&<&'secret'&>&*}&&&
9901         {*&<&'string'&>&*}}*&"
9902 .cindex "&%prvscheck%& expansion item"
9903 This expansion item is the complement of the &%prvs%& item. It is used for
9904 checking prvs-signed addresses. If the expansion of the first argument does not
9905 yield a syntactically valid prvs-signed address, the whole item expands to the
9906 empty string. When the first argument does expand to a syntactically valid
9907 prvs-signed address, the second argument is expanded, with the prvs-decoded
9908 version of the address and the key number extracted from the address in the
9909 variables &$prvscheck_address$& and &$prvscheck_keynum$&, respectively.
9910
9911 These two variables can be used in the expansion of the second argument to
9912 retrieve the secret. The validity of the prvs-signed address is then checked
9913 against the secret. The result is stored in the variable &$prvscheck_result$&,
9914 which is empty for failure or &"1"& for success.
9915
9916 The third argument is optional; if it is missing, it defaults to an empty
9917 string. This argument is now expanded. If the result is an empty string, the
9918 result of the expansion is the decoded version of the address. This is the case
9919 whether or not the signature was valid. Otherwise, the result of the expansion
9920 is the expansion of the third argument.
9921
9922 All three variables can be used in the expansion of the third argument.
9923 However, once the expansion is complete, only &$prvscheck_result$& remains set.
9924 For more discussion and an example, see section &<<SECTverifyPRVS>>&.
9925
9926 .vitem &*${readfile{*&<&'file&~name'&>&*}{*&<&'eol&~string'&>&*}}*&
9927 .cindex "expansion" "inserting an entire file"
9928 .cindex "file" "inserting into expansion"
9929 .cindex "&%readfile%& expansion item"
9930 The file name and end-of-line string are first expanded separately. The file is
9931 then read, and its contents replace the entire item. All newline characters in
9932 the file are replaced by the end-of-line string if it is present. Otherwise,
9933 newlines are left in the string.
9934 String expansion is not applied to the contents of the file. If you want this,
9935 you must wrap the item in an &%expand%& operator. If the file cannot be read,
9936 the string expansion fails.
9937
9938 The &(redirect)& router has an option called &%forbid_filter_readfile%& which
9939 locks out the use of this expansion item in filter files.
9940
9941
9942
9943 .vitem "&*${readsocket{*&<&'name'&>&*}{*&<&'request'&>&*}&&&
9944         {*&<&'options'&>&*}{*&<&'eol&~string'&>&*}{*&<&'fail&~string'&>&*}}*&"
9945 .cindex "expansion" "inserting from a socket"
9946 .cindex "socket, use of in expansion"
9947 .cindex "&%readsocket%& expansion item"
9948 This item inserts data from a Unix domain or TCP socket into the expanded
9949 string. The minimal way of using it uses just two arguments, as in these
9950 examples:
9951 .code
9952 ${readsocket{/socket/name}{request string}}
9953 ${readsocket{inet:some.host:1234}{request string}}
9954 .endd
9955 For a Unix domain socket, the first substring must be the path to the socket.
9956 For an Internet socket, the first substring must contain &`inet:`& followed by
9957 a host name or IP address, followed by a colon and a port, which can be a
9958 number or the name of a TCP port in &_/etc/services_&. An IP address may
9959 optionally be enclosed in square brackets. This is best for IPv6 addresses. For
9960 example:
9961 .code
9962 ${readsocket{inet:[::1]:1234}{request string}}
9963 .endd
9964 Only a single host name may be given, but if looking it up yields more than
9965 one IP address, they are each tried in turn until a connection is made. For
9966 both kinds of socket, Exim makes a connection, writes the request string
9967 unless it is an empty string; and no terminating NUL is ever sent)
9968 and reads from the socket until an end-of-file
9969 is read. A timeout of 5 seconds is applied. Additional, optional arguments
9970 extend what can be done. Firstly, you can vary the timeout. For example:
9971 .code
9972 ${readsocket{/socket/name}{request string}{3s}}
9973 .endd
9974
9975 The third argument is a list of options, of which the first element is the timeout
9976 and must be present if the argument is given.
9977 Further elements are options of form &'name=value'&.
9978 Two option types is currently recognised: shutdown and tls.
9979 The first defines whether (the default)
9980 or not a shutdown is done on the connection after sending the request.
9981 Example, to not do so (preferred, eg. by some webservers):
9982 .code
9983 ${readsocket{/socket/name}{request string}{3s:shutdown=no}}
9984 .endd
9985 .new
9986 The second, tls, controls the use of TLS on the connection.  Example:
9987 .code
9988 ${readsocket{/socket/name}{request string}{3s:tls=yes}}
9989 .endd
9990 The default is to not use TLS.
9991 If it is enabled, a shutdown as descripbed above is never done.
9992 .wen
9993
9994 A fourth argument allows you to change any newlines that are in the data
9995 that is read, in the same way as for &%readfile%& (see above). This example
9996 turns them into spaces:
9997 .code
9998 ${readsocket{inet:127.0.0.1:3294}{request string}{3s}{ }}
9999 .endd
10000 As with all expansions, the substrings are expanded before the processing
10001 happens. Errors in these sub-expansions cause the expansion to fail. In
10002 addition, the following errors can occur:
10003
10004 .ilist
10005 Failure to create a socket file descriptor;
10006 .next
10007 Failure to connect the socket;
10008 .next
10009 Failure to write the request string;
10010 .next
10011 Timeout on reading from the socket.
10012 .endlist
10013
10014 By default, any of these errors causes the expansion to fail. However, if
10015 you supply a fifth substring, it is expanded and used when any of the above
10016 errors occurs. For example:
10017 .code
10018 ${readsocket{/socket/name}{request string}{3s}{\n}\
10019   {socket failure}}
10020 .endd
10021 You can test for the existence of a Unix domain socket by wrapping this
10022 expansion in &`${if exists`&, but there is a race condition between that test
10023 and the actual opening of the socket, so it is safer to use the fifth argument
10024 if you want to be absolutely sure of avoiding an expansion error for a
10025 non-existent Unix domain socket, or a failure to connect to an Internet socket.
10026
10027 The &(redirect)& router has an option called &%forbid_filter_readsocket%& which
10028 locks out the use of this expansion item in filter files.
10029
10030
10031 .vitem &*${reduce{*&<&'string1'&>}{<&'string2'&>&*}{*&<&'string3'&>&*}}*&
10032 .cindex "expansion" "reducing a list to a scalar"
10033 .cindex "list" "reducing to a scalar"
10034 .vindex "&$value$&"
10035 .vindex "&$item$&"
10036 This operation reduces a list to a single, scalar string. After expansion,
10037 <&'string1'&> is interpreted as a list, colon-separated by default, but the
10038 separator can be changed in the usual way. Then <&'string2'&> is expanded and
10039 assigned to the &$value$& variable. After this, each item in the <&'string1'&>
10040 list is assigned to &$item$& in turn, and <&'string3'&> is expanded for each of
10041 them. The result of that expansion is assigned to &$value$& before the next
10042 iteration. When the end of the list is reached, the final value of &$value$& is
10043 added to the expansion output. The &*reduce*& expansion item can be used in a
10044 number of ways. For example, to add up a list of numbers:
10045 .code
10046 ${reduce {<, 1,2,3}{0}{${eval:$value+$item}}}
10047 .endd
10048 The result of that expansion would be &`6`&. The maximum of a list of numbers
10049 can be found:
10050 .code
10051 ${reduce {3:0:9:4:6}{0}{${if >{$item}{$value}{$item}{$value}}}}
10052 .endd
10053 At the end of a &*reduce*& expansion, the values of &$item$& and &$value$& are
10054 restored to what they were before. See also the &*filter*& and &*map*&
10055 expansion items.
10056
10057 .vitem &*$rheader_*&<&'header&~name'&>&*:*&&~or&~&*$rh_*&<&'header&~name'&>&*:*&
10058 This item inserts &"raw"& header lines. It is described with the &%header%&
10059 expansion item in section &<<SECTexpansionitems>>& above.
10060
10061 .vitem "&*${run{*&<&'command'&>&*&~*&<&'args'&>&*}{*&<&'string1'&>&*}&&&
10062         {*&<&'string2'&>&*}}*&"
10063 .cindex "expansion" "running a command"
10064 .cindex "&%run%& expansion item"
10065 The command and its arguments are first expanded as one string. The string is
10066 split apart into individual arguments by spaces, and then the command is run
10067 in a separate process, but under the same uid and gid.  As in other command
10068 executions from Exim, a shell is not used by default. If the command requires
10069 a shell, you must explicitly code it.
10070
10071 Since the arguments are split by spaces, when there is a variable expansion
10072 which has an empty result, it will cause the situation that the argument will
10073 simply be omitted when the program is actually executed by Exim. If the
10074 script/program requires a specific number of arguments and the expanded
10075 variable could possibly result in this empty expansion, the variable must be
10076 quoted. This is more difficult if the expanded variable itself could result
10077 in a string containing quotes, because it would interfere with the quotes
10078 around the command arguments. A possible guard against this is to wrap the
10079 variable in the &%sg%& operator to change any quote marks to some other
10080 character.
10081
10082 The standard input for the command exists, but is empty. The standard output
10083 and standard error are set to the same file descriptor.
10084 .cindex "return code" "from &%run%& expansion"
10085 .vindex "&$value$&"
10086 If the command succeeds (gives a zero return code) <&'string1'&> is expanded
10087 and replaces the entire item; during this expansion, the standard output/error
10088 from the command is in the variable &$value$&. If the command fails,
10089 <&'string2'&>, if present, is expanded and used. Once again, during the
10090 expansion, the standard output/error from the command is in the variable
10091 &$value$&.
10092
10093 If <&'string2'&> is absent, the result is empty. Alternatively, <&'string2'&>
10094 can be the word &"fail"& (not in braces) to force expansion failure if the
10095 command does not succeed. If both strings are omitted, the result is contents
10096 of the standard output/error on success, and nothing on failure.
10097
10098 .vindex "&$run_in_acl$&"
10099 The standard output/error of the command is put in the variable &$value$&.
10100 In this ACL example, the output of a command is logged for the admin to
10101 troubleshoot:
10102 .code
10103 warn  condition    = ${run{/usr/bin/id}{yes}{no}}
10104       log_message  = Output of id: $value
10105 .endd
10106 If the command requires shell idioms, such as the > redirect operator, the
10107 shell must be invoked directly, such as with:
10108 .code
10109 ${run{/bin/bash -c "/usr/bin/id >/tmp/id"}{yes}{yes}}
10110 .endd
10111
10112 .vindex "&$runrc$&"
10113 The return code from the command is put in the variable &$runrc$&, and this
10114 remains set afterwards, so in a filter file you can do things like this:
10115 .code
10116 if "${run{x y z}{}}$runrc" is 1 then ...
10117   elif $runrc is 2 then ...
10118   ...
10119 endif
10120 .endd
10121 If execution of the command fails (for example, the command does not exist),
10122 the return code is 127 &-- the same code that shells use for non-existent
10123 commands.
10124
10125 &*Warning*&: In a router or transport, you cannot assume the order in which
10126 option values are expanded, except for those preconditions whose order of
10127 testing is documented. Therefore, you cannot reliably expect to set &$runrc$&
10128 by the expansion of one option, and use it in another.
10129
10130 The &(redirect)& router has an option called &%forbid_filter_run%& which locks
10131 out the use of this expansion item in filter files.
10132
10133
10134 .vitem &*${sg{*&<&'subject'&>&*}{*&<&'regex'&>&*}{*&<&'replacement'&>&*}}*&
10135 .cindex "expansion" "string substitution"
10136 .cindex "&%sg%& expansion item"
10137 This item works like Perl's substitution operator (s) with the global (/g)
10138 option; hence its name. However, unlike the Perl equivalent, Exim does not
10139 modify the subject string; instead it returns the modified string for insertion
10140 into the overall expansion. The item takes three arguments: the subject string,
10141 a regular expression, and a substitution string. For example:
10142 .code
10143 ${sg{abcdefabcdef}{abc}{xyz}}
10144 .endd
10145 yields &"xyzdefxyzdef"&. Because all three arguments are expanded before use,
10146 if any $, } or \ characters are required in the regular expression or in the
10147 substitution string, they have to be escaped. For example:
10148 .code
10149 ${sg{abcdef}{^(...)(...)\$}{\$2\$1}}
10150 .endd
10151 yields &"defabc"&, and
10152 .code
10153 ${sg{1=A 4=D 3=C}{\N(\d+)=\N}{K\$1=}}
10154 .endd
10155 yields &"K1=A K4=D K3=C"&. Note the use of &`\N`& to protect the contents of
10156 the regular expression from string expansion.
10157
10158 The regular expression is compiled in 8-bit mode, working against bytes
10159 rather than any Unicode-aware character handling.
10160
10161
10162 .vitem &*${sort{*&<&'string'&>&*}{*&<&'comparator'&>&*}{*&<&'extractor'&>&*}}*&
10163 .cindex sorting "a list"
10164 .cindex list sorting
10165 .cindex expansion "list sorting"
10166 After expansion, <&'string'&> is interpreted as a list, colon-separated by
10167 default, but the separator can be changed in the usual way.
10168 The <&'comparator'&> argument is interpreted as the operator
10169 of a two-argument expansion condition.
10170 The numeric operators plus ge, gt, le, lt (and ~i variants) are supported.
10171 The comparison should return true when applied to two values
10172 if the first value should sort before the second value.
10173 The <&'extractor'&> expansion is applied repeatedly to elements of the list,
10174 the element being placed in &$item$&,
10175 to give values for comparison.
10176
10177 The item result is a sorted list,
10178 with the original list separator,
10179 of the list elements (in full) of the original.
10180
10181 Examples:
10182 .code
10183 ${sort{3:2:1:4}{<}{$item}}
10184 .endd
10185 sorts a list of numbers, and
10186 .code
10187 ${sort {${lookup dnsdb{>:,,mx=example.com}}} {<} {${listextract{1}{<,$item}}}}
10188 .endd
10189 will sort an MX lookup into priority order.
10190
10191
10192 .vitem &*${substr{*&<&'string1'&>&*}{*&<&'string2'&>&*}{*&<&'string3'&>&*}}*&
10193 .cindex "&%substr%& expansion item"
10194 .cindex "substring extraction"
10195 .cindex "expansion" "substring extraction"
10196 The three strings are expanded; the first two must yield numbers. Call them
10197 <&'n'&> and <&'m'&>. If you are using fixed values for these numbers, that is,
10198 if <&'string1'&> and <&'string2'&> do not change when they are expanded, you
10199 can use the simpler operator notation that avoids some of the braces:
10200 .code
10201 ${substr_<n>_<m>:<string>}
10202 .endd
10203 The second number is optional (in both notations).
10204 If it is absent in the simpler format, the preceding underscore must also be
10205 omitted.
10206
10207 The &%substr%& item can be used to extract more general substrings than
10208 &%length%&. The first number, <&'n'&>, is a starting offset, and <&'m'&> is the
10209 length required. For example
10210 .code
10211 ${substr{3}{2}{$local_part}}
10212 .endd
10213 If the starting offset is greater than the string length the result is the
10214 null string; if the length plus starting offset is greater than the string
10215 length, the result is the right-hand part of the string, starting from the
10216 given offset. The first byte (character) in the string has offset zero.
10217
10218 The &%substr%& expansion item can take negative offset values to count
10219 from the right-hand end of its operand. The last byte (character) is offset -1,
10220 the second-last is offset -2, and so on. Thus, for example,
10221 .code
10222 ${substr{-5}{2}{1234567}}
10223 .endd
10224 yields &"34"&. If the absolute value of a negative offset is greater than the
10225 length of the string, the substring starts at the beginning of the string, and
10226 the length is reduced by the amount of overshoot. Thus, for example,
10227 .code
10228 ${substr{-5}{2}{12}}
10229 .endd
10230 yields an empty string, but
10231 .code
10232 ${substr{-3}{2}{12}}
10233 .endd
10234 yields &"1"&.
10235
10236 When the second number is omitted from &%substr%&, the remainder of the string
10237 is taken if the offset is positive. If it is negative, all bytes (characters) in the
10238 string preceding the offset point are taken. For example, an offset of -1 and
10239 no length, as in these semantically identical examples:
10240 .code
10241 ${substr_-1:abcde}
10242 ${substr{-1}{abcde}}
10243 .endd
10244 yields all but the last character of the string, that is, &"abcd"&.
10245
10246 All measurement is done in bytes and is not UTF-8 aware.
10247
10248
10249
10250 .vitem "&*${tr{*&<&'subject'&>&*}{*&<&'characters'&>&*}&&&
10251         {*&<&'replacements'&>&*}}*&"
10252 .cindex "expansion" "character translation"
10253 .cindex "&%tr%& expansion item"
10254 This item does single-character (in bytes) translation on its subject string. The second
10255 argument is a list of characters to be translated in the subject string. Each
10256 matching character is replaced by the corresponding character from the
10257 replacement list. For example
10258 .code
10259 ${tr{abcdea}{ac}{13}}
10260 .endd
10261 yields &`1b3de1`&. If there are duplicates in the second character string, the
10262 last occurrence is used. If the third string is shorter than the second, its
10263 last character is replicated. However, if it is empty, no translation takes
10264 place.
10265
10266 All character handling is done in bytes and is not UTF-8 aware.
10267
10268 .endlist
10269
10270
10271
10272 .section "Expansion operators" "SECTexpop"
10273 .cindex "expansion" "operators"
10274 For expansion items that perform transformations on a single argument string,
10275 the &"operator"& notation is used because it is simpler and uses fewer braces.
10276 The substring is first expanded before the operation is applied to it. The
10277 following operations can be performed:
10278
10279 .vlist
10280 .vitem &*${address:*&<&'string'&>&*}*&
10281 .cindex "expansion" "RFC 2822 address handling"
10282 .cindex "&%address%& expansion item"
10283 The string is interpreted as an RFC 2822 address, as it might appear in a
10284 header line, and the effective address is extracted from it. If the string does
10285 not parse successfully, the result is empty.
10286
10287 The parsing correctly handles SMTPUTF8 Unicode in the string.
10288
10289
10290 .vitem &*${addresses:*&<&'string'&>&*}*&
10291 .cindex "expansion" "RFC 2822 address handling"
10292 .cindex "&%addresses%& expansion item"
10293 The string (after expansion) is interpreted as a list of addresses in RFC
10294 2822 format, such as can be found in a &'To:'& or &'Cc:'& header line. The
10295 operative address (&'local-part@domain'&) is extracted from each item, and the
10296 result of the expansion is a colon-separated list, with appropriate
10297 doubling of colons should any happen to be present in the email addresses.
10298 Syntactically invalid RFC2822 address items are omitted from the output.
10299
10300 It is possible to specify a character other than colon for the output
10301 separator by starting the string with > followed by the new separator
10302 character. For example:
10303 .code
10304 ${addresses:>& Chief <ceo@up.stairs>, sec@base.ment (dogsbody)}
10305 .endd
10306 expands to &`ceo@up.stairs&&sec@base.ment`&. The string is expanded
10307 first, so if the expanded string starts with >, it may change the output
10308 separator unintentionally. This can be avoided by setting the output
10309 separator explicitly:
10310 .code
10311 ${addresses:>:$h_from:}
10312 .endd
10313
10314 Compare the &*address*& (singular)
10315 expansion item, which extracts the working address from a single RFC2822
10316 address. See the &*filter*&, &*map*&, and &*reduce*& items for ways of
10317 processing lists.
10318
10319 To clarify "list of addresses in RFC 2822 format" mentioned above, Exim follows
10320 a strict interpretation of header line formatting.  Exim parses the bare,
10321 unquoted portion of an email address and if it finds a comma, treats it as an
10322 email address separator. For the example header line:
10323 .code
10324 From: =?iso-8859-2?Q?Last=2C_First?= <user@example.com>
10325 .endd
10326 The first example below demonstrates that Q-encoded email addresses are parsed
10327 properly if it is given the raw header (in this example, &`$rheader_from:`&).
10328 It does not see the comma because it's still encoded as "=2C".  The second
10329 example below is passed the contents of &`$header_from:`&, meaning it gets
10330 de-mimed. Exim sees the decoded "," so it treats it as &*two*& email addresses.
10331 The third example shows that the presence of a comma is skipped when it is
10332 quoted.  The fourth example shows SMTPUTF8 handling.
10333 .code
10334 # exim -be '${addresses:From: \
10335 =?iso-8859-2?Q?Last=2C_First?= <user@example.com>}'
10336 user@example.com
10337 # exim -be '${addresses:From: Last, First <user@example.com>}'
10338 Last:user@example.com
10339 # exim -be '${addresses:From: "Last, First" <user@example.com>}'
10340 user@example.com
10341 # exim -be '${addresses:フィル <フィリップ@example.jp>}'
10342 フィリップ@example.jp
10343 .endd
10344
10345 .vitem &*${base32:*&<&'digits'&>&*}*&
10346 .cindex "&%base32%& expansion item"
10347 .cindex "expansion" "conversion to base 32"
10348 The string must consist entirely of decimal digits. The number is converted to
10349 base 32 and output as a (empty, for zero) string of characters.
10350 Only lowercase letters are used.
10351
10352 .vitem &*${base32d:*&<&'base-32&~digits'&>&*}*&
10353 .cindex "&%base32d%& expansion item"
10354 .cindex "expansion" "conversion to base 32"
10355 The string must consist entirely of base-32 digits.
10356 The number is converted to decimal and output as a string.
10357
10358 .vitem &*${base62:*&<&'digits'&>&*}*&
10359 .cindex "&%base62%& expansion item"
10360 .cindex "expansion" "conversion to base 62"
10361 The string must consist entirely of decimal digits. The number is converted to
10362 base 62 and output as a string of six characters, including leading zeros. In
10363 the few operating environments where Exim uses base 36 instead of base 62 for
10364 its message identifiers (because those systems do not have case-sensitive file
10365 names), base 36 is used by this operator, despite its name. &*Note*&: Just to
10366 be absolutely clear: this is &'not'& base64 encoding.
10367
10368 .vitem &*${base62d:*&<&'base-62&~digits'&>&*}*&
10369 .cindex "&%base62d%& expansion item"
10370 .cindex "expansion" "conversion to base 62"
10371 The string must consist entirely of base-62 digits, or, in operating
10372 environments where Exim uses base 36 instead of base 62 for its message
10373 identifiers, base-36 digits. The number is converted to decimal and output as a
10374 string.
10375
10376 .vitem &*${base64:*&<&'string'&>&*}*&
10377 .cindex "expansion" "base64 encoding"
10378 .cindex "base64 encoding" "in string expansion"
10379 .cindex "&%base64%& expansion item"
10380 .cindex certificate "base64 of DER"
10381 This operator converts a string into one that is base64 encoded.
10382
10383 If the string is a single variable of type certificate,
10384 returns the base64 encoding of the DER form of the certificate.
10385
10386
10387 .vitem &*${base64d:*&<&'string'&>&*}*&
10388 .cindex "expansion" "base64 decoding"
10389 .cindex "base64 decoding" "in string expansion"
10390 .cindex "&%base64d%& expansion item"
10391 This operator converts a base64-encoded string into the un-coded form.
10392
10393
10394 .vitem &*${domain:*&<&'string'&>&*}*&
10395 .cindex "domain" "extraction"
10396 .cindex "expansion" "domain extraction"
10397 The string is interpreted as an RFC 2822 address and the domain is extracted
10398 from it. If the string does not parse successfully, the result is empty.
10399
10400
10401 .vitem &*${escape:*&<&'string'&>&*}*&
10402 .cindex "expansion" "escaping non-printing characters"
10403 .cindex "&%escape%& expansion item"
10404 If the string contains any non-printing characters, they are converted to
10405 escape sequences starting with a backslash. Whether characters with the most
10406 significant bit set (so-called &"8-bit characters"&) count as printing or not
10407 is controlled by the &%print_topbitchars%& option.
10408
10409 .vitem &*${escape8bit:*&<&'string'&>&*}*&
10410 .cindex "expansion" "escaping 8-bit characters"
10411 .cindex "&%escape8bit%& expansion item"
10412 If the string contains and characters with the most significant bit set,
10413 they are converted to escape sequences starting with a backslash.
10414 Backslashes and DEL characters are also converted.
10415
10416
10417 .vitem &*${eval:*&<&'string'&>&*}*&&~and&~&*${eval10:*&<&'string'&>&*}*&
10418 .cindex "expansion" "expression evaluation"
10419 .cindex "expansion" "arithmetic expression"
10420 .cindex "&%eval%& expansion item"
10421 These items supports simple arithmetic and bitwise logical operations in
10422 expansion strings. The string (after expansion) must be a conventional
10423 arithmetic expression, but it is limited to basic arithmetic operators, bitwise
10424 logical operators, and parentheses. All operations are carried out using
10425 integer arithmetic. The operator priorities are as follows (the same as in the
10426 C programming language):
10427 .table2 70pt 300pt
10428 .irow &'highest:'& "not (~), negate (-)"
10429 .irow ""   "multiply (*), divide (/), remainder (%)"
10430 .irow ""   "plus (+), minus (-)"
10431 .irow ""   "shift-left (<<), shift-right (>>)"
10432 .irow ""   "and (&&)"
10433 .irow ""   "xor (^)"
10434 .irow &'lowest:'&  "or (|)"
10435 .endtable
10436 Binary operators with the same priority are evaluated from left to right. White
10437 space is permitted before or after operators.
10438
10439 For &%eval%&, numbers may be decimal, octal (starting with &"0"&) or
10440 hexadecimal (starting with &"0x"&). For &%eval10%&, all numbers are taken as
10441 decimal, even if they start with a leading zero; hexadecimal numbers are not
10442 permitted. This can be useful when processing numbers extracted from dates or
10443 times, which often do have leading zeros.
10444
10445 A number may be followed by &"K"&, &"M"& or &"G"& to multiply it by 1024, 1024*1024
10446 or 1024*1024*1024,
10447 respectively. Negative numbers are supported. The result of the computation is
10448 a decimal representation of the answer (without &"K"&, &"M"& or &"G"&). For example:
10449
10450 .display
10451 &`${eval:1+1}            `&  yields 2
10452 &`${eval:1+2*3}          `&  yields 7
10453 &`${eval:(1+2)*3}        `&  yields 9
10454 &`${eval:2+42%5}         `&  yields 4
10455 &`${eval:0xc&amp;5}          `&  yields 4
10456 &`${eval:0xc|5}          `&  yields 13
10457 &`${eval:0xc^5}          `&  yields 9
10458 &`${eval:0xc>>1}         `&  yields 6
10459 &`${eval:0xc<<1}         `&  yields 24
10460 &`${eval:~255&amp;0x1234}    `&  yields 4608
10461 &`${eval:-(~255&amp;0x1234)} `&  yields -4608
10462 .endd
10463
10464 As a more realistic example, in an ACL you might have
10465 .code
10466 deny   message = Too many bad recipients
10467        condition =                    \
10468          ${if and {                   \
10469            {>{$rcpt_count}{10}}       \
10470            {                          \
10471            <                          \
10472              {$recipients_count}      \
10473              {${eval:$rcpt_count/2}}  \
10474            }                          \
10475          }{yes}{no}}
10476 .endd
10477 The condition is true if there have been more than 10 RCPT commands and
10478 fewer than half of them have resulted in a valid recipient.
10479
10480
10481 .vitem &*${expand:*&<&'string'&>&*}*&
10482 .cindex "expansion" "re-expansion of substring"
10483 The &%expand%& operator causes a string to be expanded for a second time. For
10484 example,
10485 .code
10486 ${expand:${lookup{$domain}dbm{/some/file}{$value}}}
10487 .endd
10488 first looks up a string in a file while expanding the operand for &%expand%&,
10489 and then re-expands what it has found.
10490
10491
10492 .vitem &*${from_utf8:*&<&'string'&>&*}*&
10493 .cindex "Unicode"
10494 .cindex "UTF-8" "conversion from"
10495 .cindex "expansion" "UTF-8 conversion"
10496 .cindex "&%from_utf8%& expansion item"
10497 The world is slowly moving towards Unicode, although there are no standards for
10498 email yet. However, other applications (including some databases) are starting
10499 to store data in Unicode, using UTF-8 encoding. This operator converts from a
10500 UTF-8 string to an ISO-8859-1 string. UTF-8 code values greater than 255 are
10501 converted to underscores. The input must be a valid UTF-8 string. If it is not,
10502 the result is an undefined sequence of bytes.
10503
10504 Unicode code points with values less than 256 are compatible with ASCII and
10505 ISO-8859-1 (also known as Latin-1).
10506 For example, character 169 is the copyright symbol in both cases, though the
10507 way it is encoded is different. In UTF-8, more than one byte is needed for
10508 characters with code values greater than 127, whereas ISO-8859-1 is a
10509 single-byte encoding (but thereby limited to 256 characters). This makes
10510 translation from UTF-8 to ISO-8859-1 straightforward.
10511
10512
10513 .vitem &*${hash_*&<&'n'&>&*_*&<&'m'&>&*:*&<&'string'&>&*}*&
10514 .cindex "hash function" "textual"
10515 .cindex "expansion" "textual hash"
10516 The &%hash%& operator is a simpler interface to the hashing function that can
10517 be used when the two parameters are fixed numbers (as opposed to strings that
10518 change when expanded). The effect is the same as
10519 .code
10520 ${hash{<n>}{<m>}{<string>}}
10521 .endd
10522 See the description of the general &%hash%& item above for details. The
10523 abbreviation &%h%& can be used when &%hash%& is used as an operator.
10524
10525
10526
10527 .vitem &*${hex2b64:*&<&'hexstring'&>&*}*&
10528 .cindex "base64 encoding" "conversion from hex"
10529 .cindex "expansion" "hex to base64"
10530 .cindex "&%hex2b64%& expansion item"
10531 This operator converts a hex string into one that is base64 encoded. This can
10532 be useful for processing the output of the various hashing functions.
10533
10534
10535
10536 .vitem &*${hexquote:*&<&'string'&>&*}*&
10537 .cindex "quoting" "hex-encoded unprintable characters"
10538 .cindex "&%hexquote%& expansion item"
10539 This operator converts non-printable characters in a string into a hex
10540 escape form. Byte values between 33 (!) and 126 (~) inclusive are left
10541 as is, and other byte values are converted to &`\xNN`&, for example a
10542 byte value 127 is converted to &`\x7f`&.
10543
10544
10545 .vitem &*${ipv6denorm:*&<&'string'&>&*}*&
10546 .cindex "&%ipv6denorm%& expansion item"
10547 .cindex "IP address" normalisation
10548 This expands an IPv6 address to a full eight-element colon-separated set
10549 of hex digits including leading zeroes.
10550 A trailing ipv4-style dotted-decimal set is converted to hex.
10551 Pure IPv4 addresses are converted to IPv4-mapped IPv6.
10552
10553 .vitem &*${ipv6norm:*&<&'string'&>&*}*&
10554 .cindex "&%ipv6norm%& expansion item"
10555 .cindex "IP address" normalisation
10556 .cindex "IP address" "canonical form"
10557 This converts an IPv6 address to canonical form.
10558 Leading zeroes of groups are omitted, and the longest
10559 set of zero-valued groups is replaced with a double colon.
10560 A trailing ipv4-style dotted-decimal set is converted to hex.
10561 Pure IPv4 addresses are converted to IPv4-mapped IPv6.
10562
10563
10564 .vitem &*${lc:*&<&'string'&>&*}*&
10565 .cindex "case forcing in strings"
10566 .cindex "string" "case forcing"
10567 .cindex "lower casing"
10568 .cindex "expansion" "case forcing"
10569 .cindex "&%lc%& expansion item"
10570 This forces the letters in the string into lower-case, for example:
10571 .code
10572 ${lc:$local_part}
10573 .endd
10574 Case is defined per the system C locale.
10575
10576 .vitem &*${length_*&<&'number'&>&*:*&<&'string'&>&*}*&
10577 .cindex "expansion" "string truncation"
10578 .cindex "&%length%& expansion item"
10579 The &%length%& operator is a simpler interface to the &%length%& function that
10580 can be used when the parameter is a fixed number (as opposed to a string that
10581 changes when expanded). The effect is the same as
10582 .code
10583 ${length{<number>}{<string>}}
10584 .endd
10585 See the description of the general &%length%& item above for details. Note that
10586 &%length%& is not the same as &%strlen%&. The abbreviation &%l%& can be used
10587 when &%length%& is used as an operator.
10588 All measurement is done in bytes and is not UTF-8 aware.
10589
10590
10591 .vitem &*${listcount:*&<&'string'&>&*}*&
10592 .cindex "expansion" "list item count"
10593 .cindex "list" "item count"
10594 .cindex "list" "count of items"
10595 .cindex "&%listcount%& expansion item"
10596 The string is interpreted as a list and the number of items is returned.
10597
10598
10599 .vitem &*${listnamed:*&<&'name'&>&*}*&&~and&~&*${listnamed_*&<&'type'&>&*:*&<&'name'&>&*}*&
10600 .cindex "expansion" "named list"
10601 .cindex "&%listnamed%& expansion item"
10602 The name is interpreted as a named list and the content of the list is returned,
10603 expanding any referenced lists, re-quoting as needed for colon-separation.
10604 If the optional type is given it must be one of "a", "d", "h" or "l"
10605 and selects address-, domain-, host- or localpart- lists to search among respectively.
10606 Otherwise all types are searched in an undefined order and the first
10607 matching list is returned.
10608
10609
10610 .vitem &*${local_part:*&<&'string'&>&*}*&
10611 .cindex "expansion" "local part extraction"
10612 .cindex "&%local_part%& expansion item"
10613 The string is interpreted as an RFC 2822 address and the local part is
10614 extracted from it. If the string does not parse successfully, the result is
10615 empty.
10616 The parsing correctly handles SMTPUTF8 Unicode in the string.
10617
10618
10619 .vitem &*${mask:*&<&'IP&~address'&>&*/*&<&'bit&~count'&>&*}*&
10620 .cindex "masked IP address"
10621 .cindex "IP address" "masking"
10622 .cindex "CIDR notation"
10623 .cindex "expansion" "IP address masking"
10624 .cindex "&%mask%& expansion item"
10625 If the form of the string to be operated on is not an IP address followed by a
10626 slash and an integer (that is, a network address in CIDR notation), the
10627 expansion fails. Otherwise, this operator converts the IP address to binary,
10628 masks off the least significant bits according to the bit count, and converts
10629 the result back to text, with mask appended. For example,
10630 .code
10631 ${mask:10.111.131.206/28}
10632 .endd
10633 returns the string &"10.111.131.192/28"&. Since this operation is expected to
10634 be mostly used for looking up masked addresses in files, the result for an IPv6
10635 address uses dots to separate components instead of colons, because colon
10636 terminates a key string in lsearch files. So, for example,
10637 .code
10638 ${mask:3ffe:ffff:836f:0a00:000a:0800:200a:c031/99}
10639 .endd
10640 returns the string
10641 .code
10642 3ffe.ffff.836f.0a00.000a.0800.2000.0000/99
10643 .endd
10644 Letters in IPv6 addresses are always output in lower case.
10645
10646
10647 .vitem &*${md5:*&<&'string'&>&*}*&
10648 .cindex "MD5 hash"
10649 .cindex "expansion" "MD5 hash"
10650 .cindex certificate fingerprint
10651 .cindex "&%md5%& expansion item"
10652 The &%md5%& operator computes the MD5 hash value of the string, and returns it
10653 as a 32-digit hexadecimal number, in which any letters are in lower case.
10654
10655 If the string is a single variable of type certificate,
10656 returns the MD5 hash fingerprint of the certificate.
10657
10658
10659 .vitem &*${nhash_*&<&'n'&>&*_*&<&'m'&>&*:*&<&'string'&>&*}*&
10660 .cindex "expansion" "numeric hash"
10661 .cindex "hash function" "numeric"
10662 The &%nhash%& operator is a simpler interface to the numeric hashing function
10663 that can be used when the two parameters are fixed numbers (as opposed to
10664 strings that change when expanded). The effect is the same as
10665 .code
10666 ${nhash{<n>}{<m>}{<string>}}
10667 .endd
10668 See the description of the general &%nhash%& item above for details.
10669
10670
10671 .vitem &*${quote:*&<&'string'&>&*}*&
10672 .cindex "quoting" "in string expansions"
10673 .cindex "expansion" "quoting"
10674 .cindex "&%quote%& expansion item"
10675 The &%quote%& operator puts its argument into double quotes if it
10676 is an empty string or
10677 contains anything other than letters, digits, underscores, dots, and hyphens.
10678 Any occurrences of double quotes and backslashes are escaped with a backslash.
10679 Newlines and carriage returns are converted to &`\n`& and &`\r`&,
10680 respectively For example,
10681 .code
10682 ${quote:ab"*"cd}
10683 .endd
10684 becomes
10685 .code
10686 "ab\"*\"cd"
10687 .endd
10688 The place where this is useful is when the argument is a substitution from a
10689 variable or a message header.
10690
10691 .vitem &*${quote_local_part:*&<&'string'&>&*}*&
10692 .cindex "&%quote_local_part%& expansion item"
10693 This operator is like &%quote%&, except that it quotes the string only if
10694 required to do so by the rules of RFC 2822 for quoting local parts. For
10695 example, a plus sign would not cause quoting (but it would for &%quote%&).
10696 If you are creating a new email address from the contents of &$local_part$&
10697 (or any other unknown data), you should always use this operator.
10698
10699 This quoting determination is not SMTPUTF8-aware, thus quoting non-ASCII data
10700 will likely use the quoting form.
10701 Thus &'${quote_local_part:フィル}'& will always become &'"フィル"'&.
10702
10703
10704 .vitem &*${quote_*&<&'lookup-type'&>&*:*&<&'string'&>&*}*&
10705 .cindex "quoting" "lookup-specific"
10706 This operator applies lookup-specific quoting rules to the string. Each
10707 query-style lookup type has its own quoting rules which are described with
10708 the lookups in chapter &<<CHAPfdlookup>>&. For example,
10709 .code
10710 ${quote_ldap:two * two}
10711 .endd
10712 returns
10713 .code
10714 two%20%5C2A%20two
10715 .endd
10716 For single-key lookup types, no quoting is ever necessary and this operator
10717 yields an unchanged string.
10718
10719
10720 .vitem &*${randint:*&<&'n'&>&*}*&
10721 .cindex "random number"
10722 This operator returns a somewhat random number which is less than the
10723 supplied number and is at least 0.  The quality of this randomness depends
10724 on how Exim was built; the values are not suitable for keying material.
10725 If Exim is linked against OpenSSL then RAND_pseudo_bytes() is used.
10726 If Exim is linked against GnuTLS then gnutls_rnd(GNUTLS_RND_NONCE) is used,
10727 for versions of GnuTLS with that function.
10728 Otherwise, the implementation may be arc4random(), random() seeded by
10729 srandomdev() or srandom(), or a custom implementation even weaker than
10730 random().
10731
10732
10733 .vitem &*${reverse_ip:*&<&'ipaddr'&>&*}*&
10734 .cindex "expansion" "IP address"
10735 This operator reverses an IP address; for IPv4 addresses, the result is in
10736 dotted-quad decimal form, while for IPv6 addresses the result is in
10737 dotted-nibble hexadecimal form.  In both cases, this is the "natural" form
10738 for DNS.  For example,
10739 .code
10740 ${reverse_ip:192.0.2.4}
10741 ${reverse_ip:2001:0db8:c42:9:1:abcd:192.0.2.127}
10742 .endd
10743 returns
10744 .code
10745 4.2.0.192
10746 f.7.2.0.0.0.0.c.d.c.b.a.1.0.0.0.9.0.0.0.2.4.c.0.8.b.d.0.1.0.0.2
10747 .endd
10748
10749
10750 .vitem &*${rfc2047:*&<&'string'&>&*}*&
10751 .cindex "expansion" "RFC 2047"
10752 .cindex "RFC 2047" "expansion operator"
10753 .cindex "&%rfc2047%& expansion item"
10754 This operator encodes text according to the rules of RFC 2047. This is an
10755 encoding that is used in header lines to encode non-ASCII characters. It is
10756 assumed that the input string is in the encoding specified by the
10757 &%headers_charset%& option, which gets its default at build time. If the string
10758 contains only characters in the range 33&--126, and no instances of the
10759 characters
10760 .code
10761 ? = ( ) < > @ , ; : \ " . [ ] _
10762 .endd
10763 it is not modified. Otherwise, the result is the RFC 2047 encoding of the
10764 string, using as many &"encoded words"& as necessary to encode all the
10765 characters.
10766
10767
10768 .vitem &*${rfc2047d:*&<&'string'&>&*}*&
10769 .cindex "expansion" "RFC 2047"
10770 .cindex "RFC 2047" "decoding"
10771 .cindex "&%rfc2047d%& expansion item"
10772 This operator decodes strings that are encoded as per RFC 2047. Binary zero
10773 bytes are replaced by question marks. Characters are converted into the
10774 character set defined by &%headers_charset%&. Overlong RFC 2047 &"words"& are
10775 not recognized unless &%check_rfc2047_length%& is set false.
10776
10777 &*Note*&: If you use &%$header%&_&'xxx'&&*:*& (or &%$h%&_&'xxx'&&*:*&) to
10778 access a header line, RFC 2047 decoding is done automatically. You do not need
10779 to use this operator as well.
10780
10781
10782
10783 .vitem &*${rxquote:*&<&'string'&>&*}*&
10784 .cindex "quoting" "in regular expressions"
10785 .cindex "regular expressions" "quoting"
10786 .cindex "&%rxquote%& expansion item"
10787 The &%rxquote%& operator inserts a backslash before any non-alphanumeric
10788 characters in its argument. This is useful when substituting the values of
10789 variables or headers inside regular expressions.
10790
10791
10792 .vitem &*${sha1:*&<&'string'&>&*}*&
10793 .cindex "SHA-1 hash"
10794 .cindex "expansion" "SHA-1 hashing"
10795 .cindex certificate fingerprint
10796 .cindex "&%sha1%& expansion item"
10797 The &%sha1%& operator computes the SHA-1 hash value of the string, and returns
10798 it as a 40-digit hexadecimal number, in which any letters are in upper case.
10799
10800 If the string is a single variable of type certificate,
10801 returns the SHA-1 hash fingerprint of the certificate.
10802
10803
10804 .vitem &*${sha256:*&<&'string'&>&*}*&
10805 .cindex "SHA-256 hash"
10806 .cindex certificate fingerprint
10807 .cindex "expansion" "SHA-256 hashing"
10808 .cindex "&%sha256%& expansion item"
10809 The &%sha256%& operator computes the SHA-256 hash value of the string
10810 and returns
10811 it as a 64-digit hexadecimal number, in which any letters are in upper case.
10812
10813 If the string is a single variable of type certificate,
10814 returns the SHA-256 hash fingerprint of the certificate.
10815
10816
10817 .vitem &*${sha3:*&<&'string'&>&*}*& &&&
10818        &*${sha3_<n>:*&<&'string'&>&*}*&
10819 .cindex "SHA3 hash"
10820 .cindex "expansion" "SHA3 hashing"
10821 .cindex "&%sha3%& expansion item"
10822 The &%sha3%& operator computes the SHA3-256 hash value of the string
10823 and returns
10824 it as a 64-digit hexadecimal number, in which any letters are in upper case.
10825
10826 If a number is appended, separated by an underbar, it specifies
10827 the output length.  Values of 224, 256, 384 and 512 are accepted;
10828 with 256 being the default.
10829
10830 The &%sha3%& expansion item is only supported if Exim has been
10831 compiled with GnuTLS 3.5.0 or later,
10832 or OpenSSL 1.1.1 or later.
10833 The macro "_CRYPTO_HASH_SHA3" will be defined if it is supported.
10834
10835
10836 .vitem &*${stat:*&<&'string'&>&*}*&
10837 .cindex "expansion" "statting a file"
10838 .cindex "file" "extracting characteristics"
10839 .cindex "&%stat%& expansion item"
10840 The string, after expansion, must be a file path. A call to the &[stat()]&
10841 function is made for this path. If &[stat()]& fails, an error occurs and the
10842 expansion fails. If it succeeds, the data from the stat replaces the item, as a
10843 series of <&'name'&>=<&'value'&> pairs, where the values are all numerical,
10844 except for the value of &"smode"&. The names are: &"mode"& (giving the mode as
10845 a 4-digit octal number), &"smode"& (giving the mode in symbolic format as a
10846 10-character string, as for the &'ls'& command), &"inode"&, &"device"&,
10847 &"links"&, &"uid"&, &"gid"&, &"size"&, &"atime"&, &"mtime"&, and &"ctime"&. You
10848 can extract individual fields using the &%extract%& expansion item.
10849
10850 The use of the &%stat%& expansion in users' filter files can be locked out by
10851 the system administrator. &*Warning*&: The file size may be incorrect on 32-bit
10852 systems for files larger than 2GB.
10853
10854 .vitem &*${str2b64:*&<&'string'&>&*}*&
10855 .cindex "&%str2b64%& expansion item"
10856 Now deprecated, a synonym for the &%base64%& expansion operator.
10857
10858
10859
10860 .vitem &*${strlen:*&<&'string'&>&*}*&
10861 .cindex "expansion" "string length"
10862 .cindex "string" "length in expansion"
10863 .cindex "&%strlen%& expansion item"
10864 The item is replace by the length of the expanded string, expressed as a
10865 decimal number. &*Note*&: Do not confuse &%strlen%& with &%length%&.
10866 All measurement is done in bytes and is not UTF-8 aware.
10867
10868
10869 .vitem &*${substr_*&<&'start'&>&*_*&<&'length'&>&*:*&<&'string'&>&*}*&
10870 .cindex "&%substr%& expansion item"
10871 .cindex "substring extraction"
10872 .cindex "expansion" "substring expansion"
10873 The &%substr%& operator is a simpler interface to the &%substr%& function that
10874 can be used when the two parameters are fixed numbers (as opposed to strings
10875 that change when expanded). The effect is the same as
10876 .code
10877 ${substr{<start>}{<length>}{<string>}}
10878 .endd
10879 See the description of the general &%substr%& item above for details. The
10880 abbreviation &%s%& can be used when &%substr%& is used as an operator.
10881 All measurement is done in bytes and is not UTF-8 aware.
10882
10883 .vitem &*${time_eval:*&<&'string'&>&*}*&
10884 .cindex "&%time_eval%& expansion item"
10885 .cindex "time interval" "decoding"
10886 This item converts an Exim time interval such as &`2d4h5m`& into a number of
10887 seconds.
10888
10889 .vitem &*${time_interval:*&<&'string'&>&*}*&
10890 .cindex "&%time_interval%& expansion item"
10891 .cindex "time interval" "formatting"
10892 The argument (after sub-expansion) must be a sequence of decimal digits that
10893 represents an interval of time as a number of seconds. It is converted into a
10894 number of larger units and output in Exim's normal time format, for example,
10895 &`1w3d4h2m6s`&.
10896
10897 .vitem &*${uc:*&<&'string'&>&*}*&
10898 .cindex "case forcing in strings"
10899 .cindex "string" "case forcing"
10900 .cindex "upper casing"
10901 .cindex "expansion" "case forcing"
10902 .cindex "&%uc%& expansion item"
10903 This forces the letters in the string into upper-case.
10904 Case is defined per the system C locale.
10905
10906 .vitem &*${utf8clean:*&<&'string'&>&*}*&
10907 .cindex "correction of invalid utf-8 sequences in strings"
10908 .cindex "utf-8" "utf-8 sequences"
10909 .cindex "incorrect utf-8"
10910 .cindex "expansion" "utf-8 forcing"
10911 .cindex "&%utf8clean%& expansion item"
10912 This replaces any invalid utf-8 sequence in the string by the character &`?`&.
10913 .new
10914 In versions of Exim before 4.92, this did not correctly do so for a truncated
10915 final codepoint's encoding, and the character would be silently dropped.
10916 If you must handle detection of this scenario across both sets of Exim behavior,
10917 the complexity will depend upon the task.
10918 For instance, to detect if the first character is multibyte and a 1-byte
10919 extraction can be successfully used as a path component (as is common for
10920 dividing up delivery folders), you might use:
10921 .code
10922 condition = ${if inlist{${utf8clean:${length_1:$local_part}}}{:?}{yes}{no}}
10923 .endd
10924 (which will false-positive if the first character of the local part is a
10925 literal question mark).
10926 .wen
10927
10928 .vitem "&*${utf8_domain_to_alabel:*&<&'string'&>&*}*&" &&&
10929        "&*${utf8_domain_from_alabel:*&<&'string'&>&*}*&" &&&
10930        "&*${utf8_localpart_to_alabel:*&<&'string'&>&*}*&" &&&
10931        "&*${utf8_localpart_from_alabel:*&<&'string'&>&*}*&"
10932 .cindex expansion UTF-8
10933 .cindex UTF-8 expansion
10934 .cindex EAI
10935 .cindex internationalisation
10936 .cindex "&%utf8_domain_to_alabel%& expansion item"
10937 .cindex "&%utf8_domain_from_alabel%& expansion item"
10938 .cindex "&%utf8_localpart_to_alabel%& expansion item"
10939 .cindex "&%utf8_localpart_from_alabel%& expansion item"
10940 These convert EAI mail name components between UTF-8 and a-label forms.
10941 For information on internationalisation support see &<<SECTi18nMTA>>&.
10942 .endlist
10943
10944
10945
10946
10947
10948
10949 .section "Expansion conditions" "SECTexpcond"
10950 .scindex IIDexpcond "expansion" "conditions"
10951 The following conditions are available for testing by the &%${if%& construct
10952 while expanding strings:
10953
10954 .vlist
10955 .vitem &*!*&<&'condition'&>
10956 .cindex "expansion" "negating a condition"
10957 .cindex "negation" "in expansion condition"
10958 Preceding any condition with an exclamation mark negates the result of the
10959 condition.
10960
10961 .vitem <&'symbolic&~operator'&>&~&*{*&<&'string1'&>&*}{*&<&'string2'&>&*}*&
10962 .cindex "numeric comparison"
10963 .cindex "expansion" "numeric comparison"
10964 There are a number of symbolic operators for doing numeric comparisons. They
10965 are:
10966 .display
10967 &`=   `&   equal
10968 &`==  `&   equal
10969 &`>   `&   greater
10970 &`>=  `&   greater or equal
10971 &`<   `&   less
10972 &`<=  `&   less or equal
10973 .endd
10974 For example:
10975 .code
10976 ${if >{$message_size}{10M} ...
10977 .endd
10978 Note that the general negation operator provides for inequality testing. The
10979 two strings must take the form of optionally signed decimal integers,
10980 optionally followed by one of the letters &"K"&, &"M"& or &"G"& (in either upper or
10981 lower case), signifying multiplication by 1024, 1024*1024 or 1024*1024*1024, respectively.
10982 As a special case, the numerical value of an empty string is taken as
10983 zero.
10984
10985 In all cases, a relative comparator OP is testing if <&'string1'&> OP
10986 <&'string2'&>; the above example is checking if &$message_size$& is larger than
10987 10M, not if 10M is larger than &$message_size$&.
10988
10989
10990 .vitem &*acl&~{{*&<&'name'&>&*}{*&<&'arg1'&>&*}&&&
10991         {*&<&'arg2'&>&*}...}*&
10992 .cindex "expansion" "calling an acl"
10993 .cindex "&%acl%&" "expansion condition"
10994 The name and zero to nine argument strings are first expanded separately.  The expanded
10995 arguments are assigned to the variables &$acl_arg1$& to &$acl_arg9$& in order.
10996 Any unused are made empty.  The variable &$acl_narg$& is set to the number of
10997 arguments.  The named ACL (see chapter &<<CHAPACL>>&) is called
10998 and may use the variables; if another acl expansion is used the values
10999 are restored after it returns.  If the ACL sets
11000 a value using a "message =" modifier the variable $value becomes
11001 the result of the expansion, otherwise it is empty.
11002 If the ACL returns accept the condition is true; if deny, false.
11003 If the ACL returns defer the result is a forced-fail.
11004
11005 .vitem &*bool&~{*&<&'string'&>&*}*&
11006 .cindex "expansion" "boolean parsing"
11007 .cindex "&%bool%& expansion condition"
11008 This condition turns a string holding a true or false representation into
11009 a boolean state.  It parses &"true"&, &"false"&, &"yes"& and &"no"&
11010 (case-insensitively); also integer numbers map to true if non-zero,
11011 false if zero.
11012 An empty string is treated as false.
11013 Leading and trailing whitespace is ignored;
11014 thus a string consisting only of whitespace is false.
11015 All other string values will result in expansion failure.
11016
11017 When combined with ACL variables, this expansion condition will let you
11018 make decisions in one place and act on those decisions in another place.
11019 For example:
11020 .code
11021 ${if bool{$acl_m_privileged_sender} ...
11022 .endd
11023
11024
11025 .vitem &*bool_lax&~{*&<&'string'&>&*}*&
11026 .cindex "expansion" "boolean parsing"
11027 .cindex "&%bool_lax%& expansion condition"
11028 Like &%bool%&, this condition turns a string into a boolean state.  But
11029 where &%bool%& accepts a strict set of strings, &%bool_lax%& uses the same
11030 loose definition that the Router &%condition%& option uses.  The empty string
11031 and the values &"false"&, &"no"& and &"0"& map to false, all others map to
11032 true.  Leading and trailing whitespace is ignored.
11033
11034 Note that where &"bool{00}"& is false, &"bool_lax{00}"& is true.
11035
11036 .vitem &*crypteq&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*&
11037 .cindex "expansion" "encrypted comparison"
11038 .cindex "encrypted strings, comparing"
11039 .cindex "&%crypteq%& expansion condition"
11040 This condition is included in the Exim binary if it is built to support any
11041 authentication mechanisms (see chapter &<<CHAPSMTPAUTH>>&). Otherwise, it is
11042 necessary to define SUPPORT_CRYPTEQ in &_Local/Makefile_& to get &%crypteq%&
11043 included in the binary.
11044
11045 The &%crypteq%& condition has two arguments. The first is encrypted and
11046 compared against the second, which is already encrypted. The second string may
11047 be in the LDAP form for storing encrypted strings, which starts with the
11048 encryption type in curly brackets, followed by the data. If the second string
11049 does not begin with &"{"& it is assumed to be encrypted with &[crypt()]& or
11050 &[crypt16()]& (see below), since such strings cannot begin with &"{"&.
11051 Typically this will be a field from a password file. An example of an encrypted
11052 string in LDAP form is:
11053 .code
11054 {md5}CY9rzUYh03PK3k6DJie09g==
11055 .endd
11056 If such a string appears directly in an expansion, the curly brackets have to
11057 be quoted, because they are part of the expansion syntax. For example:
11058 .code
11059 ${if crypteq {test}{\{md5\}CY9rzUYh03PK3k6DJie09g==}{yes}{no}}
11060 .endd
11061 The following encryption types (whose names are matched case-independently) are
11062 supported:
11063
11064 .ilist
11065 .cindex "MD5 hash"
11066 .cindex "base64 encoding" "in encrypted password"
11067 &%{md5}%& computes the MD5 digest of the first string, and expresses this as
11068 printable characters to compare with the remainder of the second string. If the
11069 length of the comparison string is 24, Exim assumes that it is base64 encoded
11070 (as in the above example). If the length is 32, Exim assumes that it is a
11071 hexadecimal encoding of the MD5 digest. If the length not 24 or 32, the
11072 comparison fails.
11073
11074 .next
11075 .cindex "SHA-1 hash"
11076 &%{sha1}%& computes the SHA-1 digest of the first string, and expresses this as
11077 printable characters to compare with the remainder of the second string. If the
11078 length of the comparison string is 28, Exim assumes that it is base64 encoded.
11079 If the length is 40, Exim assumes that it is a hexadecimal encoding of the
11080 SHA-1 digest. If the length is not 28 or 40, the comparison fails.
11081
11082 .next
11083 .cindex "&[crypt()]&"
11084 &%{crypt}%& calls the &[crypt()]& function, which traditionally used to use
11085 only the first eight characters of the password. However, in modern operating
11086 systems this is no longer true, and in many cases the entire password is used,
11087 whatever its length.
11088
11089 .next
11090 .cindex "&[crypt16()]&"
11091 &%{crypt16}%& calls the &[crypt16()]& function, which was originally created to
11092 use up to 16 characters of the password in some operating systems. Again, in
11093 modern operating systems, more characters may be used.
11094 .endlist
11095 Exim has its own version of &[crypt16()]&, which is just a double call to
11096 &[crypt()]&. For operating systems that have their own version, setting
11097 HAVE_CRYPT16 in &_Local/Makefile_& when building Exim causes it to use the
11098 operating system version instead of its own. This option is set by default in
11099 the OS-dependent &_Makefile_& for those operating systems that are known to
11100 support &[crypt16()]&.
11101
11102 Some years after Exim's &[crypt16()]& was implemented, a user discovered that
11103 it was not using the same algorithm as some operating systems' versions. It
11104 turns out that as well as &[crypt16()]& there is a function called
11105 &[bigcrypt()]& in some operating systems. This may or may not use the same
11106 algorithm, and both of them may be different to Exim's built-in &[crypt16()]&.
11107
11108 However, since there is now a move away from the traditional &[crypt()]&
11109 functions towards using SHA1 and other algorithms, tidying up this area of
11110 Exim is seen as very low priority.
11111
11112 If you do not put a encryption type (in curly brackets) in a &%crypteq%&
11113 comparison, the default is usually either &`{crypt}`& or &`{crypt16}`&, as
11114 determined by the setting of DEFAULT_CRYPT in &_Local/Makefile_&. The default
11115 default is &`{crypt}`&. Whatever the default, you can always use either
11116 function by specifying it explicitly in curly brackets.
11117
11118 .vitem &*def:*&<&'variable&~name'&>
11119 .cindex "expansion" "checking for empty variable"
11120 .cindex "&%def%& expansion condition"
11121 The &%def%& condition must be followed by the name of one of the expansion
11122 variables defined in section &<<SECTexpvar>>&. The condition is true if the
11123 variable does not contain the empty string. For example:
11124 .code
11125 ${if def:sender_ident {from $sender_ident}}
11126 .endd
11127 Note that the variable name is given without a leading &%$%& character. If the
11128 variable does not exist, the expansion fails.
11129
11130 .vitem "&*def:header_*&<&'header&~name'&>&*:*&&~&~or&~&&&
11131         &~&*def:h_*&<&'header&~name'&>&*:*&"
11132 .cindex "expansion" "checking header line existence"
11133 This condition is true if a message is being processed and the named header
11134 exists in the message. For example,
11135 .code
11136 ${if def:header_reply-to:{$h_reply-to:}{$h_from:}}
11137 .endd
11138 &*Note*&: No &%$%& appears before &%header_%& or &%h_%& in the condition, and
11139 the header name must be terminated by a colon if white space does not follow.
11140
11141 .vitem &*eq&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& &&&
11142        &*eqi&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*&
11143 .cindex "string" "comparison"
11144 .cindex "expansion" "string comparison"
11145 .cindex "&%eq%& expansion condition"
11146 .cindex "&%eqi%& expansion condition"
11147 The two substrings are first expanded. The condition is true if the two
11148 resulting strings are identical. For &%eq%& the comparison includes the case of
11149 letters, whereas for &%eqi%& the comparison is case-independent, where
11150 case is defined per the system C locale.
11151
11152 .vitem &*exists&~{*&<&'file&~name'&>&*}*&
11153 .cindex "expansion" "file existence test"
11154 .cindex "file" "existence test"
11155 .cindex "&%exists%&, expansion condition"
11156 The substring is first expanded and then interpreted as an absolute path. The
11157 condition is true if the named file (or directory) exists. The existence test
11158 is done by calling the &[stat()]& function. The use of the &%exists%& test in
11159 users' filter files may be locked out by the system administrator.
11160
11161 .vitem &*first_delivery*&
11162 .cindex "delivery" "first"
11163 .cindex "first delivery"
11164 .cindex "expansion" "first delivery test"
11165 .cindex "&%first_delivery%& expansion condition"
11166 This condition, which has no data, is true during a message's first delivery
11167 attempt. It is false during any subsequent delivery attempts.
11168
11169
11170 .vitem "&*forall{*&<&'a list'&>&*}{*&<&'a condition'&>&*}*&" &&&
11171        "&*forany{*&<&'a list'&>&*}{*&<&'a condition'&>&*}*&"
11172 .cindex "list" "iterative conditions"
11173 .cindex "expansion" "&*forall*& condition"
11174 .cindex "expansion" "&*forany*& condition"
11175 .vindex "&$item$&"
11176 These conditions iterate over a list. The first argument is expanded to form
11177 the list. By default, the list separator is a colon, but it can be changed by
11178 the normal method. The second argument is interpreted as a condition that is to
11179 be applied to each item in the list in turn. During the interpretation of the
11180 condition, the current list item is placed in a variable called &$item$&.
11181 .ilist
11182 For &*forany*&, interpretation stops if the condition is true for any item, and
11183 the result of the whole condition is true. If the condition is false for all
11184 items in the list, the overall condition is false.
11185 .next
11186 For &*forall*&, interpretation stops if the condition is false for any item,
11187 and the result of the whole condition is false. If the condition is true for
11188 all items in the list, the overall condition is true.
11189 .endlist
11190 Note that negation of &*forany*& means that the condition must be false for all
11191 items for the overall condition to succeed, and negation of &*forall*& means
11192 that the condition must be false for at least one item. In this example, the
11193 list separator is changed to a comma:
11194 .code
11195 ${if forany{<, $recipients}{match{$item}{^user3@}}{yes}{no}}
11196 .endd
11197 The value of &$item$& is saved and restored while &*forany*& or &*forall*& is
11198 being processed, to enable these expansion items to be nested.
11199
11200 To scan a named list, expand it with the &*listnamed*& operator.
11201
11202
11203 .vitem &*ge&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& &&&
11204        &*gei&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*&
11205 .cindex "string" "comparison"
11206 .cindex "expansion" "string comparison"
11207 .cindex "&%ge%& expansion condition"
11208 .cindex "&%gei%& expansion condition"
11209 The two substrings are first expanded. The condition is true if the first
11210 string is lexically greater than or equal to the second string. For &%ge%& the
11211 comparison includes the case of letters, whereas for &%gei%& the comparison is
11212 case-independent.
11213 Case and collation order are defined per the system C locale.
11214
11215 .vitem &*gt&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& &&&
11216        &*gti&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*&
11217 .cindex "string" "comparison"
11218 .cindex "expansion" "string comparison"
11219 .cindex "&%gt%& expansion condition"
11220 .cindex "&%gti%& expansion condition"
11221 The two substrings are first expanded. The condition is true if the first
11222 string is lexically greater than the second string. For &%gt%& the comparison
11223 includes the case of letters, whereas for &%gti%& the comparison is
11224 case-independent.
11225 Case and collation order are defined per the system C locale.
11226
11227 .vitem &*inlist&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& &&&
11228        &*inlisti&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*&
11229 .cindex "string" "comparison"
11230 .cindex "list" "iterative conditions"
11231 Both strings are expanded; the second string is treated as a list of simple
11232 strings; if the first string is a member of the second, then the condition
11233 is true.
11234 For the case-independent &%inlisti%& condition, case is defined per the system C locale.
11235
11236 These are simpler to use versions of the more powerful &*forany*& condition.
11237 Examples, and the &*forany*& equivalents:
11238 .code
11239 ${if inlist{needle}{foo:needle:bar}}
11240   ${if forany{foo:needle:bar}{eq{$item}{needle}}}
11241 ${if inlisti{Needle}{fOo:NeeDLE:bAr}}
11242   ${if forany{fOo:NeeDLE:bAr}{eqi{$item}{Needle}}}
11243 .endd
11244
11245 .vitem &*isip&~{*&<&'string'&>&*}*&  &&&
11246        &*isip4&~{*&<&'string'&>&*}*& &&&
11247        &*isip6&~{*&<&'string'&>&*}*&
11248 .cindex "IP address" "testing string format"
11249 .cindex "string" "testing for IP address"
11250 .cindex "&%isip%& expansion condition"
11251 .cindex "&%isip4%& expansion condition"
11252 .cindex "&%isip6%& expansion condition"
11253 The substring is first expanded, and then tested to see if it has the form of
11254 an IP address. Both IPv4 and IPv6 addresses are valid for &%isip%&, whereas
11255 &%isip4%& and &%isip6%& test specifically for IPv4 or IPv6 addresses.
11256
11257 For an IPv4 address, the test is for four dot-separated components, each of
11258 which consists of from one to three digits. For an IPv6 address, up to eight
11259 colon-separated components are permitted, each containing from one to four
11260 hexadecimal digits. There may be fewer than eight components if an empty
11261 component (adjacent colons) is present. Only one empty component is permitted.
11262
11263 &*Note*&: The checks used to be just on the form of the address; actual numerical
11264 values were not considered. Thus, for example, 999.999.999.999 passed the IPv4
11265 check.
11266 This is no longer the case.
11267
11268 The main use of these tests is to distinguish between IP addresses and
11269 host names, or between IPv4 and IPv6 addresses. For example, you could use
11270 .code
11271 ${if isip4{$sender_host_address}...
11272 .endd
11273 to test which IP version an incoming SMTP connection is using.
11274
11275 .vitem &*ldapauth&~{*&<&'ldap&~query'&>&*}*&
11276 .cindex "LDAP" "use for authentication"
11277 .cindex "expansion" "LDAP authentication test"
11278 .cindex "&%ldapauth%& expansion condition"
11279 This condition supports user authentication using LDAP. See section
11280 &<<SECTldap>>& for details of how to use LDAP in lookups and the syntax of
11281 queries. For this use, the query must contain a user name and password. The
11282 query itself is not used, and can be empty. The condition is true if the
11283 password is not empty, and the user name and password are accepted by the LDAP
11284 server. An empty password is rejected without calling LDAP because LDAP binds
11285 with an empty password are considered anonymous regardless of the username, and
11286 will succeed in most configurations. See chapter &<<CHAPSMTPAUTH>>& for details
11287 of SMTP authentication, and chapter &<<CHAPplaintext>>& for an example of how
11288 this can be used.
11289
11290
11291 .vitem &*le&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& &&&
11292        &*lei&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*&
11293 .cindex "string" "comparison"
11294 .cindex "expansion" "string comparison"
11295 .cindex "&%le%& expansion condition"
11296 .cindex "&%lei%& expansion condition"
11297 The two substrings are first expanded. The condition is true if the first
11298 string is lexically less than or equal to the second string. For &%le%& the
11299 comparison includes the case of letters, whereas for &%lei%& the comparison is
11300 case-independent.
11301 Case and collation order are defined per the system C locale.
11302
11303 .vitem &*lt&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& &&&
11304        &*lti&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*&
11305 .cindex "string" "comparison"
11306 .cindex "expansion" "string comparison"
11307 .cindex "&%lt%& expansion condition"
11308 .cindex "&%lti%& expansion condition"
11309 The two substrings are first expanded. The condition is true if the first
11310 string is lexically less than the second string. For &%lt%& the comparison
11311 includes the case of letters, whereas for &%lti%& the comparison is
11312 case-independent.
11313 Case and collation order are defined per the system C locale.
11314
11315
11316 .vitem &*match&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*&
11317 .cindex "expansion" "regular expression comparison"
11318 .cindex "regular expressions" "match in expanded string"
11319 .cindex "&%match%& expansion condition"
11320 The two substrings are first expanded. The second is then treated as a regular
11321 expression and applied to the first. Because of the pre-expansion, if the
11322 regular expression contains dollar, or backslash characters, they must be
11323 escaped. Care must also be taken if the regular expression contains braces
11324 (curly brackets). A closing brace must be escaped so that it is not taken as a
11325 premature termination of <&'string2'&>. The easiest approach is to use the
11326 &`\N`& feature to disable expansion of the regular expression.
11327 For example,
11328 .code
11329 ${if match {$local_part}{\N^\d{3}\N} ...
11330 .endd
11331 If the whole expansion string is in double quotes, further escaping of
11332 backslashes is also required.
11333
11334 The condition is true if the regular expression match succeeds.
11335 The regular expression is not required to begin with a circumflex
11336 metacharacter, but if there is no circumflex, the expression is not anchored,
11337 and it may match anywhere in the subject, not just at the start. If you want
11338 the pattern to match at the end of the subject, you must include the &`$`&
11339 metacharacter at an appropriate point.
11340 All character handling is done in bytes and is not UTF-8 aware,
11341 but we might change this in a future Exim release.
11342
11343 .cindex "numerical variables (&$1$& &$2$& etc)" "in &%if%& expansion"
11344 At the start of an &%if%& expansion the values of the numeric variable
11345 substitutions &$1$& etc. are remembered. Obeying a &%match%& condition that
11346 succeeds causes them to be reset to the substrings of that condition and they
11347 will have these values during the expansion of the success string. At the end
11348 of the &%if%& expansion, the previous values are restored. After testing a
11349 combination of conditions using &%or%&, the subsequent values of the numeric
11350 variables are those of the condition that succeeded.
11351
11352 .vitem &*match_address&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*&
11353 .cindex "&%match_address%& expansion condition"
11354 See &*match_local_part*&.
11355
11356 .vitem &*match_domain&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*&
11357 .cindex "&%match_domain%& expansion condition"
11358 See &*match_local_part*&.
11359
11360 .vitem &*match_ip&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*&
11361 .cindex "&%match_ip%& expansion condition"
11362 This condition matches an IP address to a list of IP address patterns. It must
11363 be followed by two argument strings. The first (after expansion) must be an IP
11364 address or an empty string. The second (not expanded) is a restricted host
11365 list that can match only an IP address, not a host name. For example:
11366 .code
11367 ${if match_ip{$sender_host_address}{1.2.3.4:5.6.7.8}{...}{...}}
11368 .endd
11369 The specific types of host list item that are permitted in the list are:
11370
11371 .ilist
11372 An IP address, optionally with a CIDR mask.
11373 .next
11374 A single asterisk, which matches any IP address.
11375 .next
11376 An empty item, which matches only if the IP address is empty. This could be
11377 useful for testing for a locally submitted message or one from specific hosts
11378 in a single test such as
11379 . ==== As this is a nested list, any displays it contains must be indented
11380 . ==== as otherwise they are too far to the left. This comment applies to
11381 . ==== the use of xmlto plus fop. There's no problem when formatting with
11382 . ==== sdop, with or without the extra indent.
11383 .code
11384   ${if match_ip{$sender_host_address}{:4.3.2.1:...}{...}{...}}
11385 .endd
11386 where the first item in the list is the empty string.
11387 .next
11388 The item @[] matches any of the local host's interface addresses.
11389 .next
11390 Single-key lookups are assumed to be like &"net-"& style lookups in host lists,
11391 even if &`net-`& is not specified. There is never any attempt to turn the IP
11392 address into a host name. The most common type of linear search for
11393 &*match_ip*& is likely to be &*iplsearch*&, in which the file can contain CIDR
11394 masks. For example:
11395 .code
11396   ${if match_ip{$sender_host_address}{iplsearch;/some/file}...
11397 .endd
11398 It is of course possible to use other kinds of lookup, and in such a case, you
11399 do need to specify the &`net-`& prefix if you want to specify a specific
11400 address mask, for example:
11401 .code
11402   ${if match_ip{$sender_host_address}{net24-dbm;/some/file}...
11403 .endd
11404 However, unless you are combining a &%match_ip%& condition with others, it is
11405 just as easy to use the fact that a lookup is itself a condition, and write:
11406 .code
11407   ${lookup{${mask:$sender_host_address/24}}dbm{/a/file}...
11408 .endd
11409 .endlist ilist
11410
11411 Note that <&'string2'&> is not itself subject to string expansion, unless
11412 Exim was built with the EXPAND_LISTMATCH_RHS option.
11413
11414 Consult section &<<SECThoslispatip>>& for further details of these patterns.
11415
11416 .vitem &*match_local_part&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*&
11417 .cindex "domain list" "in expansion condition"
11418 .cindex "address list" "in expansion condition"
11419 .cindex "local part" "list, in expansion condition"
11420 .cindex "&%match_local_part%& expansion condition"
11421 This condition, together with &%match_address%& and &%match_domain%&, make it
11422 possible to test domain, address, and local part lists within expansions. Each
11423 condition requires two arguments: an item and a list to match. A trivial
11424 example is:
11425 .code
11426 ${if match_domain{a.b.c}{x.y.z:a.b.c:p.q.r}{yes}{no}}
11427 .endd
11428 In each case, the second argument may contain any of the allowable items for a
11429 list of the appropriate type. Also, because the second argument
11430 is a standard form of list, it is possible to refer to a named list.
11431 Thus, you can use conditions like this:
11432 .code
11433 ${if match_domain{$domain}{+local_domains}{...
11434 .endd
11435 .cindex "&`+caseful`&"
11436 For address lists, the matching starts off caselessly, but the &`+caseful`&
11437 item can be used, as in all address lists, to cause subsequent items to
11438 have their local parts matched casefully. Domains are always matched
11439 caselessly.
11440
11441 Note that <&'string2'&> is not itself subject to string expansion, unless
11442 Exim was built with the EXPAND_LISTMATCH_RHS option.
11443
11444 &*Note*&: Host lists are &'not'& supported in this way. This is because
11445 hosts have two identities: a name and an IP address, and it is not clear
11446 how to specify cleanly how such a test would work. However, IP addresses can be
11447 matched using &%match_ip%&.
11448
11449 .vitem &*pam&~{*&<&'string1'&>&*:*&<&'string2'&>&*:...}*&
11450 .cindex "PAM authentication"
11451 .cindex "AUTH" "with PAM"
11452 .cindex "Solaris" "PAM support"
11453 .cindex "expansion" "PAM authentication test"
11454 .cindex "&%pam%& expansion condition"
11455 &'Pluggable Authentication Modules'&
11456 (&url(https://mirrors.edge.kernel.org/pub/linux/libs/pam/)) are a facility that is
11457 available in the latest releases of Solaris and in some GNU/Linux
11458 distributions. The Exim support, which is intended for use in conjunction with
11459 the SMTP AUTH command, is available only if Exim is compiled with
11460 .code
11461 SUPPORT_PAM=yes
11462 .endd
11463 in &_Local/Makefile_&. You probably need to add &%-lpam%& to EXTRALIBS, and
11464 in some releases of GNU/Linux &%-ldl%& is also needed.
11465
11466 The argument string is first expanded, and the result must be a
11467 colon-separated list of strings. Leading and trailing white space is ignored.
11468 The PAM module is initialized with the service name &"exim"& and the user name
11469 taken from the first item in the colon-separated data string (<&'string1'&>).
11470 The remaining items in the data string are passed over in response to requests
11471 from the authentication function. In the simple case there will only be one
11472 request, for a password, so the data consists of just two strings.
11473
11474 There can be problems if any of the strings are permitted to contain colon
11475 characters. In the usual way, these have to be doubled to avoid being taken as
11476 separators. If the data is being inserted from a variable, the &%sg%& expansion
11477 item can be used to double any existing colons. For example, the configuration
11478 of a LOGIN authenticator might contain this setting:
11479 .code
11480 server_condition = ${if pam{$auth1:${sg{$auth2}{:}{::}}}}
11481 .endd
11482 For a PLAIN authenticator you could use:
11483 .code
11484 server_condition = ${if pam{$auth2:${sg{$auth3}{:}{::}}}}
11485 .endd
11486 In some operating systems, PAM authentication can be done only from a process
11487 running as root. Since Exim is running as the Exim user when receiving
11488 messages, this means that PAM cannot be used directly in those systems.
11489 . --- 2018-09-07: the pam_exim modified variant has gone, removed claims re using Exim via that
11490
11491
11492 .vitem &*pwcheck&~{*&<&'string1'&>&*:*&<&'string2'&>&*}*&
11493 .cindex "&'pwcheck'& daemon"
11494 .cindex "Cyrus"
11495 .cindex "expansion" "&'pwcheck'& authentication test"
11496 .cindex "&%pwcheck%& expansion condition"
11497 This condition supports user authentication using the Cyrus &'pwcheck'& daemon.
11498 This is one way of making it possible for passwords to be checked by a process
11499 that is not running as root. &*Note*&: The use of &'pwcheck'& is now
11500 deprecated. Its replacement is &'saslauthd'& (see below).
11501
11502 The pwcheck support is not included in Exim by default. You need to specify
11503 the location of the pwcheck daemon's socket in &_Local/Makefile_& before
11504 building Exim. For example:
11505 .code
11506 CYRUS_PWCHECK_SOCKET=/var/pwcheck/pwcheck
11507 .endd
11508 You do not need to install the full Cyrus software suite in order to use
11509 the pwcheck daemon. You can compile and install just the daemon alone
11510 from the Cyrus SASL library. Ensure that &'exim'& is the only user that has
11511 access to the &_/var/pwcheck_& directory.
11512
11513 The &%pwcheck%& condition takes one argument, which must be the user name and
11514 password, separated by a colon. For example, in a LOGIN authenticator
11515 configuration, you might have this:
11516 .code
11517 server_condition = ${if pwcheck{$auth1:$auth2}}
11518 .endd
11519 Again, for a PLAIN authenticator configuration, this would be:
11520 .code
11521 server_condition = ${if pwcheck{$auth2:$auth3}}
11522 .endd
11523 .vitem &*queue_running*&
11524 .cindex "queue runner" "detecting when delivering from"
11525 .cindex "expansion" "queue runner test"
11526 .cindex "&%queue_running%& expansion condition"
11527 This condition, which has no data, is true during delivery attempts that are
11528 initiated by queue runner processes, and false otherwise.
11529
11530
11531 .vitem &*radius&~{*&<&'authentication&~string'&>&*}*&
11532 .cindex "Radius"
11533 .cindex "expansion" "Radius authentication"
11534 .cindex "&%radius%& expansion condition"
11535 Radius authentication (RFC 2865) is supported in a similar way to PAM. You must
11536 set RADIUS_CONFIG_FILE in &_Local/Makefile_& to specify the location of
11537 the Radius client configuration file in order to build Exim with Radius
11538 support.
11539
11540 With just that one setting, Exim expects to be linked with the &%radiusclient%&
11541 library, using the original API. If you are using release 0.4.0 or later of
11542 this library, you need to set
11543 .code
11544 RADIUS_LIB_TYPE=RADIUSCLIENTNEW
11545 .endd
11546 in &_Local/Makefile_& when building Exim. You can also link Exim with the
11547 &%libradius%& library that comes with FreeBSD. To do this, set
11548 .code
11549 RADIUS_LIB_TYPE=RADLIB
11550 .endd
11551 in &_Local/Makefile_&, in addition to setting RADIUS_CONFIGURE_FILE.
11552 You may also have to supply a suitable setting in EXTRALIBS so that the
11553 Radius library can be found when Exim is linked.
11554
11555 The string specified by RADIUS_CONFIG_FILE is expanded and passed to the
11556 Radius client library, which calls the Radius server. The condition is true if
11557 the authentication is successful. For example:
11558 .code
11559 server_condition = ${if radius{<arguments>}}
11560 .endd
11561
11562
11563 .vitem "&*saslauthd&~{{*&<&'user'&>&*}{*&<&'password'&>&*}&&&
11564         {*&<&'service'&>&*}{*&<&'realm'&>&*}}*&"
11565 .cindex "&'saslauthd'& daemon"
11566 .cindex "Cyrus"
11567 .cindex "expansion" "&'saslauthd'& authentication test"
11568 .cindex "&%saslauthd%& expansion condition"
11569 This condition supports user authentication using the Cyrus &'saslauthd'&
11570 daemon. This replaces the older &'pwcheck'& daemon, which is now deprecated.
11571 Using this daemon is one way of making it possible for passwords to be checked
11572 by a process that is not running as root.
11573
11574 The saslauthd support is not included in Exim by default. You need to specify
11575 the location of the saslauthd daemon's socket in &_Local/Makefile_& before
11576 building Exim. For example:
11577 .code
11578 CYRUS_SASLAUTHD_SOCKET=/var/state/saslauthd/mux
11579 .endd
11580 You do not need to install the full Cyrus software suite in order to use
11581 the saslauthd daemon. You can compile and install just the daemon alone
11582 from the Cyrus SASL library.
11583
11584 Up to four arguments can be supplied to the &%saslauthd%& condition, but only
11585 two are mandatory. For example:
11586 .code
11587 server_condition = ${if saslauthd{{$auth1}{$auth2}}}
11588 .endd
11589 The service and the realm are optional (which is why the arguments are enclosed
11590 in their own set of braces). For details of the meaning of the service and
11591 realm, and how to run the daemon, consult the Cyrus documentation.
11592 .endlist vlist
11593
11594
11595
11596 .section "Combining expansion conditions" "SECID84"
11597 .cindex "expansion" "combining conditions"
11598 Several conditions can be tested at once by combining them using the &%and%&
11599 and &%or%& combination conditions. Note that &%and%& and &%or%& are complete
11600 conditions on their own, and precede their lists of sub-conditions. Each
11601 sub-condition must be enclosed in braces within the overall braces that contain
11602 the list. No repetition of &%if%& is used.
11603
11604
11605 .vlist
11606 .vitem &*or&~{{*&<&'cond1'&>&*}{*&<&'cond2'&>&*}...}*&
11607 .cindex "&""or""& expansion condition"
11608 .cindex "expansion" "&""or""& of conditions"
11609 The sub-conditions are evaluated from left to right. The condition is true if
11610 any one of the sub-conditions is true.
11611 For example,
11612 .code
11613 ${if or {{eq{$local_part}{spqr}}{eq{$domain}{testing.com}}}...
11614 .endd
11615 When a true sub-condition is found, the following ones are parsed but not
11616 evaluated. If there are several &"match"& sub-conditions the values of the
11617 numeric variables afterwards are taken from the first one that succeeds.
11618
11619 .vitem &*and&~{{*&<&'cond1'&>&*}{*&<&'cond2'&>&*}...}*&
11620 .cindex "&""and""& expansion condition"
11621 .cindex "expansion" "&""and""& of conditions"
11622 The sub-conditions are evaluated from left to right. The condition is true if
11623 all of the sub-conditions are true. If there are several &"match"&
11624 sub-conditions, the values of the numeric variables afterwards are taken from
11625 the last one. When a false sub-condition is found, the following ones are
11626 parsed but not evaluated.
11627 .endlist
11628 .ecindex IIDexpcond
11629
11630
11631
11632
11633 .section "Expansion variables" "SECTexpvar"
11634 .cindex "expansion" "variables, list of"
11635 This section contains an alphabetical list of all the expansion variables. Some
11636 of them are available only when Exim is compiled with specific options such as
11637 support for TLS or the content scanning extension.
11638
11639 .vlist
11640 .vitem "&$0$&, &$1$&, etc"
11641 .cindex "numerical variables (&$1$& &$2$& etc)"
11642 When a &%match%& expansion condition succeeds, these variables contain the
11643 captured substrings identified by the regular expression during subsequent
11644 processing of the success string of the containing &%if%& expansion item.
11645 In the expansion condition case
11646 they do not retain their values afterwards; in fact, their previous
11647 values are restored at the end of processing an &%if%& item. The numerical
11648 variables may also be set externally by some other matching process which
11649 precedes the expansion of the string. For example, the commands available in
11650 Exim filter files include an &%if%& command with its own regular expression
11651 matching condition.
11652
11653 .vitem "&$acl_arg1$&, &$acl_arg2$&, etc"
11654 Within an acl condition, expansion condition or expansion item
11655 any arguments are copied to these variables,
11656 any unused variables being made empty.
11657
11658 .vitem "&$acl_c...$&"
11659 Values can be placed in these variables by the &%set%& modifier in an ACL. They
11660 can be given any name that starts with &$acl_c$& and is at least six characters
11661 long, but the sixth character must be either a digit or an underscore. For
11662 example: &$acl_c5$&, &$acl_c_mycount$&. The values of the &$acl_c...$&
11663 variables persist throughout the lifetime of an SMTP connection. They can be
11664 used to pass information between ACLs and between different invocations of the
11665 same ACL. When a message is received, the values of these variables are saved
11666 with the message, and can be accessed by filters, routers, and transports
11667 during subsequent delivery.
11668
11669 .vitem "&$acl_m...$&"
11670 These variables are like the &$acl_c...$& variables, except that their values
11671 are reset after a message has been received. Thus, if several messages are
11672 received in one SMTP connection, &$acl_m...$& values are not passed on from one
11673 message to the next, as &$acl_c...$& values are. The &$acl_m...$& variables are
11674 also reset by MAIL, RSET, EHLO, HELO, and after starting a TLS session. When a
11675 message is received, the values of these variables are saved with the message,
11676 and can be accessed by filters, routers, and transports during subsequent
11677 delivery.
11678
11679 .vitem &$acl_narg$&
11680 Within an acl condition, expansion condition or expansion item
11681 this variable has the number of arguments.
11682
11683 .vitem &$acl_verify_message$&
11684 .vindex "&$acl_verify_message$&"
11685 After an address verification has failed, this variable contains the failure
11686 message. It retains its value for use in subsequent modifiers. The message can
11687 be preserved by coding like this:
11688 .code
11689 warn !verify = sender
11690      set acl_m0 = $acl_verify_message
11691 .endd
11692 You can use &$acl_verify_message$& during the expansion of the &%message%& or
11693 &%log_message%& modifiers, to include information about the verification
11694 failure.
11695
11696 .vitem &$address_data$&
11697 .vindex "&$address_data$&"
11698 This variable is set by means of the &%address_data%& option in routers. The
11699 value then remains with the address while it is processed by subsequent routers
11700 and eventually a transport. If the transport is handling multiple addresses,
11701 the value from the first address is used. See chapter &<<CHAProutergeneric>>&
11702 for more details. &*Note*&: The contents of &$address_data$& are visible in
11703 user filter files.
11704
11705 If &$address_data$& is set when the routers are called from an ACL to verify
11706 a recipient address, the final value is still in the variable for subsequent
11707 conditions and modifiers of the ACL statement. If routing the address caused it
11708 to be redirected to just one address, the child address is also routed as part
11709 of the verification, and in this case the final value of &$address_data$& is
11710 from the child's routing.
11711
11712 If &$address_data$& is set when the routers are called from an ACL to verify a
11713 sender address, the final value is also preserved, but this time in
11714 &$sender_address_data$&, to distinguish it from data from a recipient
11715 address.
11716
11717 In both cases (recipient and sender verification), the value does not persist
11718 after the end of the current ACL statement. If you want to preserve
11719 these values for longer, you can save them in ACL variables.
11720
11721 .vitem &$address_file$&
11722 .vindex "&$address_file$&"
11723 When, as a result of aliasing, forwarding, or filtering, a message is directed
11724 to a specific file, this variable holds the name of the file when the transport
11725 is running. At other times, the variable is empty. For example, using the
11726 default configuration, if user &%r2d2%& has a &_.forward_& file containing
11727 .code
11728 /home/r2d2/savemail
11729 .endd
11730 then when the &(address_file)& transport is running, &$address_file$&
11731 contains the text string &`/home/r2d2/savemail`&.
11732 .cindex "Sieve filter" "value of &$address_file$&"
11733 For Sieve filters, the value may be &"inbox"& or a relative folder name. It is
11734 then up to the transport configuration to generate an appropriate absolute path
11735 to the relevant file.
11736
11737 .vitem &$address_pipe$&
11738 .vindex "&$address_pipe$&"
11739 When, as a result of aliasing or forwarding, a message is directed to a pipe,
11740 this variable holds the pipe command when the transport is running.
11741
11742 .vitem "&$auth1$& &-- &$auth3$&"
11743 .vindex "&$auth1$&, &$auth2$&, etc"
11744 These variables are used in SMTP authenticators (see chapters
11745 &<<CHAPplaintext>>&&--&<<CHAPtlsauth>>&). Elsewhere, they are empty.
11746
11747 .vitem &$authenticated_id$&
11748 .cindex "authentication" "id"
11749 .vindex "&$authenticated_id$&"
11750 When a server successfully authenticates a client it may be configured to
11751 preserve some of the authentication information in the variable
11752 &$authenticated_id$& (see chapter &<<CHAPSMTPAUTH>>&). For example, a
11753 user/password authenticator configuration might preserve the user name for use
11754 in the routers. Note that this is not the same information that is saved in
11755 &$sender_host_authenticated$&.
11756
11757 When a message is submitted locally (that is, not over a TCP connection)
11758 the value of &$authenticated_id$& is normally the login name of the calling
11759 process. However, a trusted user can override this by means of the &%-oMai%&
11760 command line option.
11761 This second case also sets up information used by the
11762 &$authresults$& expansion item.
11763
11764 .vitem &$authenticated_fail_id$&
11765 .cindex "authentication" "fail" "id"
11766 .vindex "&$authenticated_fail_id$&"
11767 When an authentication attempt fails, the variable &$authenticated_fail_id$&
11768 will contain the failed authentication id. If more than one authentication
11769 id is attempted, it will contain only the last one. The variable is
11770 available for processing in the ACL's, generally the quit or notquit ACL.
11771 A message to a local recipient could still be accepted without requiring
11772 authentication, which means this variable could also be visible in all of
11773 the ACL's as well.
11774
11775
11776 .vitem &$authenticated_sender$&
11777 .cindex "sender" "authenticated"
11778 .cindex "authentication" "sender"
11779 .cindex "AUTH" "on MAIL command"
11780 .vindex "&$authenticated_sender$&"
11781 When acting as a server, Exim takes note of the AUTH= parameter on an incoming
11782 SMTP MAIL command if it believes the sender is sufficiently trusted, as
11783 described in section &<<SECTauthparamail>>&. Unless the data is the string
11784 &"<>"&, it is set as the authenticated sender of the message, and the value is
11785 available during delivery in the &$authenticated_sender$& variable. If the
11786 sender is not trusted, Exim accepts the syntax of AUTH=, but ignores the data.
11787
11788 .vindex "&$qualify_domain$&"
11789 When a message is submitted locally (that is, not over a TCP connection), the
11790 value of &$authenticated_sender$& is an address constructed from the login
11791 name of the calling process and &$qualify_domain$&, except that a trusted user
11792 can override this by means of the &%-oMas%& command line option.
11793
11794
11795 .vitem &$authentication_failed$&
11796 .cindex "authentication" "failure"
11797 .vindex "&$authentication_failed$&"
11798 This variable is set to &"1"& in an Exim server if a client issues an AUTH
11799 command that does not succeed. Otherwise it is set to &"0"&. This makes it
11800 possible to distinguish between &"did not try to authenticate"&
11801 (&$sender_host_authenticated$& is empty and &$authentication_failed$& is set to
11802 &"0"&) and &"tried to authenticate but failed"& (&$sender_host_authenticated$&
11803 is empty and &$authentication_failed$& is set to &"1"&). Failure includes any
11804 negative response to an AUTH command, including (for example) an attempt to use
11805 an undefined mechanism.
11806
11807 .vitem &$av_failed$&
11808 .cindex "content scanning" "AV scanner failure"
11809 This variable is available when Exim is compiled with the content-scanning
11810 extension. It is set to &"0"& by default, but will be set to &"1"& if any
11811 problem occurs with the virus scanner (specified by &%av_scanner%&) during
11812 the ACL malware condition.
11813
11814 .vitem &$body_linecount$&
11815 .cindex "message body" "line count"
11816 .cindex "body of message" "line count"
11817 .vindex "&$body_linecount$&"
11818 When a message is being received or delivered, this variable contains the
11819 number of lines in the message's body. See also &$message_linecount$&.
11820
11821 .vitem &$body_zerocount$&
11822 .cindex "message body" "binary zero count"
11823 .cindex "body of message" "binary zero count"
11824 .cindex "binary zero" "in message body"
11825 .vindex "&$body_zerocount$&"
11826 When a message is being received or delivered, this variable contains the
11827 number of binary zero bytes (ASCII NULs) in the message's body.
11828
11829 .vitem &$bounce_recipient$&
11830 .vindex "&$bounce_recipient$&"
11831 This is set to the recipient address of a bounce message while Exim is creating
11832 it. It is useful if a customized bounce message text file is in use (see
11833 chapter &<<CHAPemsgcust>>&).
11834
11835 .vitem &$bounce_return_size_limit$&
11836 .vindex "&$bounce_return_size_limit$&"
11837 This contains the value set in the &%bounce_return_size_limit%& option, rounded
11838 up to a multiple of 1000. It is useful when a customized error message text
11839 file is in use (see chapter &<<CHAPemsgcust>>&).
11840
11841 .vitem &$caller_gid$&
11842 .cindex "gid (group id)" "caller"
11843 .vindex "&$caller_gid$&"
11844 The real group id under which the process that called Exim was running. This is
11845 not the same as the group id of the originator of a message (see
11846 &$originator_gid$&). If Exim re-execs itself, this variable in the new
11847 incarnation normally contains the Exim gid.
11848
11849 .vitem &$caller_uid$&
11850 .cindex "uid (user id)" "caller"
11851 .vindex "&$caller_uid$&"
11852 The real user id under which the process that called Exim was running. This is
11853 not the same as the user id of the originator of a message (see
11854 &$originator_uid$&). If Exim re-execs itself, this variable in the new
11855 incarnation normally contains the Exim uid.
11856
11857 .vitem &$callout_address$&
11858 .vindex "&$callout_address$&"
11859 After a callout for verification, spamd or malware daemon service, the
11860 address that was connected to.
11861
11862 .vitem &$compile_number$&
11863 .vindex "&$compile_number$&"
11864 The building process for Exim keeps a count of the number
11865 of times it has been compiled. This serves to distinguish different
11866 compilations of the same version of the program.
11867
11868 .vitem &$config_dir$&
11869 .vindex "&$config_dir$&"
11870 The directory name of the main configuration file. That is, the content of
11871 &$config_file$& with the last component stripped. The value does not
11872 contain the trailing slash. If &$config_file$& does not contain a slash,
11873 &$config_dir$& is ".".
11874
11875 .vitem &$config_file$&
11876 .vindex "&$config_file$&"
11877 The name of the main configuration file Exim is using.
11878
11879 .vitem &$dkim_verify_status$&
11880 Results of DKIM verification.
11881 For details see section &<<SECDKIMVFY>>&.
11882
11883 .vitem &$dkim_cur_signer$& &&&
11884        &$dkim_verify_reason$& &&&
11885        &$dkim_domain$& &&&
11886        &$dkim_identity$& &&&
11887        &$dkim_selector$& &&&
11888        &$dkim_algo$& &&&
11889        &$dkim_canon_body$& &&&
11890        &$dkim_canon_headers$& &&&
11891        &$dkim_copiedheaders$& &&&
11892        &$dkim_bodylength$& &&&
11893        &$dkim_created$& &&&
11894        &$dkim_expires$& &&&
11895        &$dkim_headernames$& &&&
11896        &$dkim_key_testing$& &&&
11897        &$dkim_key_nosubdomains$& &&&
11898        &$dkim_key_srvtype$& &&&
11899        &$dkim_key_granularity$& &&&
11900        &$dkim_key_notes$& &&&
11901        &$dkim_key_length$&
11902 These variables are only available within the DKIM ACL.
11903 For details see section &<<SECDKIMVFY>>&.
11904
11905 .vitem &$dkim_signers$&
11906 .vindex &$dkim_signers$&
11907 When a message has been received this variable contains
11908 a colon-separated list of signer domains and identities for the message.
11909 For details see section &<<SECDKIMVFY>>&.
11910
11911 .vitem &$dnslist_domain$& &&&
11912        &$dnslist_matched$& &&&
11913        &$dnslist_text$& &&&
11914        &$dnslist_value$&
11915 .vindex "&$dnslist_domain$&"
11916 .vindex "&$dnslist_matched$&"
11917 .vindex "&$dnslist_text$&"
11918 .vindex "&$dnslist_value$&"
11919 .cindex "black list (DNS)"
11920 When a DNS (black) list lookup succeeds, these variables are set to contain
11921 the following data from the lookup: the list's domain name, the key that was
11922 looked up, the contents of any associated TXT record, and the value from the
11923 main A record. See section &<<SECID204>>& for more details.
11924
11925 .vitem &$domain$&
11926 .vindex "&$domain$&"
11927 When an address is being routed, or delivered on its own, this variable
11928 contains the domain. Uppercase letters in the domain are converted into lower
11929 case for &$domain$&.
11930
11931 Global address rewriting happens when a message is received, so the value of
11932 &$domain$& during routing and delivery is the value after rewriting. &$domain$&
11933 is set during user filtering, but not during system filtering, because a
11934 message may have many recipients and the system filter is called just once.
11935
11936 When more than one address is being delivered at once (for example, several
11937 RCPT commands in one SMTP delivery), &$domain$& is set only if they all
11938 have the same domain. Transports can be restricted to handling only one domain
11939 at a time if the value of &$domain$& is required at transport time &-- this is
11940 the default for local transports. For further details of the environment in
11941 which local transports are run, see chapter &<<CHAPenvironment>>&.
11942
11943 .oindex "&%delay_warning_condition%&"
11944 At the end of a delivery, if all deferred addresses have the same domain, it is
11945 set in &$domain$& during the expansion of &%delay_warning_condition%&.
11946
11947 The &$domain$& variable is also used in some other circumstances:
11948
11949 .ilist
11950 When an ACL is running for a RCPT command, &$domain$& contains the domain of
11951 the recipient address. The domain of the &'sender'& address is in
11952 &$sender_address_domain$& at both MAIL time and at RCPT time. &$domain$& is not
11953 normally set during the running of the MAIL ACL. However, if the sender address
11954 is verified with a callout during the MAIL ACL, the sender domain is placed in
11955 &$domain$& during the expansions of &%hosts%&, &%interface%&, and &%port%& in
11956 the &(smtp)& transport.
11957
11958 .next
11959 When a rewrite item is being processed (see chapter &<<CHAPrewrite>>&),
11960 &$domain$& contains the domain portion of the address that is being rewritten;
11961 it can be used in the expansion of the replacement address, for example, to
11962 rewrite domains by file lookup.
11963
11964 .next
11965 With one important exception, whenever a domain list is being scanned,
11966 &$domain$& contains the subject domain. &*Exception*&: When a domain list in
11967 a &%sender_domains%& condition in an ACL is being processed, the subject domain
11968 is in &$sender_address_domain$& and not in &$domain$&. It works this way so
11969 that, in a RCPT ACL, the sender domain list can be dependent on the
11970 recipient domain (which is what is in &$domain$& at this time).
11971
11972 .next
11973 .cindex "ETRN" "value of &$domain$&"
11974 .oindex "&%smtp_etrn_command%&"
11975 When the &%smtp_etrn_command%& option is being expanded, &$domain$& contains
11976 the complete argument of the ETRN command (see section &<<SECTETRN>>&).
11977 .endlist
11978
11979
11980 .vitem &$domain_data$&
11981 .vindex "&$domain_data$&"
11982 When the &%domains%& option on a router matches a domain by
11983 means of a lookup, the data read by the lookup is available during the running
11984 of the router as &$domain_data$&. In addition, if the driver routes the
11985 address to a transport, the value is available in that transport. If the
11986 transport is handling multiple addresses, the value from the first address is
11987 used.
11988
11989 &$domain_data$& is also set when the &%domains%& condition in an ACL matches a
11990 domain by means of a lookup. The data read by the lookup is available during
11991 the rest of the ACL statement. In all other situations, this variable expands
11992 to nothing.
11993
11994 .vitem &$exim_gid$&
11995 .vindex "&$exim_gid$&"
11996 This variable contains the numerical value of the Exim group id.
11997
11998 .vitem &$exim_path$&
11999 .vindex "&$exim_path$&"
12000 This variable contains the path to the Exim binary.
12001
12002 .vitem &$exim_uid$&
12003 .vindex "&$exim_uid$&"
12004 This variable contains the numerical value of the Exim user id.
12005
12006 .vitem &$exim_version$&
12007 .vindex "&$exim_version$&"
12008 This variable contains the version string of the Exim build.
12009 The first character is a major version number, currently 4.
12010 Then after a dot, the next group of digits is a minor version number.
12011 There may be other characters following the minor version.
12012
12013 .vitem &$header_$&<&'name'&>
12014 This is not strictly an expansion variable. It is expansion syntax for
12015 inserting the message header line with the given name. Note that the name must
12016 be terminated by colon or white space, because it may contain a wide variety of
12017 characters. Note also that braces must &'not'& be used.
12018 See the full description in section &<<SECTexpansionitems>>& above.
12019
12020 .vitem &$headers_added$&
12021 .vindex "&$headers_added$&"
12022 Within an ACL this variable contains the headers added so far by
12023 the ACL modifier add_header (section &<<SECTaddheadacl>>&).
12024 The headers are a newline-separated list.
12025
12026 .vitem &$home$&
12027 .vindex "&$home$&"
12028 When the &%check_local_user%& option is set for a router, the user's home
12029 directory is placed in &$home$& when the check succeeds. In particular, this
12030 means it is set during the running of users' filter files. A router may also
12031 explicitly set a home directory for use by a transport; this can be overridden
12032 by a setting on the transport itself.
12033
12034 When running a filter test via the &%-bf%& option, &$home$& is set to the value
12035 of the environment variable HOME, which is subject to the
12036 &%keep_environment%& and &%add_environment%& main config options.
12037
12038 .vitem &$host$&
12039 .vindex "&$host$&"
12040 If a router assigns an address to a transport (any transport), and passes a
12041 list of hosts with the address, the value of &$host$& when the transport starts
12042 to run is the name of the first host on the list. Note that this applies both
12043 to local and remote transports.
12044
12045 .cindex "transport" "filter"
12046 .cindex "filter" "transport filter"
12047 For the &(smtp)& transport, if there is more than one host, the value of
12048 &$host$& changes as the transport works its way through the list. In
12049 particular, when the &(smtp)& transport is expanding its options for encryption
12050 using TLS, or for specifying a transport filter (see chapter
12051 &<<CHAPtransportgeneric>>&), &$host$& contains the name of the host to which it
12052 is connected.
12053
12054 When used in the client part of an authenticator configuration (see chapter
12055 &<<CHAPSMTPAUTH>>&), &$host$& contains the name of the server to which the
12056 client is connected.
12057
12058
12059 .vitem &$host_address$&
12060 .vindex "&$host_address$&"
12061 This variable is set to the remote host's IP address whenever &$host$& is set
12062 for a remote connection. It is also set to the IP address that is being checked
12063 when the &%ignore_target_hosts%& option is being processed.
12064
12065 .vitem &$host_data$&
12066 .vindex "&$host_data$&"
12067 If a &%hosts%& condition in an ACL is satisfied by means of a lookup, the
12068 result of the lookup is made available in the &$host_data$& variable. This
12069 allows you, for example, to do things like this:
12070 .code
12071 deny  hosts = net-lsearch;/some/file
12072 message = $host_data
12073 .endd
12074 .vitem &$host_lookup_deferred$&
12075 .cindex "host name" "lookup, failure of"
12076 .vindex "&$host_lookup_deferred$&"
12077 This variable normally contains &"0"&, as does &$host_lookup_failed$&. When a
12078 message comes from a remote host and there is an attempt to look up the host's
12079 name from its IP address, and the attempt is not successful, one of these
12080 variables is set to &"1"&.
12081
12082 .ilist
12083 If the lookup receives a definite negative response (for example, a DNS lookup
12084 succeeded, but no records were found), &$host_lookup_failed$& is set to &"1"&.
12085
12086 .next
12087 If there is any kind of problem during the lookup, such that Exim cannot
12088 tell whether or not the host name is defined (for example, a timeout for a DNS
12089 lookup), &$host_lookup_deferred$& is set to &"1"&.
12090 .endlist ilist
12091
12092 Looking up a host's name from its IP address consists of more than just a
12093 single reverse lookup. Exim checks that a forward lookup of at least one of the
12094 names it receives from a reverse lookup yields the original IP address. If this
12095 is not the case, Exim does not accept the looked up name(s), and
12096 &$host_lookup_failed$& is set to &"1"&. Thus, being able to find a name from an
12097 IP address (for example, the existence of a PTR record in the DNS) is not
12098 sufficient on its own for the success of a host name lookup. If the reverse
12099 lookup succeeds, but there is a lookup problem such as a timeout when checking
12100 the result, the name is not accepted, and &$host_lookup_deferred$& is set to
12101 &"1"&. See also &$sender_host_name$&.
12102
12103 .cindex authentication "expansion item"
12104 Performing these checks sets up information used by the
12105 &$authresults$& expansion item.
12106
12107
12108 .vitem &$host_lookup_failed$&
12109 .vindex "&$host_lookup_failed$&"
12110 See &$host_lookup_deferred$&.
12111
12112 .vitem &$host_port$&
12113 .vindex "&$host_port$&"
12114 This variable is set to the remote host's TCP port whenever &$host$& is set
12115 for an outbound connection.
12116
12117 .vitem &$initial_cwd$&
12118 .vindex "&$initial_cwd$&
12119 This variable contains the full path name of the initial working
12120 directory of the current Exim process. This may differ from the current
12121 working directory, as Exim changes this to "/" during early startup, and
12122 to &$spool_directory$& later.
12123
12124 .vitem &$inode$&
12125 .vindex "&$inode$&"
12126 The only time this variable is set is while expanding the &%directory_file%&
12127 option in the &(appendfile)& transport. The variable contains the inode number
12128 of the temporary file which is about to be renamed. It can be used to construct
12129 a unique name for the file.
12130
12131 .vitem &$interface_address$&
12132 .vindex "&$interface_address$&"
12133 This is an obsolete name for &$received_ip_address$&.
12134
12135 .vitem &$interface_port$&
12136 .vindex "&$interface_port$&"
12137 This is an obsolete name for &$received_port$&.
12138
12139 .vitem &$item$&
12140 .vindex "&$item$&"
12141 This variable is used during the expansion of &*forall*& and &*forany*&
12142 conditions (see section &<<SECTexpcond>>&), and &*filter*&, &*map*&, and
12143 &*reduce*& items (see section &<<SECTexpcond>>&). In other circumstances, it is
12144 empty.
12145
12146 .vitem &$ldap_dn$&
12147 .vindex "&$ldap_dn$&"
12148 This variable, which is available only when Exim is compiled with LDAP support,
12149 contains the DN from the last entry in the most recently successful LDAP
12150 lookup.
12151
12152 .vitem &$load_average$&
12153 .vindex "&$load_average$&"
12154 This variable contains the system load average, multiplied by 1000 so that it
12155 is an integer. For example, if the load average is 0.21, the value of the
12156 variable is 210. The value is recomputed every time the variable is referenced.
12157
12158 .vitem &$local_part$&
12159 .vindex "&$local_part$&"
12160 When an address is being routed, or delivered on its own, this
12161 variable contains the local part. When a number of addresses are being
12162 delivered together (for example, multiple RCPT commands in an SMTP
12163 session), &$local_part$& is not set.
12164
12165 Global address rewriting happens when a message is received, so the value of
12166 &$local_part$& during routing and delivery is the value after rewriting.
12167 &$local_part$& is set during user filtering, but not during system filtering,
12168 because a message may have many recipients and the system filter is called just
12169 once.
12170
12171 .vindex "&$local_part_prefix$&"
12172 .vindex "&$local_part_suffix$&"
12173 .cindex affix variables
12174 If a local part prefix or suffix has been recognized, it is not included in the
12175 value of &$local_part$& during routing and subsequent delivery. The values of
12176 any prefix or suffix are in &$local_part_prefix$& and
12177 &$local_part_suffix$&, respectively.
12178
12179 When a message is being delivered to a file, pipe, or autoreply transport as a
12180 result of aliasing or forwarding, &$local_part$& is set to the local part of
12181 the parent address, not to the file name or command (see &$address_file$& and
12182 &$address_pipe$&).
12183
12184 When an ACL is running for a RCPT command, &$local_part$& contains the
12185 local part of the recipient address.
12186
12187 When a rewrite item is being processed (see chapter &<<CHAPrewrite>>&),
12188 &$local_part$& contains the local part of the address that is being rewritten;
12189 it can be used in the expansion of the replacement address, for example.
12190
12191 In all cases, all quoting is removed from the local part. For example, for both
12192 the addresses
12193 .code
12194 "abc:xyz"@test.example
12195 abc\:xyz@test.example
12196 .endd
12197 the value of &$local_part$& is
12198 .code
12199 abc:xyz
12200 .endd
12201 If you use &$local_part$& to create another address, you should always wrap it
12202 inside a quoting operator. For example, in a &(redirect)& router you could
12203 have:
12204 .code
12205 data = ${quote_local_part:$local_part}@new.domain.example
12206 .endd
12207 &*Note*&: The value of &$local_part$& is normally lower cased. If you want
12208 to process local parts in a case-dependent manner in a router, you can set the
12209 &%caseful_local_part%& option (see chapter &<<CHAProutergeneric>>&).
12210
12211 .vitem &$local_part_data$&
12212 .vindex "&$local_part_data$&"
12213 When the &%local_parts%& option on a router matches a local part by means of a
12214 lookup, the data read by the lookup is available during the running of the
12215 router as &$local_part_data$&. In addition, if the driver routes the address
12216 to a transport, the value is available in that transport. If the transport is
12217 handling multiple addresses, the value from the first address is used.
12218
12219 &$local_part_data$& is also set when the &%local_parts%& condition in an ACL
12220 matches a local part by means of a lookup. The data read by the lookup is
12221 available during the rest of the ACL statement. In all other situations, this
12222 variable expands to nothing.
12223
12224 .vitem &$local_part_prefix$&
12225 .vindex "&$local_part_prefix$&"
12226 .cindex affix variables
12227 When an address is being routed or delivered, and a
12228 specific prefix for the local part was recognized, it is available in this
12229 variable, having been removed from &$local_part$&.
12230
12231 .vitem &$local_part_suffix$&
12232 .vindex "&$local_part_suffix$&"
12233 When an address is being routed or delivered, and a
12234 specific suffix for the local part was recognized, it is available in this
12235 variable, having been removed from &$local_part$&.
12236
12237 .vitem &$local_scan_data$&
12238 .vindex "&$local_scan_data$&"
12239 This variable contains the text returned by the &[local_scan()]& function when
12240 a message is received. See chapter &<<CHAPlocalscan>>& for more details.
12241
12242 .vitem &$local_user_gid$&
12243 .vindex "&$local_user_gid$&"
12244 See &$local_user_uid$&.
12245
12246 .vitem &$local_user_uid$&
12247 .vindex "&$local_user_uid$&"
12248 This variable and &$local_user_gid$& are set to the uid and gid after the
12249 &%check_local_user%& router precondition succeeds. This means that their values
12250 are available for the remaining preconditions (&%senders%&, &%require_files%&,
12251 and &%condition%&), for the &%address_data%& expansion, and for any
12252 router-specific expansions. At all other times, the values in these variables
12253 are &`(uid_t)(-1)`& and &`(gid_t)(-1)`&, respectively.
12254
12255 .vitem &$localhost_number$&
12256 .vindex "&$localhost_number$&"
12257 This contains the expanded value of the
12258 &%localhost_number%& option. The expansion happens after the main options have
12259 been read.
12260
12261 .vitem &$log_inodes$&
12262 .vindex "&$log_inodes$&"
12263 The number of free inodes in the disk partition where Exim's
12264 log files are being written. The value is recalculated whenever the variable is
12265 referenced. If the relevant file system does not have the concept of inodes,
12266 the value of is -1. See also the &%check_log_inodes%& option.
12267
12268 .vitem &$log_space$&
12269 .vindex "&$log_space$&"
12270 The amount of free space (as a number of kilobytes) in the disk
12271 partition where Exim's log files are being written. The value is recalculated
12272 whenever the variable is referenced. If the operating system does not have the
12273 ability to find the amount of free space (only true for experimental systems),
12274 the space value is -1. See also the &%check_log_space%& option.
12275
12276
12277 .vitem &$lookup_dnssec_authenticated$&
12278 .vindex "&$lookup_dnssec_authenticated$&"
12279 This variable is set after a DNS lookup done by
12280 a dnsdb lookup expansion, dnslookup router or smtp transport.
12281 .cindex "DNS" "DNSSEC"
12282 It will be empty if &(DNSSEC)& was not requested,
12283 &"no"& if the result was not labelled as authenticated data
12284 and &"yes"& if it was.
12285 Results that are labelled as authoritative answer that match
12286 the &%dns_trust_aa%& configuration variable count also
12287 as authenticated data.
12288
12289 .vitem &$mailstore_basename$&
12290 .vindex "&$mailstore_basename$&"
12291 This variable is set only when doing deliveries in &"mailstore"& format in the
12292 &(appendfile)& transport. During the expansion of the &%mailstore_prefix%&,
12293 &%mailstore_suffix%&, &%message_prefix%&, and &%message_suffix%& options, it
12294 contains the basename of the files that are being written, that is, the name
12295 without the &".tmp"&, &".env"&, or &".msg"& suffix. At all other times, this
12296 variable is empty.
12297
12298 .vitem &$malware_name$&
12299 .vindex "&$malware_name$&"
12300 This variable is available when Exim is compiled with the
12301 content-scanning extension. It is set to the name of the virus that was found
12302 when the ACL &%malware%& condition is true (see section &<<SECTscanvirus>>&).
12303
12304 .vitem &$max_received_linelength$&
12305 .vindex "&$max_received_linelength$&"
12306 .cindex "maximum" "line length"
12307 .cindex "line length" "maximum"
12308 This variable contains the number of bytes in the longest line that was
12309 received as part of the message, not counting the line termination
12310 character(s).
12311 It is not valid if the &%spool_files_wireformat%& option is used.
12312
12313 .vitem &$message_age$&
12314 .cindex "message" "age of"
12315 .vindex "&$message_age$&"
12316 This variable is set at the start of a delivery attempt to contain the number
12317 of seconds since the message was received. It does not change during a single
12318 delivery attempt.
12319
12320 .vitem &$message_body$&
12321 .cindex "body of message" "expansion variable"
12322 .cindex "message body" "in expansion"
12323 .cindex "binary zero" "in message body"
12324 .vindex "&$message_body$&"
12325 .oindex "&%message_body_visible%&"
12326 This variable contains the initial portion of a message's body while it is
12327 being delivered, and is intended mainly for use in filter files. The maximum
12328 number of characters of the body that are put into the variable is set by the
12329 &%message_body_visible%& configuration option; the default is 500.
12330
12331 .oindex "&%message_body_newlines%&"
12332 By default, newlines are converted into spaces in &$message_body$&, to make it
12333 easier to search for phrases that might be split over a line break. However,
12334 this can be disabled by setting &%message_body_newlines%& to be true. Binary
12335 zeros are always converted into spaces.
12336
12337 .vitem &$message_body_end$&
12338 .cindex "body of message" "expansion variable"
12339 .cindex "message body" "in expansion"
12340 .vindex "&$message_body_end$&"
12341 This variable contains the final portion of a message's
12342 body while it is being delivered. The format and maximum size are as for
12343 &$message_body$&.
12344
12345 .vitem &$message_body_size$&
12346 .cindex "body of message" "size"
12347 .cindex "message body" "size"
12348 .vindex "&$message_body_size$&"
12349 When a message is being delivered, this variable contains the size of the body
12350 in bytes. The count starts from the character after the blank line that
12351 separates the body from the header. Newlines are included in the count. See
12352 also &$message_size$&, &$body_linecount$&, and &$body_zerocount$&.
12353
12354 If the spool file is wireformat
12355 (see the &%spool_files_wireformat%& main option)
12356 the CRLF line-terminators are included in the count.
12357
12358 .vitem &$message_exim_id$&
12359 .vindex "&$message_exim_id$&"
12360 When a message is being received or delivered, this variable contains the
12361 unique message id that is generated and used by Exim to identify the message.
12362 An id is not created for a message until after its header has been successfully
12363 received. &*Note*&: This is &'not'& the contents of the &'Message-ID:'& header
12364 line; it is the local id that Exim assigns to the message, for example:
12365 &`1BXTIK-0001yO-VA`&.
12366
12367 .vitem &$message_headers$&
12368 .vindex &$message_headers$&
12369 This variable contains a concatenation of all the header lines when a message
12370 is being processed, except for lines added by routers or transports. The header
12371 lines are separated by newline characters. Their contents are decoded in the
12372 same way as a header line that is inserted by &%bheader%&.
12373
12374 .vitem &$message_headers_raw$&
12375 .vindex &$message_headers_raw$&
12376 This variable is like &$message_headers$& except that no processing of the
12377 contents of header lines is done.
12378
12379 .vitem &$message_id$&
12380 This is an old name for &$message_exim_id$&. It is now deprecated.
12381
12382 .vitem &$message_linecount$&
12383 .vindex "&$message_linecount$&"
12384 This variable contains the total number of lines in the header and body of the
12385 message. Compare &$body_linecount$&, which is the count for the body only.
12386 During the DATA and content-scanning ACLs, &$message_linecount$& contains the
12387 number of lines received. Before delivery happens (that is, before filters,
12388 routers, and transports run) the count is increased to include the
12389 &'Received:'& header line that Exim standardly adds, and also any other header
12390 lines that are added by ACLs. The blank line that separates the message header
12391 from the body is not counted.
12392
12393 As with the special case of &$message_size$&, during the expansion of the
12394 appendfile transport's maildir_tag option in maildir format, the value of
12395 &$message_linecount$& is the precise size of the number of newlines in the
12396 file that has been written (minus one for the blank line between the
12397 header and the body).
12398
12399 Here is an example of the use of this variable in a DATA ACL:
12400 .code
12401 deny message   = Too many lines in message header
12402      condition = \
12403       ${if <{250}{${eval:$message_linecount - $body_linecount}}}
12404 .endd
12405 In the MAIL and RCPT ACLs, the value is zero because at that stage the
12406 message has not yet been received.
12407
12408 This variable is not valid if the &%spool_files_wireformat%& option is used.
12409
12410 .vitem &$message_size$&
12411 .cindex "size" "of message"
12412 .cindex "message" "size"
12413 .vindex "&$message_size$&"
12414 When a message is being processed, this variable contains its size in bytes. In
12415 most cases, the size includes those headers that were received with the
12416 message, but not those (such as &'Envelope-to:'&) that are added to individual
12417 deliveries as they are written. However, there is one special case: during the
12418 expansion of the &%maildir_tag%& option in the &(appendfile)& transport while
12419 doing a delivery in maildir format, the value of &$message_size$& is the
12420 precise size of the file that has been written. See also
12421 &$message_body_size$&, &$body_linecount$&, and &$body_zerocount$&.
12422
12423 .cindex "RCPT" "value of &$message_size$&"
12424 While running a per message ACL (mail/rcpt/predata), &$message_size$&
12425 contains the size supplied on the MAIL command, or -1 if no size was given. The
12426 value may not, of course, be truthful.
12427
12428 .vitem &$mime_$&&'xxx'&
12429 A number of variables whose names start with &$mime$& are
12430 available when Exim is compiled with the content-scanning extension. For
12431 details, see section &<<SECTscanmimepart>>&.
12432
12433 .vitem "&$n0$& &-- &$n9$&"
12434 These variables are counters that can be incremented by means
12435 of the &%add%& command in filter files.
12436
12437 .vitem &$original_domain$&
12438 .vindex "&$domain$&"
12439 .vindex "&$original_domain$&"
12440 When a top-level address is being processed for delivery, this contains the
12441 same value as &$domain$&. However, if a &"child"& address (for example,
12442 generated by an alias, forward, or filter file) is being processed, this
12443 variable contains the domain of the original address (lower cased). This
12444 differs from &$parent_domain$& only when there is more than one level of
12445 aliasing or forwarding. When more than one address is being delivered in a
12446 single transport run, &$original_domain$& is not set.
12447
12448 If a new address is created by means of a &%deliver%& command in a system
12449 filter, it is set up with an artificial &"parent"& address. This has the local
12450 part &'system-filter'& and the default qualify domain.
12451
12452 .vitem &$original_local_part$&
12453 .vindex "&$local_part$&"
12454 .vindex "&$original_local_part$&"
12455 When a top-level address is being processed for delivery, this contains the
12456 same value as &$local_part$&, unless a prefix or suffix was removed from the
12457 local part, because &$original_local_part$& always contains the full local
12458 part. When a &"child"& address (for example, generated by an alias, forward, or
12459 filter file) is being processed, this variable contains the full local part of
12460 the original address.
12461
12462 If the router that did the redirection processed the local part
12463 case-insensitively, the value in &$original_local_part$& is in lower case.
12464 This variable differs from &$parent_local_part$& only when there is more than
12465 one level of aliasing or forwarding. When more than one address is being
12466 delivered in a single transport run, &$original_local_part$& is not set.
12467
12468 If a new address is created by means of a &%deliver%& command in a system
12469 filter, it is set up with an artificial &"parent"& address. This has the local
12470 part &'system-filter'& and the default qualify domain.
12471
12472 .vitem &$originator_gid$&
12473 .cindex "gid (group id)" "of originating user"
12474 .cindex "sender" "gid"
12475 .vindex "&$caller_gid$&"
12476 .vindex "&$originator_gid$&"
12477 This variable contains the value of &$caller_gid$& that was set when the
12478 message was received. For messages received via the command line, this is the
12479 gid of the sending user. For messages received by SMTP over TCP/IP, this is
12480 normally the gid of the Exim user.
12481
12482 .vitem &$originator_uid$&
12483 .cindex "uid (user id)" "of originating user"
12484 .cindex "sender" "uid"
12485 .vindex "&$caller_uid$&"
12486 .vindex "&$originator_uid$&"
12487 The value of &$caller_uid$& that was set when the message was received. For
12488 messages received via the command line, this is the uid of the sending user.
12489 For messages received by SMTP over TCP/IP, this is normally the uid of the Exim
12490 user.
12491
12492 .vitem &$parent_domain$&
12493 .vindex "&$parent_domain$&"
12494 This variable is similar to &$original_domain$& (see
12495 above), except that it refers to the immediately preceding parent address.
12496
12497 .vitem &$parent_local_part$&
12498 .vindex "&$parent_local_part$&"
12499 This variable is similar to &$original_local_part$&
12500 (see above), except that it refers to the immediately preceding parent address.
12501
12502 .vitem &$pid$&
12503 .cindex "pid (process id)" "of current process"
12504 .vindex "&$pid$&"
12505 This variable contains the current process id.
12506
12507 .vitem &$pipe_addresses$&
12508 .cindex "filter" "transport filter"
12509 .cindex "transport" "filter"
12510 .vindex "&$pipe_addresses$&"
12511 This is not an expansion variable, but is mentioned here because the string
12512 &`$pipe_addresses`& is handled specially in the command specification for the
12513 &(pipe)& transport (chapter &<<CHAPpipetransport>>&) and in transport filters
12514 (described under &%transport_filter%& in chapter &<<CHAPtransportgeneric>>&).
12515 It cannot be used in general expansion strings, and provokes an &"unknown
12516 variable"& error if encountered.
12517
12518 .vitem &$primary_hostname$&
12519 .vindex "&$primary_hostname$&"
12520 This variable contains the value set by &%primary_hostname%& in the
12521 configuration file, or read by the &[uname()]& function. If &[uname()]& returns
12522 a single-component name, Exim calls &[gethostbyname()]& (or
12523 &[getipnodebyname()]& where available) in an attempt to acquire a fully
12524 qualified host name. See also &$smtp_active_hostname$&.
12525
12526
12527 .vitem &$proxy_external_address$& &&&
12528        &$proxy_external_port$& &&&
12529        &$proxy_local_address$& &&&
12530        &$proxy_local_port$& &&&
12531        &$proxy_session$&
12532 These variables are only available when built with Proxy Protocol
12533 or SOCKS5 support.
12534 For details see chapter &<<SECTproxyInbound>>&.
12535
12536 .vitem &$prdr_requested$&
12537 .cindex "PRDR" "variable for"
12538 This variable is set to &"yes"& if PRDR was requested by the client for the
12539 current message, otherwise &"no"&.
12540
12541 .vitem &$prvscheck_address$&
12542 This variable is used in conjunction with the &%prvscheck%& expansion item,
12543 which is described in sections &<<SECTexpansionitems>>& and
12544 &<<SECTverifyPRVS>>&.
12545
12546 .vitem &$prvscheck_keynum$&
12547 This variable is used in conjunction with the &%prvscheck%& expansion item,
12548 which is described in sections &<<SECTexpansionitems>>& and
12549 &<<SECTverifyPRVS>>&.
12550
12551 .vitem &$prvscheck_result$&
12552 This variable is used in conjunction with the &%prvscheck%& expansion item,
12553 which is described in sections &<<SECTexpansionitems>>& and
12554 &<<SECTverifyPRVS>>&.
12555
12556 .vitem &$qualify_domain$&
12557 .vindex "&$qualify_domain$&"
12558 The value set for the &%qualify_domain%& option in the configuration file.
12559
12560 .vitem &$qualify_recipient$&
12561 .vindex "&$qualify_recipient$&"
12562 The value set for the &%qualify_recipient%& option in the configuration file,
12563 or if not set, the value of &$qualify_domain$&.
12564
12565 .vitem &$queue_name$&
12566 .vindex &$queue_name$&
12567 .cindex "named queues"
12568 .cindex queues named
12569 The name of the spool queue in use; empty for the default queue.
12570
12571 .vitem &$rcpt_count$&
12572 .vindex "&$rcpt_count$&"
12573 When a message is being received by SMTP, this variable contains the number of
12574 RCPT commands received for the current message. If this variable is used in a
12575 RCPT ACL, its value includes the current command.
12576
12577 .vitem &$rcpt_defer_count$&
12578 .vindex "&$rcpt_defer_count$&"
12579 .cindex "4&'xx'& responses" "count of"
12580 When a message is being received by SMTP, this variable contains the number of
12581 RCPT commands in the current message that have previously been rejected with a
12582 temporary (4&'xx'&) response.
12583
12584 .vitem &$rcpt_fail_count$&
12585 .vindex "&$rcpt_fail_count$&"
12586 When a message is being received by SMTP, this variable contains the number of
12587 RCPT commands in the current message that have previously been rejected with a
12588 permanent (5&'xx'&) response.
12589
12590 .vitem &$received_count$&
12591 .vindex "&$received_count$&"
12592 This variable contains the number of &'Received:'& header lines in the message,
12593 including the one added by Exim (so its value is always greater than zero). It
12594 is available in the DATA ACL, the non-SMTP ACL, and while routing and
12595 delivering.
12596
12597 .vitem &$received_for$&
12598 .vindex "&$received_for$&"
12599 If there is only a single recipient address in an incoming message, this
12600 variable contains that address when the &'Received:'& header line is being
12601 built. The value is copied after recipient rewriting has happened, but before
12602 the &[local_scan()]& function is run.
12603
12604 .vitem &$received_ip_address$&
12605 .vindex "&$received_ip_address$&"
12606 As soon as an Exim server starts processing an incoming TCP/IP connection, this
12607 variable is set to the address of the local IP interface, and &$received_port$&
12608 is set to the local port number. (The remote IP address and port are in
12609 &$sender_host_address$& and &$sender_host_port$&.) When testing with &%-bh%&,
12610 the port value is -1 unless it has been set using the &%-oMi%& command line
12611 option.
12612
12613 As well as being useful in ACLs (including the &"connect"& ACL), these variable
12614 could be used, for example, to make the file name for a TLS certificate depend
12615 on which interface and/or port is being used for the incoming connection. The
12616 values of &$received_ip_address$& and &$received_port$& are saved with any
12617 messages that are received, thus making these variables available at delivery
12618 time.
12619 For outbound connections see &$sending_ip_address$&.
12620
12621 .vitem &$received_port$&
12622 .vindex "&$received_port$&"
12623 See &$received_ip_address$&.
12624
12625 .vitem &$received_protocol$&
12626 .vindex "&$received_protocol$&"
12627 When a message is being processed, this variable contains the name of the
12628 protocol by which it was received. Most of the names used by Exim are defined
12629 by RFCs 821, 2821, and 3848. They start with &"smtp"& (the client used HELO) or
12630 &"esmtp"& (the client used EHLO). This can be followed by &"s"& for secure
12631 (encrypted) and/or &"a"& for authenticated. Thus, for example, if the protocol
12632 is set to &"esmtpsa"&, the message was received over an encrypted SMTP
12633 connection and the client was successfully authenticated.
12634
12635 Exim uses the protocol name &"smtps"& for the case when encryption is
12636 automatically set up on connection without the use of STARTTLS (see
12637 &%tls_on_connect_ports%&), and the client uses HELO to initiate the
12638 encrypted SMTP session. The name &"smtps"& is also used for the rare situation
12639 where the client initially uses EHLO, sets up an encrypted connection using
12640 STARTTLS, and then uses HELO afterwards.
12641
12642 The &%-oMr%& option provides a way of specifying a custom protocol name for
12643 messages that are injected locally by trusted callers. This is commonly used to
12644 identify messages that are being re-injected after some kind of scanning.
12645
12646 .vitem &$received_time$&
12647 .vindex "&$received_time$&"
12648 This variable contains the date and time when the current message was received,
12649 as a number of seconds since the start of the Unix epoch.
12650
12651 .vitem &$recipient_data$&
12652 .vindex "&$recipient_data$&"
12653 This variable is set after an indexing lookup success in an ACL &%recipients%&
12654 condition. It contains the data from the lookup, and the value remains set
12655 until the next &%recipients%& test. Thus, you can do things like this:
12656 .display
12657 &`require recipients  = cdb*@;/some/file`&
12658 &`deny    `&&'some further test involving'& &`$recipient_data`&
12659 .endd
12660 &*Warning*&: This variable is set only when a lookup is used as an indexing
12661 method in the address list, using the semicolon syntax as in the example above.
12662 The variable is not set for a lookup that is used as part of the string
12663 expansion that all such lists undergo before being interpreted.
12664
12665 .vitem &$recipient_verify_failure$&
12666 .vindex "&$recipient_verify_failure$&"
12667 In an ACL, when a recipient verification fails, this variable contains
12668 information about the failure. It is set to one of the following words:
12669
12670 .ilist
12671 &"qualify"&: The address was unqualified (no domain), and the message
12672 was neither local nor came from an exempted host.
12673
12674 .next
12675 &"route"&: Routing failed.
12676
12677 .next
12678 &"mail"&: Routing succeeded, and a callout was attempted; rejection occurred at
12679 or before the MAIL command (that is, on initial connection, HELO, or
12680 MAIL).
12681
12682 .next
12683 &"recipient"&: The RCPT command in a callout was rejected.
12684 .next
12685
12686 &"postmaster"&: The postmaster check in a callout was rejected.
12687 .endlist
12688
12689 The main use of this variable is expected to be to distinguish between
12690 rejections of MAIL and rejections of RCPT.
12691
12692 .vitem &$recipients$&
12693 .vindex "&$recipients$&"
12694 This variable contains a list of envelope recipients for a message. A comma and
12695 a space separate the addresses in the replacement text. However, the variable
12696 is not generally available, to prevent exposure of Bcc recipients in
12697 unprivileged users' filter files. You can use &$recipients$& only in these
12698 cases:
12699
12700 .olist
12701 In a system filter file.
12702 .next
12703 In the ACLs associated with the DATA command and with non-SMTP messages, that
12704 is, the ACLs defined by &%acl_smtp_predata%&, &%acl_smtp_data%&,
12705 &%acl_smtp_mime%&, &%acl_not_smtp_start%&, &%acl_not_smtp%&, and
12706 &%acl_not_smtp_mime%&.
12707 .next
12708 From within a &[local_scan()]& function.
12709 .endlist
12710
12711
12712 .vitem &$recipients_count$&
12713 .vindex "&$recipients_count$&"
12714 When a message is being processed, this variable contains the number of
12715 envelope recipients that came with the message. Duplicates are not excluded
12716 from the count. While a message is being received over SMTP, the number
12717 increases for each accepted recipient. It can be referenced in an ACL.
12718
12719
12720 .vitem &$regex_match_string$&
12721 .vindex "&$regex_match_string$&"
12722 This variable is set to contain the matching regular expression after a
12723 &%regex%& ACL condition has matched (see section &<<SECTscanregex>>&).
12724
12725 .vitem "&$regex1$&, &$regex2$&, etc"
12726 .cindex "regex submatch variables (&$1regex$& &$2regex$& etc)"
12727 When a &%regex%& or &%mime_regex%& ACL condition succeeds,
12728 these variables contain the
12729 captured substrings identified by the regular expression.
12730
12731
12732 .vitem &$reply_address$&
12733 .vindex "&$reply_address$&"
12734 When a message is being processed, this variable contains the contents of the
12735 &'Reply-To:'& header line if one exists and it is not empty, or otherwise the
12736 contents of the &'From:'& header line. Apart from the removal of leading
12737 white space, the value is not processed in any way. In particular, no RFC 2047
12738 decoding or character code translation takes place.
12739
12740 .vitem &$return_path$&
12741 .vindex "&$return_path$&"
12742 When a message is being delivered, this variable contains the return path &--
12743 the sender field that will be sent as part of the envelope. It is not enclosed
12744 in <> characters. At the start of routing an address, &$return_path$& has the
12745 same value as &$sender_address$&, but if, for example, an incoming message to a
12746 mailing list has been expanded by a router which specifies a different address
12747 for bounce messages, &$return_path$& subsequently contains the new bounce
12748 address, whereas &$sender_address$& always contains the original sender address
12749 that was received with the message. In other words, &$sender_address$& contains
12750 the incoming envelope sender, and &$return_path$& contains the outgoing
12751 envelope sender.
12752
12753 .vitem &$return_size_limit$&
12754 .vindex "&$return_size_limit$&"
12755 This is an obsolete name for &$bounce_return_size_limit$&.
12756
12757 .vitem &$router_name$&
12758 .cindex "router" "name"
12759 .cindex "name" "of router"
12760 .vindex "&$router_name$&"
12761 During the running of a router this variable contains its name.
12762
12763 .vitem &$runrc$&
12764 .cindex "return code" "from &%run%& expansion"
12765 .vindex "&$runrc$&"
12766 This variable contains the return code from a command that is run by the
12767 &%${run...}%& expansion item. &*Warning*&: In a router or transport, you cannot
12768 assume the order in which option values are expanded, except for those
12769 preconditions whose order of testing is documented. Therefore, you cannot
12770 reliably expect to set &$runrc$& by the expansion of one option, and use it in
12771 another.
12772
12773 .vitem &$self_hostname$&
12774 .oindex "&%self%&" "value of host name"
12775 .vindex "&$self_hostname$&"
12776 When an address is routed to a supposedly remote host that turns out to be the
12777 local host, what happens is controlled by the &%self%& generic router option.
12778 One of its values causes the address to be passed to another router. When this
12779 happens, &$self_hostname$& is set to the name of the local host that the
12780 original router encountered. In other circumstances its contents are null.
12781
12782 .vitem &$sender_address$&
12783 .vindex "&$sender_address$&"
12784 When a message is being processed, this variable contains the sender's address
12785 that was received in the message's envelope. The case of letters in the address
12786 is retained, in both the local part and the domain. For bounce messages, the
12787 value of this variable is the empty string. See also &$return_path$&.
12788
12789 .vitem &$sender_address_data$&
12790 .vindex "&$address_data$&"
12791 .vindex "&$sender_address_data$&"
12792 If &$address_data$& is set when the routers are called from an ACL to verify a
12793 sender address, the final value is preserved in &$sender_address_data$&, to
12794 distinguish it from data from a recipient address. The value does not persist
12795 after the end of the current ACL statement. If you want to preserve it for
12796 longer, you can save it in an ACL variable.
12797
12798 .vitem &$sender_address_domain$&
12799 .vindex "&$sender_address_domain$&"
12800 The domain portion of &$sender_address$&.
12801
12802 .vitem &$sender_address_local_part$&
12803 .vindex "&$sender_address_local_part$&"
12804 The local part portion of &$sender_address$&.
12805
12806 .vitem &$sender_data$&
12807 .vindex "&$sender_data$&"
12808 This variable is set after a lookup success in an ACL &%senders%& condition or
12809 in a router &%senders%& option. It contains the data from the lookup, and the
12810 value remains set until the next &%senders%& test. Thus, you can do things like
12811 this:
12812 .display
12813 &`require senders      = cdb*@;/some/file`&
12814 &`deny    `&&'some further test involving'& &`$sender_data`&
12815 .endd
12816 &*Warning*&: This variable is set only when a lookup is used as an indexing
12817 method in the address list, using the semicolon syntax as in the example above.
12818 The variable is not set for a lookup that is used as part of the string
12819 expansion that all such lists undergo before being interpreted.
12820
12821 .vitem &$sender_fullhost$&
12822 .vindex "&$sender_fullhost$&"
12823 When a message is received from a remote host, this variable contains the host
12824 name and IP address in a single string. It ends with the IP address in square
12825 brackets, followed by a colon and a port number if the logging of ports is
12826 enabled. The format of the rest of the string depends on whether the host
12827 issued a HELO or EHLO SMTP command, and whether the host name was verified by
12828 looking up its IP address. (Looking up the IP address can be forced by the
12829 &%host_lookup%& option, independent of verification.) A plain host name at the
12830 start of the string is a verified host name; if this is not present,
12831 verification either failed or was not requested. A host name in parentheses is
12832 the argument of a HELO or EHLO command. This is omitted if it is identical to
12833 the verified host name or to the host's IP address in square brackets.
12834
12835 .vitem &$sender_helo_dnssec$&
12836 .vindex "&$sender_helo_dnssec$&"
12837 This boolean variable is true if a successful HELO verification was
12838 .cindex "DNS" "DNSSEC"
12839 done using DNS information the resolver library stated was authenticated data.
12840
12841 .vitem &$sender_helo_name$&
12842 .vindex "&$sender_helo_name$&"
12843 When a message is received from a remote host that has issued a HELO or EHLO
12844 command, the argument of that command is placed in this variable. It is also
12845 set if HELO or EHLO is used when a message is received using SMTP locally via
12846 the &%-bs%& or &%-bS%& options.
12847
12848 .vitem &$sender_host_address$&
12849 .vindex "&$sender_host_address$&"
12850 When a message is received from a remote host using SMTP,
12851 this variable contains that
12852 host's IP address. For locally non-SMTP submitted messages, it is empty.
12853
12854 .vitem &$sender_host_authenticated$&
12855 .vindex "&$sender_host_authenticated$&"
12856 This variable contains the name (not the public name) of the authenticator
12857 driver that successfully authenticated the client from which the message was
12858 received. It is empty if there was no successful authentication. See also
12859 &$authenticated_id$&.
12860
12861 .vitem &$sender_host_dnssec$&
12862 .vindex "&$sender_host_dnssec$&"
12863 If an attempt to populate &$sender_host_name$& has been made
12864 (by reference, &%hosts_lookup%& or
12865 otherwise) then this boolean will have been set true if, and only if, the
12866 resolver library states that both
12867 the reverse and forward DNS were authenticated data.  At all
12868 other times, this variable is false.
12869
12870 .cindex "DNS" "DNSSEC"
12871 It is likely that you will need to coerce DNSSEC support on in the resolver
12872 library, by setting:
12873 .code
12874 dns_dnssec_ok = 1
12875 .endd
12876
12877 Exim does not perform DNSSEC validation itself, instead leaving that to a
12878 validating resolver (e.g. unbound, or bind with suitable configuration).
12879
12880 If you have changed &%host_lookup_order%& so that &`bydns`& is not the first
12881 mechanism in the list, then this variable will be false.
12882
12883 This requires that your system resolver library support EDNS0 (and that
12884 DNSSEC flags exist in the system headers).  If the resolver silently drops
12885 all EDNS0 options, then this will have no effect.  OpenBSD's asr resolver
12886 is known to currently ignore EDNS0, documented in CAVEATS of asr_run(3).
12887
12888
12889 .vitem &$sender_host_name$&
12890 .vindex "&$sender_host_name$&"
12891 When a message is received from a remote host, this variable contains the
12892 host's name as obtained by looking up its IP address. For messages received by
12893 other means, this variable is empty.
12894
12895 .vindex "&$host_lookup_failed$&"
12896 If the host name has not previously been looked up, a reference to
12897 &$sender_host_name$& triggers a lookup (for messages from remote hosts).
12898 A looked up name is accepted only if it leads back to the original IP address
12899 via a forward lookup. If either the reverse or the forward lookup fails to find
12900 any data, or if the forward lookup does not yield the original IP address,
12901 &$sender_host_name$& remains empty, and &$host_lookup_failed$& is set to &"1"&.
12902
12903 .vindex "&$host_lookup_deferred$&"
12904 However, if either of the lookups cannot be completed (for example, there is a
12905 DNS timeout), &$host_lookup_deferred$& is set to &"1"&, and
12906 &$host_lookup_failed$& remains set to &"0"&.
12907
12908 Once &$host_lookup_failed$& is set to &"1"&, Exim does not try to look up the
12909 host name again if there is a subsequent reference to &$sender_host_name$&
12910 in the same Exim process, but it does try again if &$host_lookup_deferred$&
12911 is set to &"1"&.
12912
12913 Exim does not automatically look up every calling host's name. If you want
12914 maximum efficiency, you should arrange your configuration so that it avoids
12915 these lookups altogether. The lookup happens only if one or more of the
12916 following are true:
12917
12918 .ilist
12919 A string containing &$sender_host_name$& is expanded.
12920 .next
12921 The calling host matches the list in &%host_lookup%&. In the default
12922 configuration, this option is set to *, so it must be changed if lookups are
12923 to be avoided. (In the code, the default for &%host_lookup%& is unset.)
12924 .next
12925 Exim needs the host name in order to test an item in a host list. The items
12926 that require this are described in sections &<<SECThoslispatnam>>& and
12927 &<<SECThoslispatnamsk>>&.
12928 .next
12929 The calling host matches &%helo_try_verify_hosts%& or &%helo_verify_hosts%&.
12930 In this case, the host name is required to compare with the name quoted in any
12931 EHLO or HELO commands that the client issues.
12932 .next
12933 The remote host issues a EHLO or HELO command that quotes one of the
12934 domains in &%helo_lookup_domains%&. The default value of this option is
12935 . ==== As this is a nested list, any displays it contains must be indented
12936 . ==== as otherwise they are too far to the left.
12937 .code
12938   helo_lookup_domains = @ : @[]
12939 .endd
12940 which causes a lookup if a remote host (incorrectly) gives the server's name or
12941 IP address in an EHLO or HELO command.
12942 .endlist
12943
12944
12945 .vitem &$sender_host_port$&
12946 .vindex "&$sender_host_port$&"
12947 When a message is received from a remote host, this variable contains the port
12948 number that was used on the remote host.
12949
12950 .vitem &$sender_ident$&
12951 .vindex "&$sender_ident$&"
12952 When a message is received from a remote host, this variable contains the
12953 identification received in response to an RFC 1413 request. When a message has
12954 been received locally, this variable contains the login name of the user that
12955 called Exim.
12956
12957 .vitem &$sender_rate_$&&'xxx'&
12958 A number of variables whose names begin &$sender_rate_$& are set as part of the
12959 &%ratelimit%& ACL condition. Details are given in section
12960 &<<SECTratelimiting>>&.
12961
12962 .vitem &$sender_rcvhost$&
12963 .cindex "DNS" "reverse lookup"
12964 .cindex "reverse DNS lookup"
12965 .vindex "&$sender_rcvhost$&"
12966 This is provided specifically for use in &'Received:'& headers. It starts with
12967 either the verified host name (as obtained from a reverse DNS lookup) or, if
12968 there is no verified host name, the IP address in square brackets. After that
12969 there may be text in parentheses. When the first item is a verified host name,
12970 the first thing in the parentheses is the IP address in square brackets,
12971 followed by a colon and a port number if port logging is enabled. When the
12972 first item is an IP address, the port is recorded as &"port=&'xxxx'&"& inside
12973 the parentheses.
12974
12975 There may also be items of the form &"helo=&'xxxx'&"& if HELO or EHLO
12976 was used and its argument was not identical to the real host name or IP
12977 address, and &"ident=&'xxxx'&"& if an RFC 1413 ident string is available. If
12978 all three items are present in the parentheses, a newline and tab are inserted
12979 into the string, to improve the formatting of the &'Received:'& header.
12980
12981 .vitem &$sender_verify_failure$&
12982 .vindex "&$sender_verify_failure$&"
12983 In an ACL, when a sender verification fails, this variable contains information
12984 about the failure. The details are the same as for
12985 &$recipient_verify_failure$&.
12986
12987 .vitem &$sending_ip_address$&
12988 .vindex "&$sending_ip_address$&"
12989 This variable is set whenever an outgoing SMTP connection to another host has
12990 been set up. It contains the IP address of the local interface that is being
12991 used. This is useful if a host that has more than one IP address wants to take
12992 on different personalities depending on which one is being used. For incoming
12993 connections, see &$received_ip_address$&.
12994
12995 .vitem &$sending_port$&
12996 .vindex "&$sending_port$&"
12997 This variable is set whenever an outgoing SMTP connection to another host has
12998 been set up. It contains the local port that is being used. For incoming
12999 connections, see &$received_port$&.
13000
13001 .vitem &$smtp_active_hostname$&
13002 .vindex "&$smtp_active_hostname$&"
13003 During an incoming SMTP session, this variable contains the value of the active
13004 host name, as specified by the &%smtp_active_hostname%& option. The value of
13005 &$smtp_active_hostname$& is saved with any message that is received, so its
13006 value can be consulted during routing and delivery.
13007
13008 .vitem &$smtp_command$&
13009 .vindex "&$smtp_command$&"
13010 During the processing of an incoming SMTP command, this variable contains the
13011 entire command. This makes it possible to distinguish between HELO and EHLO in
13012 the HELO ACL, and also to distinguish between commands such as these:
13013 .code
13014 MAIL FROM:<>
13015 MAIL FROM: <>
13016 .endd
13017 For a MAIL command, extra parameters such as SIZE can be inspected. For a RCPT
13018 command, the address in &$smtp_command$& is the original address before any
13019 rewriting, whereas the values in &$local_part$& and &$domain$& are taken from
13020 the address after SMTP-time rewriting.
13021
13022 .vitem &$smtp_command_argument$&
13023 .cindex "SMTP" "command, argument for"
13024 .vindex "&$smtp_command_argument$&"
13025 While an ACL is running to check an SMTP command, this variable contains the
13026 argument, that is, the text that follows the command name, with leading white
13027 space removed. Following the introduction of &$smtp_command$&, this variable is
13028 somewhat redundant, but is retained for backwards compatibility.
13029
13030 .vitem &$smtp_command_history$&
13031 .cindex SMTP "command history"
13032 .vindex "&$smtp_command_history$&"
13033 A comma-separated list (with no whitespace) of the most-recent SMTP commands
13034 received, in time-order left to right.  Only a limited number of commands
13035 are remembered.
13036
13037 .vitem &$smtp_count_at_connection_start$&
13038 .vindex "&$smtp_count_at_connection_start$&"
13039 This variable is set greater than zero only in processes spawned by the Exim
13040 daemon for handling incoming SMTP connections. The name is deliberately long,
13041 in order to emphasize what the contents are. When the daemon accepts a new
13042 connection, it increments this variable. A copy of the variable is passed to
13043 the child process that handles the connection, but its value is fixed, and
13044 never changes. It is only an approximation of how many incoming connections
13045 there actually are, because many other connections may come and go while a
13046 single connection is being processed. When a child process terminates, the
13047 daemon decrements its copy of the variable.
13048
13049 .vitem "&$sn0$& &-- &$sn9$&"
13050 These variables are copies of the values of the &$n0$& &-- &$n9$& accumulators
13051 that were current at the end of the system filter file. This allows a system
13052 filter file to set values that can be tested in users' filter files. For
13053 example, a system filter could set a value indicating how likely it is that a
13054 message is junk mail.
13055
13056 .vitem &$spam_$&&'xxx'&
13057 A number of variables whose names start with &$spam$& are available when Exim
13058 is compiled with the content-scanning extension. For details, see section
13059 &<<SECTscanspamass>>&.
13060
13061 .vitem &$spf_header_comment$& &&&
13062        &$spf_received$& &&&
13063        &$spf_result$& &&&
13064        &$spf_result_guessed$& &&&
13065        &$spf_smtp_comment$&
13066 These variables are only available if Exim is built with SPF support.
13067 For details see section &<<SECSPF>>&.
13068
13069 .vitem &$spool_directory$&
13070 .vindex "&$spool_directory$&"
13071 The name of Exim's spool directory.
13072
13073 .vitem &$spool_inodes$&
13074 .vindex "&$spool_inodes$&"
13075 The number of free inodes in the disk partition where Exim's spool files are
13076 being written. The value is recalculated whenever the variable is referenced.
13077 If the relevant file system does not have the concept of inodes, the value of
13078 is -1. See also the &%check_spool_inodes%& option.
13079
13080 .vitem &$spool_space$&
13081 .vindex "&$spool_space$&"
13082 The amount of free space (as a number of kilobytes) in the disk partition where
13083 Exim's spool files are being written. The value is recalculated whenever the
13084 variable is referenced. If the operating system does not have the ability to
13085 find the amount of free space (only true for experimental systems), the space
13086 value is -1. For example, to check in an ACL that there is at least 50
13087 megabytes free on the spool, you could write:
13088 .code
13089 condition = ${if > {$spool_space}{50000}}
13090 .endd
13091 See also the &%check_spool_space%& option.
13092
13093
13094 .vitem &$thisaddress$&
13095 .vindex "&$thisaddress$&"
13096 This variable is set only during the processing of the &%foranyaddress%&
13097 command in a filter file. Its use is explained in the description of that
13098 command, which can be found in the separate document entitled &'Exim's
13099 interfaces to mail filtering'&.
13100
13101 .vitem &$tls_in_bits$&
13102 .vindex "&$tls_in_bits$&"
13103 Contains an approximation of the TLS cipher's bit-strength
13104 on the inbound connection; the meaning of
13105 this depends upon the TLS implementation used.
13106 If TLS has not been negotiated, the value will be 0.
13107 The value of this is automatically fed into the Cyrus SASL authenticator
13108 when acting as a server, to specify the "external SSF" (a SASL term).
13109
13110 The deprecated &$tls_bits$& variable refers to the inbound side
13111 except when used in the context of an outbound SMTP delivery, when it refers to
13112 the outbound.
13113
13114 .vitem &$tls_out_bits$&
13115 .vindex "&$tls_out_bits$&"
13116 Contains an approximation of the TLS cipher's bit-strength
13117 on an outbound SMTP connection; the meaning of
13118 this depends upon the TLS implementation used.
13119 If TLS has not been negotiated, the value will be 0.
13120
13121 .vitem &$tls_in_ourcert$&
13122 .vindex "&$tls_in_ourcert$&"
13123 .cindex certificate variables
13124 This variable refers to the certificate presented to the peer of an
13125 inbound connection when the message was received.
13126 It is only useful as the argument of a
13127 &%certextract%& expansion item, &%md5%&, &%sha1%& or &%sha256%& operator,
13128 or a &%def%& condition.
13129
13130 &*Note*&: Under versions of OpenSSL preceding 1.1.1,
13131 when a list of more than one
13132 file is used for &%tls_certificate%&, this variable is not reliable.
13133
13134 .vitem &$tls_in_peercert$&
13135 .vindex "&$tls_in_peercert$&"
13136 This variable refers to the certificate presented by the peer of an
13137 inbound connection when the message was received.
13138 It is only useful as the argument of a
13139 &%certextract%& expansion item, &%md5%&, &%sha1%& or &%sha256%& operator,
13140 or a &%def%& condition.
13141 If certificate verification fails it may refer to a failing chain element
13142 which is not the leaf.
13143
13144 .vitem &$tls_out_ourcert$&
13145 .vindex "&$tls_out_ourcert$&"
13146 This variable refers to the certificate presented to the peer of an
13147 outbound connection.  It is only useful as the argument of a
13148 &%certextract%& expansion item, &%md5%&, &%sha1%& or &%sha256%& operator,
13149 or a &%def%& condition.
13150
13151 .vitem &$tls_out_peercert$&
13152 .vindex "&$tls_out_peercert$&"
13153 This variable refers to the certificate presented by the peer of an
13154 outbound connection.  It is only useful as the argument of a
13155 &%certextract%& expansion item, &%md5%&, &%sha1%& or &%sha256%& operator,
13156 or a &%def%& condition.
13157 If certificate verification fails it may refer to a failing chain element
13158 which is not the leaf.
13159
13160 .vitem &$tls_in_certificate_verified$&
13161 .vindex "&$tls_in_certificate_verified$&"
13162 This variable is set to &"1"& if a TLS certificate was verified when the
13163 message was received, and &"0"& otherwise.
13164
13165 The deprecated &$tls_certificate_verified$& variable refers to the inbound side
13166 except when used in the context of an outbound SMTP delivery, when it refers to
13167 the outbound.
13168
13169 .vitem &$tls_out_certificate_verified$&
13170 .vindex "&$tls_out_certificate_verified$&"
13171 This variable is set to &"1"& if a TLS certificate was verified when an
13172 outbound SMTP connection was made,
13173 and &"0"& otherwise.
13174
13175 .vitem &$tls_in_cipher$&
13176 .vindex "&$tls_in_cipher$&"
13177 .vindex "&$tls_cipher$&"
13178 When a message is received from a remote host over an encrypted SMTP
13179 connection, this variable is set to the cipher suite that was negotiated, for
13180 example DES-CBC3-SHA. In other circumstances, in particular, for message
13181 received over unencrypted connections, the variable is empty. Testing
13182 &$tls_in_cipher$& for emptiness is one way of distinguishing between encrypted and
13183 non-encrypted connections during ACL processing.
13184
13185 The deprecated &$tls_cipher$& variable is the same as &$tls_in_cipher$& during message reception,
13186 but in the context of an outward SMTP delivery taking place via the &(smtp)& transport
13187 becomes the same as &$tls_out_cipher$&.
13188
13189 .vitem &$tls_out_cipher$&
13190 .vindex "&$tls_out_cipher$&"
13191 This variable is
13192 cleared before any outgoing SMTP connection is made,
13193 and then set to the outgoing cipher suite if one is negotiated. See chapter
13194 &<<CHAPTLS>>& for details of TLS support and chapter &<<CHAPsmtptrans>>& for
13195 details of the &(smtp)& transport.
13196
13197 .vitem &$tls_out_dane$&
13198 .vindex &$tls_out_dane$&
13199 DANE active status.  See section &<<SECDANE>>&.
13200
13201 .vitem &$tls_in_ocsp$&
13202 .vindex "&$tls_in_ocsp$&"
13203 When a message is received from a remote client connection
13204 the result of any OCSP request from the client is encoded in this variable:
13205 .code
13206 0 OCSP proof was not requested (default value)
13207 1 No response to request
13208 2 Response not verified
13209 3 Verification failed
13210 4 Verification succeeded
13211 .endd
13212
13213 .vitem &$tls_out_ocsp$&
13214 .vindex "&$tls_out_ocsp$&"
13215 When a message is sent to a remote host connection
13216 the result of any OCSP request made is encoded in this variable.
13217 See &$tls_in_ocsp$& for values.
13218
13219 .vitem &$tls_in_peerdn$&
13220 .vindex "&$tls_in_peerdn$&"
13221 .vindex "&$tls_peerdn$&"
13222 .cindex certificate "extracting fields"
13223 When a message is received from a remote host over an encrypted SMTP
13224 connection, and Exim is configured to request a certificate from the client,
13225 the value of the Distinguished Name of the certificate is made available in the
13226 &$tls_in_peerdn$& during subsequent processing.
13227 If certificate verification fails it may refer to a failing chain element
13228 which is not the leaf.
13229
13230 The deprecated &$tls_peerdn$& variable refers to the inbound side
13231 except when used in the context of an outbound SMTP delivery, when it refers to
13232 the outbound.
13233
13234 .vitem &$tls_out_peerdn$&
13235 .vindex "&$tls_out_peerdn$&"
13236 When a message is being delivered to a remote host over an encrypted SMTP
13237 connection, and Exim is configured to request a certificate from the server,
13238 the value of the Distinguished Name of the certificate is made available in the
13239 &$tls_out_peerdn$& during subsequent processing.
13240 If certificate verification fails it may refer to a failing chain element
13241 which is not the leaf.
13242
13243 .vitem &$tls_in_sni$&
13244 .vindex "&$tls_in_sni$&"
13245 .vindex "&$tls_sni$&"
13246 .cindex "TLS" "Server Name Indication"
13247 When a TLS session is being established, if the client sends the Server
13248 Name Indication extension, the value will be placed in this variable.
13249 If the variable appears in &%tls_certificate%& then this option and
13250 some others, described in &<<SECTtlssni>>&,
13251 will be re-expanded early in the TLS session, to permit
13252 a different certificate to be presented (and optionally a different key to be
13253 used) to the client, based upon the value of the SNI extension.
13254
13255 The deprecated &$tls_sni$& variable refers to the inbound side
13256 except when used in the context of an outbound SMTP delivery, when it refers to
13257 the outbound.
13258
13259 .vitem &$tls_out_sni$&
13260 .vindex "&$tls_out_sni$&"
13261 .cindex "TLS" "Server Name Indication"
13262 During outbound
13263 SMTP deliveries, this variable reflects the value of the &%tls_sni%& option on
13264 the transport.
13265
13266 .vitem &$tls_out_tlsa_usage$&
13267 .vindex &$tls_out_tlsa_usage$&
13268 Bitfield of TLSA record types found.  See section &<<SECDANE>>&.
13269
13270 .vitem &$tod_bsdinbox$&
13271 .vindex "&$tod_bsdinbox$&"
13272 The time of day and the date, in the format required for BSD-style mailbox
13273 files, for example: Thu Oct 17 17:14:09 1995.
13274
13275 .vitem &$tod_epoch$&
13276 .vindex "&$tod_epoch$&"
13277 The time and date as a number of seconds since the start of the Unix epoch.
13278
13279 .vitem &$tod_epoch_l$&
13280 .vindex "&$tod_epoch_l$&"
13281 The time and date as a number of microseconds since the start of the Unix epoch.
13282
13283 .vitem &$tod_full$&
13284 .vindex "&$tod_full$&"
13285 A full version of the time and date, for example: Wed, 16 Oct 1995 09:51:40
13286 +0100. The timezone is always given as a numerical offset from UTC, with
13287 positive values used for timezones that are ahead (east) of UTC, and negative
13288 values for those that are behind (west).
13289
13290 .vitem &$tod_log$&
13291 .vindex "&$tod_log$&"
13292 The time and date in the format used for writing Exim's log files, for example:
13293 1995-10-12 15:32:29, but without a timezone.
13294
13295 .vitem &$tod_logfile$&
13296 .vindex "&$tod_logfile$&"
13297 This variable contains the date in the format yyyymmdd. This is the format that
13298 is used for datestamping log files when &%log_file_path%& contains the &`%D`&
13299 flag.
13300
13301 .vitem &$tod_zone$&
13302 .vindex "&$tod_zone$&"
13303 This variable contains the numerical value of the local timezone, for example:
13304 -0500.
13305
13306 .vitem &$tod_zulu$&
13307 .vindex "&$tod_zulu$&"
13308 This variable contains the UTC date and time in &"Zulu"& format, as specified
13309 by ISO 8601, for example: 20030221154023Z.
13310
13311 .vitem &$transport_name$&
13312 .cindex "transport" "name"
13313 .cindex "name" "of transport"
13314 .vindex "&$transport_name$&"
13315 During the running of a transport, this variable contains its name.
13316
13317 .vitem &$value$&
13318 .vindex "&$value$&"
13319 This variable contains the result of an expansion lookup, extraction operation,
13320 or external command, as described above. It is also used during a
13321 &*reduce*& expansion.
13322
13323 .vitem &$verify_mode$&
13324 .vindex "&$verify_mode$&"
13325 While a router or transport is being run in verify mode or for cutthrough delivery,
13326 contains "S" for sender-verification or "R" for recipient-verification.
13327 Otherwise, empty.
13328
13329 .vitem &$version_number$&
13330 .vindex "&$version_number$&"
13331 The version number of Exim.
13332
13333 .vitem &$warn_message_delay$&
13334 .vindex "&$warn_message_delay$&"
13335 This variable is set only during the creation of a message warning about a
13336 delivery delay. Details of its use are explained in section &<<SECTcustwarn>>&.
13337
13338 .vitem &$warn_message_recipients$&
13339 .vindex "&$warn_message_recipients$&"
13340 This variable is set only during the creation of a message warning about a
13341 delivery delay. Details of its use are explained in section &<<SECTcustwarn>>&.
13342 .endlist
13343 .ecindex IIDstrexp
13344
13345
13346
13347 . ////////////////////////////////////////////////////////////////////////////
13348 . ////////////////////////////////////////////////////////////////////////////
13349
13350 .chapter "Embedded Perl" "CHAPperl"
13351 .scindex IIDperl "Perl" "calling from Exim"
13352 Exim can be built to include an embedded Perl interpreter. When this is done,
13353 Perl subroutines can be called as part of the string expansion process. To make
13354 use of the Perl support, you need version 5.004 or later of Perl installed on
13355 your system. To include the embedded interpreter in the Exim binary, include
13356 the line
13357 .code
13358 EXIM_PERL = perl.o
13359 .endd
13360 in your &_Local/Makefile_& and then build Exim in the normal way.
13361
13362
13363 .section "Setting up so Perl can be used" "SECID85"
13364 .oindex "&%perl_startup%&"
13365 Access to Perl subroutines is via a global configuration option called
13366 &%perl_startup%& and an expansion string operator &%${perl ...}%&. If there is
13367 no &%perl_startup%& option in the Exim configuration file then no Perl
13368 interpreter is started and there is almost no overhead for Exim (since none of
13369 the Perl library will be paged in unless used). If there is a &%perl_startup%&
13370 option then the associated value is taken to be Perl code which is executed in
13371 a newly created Perl interpreter.
13372
13373 The value of &%perl_startup%& is not expanded in the Exim sense, so you do not
13374 need backslashes before any characters to escape special meanings. The option
13375 should usually be something like
13376 .code
13377 perl_startup = do '/etc/exim.pl'
13378 .endd
13379 where &_/etc/exim.pl_& is Perl code which defines any subroutines you want to
13380 use from Exim. Exim can be configured either to start up a Perl interpreter as
13381 soon as it is entered, or to wait until the first time it is needed. Starting
13382 the interpreter at the beginning ensures that it is done while Exim still has
13383 its setuid privilege, but can impose an unnecessary overhead if Perl is not in
13384 fact used in a particular run. Also, note that this does not mean that Exim is
13385 necessarily running as root when Perl is called at a later time. By default,
13386 the interpreter is started only when it is needed, but this can be changed in
13387 two ways:
13388
13389 .ilist
13390 .oindex "&%perl_at_start%&"
13391 Setting &%perl_at_start%& (a boolean option) in the configuration requests
13392 a startup when Exim is entered.
13393 .next
13394 The command line option &%-ps%& also requests a startup when Exim is entered,
13395 overriding the setting of &%perl_at_start%&.
13396 .endlist
13397
13398 There is also a command line option &%-pd%& (for delay) which suppresses the
13399 initial startup, even if &%perl_at_start%& is set.
13400
13401 .ilist
13402 .oindex "&%perl_taintmode%&"
13403 .cindex "Perl" "taintmode"
13404 To provide more security executing Perl code via the embedded Perl
13405 interpreter, the &%perl_taintmode%& option can be set. This enables the
13406 taint mode of the Perl interpreter. You are encouraged to set this
13407 option to a true value. To avoid breaking existing installations, it
13408 defaults to false.
13409
13410
13411 .section "Calling Perl subroutines" "SECID86"
13412 When the configuration file includes a &%perl_startup%& option you can make use
13413 of the string expansion item to call the Perl subroutines that are defined
13414 by the &%perl_startup%& code. The operator is used in any of the following
13415 forms:
13416 .code
13417 ${perl{foo}}
13418 ${perl{foo}{argument}}
13419 ${perl{foo}{argument1}{argument2} ... }
13420 .endd
13421 which calls the subroutine &%foo%& with the given arguments. A maximum of eight
13422 arguments may be passed. Passing more than this results in an expansion failure
13423 with an error message of the form
13424 .code
13425 Too many arguments passed to Perl subroutine "foo" (max is 8)
13426 .endd
13427 The return value of the Perl subroutine is evaluated in a scalar context before
13428 it is passed back to Exim to be inserted into the expanded string. If the
13429 return value is &'undef'&, the expansion is forced to fail in the same way as
13430 an explicit &"fail"& on an &%if%& or &%lookup%& item. If the subroutine aborts
13431 by obeying Perl's &%die%& function, the expansion fails with the error message
13432 that was passed to &%die%&.
13433
13434
13435 .section "Calling Exim functions from Perl" "SECID87"
13436 Within any Perl code called from Exim, the function &'Exim::expand_string()'&
13437 is available to call back into Exim's string expansion function. For example,
13438 the Perl code
13439 .code
13440 my $lp = Exim::expand_string('$local_part');
13441 .endd
13442 makes the current Exim &$local_part$& available in the Perl variable &$lp$&.
13443 Note those are single quotes and not double quotes to protect against
13444 &$local_part$& being interpolated as a Perl variable.
13445
13446 If the string expansion is forced to fail by a &"fail"& item, the result of
13447 &'Exim::expand_string()'& is &%undef%&. If there is a syntax error in the
13448 expansion string, the Perl call from the original expansion string fails with
13449 an appropriate error message, in the same way as if &%die%& were used.
13450
13451 .cindex "debugging" "from embedded Perl"
13452 .cindex "log" "writing from embedded Perl"
13453 Two other Exim functions are available for use from within Perl code.
13454 &'Exim::debug_write()'& writes a string to the standard error stream if Exim's
13455 debugging is enabled. If you want a newline at the end, you must supply it.
13456 &'Exim::log_write()'& writes a string to Exim's main log, adding a leading
13457 timestamp. In this case, you should not supply a terminating newline.
13458
13459
13460 .section "Use of standard output and error by Perl" "SECID88"
13461 .cindex "Perl" "standard output and error"
13462 You should not write to the standard error or output streams from within your
13463 Perl code, as it is not defined how these are set up. In versions of Exim
13464 before 4.50, it is possible for the standard output or error to refer to the
13465 SMTP connection during message reception via the daemon. Writing to this stream
13466 is certain to cause chaos. From Exim 4.50 onwards, the standard output and
13467 error streams are connected to &_/dev/null_& in the daemon. The chaos is
13468 avoided, but the output is lost.
13469
13470 .cindex "Perl" "use of &%warn%&"
13471 The Perl &%warn%& statement writes to the standard error stream by default.
13472 Calls to &%warn%& may be embedded in Perl modules that you use, but over which
13473 you have no control. When Exim starts up the Perl interpreter, it arranges for
13474 output from the &%warn%& statement to be written to the Exim main log. You can
13475 change this by including appropriate Perl magic somewhere in your Perl code.
13476 For example, to discard &%warn%& output completely, you need this:
13477 .code
13478 $SIG{__WARN__} = sub { };
13479 .endd
13480 Whenever a &%warn%& is obeyed, the anonymous subroutine is called. In this
13481 example, the code for the subroutine is empty, so it does nothing, but you can
13482 include any Perl code that you like. The text of the &%warn%& message is passed
13483 as the first subroutine argument.
13484 .ecindex IIDperl
13485
13486
13487 . ////////////////////////////////////////////////////////////////////////////
13488 . ////////////////////////////////////////////////////////////////////////////
13489
13490 .chapter "Starting the daemon and the use of network interfaces" &&&
13491          "CHAPinterfaces" &&&
13492          "Starting the daemon"
13493 .cindex "daemon" "starting"
13494 .cindex "interface" "listening"
13495 .cindex "network interface"
13496 .cindex "interface" "network"
13497 .cindex "IP address" "for listening"
13498 .cindex "daemon" "listening IP addresses"
13499 .cindex "TCP/IP" "setting listening interfaces"
13500 .cindex "TCP/IP" "setting listening ports"
13501 A host that is connected to a TCP/IP network may have one or more physical
13502 hardware network interfaces. Each of these interfaces may be configured as one
13503 or more &"logical"& interfaces, which are the entities that a program actually
13504 works with. Each of these logical interfaces is associated with an IP address.
13505 In addition, TCP/IP software supports &"loopback"& interfaces (127.0.0.1 in
13506 IPv4 and ::1 in IPv6), which do not use any physical hardware. Exim requires
13507 knowledge about the host's interfaces for use in three different circumstances:
13508
13509 .olist
13510 When a listening daemon is started, Exim needs to know which interfaces
13511 and ports to listen on.
13512 .next
13513 When Exim is routing an address, it needs to know which IP addresses
13514 are associated with local interfaces. This is required for the correct
13515 processing of MX lists by removing the local host and others with the
13516 same or higher priority values. Also, Exim needs to detect cases
13517 when an address is routed to an IP address that in fact belongs to the
13518 local host. Unless the &%self%& router option or the &%allow_localhost%&
13519 option of the smtp transport is set (as appropriate), this is treated
13520 as an error situation.
13521 .next
13522 When Exim connects to a remote host, it may need to know which interface to use
13523 for the outgoing connection.
13524 .endlist
13525
13526
13527 Exim's default behaviour is likely to be appropriate in the vast majority
13528 of cases. If your host has only one interface, and you want all its IP
13529 addresses to be treated in the same way, and you are using only the
13530 standard SMTP port, you should not need to take any special action. The
13531 rest of this chapter does not apply to you.
13532
13533 In a more complicated situation you may want to listen only on certain
13534 interfaces, or on different ports, and for this reason there are a number of
13535 options that can be used to influence Exim's behaviour. The rest of this
13536 chapter describes how they operate.
13537
13538 When a message is received over TCP/IP, the interface and port that were
13539 actually used are set in &$received_ip_address$& and &$received_port$&.
13540
13541
13542
13543 .section "Starting a listening daemon" "SECID89"
13544 When a listening daemon is started (by means of the &%-bd%& command line
13545 option), the interfaces and ports on which it listens are controlled by the
13546 following options:
13547
13548 .ilist
13549 &%daemon_smtp_ports%& contains a list of default ports
13550 or service names.
13551 (For backward compatibility, this option can also be specified in the singular.)
13552 .next
13553 &%local_interfaces%& contains list of interface IP addresses on which to
13554 listen. Each item may optionally also specify a port.
13555 .endlist
13556
13557 The default list separator in both cases is a colon, but this can be changed as
13558 described in section &<<SECTlistconstruct>>&. When IPv6 addresses are involved,
13559 it is usually best to change the separator to avoid having to double all the
13560 colons. For example:
13561 .code
13562 local_interfaces = <; 127.0.0.1 ; \
13563                       192.168.23.65 ; \
13564                       ::1 ; \
13565                       3ffe:ffff:836f::fe86:a061
13566 .endd
13567 There are two different formats for specifying a port along with an IP address
13568 in &%local_interfaces%&:
13569
13570 .olist
13571 The port is added onto the address with a dot separator. For example, to listen
13572 on port 1234 on two different IP addresses:
13573 .code
13574 local_interfaces = <; 192.168.23.65.1234 ; \
13575                       3ffe:ffff:836f::fe86:a061.1234
13576 .endd
13577 .next
13578 The IP address is enclosed in square brackets, and the port is added
13579 with a colon separator, for example:
13580 .code
13581 local_interfaces = <; [192.168.23.65]:1234 ; \
13582                       [3ffe:ffff:836f::fe86:a061]:1234
13583 .endd
13584 .endlist
13585
13586 When a port is not specified, the value of &%daemon_smtp_ports%& is used. The
13587 default setting contains just one port:
13588 .code
13589 daemon_smtp_ports = smtp
13590 .endd
13591 If more than one port is listed, each interface that does not have its own port
13592 specified listens on all of them. Ports that are listed in
13593 &%daemon_smtp_ports%& can be identified either by name (defined in
13594 &_/etc/services_&) or by number. However, when ports are given with individual
13595 IP addresses in &%local_interfaces%&, only numbers (not names) can be used.
13596
13597
13598
13599 .section "Special IP listening addresses" "SECID90"
13600 The addresses 0.0.0.0 and ::0 are treated specially. They are interpreted
13601 as &"all IPv4 interfaces"& and &"all IPv6 interfaces"&, respectively. In each
13602 case, Exim tells the TCP/IP stack to &"listen on all IPv&'x'& interfaces"&
13603 instead of setting up separate listening sockets for each interface. The
13604 default value of &%local_interfaces%& is
13605 .code
13606 local_interfaces = 0.0.0.0
13607 .endd
13608 when Exim is built without IPv6 support; otherwise it is:
13609 .code
13610 local_interfaces = <; ::0 ; 0.0.0.0
13611 .endd
13612 Thus, by default, Exim listens on all available interfaces, on the SMTP port.
13613
13614
13615
13616 .section "Overriding local_interfaces and daemon_smtp_ports" "SECID91"
13617 The &%-oX%& command line option can be used to override the values of
13618 &%daemon_smtp_ports%& and/or &%local_interfaces%& for a particular daemon
13619 instance. Another way of doing this would be to use macros and the &%-D%&
13620 option. However, &%-oX%& can be used by any admin user, whereas modification of
13621 the runtime configuration by &%-D%& is allowed only when the caller is root or
13622 exim.
13623
13624 The value of &%-oX%& is a list of items. The default colon separator can be
13625 changed in the usual way if required. If there are any items that do not
13626 contain dots or colons (that is, are not IP addresses), the value of
13627 &%daemon_smtp_ports%& is replaced by the list of those items. If there are any
13628 items that do contain dots or colons, the value of &%local_interfaces%& is
13629 replaced by those items. Thus, for example,
13630 .code
13631 -oX 1225
13632 .endd
13633 overrides &%daemon_smtp_ports%&, but leaves &%local_interfaces%& unchanged,
13634 whereas
13635 .code
13636 -oX 192.168.34.5.1125
13637 .endd
13638 overrides &%local_interfaces%&, leaving &%daemon_smtp_ports%& unchanged.
13639 (However, since &%local_interfaces%& now contains no items without ports, the
13640 value of &%daemon_smtp_ports%& is no longer relevant in this example.)
13641
13642
13643
13644 .section "Support for the submissions (aka SSMTP or SMTPS) protocol" "SECTsupobssmt"
13645 .cindex "submissions protocol"
13646 .cindex "ssmtp protocol"
13647 .cindex "smtps protocol"
13648 .cindex "SMTP" "ssmtp protocol"
13649 .cindex "SMTP" "smtps protocol"
13650 Exim supports the use of TLS-on-connect, used by mail clients in the
13651 &"submissions"& protocol, historically also known as SMTPS or SSMTP.
13652 For some years, IETF Standards Track documents only blessed the
13653 STARTTLS-based Submission service (port 587) while common practice was to support
13654 the same feature set on port 465, but using TLS-on-connect.
13655 If your installation needs to provide service to mail clients
13656 (Mail User Agents, MUAs) then you should provide service on both the 587 and
13657 the 465 TCP ports.
13658
13659 If the &%tls_on_connect_ports%& option is set to a list of port numbers or
13660 service names, connections to those ports must first establish TLS, before
13661 proceeding to the application layer use of the SMTP protocol.
13662
13663 The common use of this option is expected to be
13664 .code
13665 tls_on_connect_ports = 465
13666 .endd
13667 per RFC 8314.
13668 There is also a command line option &%-tls-on-connect%&, which forces all ports
13669 to behave in this way when a daemon is started.
13670
13671 &*Warning*&: Setting &%tls_on_connect_ports%& does not of itself cause the
13672 daemon to listen on those ports. You must still specify them in
13673 &%daemon_smtp_ports%&, &%local_interfaces%&, or the &%-oX%& option. (This is
13674 because &%tls_on_connect_ports%& applies to &%inetd%& connections as well as to
13675 connections via the daemon.)
13676
13677
13678
13679
13680 .section "IPv6 address scopes" "SECID92"
13681 .cindex "IPv6" "address scopes"
13682 IPv6 addresses have &"scopes"&, and a host with multiple hardware interfaces
13683 can, in principle, have the same link-local IPv6 address on different
13684 interfaces. Thus, additional information is needed, over and above the IP
13685 address, to distinguish individual interfaces. A convention of using a
13686 percent sign followed by something (often the interface name) has been
13687 adopted in some cases, leading to addresses like this:
13688 .code
13689 fe80::202:b3ff:fe03:45c1%eth0
13690 .endd
13691 To accommodate this usage, a percent sign followed by an arbitrary string is
13692 allowed at the end of an IPv6 address. By default, Exim calls &[getaddrinfo()]&
13693 to convert a textual IPv6 address for actual use. This function recognizes the
13694 percent convention in operating systems that support it, and it processes the
13695 address appropriately. Unfortunately, some older libraries have problems with
13696 &[getaddrinfo()]&. If
13697 .code
13698 IPV6_USE_INET_PTON=yes
13699 .endd
13700 is set in &_Local/Makefile_& (or an OS-dependent Makefile) when Exim is built,
13701 Exim uses &'inet_pton()'& to convert a textual IPv6 address for actual use,
13702 instead of &[getaddrinfo()]&. (Before version 4.14, it always used this
13703 function.) Of course, this means that the additional functionality of
13704 &[getaddrinfo()]& &-- recognizing scoped addresses &-- is lost.
13705
13706 .section "Disabling IPv6" "SECID93"
13707 .cindex "IPv6" "disabling"
13708 Sometimes it happens that an Exim binary that was compiled with IPv6 support is
13709 run on a host whose kernel does not support IPv6. The binary will fall back to
13710 using IPv4, but it may waste resources looking up AAAA records, and trying to
13711 connect to IPv6 addresses, causing delays to mail delivery. If you set the
13712 .oindex "&%disable_ipv6%&"
13713 &%disable_ipv6%& option true, even if the Exim binary has IPv6 support, no IPv6
13714 activities take place. AAAA records are never looked up, and any IPv6 addresses
13715 that are listed in &%local_interfaces%&, data for the &(manualroute)& router,
13716 etc. are ignored. If IP literals are enabled, the &(ipliteral)& router declines
13717 to handle IPv6 literal addresses.
13718
13719 On the other hand, when IPv6 is in use, there may be times when you want to
13720 disable it for certain hosts or domains. You can use the &%dns_ipv4_lookup%&
13721 option to globally suppress the lookup of AAAA records for specified domains,
13722 and you can use the &%ignore_target_hosts%& generic router option to ignore
13723 IPv6 addresses in an individual router.
13724
13725
13726
13727 .section "Examples of starting a listening daemon" "SECID94"
13728 The default case in an IPv6 environment is
13729 .code
13730 daemon_smtp_ports = smtp
13731 local_interfaces = <; ::0 ; 0.0.0.0
13732 .endd
13733 This specifies listening on the smtp port on all IPv6 and IPv4 interfaces.
13734 Either one or two sockets may be used, depending on the characteristics of
13735 the TCP/IP stack. (This is complicated and messy; for more information,
13736 read the comments in the &_daemon.c_& source file.)
13737
13738 To specify listening on ports 25 and 26 on all interfaces:
13739 .code
13740 daemon_smtp_ports = 25 : 26
13741 .endd
13742 (leaving &%local_interfaces%& at the default setting) or, more explicitly:
13743 .code
13744 local_interfaces = <; ::0.25     ; ::0.26 \
13745                       0.0.0.0.25 ; 0.0.0.0.26
13746 .endd
13747 To listen on the default port on all IPv4 interfaces, and on port 26 on the
13748 IPv4 loopback address only:
13749 .code
13750 local_interfaces = 0.0.0.0 : 127.0.0.1.26
13751 .endd
13752 To specify listening on the default port on specific interfaces only:
13753 .code
13754 local_interfaces = 10.0.0.67 : 192.168.34.67
13755 .endd
13756 &*Warning*&: Such a setting excludes listening on the loopback interfaces.
13757
13758
13759
13760 .section "Recognizing the local host" "SECTreclocipadd"
13761 The &%local_interfaces%& option is also used when Exim needs to determine
13762 whether or not an IP address refers to the local host. That is, the IP
13763 addresses of all the interfaces on which a daemon is listening are always
13764 treated as local.
13765
13766 For this usage, port numbers in &%local_interfaces%& are ignored. If either of
13767 the items 0.0.0.0 or ::0 are encountered, Exim gets a complete list of
13768 available interfaces from the operating system, and extracts the relevant
13769 (that is, IPv4 or IPv6) addresses to use for checking.
13770
13771 Some systems set up large numbers of virtual interfaces in order to provide
13772 many virtual web servers. In this situation, you may want to listen for
13773 email on only a few of the available interfaces, but nevertheless treat all
13774 interfaces as local when routing. You can do this by setting
13775 &%extra_local_interfaces%& to a list of IP addresses, possibly including the
13776 &"all"& wildcard values. These addresses are recognized as local, but are not
13777 used for listening. Consider this example:
13778 .code
13779 local_interfaces = <; 127.0.0.1 ; ::1 ; \
13780                       192.168.53.235 ; \
13781                       3ffe:2101:12:1:a00:20ff:fe86:a061
13782
13783 extra_local_interfaces = <; ::0 ; 0.0.0.0
13784 .endd
13785 The daemon listens on the loopback interfaces and just one IPv4 and one IPv6
13786 address, but all available interface addresses are treated as local when
13787 Exim is routing.
13788
13789 In some environments the local host name may be in an MX list, but with an IP
13790 address that is not assigned to any local interface. In other cases it may be
13791 desirable to treat other host names as if they referred to the local host. Both
13792 these cases can be handled by setting the &%hosts_treat_as_local%& option.
13793 This contains host names rather than IP addresses. When a host is referenced
13794 during routing, either via an MX record or directly, it is treated as the local
13795 host if its name matches &%hosts_treat_as_local%&, or if any of its IP
13796 addresses match &%local_interfaces%& or &%extra_local_interfaces%&.
13797
13798
13799
13800 .section "Delivering to a remote host" "SECID95"
13801 Delivery to a remote host is handled by the smtp transport. By default, it
13802 allows the system's TCP/IP functions to choose which interface to use (if
13803 there is more than one) when connecting to a remote host. However, the
13804 &%interface%& option can be set to specify which interface is used. See the
13805 description of the smtp transport in chapter &<<CHAPsmtptrans>>& for more
13806 details.
13807
13808
13809
13810
13811 . ////////////////////////////////////////////////////////////////////////////
13812 . ////////////////////////////////////////////////////////////////////////////
13813
13814 .chapter "Main configuration" "CHAPmainconfig"
13815 .scindex IIDconfima "configuration file" "main section"
13816 .scindex IIDmaiconf "main configuration"
13817 The first part of the run time configuration file contains three types of item:
13818
13819 .ilist
13820 Macro definitions: These lines start with an upper case letter. See section
13821 &<<SECTmacrodefs>>& for details of macro processing.
13822 .next
13823 Named list definitions: These lines start with one of the words &"domainlist"&,
13824 &"hostlist"&, &"addresslist"&, or &"localpartlist"&. Their use is described in
13825 section &<<SECTnamedlists>>&.
13826 .next
13827 Main configuration settings: Each setting occupies one line of the file
13828 (with possible continuations). If any setting is preceded by the word
13829 &"hide"&, the &%-bP%& command line option displays its value to admin users
13830 only. See section &<<SECTcos>>& for a description of the syntax of these option
13831 settings.
13832 .endlist
13833
13834 This chapter specifies all the main configuration options, along with their
13835 types and default values. For ease of finding a particular option, they appear
13836 in alphabetical order in section &<<SECTalomo>>& below. However, because there
13837 are now so many options, they are first listed briefly in functional groups, as
13838 an aid to finding the name of the option you are looking for. Some options are
13839 listed in more than one group.
13840
13841 .section "Miscellaneous" "SECID96"
13842 .table2
13843 .row &%bi_command%&                  "to run for &%-bi%& command line option"
13844 .row &%debug_store%&                 "do extra internal checks"
13845 .row &%disable_ipv6%&                "do no IPv6 processing"
13846 .row &%keep_malformed%&              "for broken files &-- should not happen"
13847 .row &%localhost_number%&            "for unique message ids in clusters"
13848 .row &%message_body_newlines%&       "retain newlines in &$message_body$&"
13849 .row &%message_body_visible%&        "how much to show in &$message_body$&"
13850 .row &%mua_wrapper%&                 "run in &""MUA wrapper""& mode"
13851 .row &%print_topbitchars%&           "top-bit characters are printing"
13852 .row &%spool_wireformat%&            "use wire-format spool data files when possible"
13853 .row &%timezone%&                    "force time zone"
13854 .endtable
13855
13856
13857 .section "Exim parameters" "SECID97"
13858 .table2
13859 .row &%exim_group%&                  "override compiled-in value"
13860 .row &%exim_path%&                   "override compiled-in value"
13861 .row &%exim_user%&                   "override compiled-in value"
13862 .row &%primary_hostname%&            "default from &[uname()]&"
13863 .row &%split_spool_directory%&       "use multiple directories"
13864 .row &%spool_directory%&             "override compiled-in value"
13865 .endtable
13866
13867
13868
13869 .section "Privilege controls" "SECID98"
13870 .table2
13871 .row &%admin_groups%&                "groups that are Exim admin users"
13872 .row &%commandline_checks_require_admin%& "require admin for various checks"
13873 .row &%deliver_drop_privilege%&      "drop root for delivery processes"
13874 .row &%local_from_check%&            "insert &'Sender:'& if necessary"
13875 .row &%local_from_prefix%&           "for testing &'From:'& for local sender"
13876 .row &%local_from_suffix%&           "for testing &'From:'& for local sender"
13877 .row &%local_sender_retain%&         "keep &'Sender:'& from untrusted user"
13878 .row &%never_users%&                 "do not run deliveries as these"
13879 .row &%prod_requires_admin%&         "forced delivery requires admin user"
13880 .row &%queue_list_requires_admin%&   "queue listing requires admin user"
13881 .row &%trusted_groups%&              "groups that are trusted"
13882 .row &%trusted_users%&               "users that are trusted"
13883 .endtable
13884
13885
13886
13887 .section "Logging" "SECID99"
13888 .table2
13889 .row &%event_action%&                "custom logging"
13890 .row &%hosts_connection_nolog%&      "exemption from connect logging"
13891 .row &%log_file_path%&               "override compiled-in value"
13892 .row &%log_selector%&                "set/unset optional logging"
13893 .row &%log_timezone%&                "add timezone to log lines"
13894 .row &%message_logs%&                "create per-message logs"
13895 .row &%preserve_message_logs%&       "after message completion"
13896 .row &%process_log_path%&            "for SIGUSR1 and &'exiwhat'&"
13897 .row &%slow_lookup_log%&             "control logging of slow DNS lookups"
13898 .row &%syslog_duplication%&          "controls duplicate log lines on syslog"
13899 .row &%syslog_facility%&             "set syslog &""facility""& field"
13900 .row &%syslog_pid%&                  "pid in syslog lines"
13901 .row &%syslog_processname%&          "set syslog &""ident""& field"
13902 .row &%syslog_timestamp%&            "timestamp syslog lines"
13903 .row &%write_rejectlog%&             "control use of message log"
13904 .endtable
13905
13906
13907
13908 .section "Frozen messages" "SECID100"
13909 .table2
13910 .row &%auto_thaw%&                   "sets time for retrying frozen messages"
13911 .row &%freeze_tell%&                 "send message when freezing"
13912 .row &%move_frozen_messages%&        "to another directory"
13913 .row &%timeout_frozen_after%&        "keep frozen messages only so long"
13914 .endtable
13915
13916
13917
13918 .section "Data lookups" "SECID101"
13919 .table2
13920 .row &%ibase_servers%&               "InterBase servers"
13921 .row &%ldap_ca_cert_dir%&            "dir of CA certs to verify LDAP server's"
13922 .row &%ldap_ca_cert_file%&           "file of CA certs to verify LDAP server's"
13923 .row &%ldap_cert_file%&              "client cert file for LDAP"
13924 .row &%ldap_cert_key%&               "client key file for LDAP"
13925 .row &%ldap_cipher_suite%&           "TLS negotiation preference control"
13926 .row &%ldap_default_servers%&        "used if no server in query"
13927 .row &%ldap_require_cert%&           "action to take without LDAP server cert"
13928 .row &%ldap_start_tls%&              "require TLS within LDAP"
13929 .row &%ldap_version%&                "set protocol version"
13930 .row &%lookup_open_max%&             "lookup files held open"
13931 .row &%mysql_servers%&               "default MySQL servers"
13932 .row &%oracle_servers%&              "Oracle servers"
13933 .row &%pgsql_servers%&               "default PostgreSQL servers"
13934 .row &%sqlite_lock_timeout%&         "as it says"
13935 .endtable
13936
13937
13938
13939 .section "Message ids" "SECID102"
13940 .table2
13941 .row &%message_id_header_domain%&    "used to build &'Message-ID:'& header"
13942 .row &%message_id_header_text%&      "ditto"
13943 .endtable
13944
13945
13946
13947 .section "Embedded Perl Startup" "SECID103"
13948 .table2
13949 .row &%perl_at_start%&               "always start the interpreter"
13950 .row &%perl_startup%&                "code to obey when starting Perl"
13951 .row &%perl_taintmode%&              "enable taint mode in Perl"
13952 .endtable
13953
13954
13955
13956 .section "Daemon" "SECID104"
13957 .table2
13958 .row &%daemon_smtp_ports%&           "default ports"
13959 .row &%daemon_startup_retries%&      "number of times to retry"
13960 .row &%daemon_startup_sleep%&        "time to sleep between tries"
13961 .row &%extra_local_interfaces%&      "not necessarily listened on"
13962 .row &%local_interfaces%&            "on which to listen, with optional ports"
13963 .row &%pid_file_path%&               "override compiled-in value"
13964 .row &%queue_run_max%&               "maximum simultaneous queue runners"
13965 .endtable
13966
13967
13968
13969 .section "Resource control" "SECID105"
13970 .table2
13971 .row &%check_log_inodes%&            "before accepting a message"
13972 .row &%check_log_space%&             "before accepting a message"
13973 .row &%check_spool_inodes%&          "before accepting a message"
13974 .row &%check_spool_space%&           "before accepting a message"
13975 .row &%deliver_queue_load_max%&      "no queue deliveries if load high"
13976 .row &%queue_only_load%&             "queue incoming if load high"
13977 .row &%queue_only_load_latch%&       "don't re-evaluate load for each message"
13978 .row &%queue_run_max%&               "maximum simultaneous queue runners"
13979 .row &%remote_max_parallel%&         "parallel SMTP delivery per message"
13980 .row &%smtp_accept_max%&             "simultaneous incoming connections"
13981 .row &%smtp_accept_max_nonmail%&     "non-mail commands"
13982 .row &%smtp_accept_max_nonmail_hosts%& "hosts to which the limit applies"
13983 .row &%smtp_accept_max_per_connection%& "messages per connection"
13984 .row &%smtp_accept_max_per_host%&    "connections from one host"
13985 .row &%smtp_accept_queue%&           "queue mail if more connections"
13986 .row &%smtp_accept_queue_per_connection%& "queue if more messages per &&&
13987                                            connection"
13988 .row &%smtp_accept_reserve%&         "only reserve hosts if more connections"
13989 .row &%smtp_check_spool_space%&      "from SIZE on MAIL command"
13990 .row &%smtp_connect_backlog%&        "passed to TCP/IP stack"
13991 .row &%smtp_load_reserve%&           "SMTP from reserved hosts if load high"
13992 .row &%smtp_reserve_hosts%&          "these are the reserve hosts"
13993 .endtable
13994
13995
13996
13997 .section "Policy controls" "SECID106"
13998 .table2
13999 .row &%acl_not_smtp%&                "ACL for non-SMTP messages"
14000 .row &%acl_not_smtp_mime%&           "ACL for non-SMTP MIME parts"
14001 .row &%acl_not_smtp_start%&          "ACL for start of non-SMTP message"
14002 .row &%acl_smtp_auth%&               "ACL for AUTH"
14003 .row &%acl_smtp_connect%&            "ACL for connection"
14004 .row &%acl_smtp_data%&               "ACL for DATA"
14005 .row &%acl_smtp_data_prdr%&          "ACL for DATA, per-recipient"
14006 .row &%acl_smtp_dkim%&               "ACL for DKIM verification"
14007 .row &%acl_smtp_etrn%&               "ACL for ETRN"
14008 .row &%acl_smtp_expn%&               "ACL for EXPN"
14009 .row &%acl_smtp_helo%&               "ACL for EHLO or HELO"
14010 .row &%acl_smtp_mail%&               "ACL for MAIL"
14011 .row &%acl_smtp_mailauth%&           "ACL for AUTH on MAIL command"
14012 .row &%acl_smtp_mime%&               "ACL for MIME parts"
14013 .row &%acl_smtp_notquit%&            "ACL for non-QUIT terminations"
14014 .row &%acl_smtp_predata%&            "ACL for start of data"
14015 .row &%acl_smtp_quit%&               "ACL for QUIT"
14016 .row &%acl_smtp_rcpt%&               "ACL for RCPT"
14017 .row &%acl_smtp_starttls%&           "ACL for STARTTLS"
14018 .row &%acl_smtp_vrfy%&               "ACL for VRFY"
14019 .row &%av_scanner%&                  "specify virus scanner"
14020 .row &%check_rfc2047_length%&        "check length of RFC 2047 &""encoded &&&
14021                                       words""&"
14022 .row &%dns_cname_loops%&             "follow CNAMEs returned by resolver"
14023 .row &%dns_csa_search_limit%&        "control CSA parent search depth"
14024 .row &%dns_csa_use_reverse%&         "en/disable CSA IP reverse search"
14025 .row &%header_maxsize%&              "total size of message header"
14026 .row &%header_line_maxsize%&         "individual header line limit"
14027 .row &%helo_accept_junk_hosts%&      "allow syntactic junk from these hosts"
14028 .row &%helo_allow_chars%&            "allow illegal chars in HELO names"
14029 .row &%helo_lookup_domains%&         "lookup hostname for these HELO names"
14030 .row &%helo_try_verify_hosts%&       "HELO soft-checked for these hosts"
14031 .row &%helo_verify_hosts%&           "HELO hard-checked for these hosts"
14032 .row &%host_lookup%&                 "host name looked up for these hosts"
14033 .row &%host_lookup_order%&           "order of DNS and local name lookups"
14034 .row &%hosts_proxy%&                 "use proxy protocol for these hosts"
14035 .row &%host_reject_connection%&      "reject connection from these hosts"
14036 .row &%hosts_treat_as_local%&        "useful in some cluster configurations"
14037 .row &%local_scan_timeout%&          "timeout for &[local_scan()]&"
14038 .row &%message_size_limit%&          "for all messages"
14039 .row &%percent_hack_domains%&        "recognize %-hack for these domains"
14040 .row &%spamd_address%&               "set interface to SpamAssassin"
14041 .row &%strict_acl_vars%&             "object to unset ACL variables"
14042 .endtable
14043
14044
14045
14046 .section "Callout cache" "SECID107"
14047 .table2
14048 .row &%callout_domain_negative_expire%& "timeout for negative domain cache &&&
14049                                          item"
14050 .row &%callout_domain_positive_expire%& "timeout for positive domain cache &&&
14051                                          item"
14052 .row &%callout_negative_expire%&     "timeout for negative address cache item"
14053 .row &%callout_positive_expire%&     "timeout for positive address cache item"
14054 .row &%callout_random_local_part%&   "string to use for &""random""& testing"
14055 .endtable
14056
14057
14058
14059 .section "TLS" "SECID108"
14060 .table2
14061 .row &%gnutls_compat_mode%&          "use GnuTLS compatibility mode"
14062 .row &%gnutls_allow_auto_pkcs11%&    "allow GnuTLS to autoload PKCS11 modules"
14063 .row &%openssl_options%&             "adjust OpenSSL compatibility options"
14064 .row &%tls_advertise_hosts%&         "advertise TLS to these hosts"
14065 .row &%tls_certificate%&             "location of server certificate"
14066 .row &%tls_crl%&                     "certificate revocation list"
14067 .row &%tls_dh_max_bits%&             "clamp D-H bit count suggestion"
14068 .row &%tls_dhparam%&                 "DH parameters for server"
14069 .row &%tls_eccurve%&                 "EC curve selection for server"
14070 .row &%tls_ocsp_file%&               "location of server certificate status proof"
14071 .row &%tls_on_connect_ports%&        "specify SSMTP (SMTPS) ports"
14072 .row &%tls_privatekey%&              "location of server private key"
14073 .row &%tls_remember_esmtp%&          "don't reset after starting TLS"
14074 .row &%tls_require_ciphers%&         "specify acceptable ciphers"
14075 .row &%tls_try_verify_hosts%&        "try to verify client certificate"
14076 .row &%tls_verify_certificates%&     "expected client certificates"
14077 .row &%tls_verify_hosts%&            "insist on client certificate verify"
14078 .endtable
14079
14080
14081
14082 .section "Local user handling" "SECID109"
14083 .table2
14084 .row &%finduser_retries%&            "useful in NIS environments"
14085 .row &%gecos_name%&                  "used when creating &'Sender:'&"
14086 .row &%gecos_pattern%&               "ditto"
14087 .row &%max_username_length%&         "for systems that truncate"
14088 .row &%unknown_login%&               "used when no login name found"
14089 .row &%unknown_username%&            "ditto"
14090 .row &%uucp_from_pattern%&           "for recognizing &""From ""& lines"
14091 .row &%uucp_from_sender%&            "ditto"
14092 .endtable
14093
14094
14095
14096 .section "All incoming messages (SMTP and non-SMTP)" "SECID110"
14097 .table2
14098 .row &%header_maxsize%&              "total size of message header"
14099 .row &%header_line_maxsize%&         "individual header line limit"
14100 .row &%message_size_limit%&          "applies to all messages"
14101 .row &%percent_hack_domains%&        "recognize %-hack for these domains"
14102 .row &%received_header_text%&        "expanded to make &'Received:'&"
14103 .row &%received_headers_max%&        "for mail loop detection"
14104 .row &%recipients_max%&              "limit per message"
14105 .row &%recipients_max_reject%&       "permanently reject excess recipients"
14106 .endtable
14107
14108
14109
14110
14111 .section "Non-SMTP incoming messages" "SECID111"
14112 .table2
14113 .row &%receive_timeout%&             "for non-SMTP messages"
14114 .endtable
14115
14116
14117
14118
14119
14120 .section "Incoming SMTP messages" "SECID112"
14121 See also the &'Policy controls'& section above.
14122
14123 .table2
14124 .row &%dkim_verify_signers%&         "DKIM domain for which DKIM ACL is run"
14125 .row &%host_lookup%&                 "host name looked up for these hosts"
14126 .row &%host_lookup_order%&           "order of DNS and local name lookups"
14127 .row &%recipient_unqualified_hosts%& "may send unqualified recipients"
14128 .row &%rfc1413_hosts%&               "make ident calls to these hosts"
14129 .row &%rfc1413_query_timeout%&       "zero disables ident calls"
14130 .row &%sender_unqualified_hosts%&    "may send unqualified senders"
14131 .row &%smtp_accept_keepalive%&       "some TCP/IP magic"
14132 .row &%smtp_accept_max%&             "simultaneous incoming connections"
14133 .row &%smtp_accept_max_nonmail%&     "non-mail commands"
14134 .row &%smtp_accept_max_nonmail_hosts%& "hosts to which the limit applies"
14135 .row &%smtp_accept_max_per_connection%& "messages per connection"
14136 .row &%smtp_accept_max_per_host%&    "connections from one host"
14137 .row &%smtp_accept_queue%&           "queue mail if more connections"
14138 .row &%smtp_accept_queue_per_connection%& "queue if more messages per &&&
14139                                            connection"
14140 .row &%smtp_accept_reserve%&         "only reserve hosts if more connections"
14141 .row &%smtp_active_hostname%&        "host name to use in messages"
14142 .row &%smtp_banner%&                 "text for welcome banner"
14143 .row &%smtp_check_spool_space%&      "from SIZE on MAIL command"
14144 .row &%smtp_connect_backlog%&        "passed to TCP/IP stack"
14145 .row &%smtp_enforce_sync%&           "of SMTP command/responses"
14146 .row &%smtp_etrn_command%&           "what to run for ETRN"
14147 .row &%smtp_etrn_serialize%&         "only one at once"
14148 .row &%smtp_load_reserve%&           "only reserve hosts if this load"
14149 .row &%smtp_max_unknown_commands%&   "before dropping connection"
14150 .row &%smtp_ratelimit_hosts%&        "apply ratelimiting to these hosts"
14151 .row &%smtp_ratelimit_mail%&         "ratelimit for MAIL commands"
14152 .row &%smtp_ratelimit_rcpt%&         "ratelimit for RCPT commands"
14153 .row &%smtp_receive_timeout%&        "per command or data line"
14154 .row &%smtp_reserve_hosts%&          "these are the reserve hosts"
14155 .row &%smtp_return_error_details%&   "give detail on rejections"
14156 .endtable
14157
14158
14159
14160 .section "SMTP extensions" "SECID113"
14161 .table2
14162 .row &%accept_8bitmime%&             "advertise 8BITMIME"
14163 .row &%auth_advertise_hosts%&        "advertise AUTH to these hosts"
14164 .row &%chunking_advertise_hosts%&    "advertise CHUNKING to these hosts"
14165 .row &%dsn_advertise_hosts%&         "advertise DSN extensions to these hosts"
14166 .row &%ignore_fromline_hosts%&       "allow &""From ""& from these hosts"
14167 .row &%ignore_fromline_local%&       "allow &""From ""& from local SMTP"
14168 .row &%pipelining_advertise_hosts%&  "advertise pipelining to these hosts"
14169 .row &%prdr_enable%&                 "advertise PRDR to all hosts"
14170 .row &%smtputf8_advertise_hosts%&    "advertise SMTPUTF8 to these hosts"
14171 .row &%tls_advertise_hosts%&         "advertise TLS to these hosts"
14172 .endtable
14173
14174
14175
14176 .section "Processing messages" "SECID114"
14177 .table2
14178 .row &%allow_domain_literals%&       "recognize domain literal syntax"
14179 .row &%allow_mx_to_ip%&              "allow MX to point to IP address"
14180 .row &%allow_utf8_domains%&          "in addresses"
14181 .row &%check_rfc2047_length%&        "check length of RFC 2047 &""encoded &&&
14182                                       words""&"
14183 .row &%delivery_date_remove%&        "from incoming messages"
14184 .row &%envelope_to_remove%&          "from incoming messages"
14185 .row &%extract_addresses_remove_arguments%& "affects &%-t%& processing"
14186 .row &%headers_charset%&             "default for translations"
14187 .row &%qualify_domain%&              "default for senders"
14188 .row &%qualify_recipient%&           "default for recipients"
14189 .row &%return_path_remove%&          "from incoming messages"
14190 .row &%strip_excess_angle_brackets%& "in addresses"
14191 .row &%strip_trailing_dot%&          "at end of addresses"
14192 .row &%untrusted_set_sender%&        "untrusted can set envelope sender"
14193 .endtable
14194
14195
14196
14197 .section "System filter" "SECID115"
14198 .table2
14199 .row &%system_filter%&               "locate system filter"
14200 .row &%system_filter_directory_transport%& "transport for delivery to a &&&
14201                                             directory"
14202 .row &%system_filter_file_transport%& "transport for delivery to a file"
14203 .row &%system_filter_group%&         "group for filter running"
14204 .row &%system_filter_pipe_transport%& "transport for delivery to a pipe"
14205 .row &%system_filter_reply_transport%& "transport for autoreply delivery"
14206 .row &%system_filter_user%&          "user for filter running"
14207 .endtable
14208
14209
14210
14211 .section "Routing and delivery" "SECID116"
14212 .table2
14213 .row &%disable_ipv6%&                "do no IPv6 processing"
14214 .row &%dns_again_means_nonexist%&    "for broken domains"
14215 .row &%dns_check_names_pattern%&     "pre-DNS syntax check"
14216 .row &%dns_dnssec_ok%&               "parameter for resolver"
14217 .row &%dns_ipv4_lookup%&             "only v4 lookup for these domains"
14218 .row &%dns_retrans%&                 "parameter for resolver"
14219 .row &%dns_retry%&                   "parameter for resolver"
14220 .row &%dns_trust_aa%&                "DNS zones trusted as authentic"
14221 .row &%dns_use_edns0%&               "parameter for resolver"
14222 .row &%hold_domains%&                "hold delivery for these domains"
14223 .row &%local_interfaces%&            "for routing checks"
14224 .row &%queue_domains%&               "no immediate delivery for these"
14225 .row &%queue_only%&                  "no immediate delivery at all"
14226 .row &%queue_only_file%&             "no immediate delivery if file exists"
14227 .row &%queue_only_load%&             "no immediate delivery if load is high"
14228 .row &%queue_only_load_latch%&       "don't re-evaluate load for each message"
14229 .row &%queue_only_override%&         "allow command line to override"
14230 .row &%queue_run_in_order%&          "order of arrival"
14231 .row &%queue_run_max%&               "of simultaneous queue runners"
14232 .row &%queue_smtp_domains%&          "no immediate SMTP delivery for these"
14233 .row &%remote_max_parallel%&         "parallel SMTP delivery per message"
14234 .row &%remote_sort_domains%&         "order of remote deliveries"
14235 .row &%retry_data_expire%&           "timeout for retry data"
14236 .row &%retry_interval_max%&          "safety net for retry rules"
14237 .endtable
14238
14239
14240
14241 .section "Bounce and warning messages" "SECID117"
14242 .table2
14243 .row &%bounce_message_file%&         "content of bounce"
14244 .row &%bounce_message_text%&         "content of bounce"
14245 .row &%bounce_return_body%&          "include body if returning message"
14246 .row &%bounce_return_linesize_limit%& "limit on returned message line length"
14247 .row &%bounce_return_message%&       "include original message in bounce"
14248 .row &%bounce_return_size_limit%&    "limit on returned message"
14249 .row &%bounce_sender_authentication%& "send authenticated sender with bounce"
14250 .row &%dsn_from%&                    "set &'From:'& contents in bounces"
14251 .row &%errors_copy%&                 "copy bounce messages"
14252 .row &%errors_reply_to%&             "&'Reply-to:'& in bounces"
14253 .row &%delay_warning%&               "time schedule"
14254 .row &%delay_warning_condition%&     "condition for warning messages"
14255 .row &%ignore_bounce_errors_after%&  "discard undeliverable bounces"
14256 .row &%smtp_return_error_details%&   "give detail on rejections"
14257 .row &%warn_message_file%&           "content of warning message"
14258 .endtable
14259
14260
14261
14262 .section "Alphabetical list of main options" "SECTalomo"
14263 Those options that undergo string expansion before use are marked with
14264 &dagger;.
14265
14266 .option accept_8bitmime main boolean true
14267 .cindex "8BITMIME"
14268 .cindex "8-bit characters"
14269 .cindex "log" "selectors"
14270 .cindex "log" "8BITMIME"
14271 This option causes Exim to send 8BITMIME in its response to an SMTP
14272 EHLO command, and to accept the BODY= parameter on MAIL commands.
14273 However, though Exim is 8-bit clean, it is not a protocol converter, and it
14274 takes no steps to do anything special with messages received by this route.
14275
14276 Historically Exim kept this option off by default, but the maintainers
14277 feel that in today's Internet, this causes more problems than it solves.
14278 It now defaults to true.
14279 A more detailed analysis of the issues is provided by Dan Bernstein:
14280 .display
14281 &url(https://cr.yp.to/smtp/8bitmime.html)
14282 .endd
14283
14284 To log received 8BITMIME status use
14285 .code
14286 log_selector = +8bitmime
14287 .endd
14288
14289 .option acl_not_smtp main string&!! unset
14290 .cindex "&ACL;" "for non-SMTP messages"
14291 .cindex "non-SMTP messages" "ACLs for"
14292 This option defines the ACL that is run when a non-SMTP message has been
14293 read and is on the point of being accepted. See chapter &<<CHAPACL>>& for
14294 further details.
14295
14296 .option acl_not_smtp_mime main string&!! unset
14297 This option defines the ACL that is run for individual MIME parts of non-SMTP
14298 messages. It operates in exactly the same way as &%acl_smtp_mime%& operates for
14299 SMTP messages.
14300
14301 .option acl_not_smtp_start main string&!! unset
14302 .cindex "&ACL;" "at start of non-SMTP message"
14303 .cindex "non-SMTP messages" "ACLs for"
14304 This option defines the ACL that is run before Exim starts reading a
14305 non-SMTP message. See chapter &<<CHAPACL>>& for further details.
14306
14307 .option acl_smtp_auth main string&!! unset
14308 .cindex "&ACL;" "setting up for SMTP commands"
14309 .cindex "AUTH" "ACL for"
14310 This option defines the ACL that is run when an SMTP AUTH command is
14311 received. See chapter &<<CHAPACL>>& for further details.
14312
14313 .option acl_smtp_connect main string&!! unset
14314 .cindex "&ACL;" "on SMTP connection"
14315 This option defines the ACL that is run when an SMTP connection is received.
14316 See chapter &<<CHAPACL>>& for further details.
14317
14318 .option acl_smtp_data main string&!! unset
14319 .cindex "DATA" "ACL for"
14320 This option defines the ACL that is run after an SMTP DATA command has been
14321 processed and the message itself has been received, but before the final
14322 acknowledgment is sent. See chapter &<<CHAPACL>>& for further details.
14323
14324 .option acl_smtp_data_prdr main string&!! accept
14325 .cindex "PRDR" "ACL for"
14326 .cindex "DATA" "PRDR ACL for"
14327 .cindex "&ACL;" "PRDR-related"
14328 .cindex "&ACL;" "per-user data processing"
14329 This option defines the ACL that,
14330 if the PRDR feature has been negotiated,
14331 is run for each recipient after an SMTP DATA command has been
14332 processed and the message itself has been received, but before the
14333 acknowledgment is sent. See chapter &<<CHAPACL>>& for further details.
14334
14335 .option acl_smtp_dkim main string&!! unset
14336 .cindex DKIM "ACL for"
14337 This option defines the ACL that is run for each DKIM signature
14338 (by default, or as specified in the dkim_verify_signers option)
14339 of a received message.
14340 See section &<<SECDKIMVFY>>& for further details.
14341
14342 .option acl_smtp_etrn main string&!! unset
14343 .cindex "ETRN" "ACL for"
14344 This option defines the ACL that is run when an SMTP ETRN command is
14345 received. See chapter &<<CHAPACL>>& for further details.
14346
14347 .option acl_smtp_expn main string&!! unset
14348 .cindex "EXPN" "ACL for"
14349 This option defines the ACL that is run when an SMTP EXPN command is
14350 received. See chapter &<<CHAPACL>>& for further details.
14351
14352 .option acl_smtp_helo main string&!! unset
14353 .cindex "EHLO" "ACL for"
14354 .cindex "HELO" "ACL for"
14355 This option defines the ACL that is run when an SMTP EHLO or HELO
14356 command is received. See chapter &<<CHAPACL>>& for further details.
14357
14358
14359 .option acl_smtp_mail main string&!! unset
14360 .cindex "MAIL" "ACL for"
14361 This option defines the ACL that is run when an SMTP MAIL command is
14362 received. See chapter &<<CHAPACL>>& for further details.
14363
14364 .option acl_smtp_mailauth main string&!! unset
14365 .cindex "AUTH" "on MAIL command"
14366 This option defines the ACL that is run when there is an AUTH parameter on
14367 a MAIL command. See chapter &<<CHAPACL>>& for details of ACLs, and chapter
14368 &<<CHAPSMTPAUTH>>& for details of authentication.
14369
14370 .option acl_smtp_mime main string&!! unset
14371 .cindex "MIME content scanning" "ACL for"
14372 This option is available when Exim is built with the content-scanning
14373 extension. It defines the ACL that is run for each MIME part in a message. See
14374 section &<<SECTscanmimepart>>& for details.
14375
14376 .option acl_smtp_notquit main string&!! unset
14377 .cindex "not-QUIT, ACL for"
14378 This option defines the ACL that is run when an SMTP session
14379 ends without a QUIT command being received.
14380 See chapter &<<CHAPACL>>& for further details.
14381
14382 .option acl_smtp_predata main string&!! unset
14383 This option defines the ACL that is run when an SMTP DATA command is
14384 received, before the message itself is received. See chapter &<<CHAPACL>>& for
14385 further details.
14386
14387 .option acl_smtp_quit main string&!! unset
14388 .cindex "QUIT, ACL for"
14389 This option defines the ACL that is run when an SMTP QUIT command is
14390 received. See chapter &<<CHAPACL>>& for further details.
14391
14392 .option acl_smtp_rcpt main string&!! unset
14393 .cindex "RCPT" "ACL for"
14394 This option defines the ACL that is run when an SMTP RCPT command is
14395 received. See chapter &<<CHAPACL>>& for further details.
14396
14397 .option acl_smtp_starttls main string&!! unset
14398 .cindex "STARTTLS, ACL for"
14399 This option defines the ACL that is run when an SMTP STARTTLS command is
14400 received. See chapter &<<CHAPACL>>& for further details.
14401
14402 .option acl_smtp_vrfy main string&!! unset
14403 .cindex "VRFY" "ACL for"
14404 This option defines the ACL that is run when an SMTP VRFY command is
14405 received. See chapter &<<CHAPACL>>& for further details.
14406
14407 .option add_environment main "string list" empty
14408 .cindex "environment" "set values"
14409 This option allows to set individual environment variables that the
14410 currently linked libraries and programs in child processes use.
14411 See &<<SECTpipeenv>>& for the environment of &(pipe)& transports.
14412
14413 .option admin_groups main "string list&!!" unset
14414 .cindex "admin user"
14415 This option is expanded just once, at the start of Exim's processing. If the
14416 current group or any of the supplementary groups of an Exim caller is in this
14417 colon-separated list, the caller has admin privileges. If all your system
14418 programmers are in a specific group, for example, you can give them all Exim
14419 admin privileges by putting that group in &%admin_groups%&. However, this does
14420 not permit them to read Exim's spool files (whose group owner is the Exim gid).
14421 To permit this, you have to add individuals to the Exim group.
14422
14423 .option allow_domain_literals main boolean false
14424 .cindex "domain literal"
14425 If this option is set, the RFC 2822 domain literal format is permitted in
14426 email addresses. The option is not set by default, because the domain literal
14427 format is not normally required these days, and few people know about it. It
14428 has, however, been exploited by mail abusers.
14429
14430 Unfortunately, it seems that some DNS black list maintainers are using this
14431 format to report black listing to postmasters. If you want to accept messages
14432 addressed to your hosts by IP address, you need to set
14433 &%allow_domain_literals%& true, and also to add &`@[]`& to the list of local
14434 domains (defined in the named domain list &%local_domains%& in the default
14435 configuration). This &"magic string"& matches the domain literal form of all
14436 the local host's IP addresses.
14437
14438
14439 .option allow_mx_to_ip main boolean false
14440 .cindex "MX record" "pointing to IP address"
14441 It appears that more and more DNS zone administrators are breaking the rules
14442 and putting domain names that look like IP addresses on the right hand side of
14443 MX records. Exim follows the rules and rejects this, giving an error message
14444 that explains the misconfiguration. However, some other MTAs support this
14445 practice, so to avoid &"Why can't Exim do this?"& complaints,
14446 &%allow_mx_to_ip%& exists, in order to enable this heinous activity. It is not
14447 recommended, except when you have no other choice.
14448
14449 .option allow_utf8_domains main boolean false
14450 .cindex "domain" "UTF-8 characters in"
14451 .cindex "UTF-8" "in domain name"
14452 Lots of discussion is going on about internationalized domain names. One
14453 camp is strongly in favour of just using UTF-8 characters, and it seems
14454 that at least two other MTAs permit this. This option allows Exim users to
14455 experiment if they wish.
14456
14457 If it is set true, Exim's domain parsing function allows valid
14458 UTF-8 multicharacters to appear in domain name components, in addition to
14459 letters, digits, and hyphens. However, just setting this option is not
14460 enough; if you want to look up these domain names in the DNS, you must also
14461 adjust the value of &%dns_check_names_pattern%& to match the extended form. A
14462 suitable setting is:
14463 .code
14464 dns_check_names_pattern = (?i)^(?>(?(1)\.|())[a-z0-9\xc0-\xff]\
14465   (?>[-a-z0-9\x80-\xff]*[a-z0-9\x80-\xbf])?)+$
14466 .endd
14467 Alternatively, you can just disable this feature by setting
14468 .code
14469 dns_check_names_pattern =
14470 .endd
14471 That is, set the option to an empty string so that no check is done.
14472
14473
14474 .option auth_advertise_hosts main "host list&!!" *
14475 .cindex "authentication" "advertising"
14476 .cindex "AUTH" "advertising"
14477 If any server authentication mechanisms are configured, Exim advertises them in
14478 response to an EHLO command only if the calling host matches this list.
14479 Otherwise, Exim does not advertise AUTH.
14480 Exim does not accept AUTH commands from clients to which it has not
14481 advertised the availability of AUTH. The advertising of individual
14482 authentication mechanisms can be controlled by the use of the
14483 &%server_advertise_condition%& generic authenticator option on the individual
14484 authenticators. See chapter &<<CHAPSMTPAUTH>>& for further details.
14485
14486 Certain mail clients (for example, Netscape) require the user to provide a name
14487 and password for authentication if AUTH is advertised, even though it may
14488 not be needed (the host may accept messages from hosts on its local LAN without
14489 authentication, for example). The &%auth_advertise_hosts%& option can be used
14490 to make these clients more friendly by excluding them from the set of hosts to
14491 which Exim advertises AUTH.
14492
14493 .cindex "AUTH" "advertising when encrypted"
14494 If you want to advertise the availability of AUTH only when the connection
14495 is encrypted using TLS, you can make use of the fact that the value of this
14496 option is expanded, with a setting like this:
14497 .code
14498 auth_advertise_hosts = ${if eq{$tls_in_cipher}{}{}{*}}
14499 .endd
14500 .vindex "&$tls_in_cipher$&"
14501 If &$tls_in_cipher$& is empty, the session is not encrypted, and the result of
14502 the expansion is empty, thus matching no hosts. Otherwise, the result of the
14503 expansion is *, which matches all hosts.
14504
14505
14506 .option auto_thaw main time 0s
14507 .cindex "thawing messages"
14508 .cindex "unfreezing messages"
14509 If this option is set to a time greater than zero, a queue runner will try a
14510 new delivery attempt on any frozen message, other than a bounce message, if
14511 this much time has passed since it was frozen. This may result in the message
14512 being re-frozen if nothing has changed since the last attempt. It is a way of
14513 saying &"keep on trying, even though there are big problems"&.
14514
14515 &*Note*&: This is an old option, which predates &%timeout_frozen_after%& and
14516 &%ignore_bounce_errors_after%&. It is retained for compatibility, but it is not
14517 thought to be very useful any more, and its use should probably be avoided.
14518
14519
14520 .option av_scanner main string "see below"
14521 This option is available if Exim is built with the content-scanning extension.
14522 It specifies which anti-virus scanner to use. The default value is:
14523 .code
14524 sophie:/var/run/sophie
14525 .endd
14526 If the value of &%av_scanner%& starts with a dollar character, it is expanded
14527 before use. See section &<<SECTscanvirus>>& for further details.
14528
14529
14530 .option bi_command main string unset
14531 .oindex "&%-bi%&"
14532 This option supplies the name of a command that is run when Exim is called with
14533 the &%-bi%& option (see chapter &<<CHAPcommandline>>&). The string value is
14534 just the command name, it is not a complete command line. If an argument is
14535 required, it must come from the &%-oA%& command line option.
14536
14537
14538 .option bounce_message_file main string unset
14539 .cindex "bounce message" "customizing"
14540 .cindex "customizing" "bounce message"
14541 This option defines a template file containing paragraphs of text to be used
14542 for constructing bounce messages.  Details of the file's contents are given in
14543 chapter &<<CHAPemsgcust>>&. See also &%warn_message_file%&.
14544
14545
14546 .option bounce_message_text main string unset
14547 When this option is set, its contents are included in the default bounce
14548 message immediately after &"This message was created automatically by mail
14549 delivery software."& It is not used if &%bounce_message_file%& is set.
14550
14551 .option bounce_return_body main boolean true
14552 .cindex "bounce message" "including body"
14553 This option controls whether the body of an incoming message is included in a
14554 bounce message when &%bounce_return_message%& is true. The default setting
14555 causes the entire message, both header and body, to be returned (subject to the
14556 value of &%bounce_return_size_limit%&). If this option is false, only the
14557 message header is included. In the case of a non-SMTP message containing an
14558 error that is detected during reception, only those header lines preceding the
14559 point at which the error was detected are returned.
14560 .cindex "bounce message" "including original"
14561
14562 .option bounce_return_linesize_limit main integer 998
14563 .cindex "size" "of bounce lines, limit"
14564 .cindex "bounce message" "line length limit"
14565 .cindex "limit" "bounce message line length"
14566 This option sets a limit in bytes on the line length of messages
14567 that are returned to senders due to delivery problems,
14568 when &%bounce_return_message%& is true.
14569 The default value corresponds to RFC limits.
14570 If the message being returned has lines longer than this value it is
14571 treated as if the &%bounce_return_size_limit%& (below) restriction was exceeded.
14572
14573 The option also applies to bounces returned when an error is detected
14574 during reception of a message.
14575 In this case lines from the original are truncated.
14576
14577 The option does not apply to messages generated by an &(autoreply)& transport.
14578
14579
14580 .option bounce_return_message main boolean true
14581 If this option is set false, none of the original message is included in
14582 bounce messages generated by Exim. See also &%bounce_return_size_limit%& and
14583 &%bounce_return_body%&.
14584
14585
14586 .option bounce_return_size_limit main integer 100K
14587 .cindex "size" "of bounce, limit"
14588 .cindex "bounce message" "size limit"
14589 .cindex "limit" "bounce message size"
14590 This option sets a limit in bytes on the size of messages that are returned to
14591 senders as part of bounce messages when &%bounce_return_message%& is true. The
14592 limit should be less than the value of the global &%message_size_limit%& and of
14593 any &%message_size_limit%& settings on transports, to allow for the bounce text
14594 that Exim generates. If this option is set to zero there is no limit.
14595
14596 When the body of any message that is to be included in a bounce message is
14597 greater than the limit, it is truncated, and a comment pointing this out is
14598 added at the top. The actual cutoff may be greater than the value given, owing
14599 to the use of buffering for transferring the message in chunks (typically 8K in
14600 size). The idea is to save bandwidth on those undeliverable 15-megabyte
14601 messages.
14602
14603 .option bounce_sender_authentication main string unset
14604 .cindex "bounce message" "sender authentication"
14605 .cindex "authentication" "bounce message"
14606 .cindex "AUTH" "on bounce message"
14607 This option provides an authenticated sender address that is sent with any
14608 bounce messages generated by Exim that are sent over an authenticated SMTP
14609 connection. A typical setting might be:
14610 .code
14611 bounce_sender_authentication = mailer-daemon@my.domain.example
14612 .endd
14613 which would cause bounce messages to be sent using the SMTP command:
14614 .code
14615 MAIL FROM:<> AUTH=mailer-daemon@my.domain.example
14616 .endd
14617 The value of &%bounce_sender_authentication%& must always be a complete email
14618 address.
14619
14620 .option callout_domain_negative_expire main time 3h
14621 .cindex "caching" "callout timeouts"
14622 .cindex "callout" "caching timeouts"
14623 This option specifies the expiry time for negative callout cache data for a
14624 domain. See section &<<SECTcallver>>& for details of callout verification, and
14625 section &<<SECTcallvercache>>& for details of the caching.
14626
14627
14628 .option callout_domain_positive_expire main time 7d
14629 This option specifies the expiry time for positive callout cache data for a
14630 domain. See section &<<SECTcallver>>& for details of callout verification, and
14631 section &<<SECTcallvercache>>& for details of the caching.
14632
14633
14634 .option callout_negative_expire main time 2h
14635 This option specifies the expiry time for negative callout cache data for an
14636 address. See section &<<SECTcallver>>& for details of callout verification, and
14637 section &<<SECTcallvercache>>& for details of the caching.
14638
14639
14640 .option callout_positive_expire main time 24h
14641 This option specifies the expiry time for positive callout cache data for an
14642 address. See section &<<SECTcallver>>& for details of callout verification, and
14643 section &<<SECTcallvercache>>& for details of the caching.
14644
14645
14646 .option callout_random_local_part main string&!! "see below"
14647 This option defines the &"random"& local part that can be used as part of
14648 callout verification. The default value is
14649 .code
14650 $primary_hostname-$tod_epoch-testing
14651 .endd
14652 See section &<<CALLaddparcall>>& for details of how this value is used.
14653
14654
14655 .option check_log_inodes main integer 100
14656 See &%check_spool_space%& below.
14657
14658
14659 .option check_log_space main integer 10M
14660 See &%check_spool_space%& below.
14661
14662 .oindex "&%check_rfc2047_length%&"
14663 .cindex "RFC 2047" "disabling length check"
14664 .option check_rfc2047_length main boolean true
14665 RFC 2047 defines a way of encoding non-ASCII characters in headers using a
14666 system of &"encoded words"&. The RFC specifies a maximum length for an encoded
14667 word; strings to be encoded that exceed this length are supposed to use
14668 multiple encoded words. By default, Exim does not recognize encoded words that
14669 exceed the maximum length. However, it seems that some software, in violation
14670 of the RFC, generates overlong encoded words. If &%check_rfc2047_length%& is
14671 set false, Exim recognizes encoded words of any length.
14672
14673
14674 .option check_spool_inodes main integer 100
14675 See &%check_spool_space%& below.
14676
14677
14678 .option check_spool_space main integer 10M
14679 .cindex "checking disk space"
14680 .cindex "disk space, checking"
14681 .cindex "spool directory" "checking space"
14682 The four &%check_...%& options allow for checking of disk resources before a
14683 message is accepted.
14684
14685 .vindex "&$log_inodes$&"
14686 .vindex "&$log_space$&"
14687 .vindex "&$spool_inodes$&"
14688 .vindex "&$spool_space$&"
14689 When any of these options are nonzero, they apply to all incoming messages. If you
14690 want to apply different checks to different kinds of message, you can do so by
14691 testing the variables &$log_inodes$&, &$log_space$&, &$spool_inodes$&, and
14692 &$spool_space$& in an ACL with appropriate additional conditions.
14693
14694
14695 &%check_spool_space%& and &%check_spool_inodes%& check the spool partition if
14696 either value is greater than zero, for example:
14697 .code
14698 check_spool_space = 100M
14699 check_spool_inodes = 100
14700 .endd
14701 The spool partition is the one that contains the directory defined by
14702 SPOOL_DIRECTORY in &_Local/Makefile_&. It is used for holding messages in
14703 transit.
14704
14705 &%check_log_space%& and &%check_log_inodes%&  check the partition in which log
14706 files are written if either is greater than zero. These should be set only if
14707 &%log_file_path%& and &%spool_directory%& refer to different partitions.
14708
14709 If there is less space or fewer inodes than requested, Exim refuses to accept
14710 incoming mail. In the case of SMTP input this is done by giving a 452 temporary
14711 error response to the MAIL command. If ESMTP is in use and there was a
14712 SIZE parameter on the MAIL command, its value is added to the
14713 &%check_spool_space%& value, and the check is performed even if
14714 &%check_spool_space%& is zero, unless &%no_smtp_check_spool_space%& is set.
14715
14716 The values for &%check_spool_space%& and &%check_log_space%& are held as a
14717 number of kilobytes (though specified in bytes).
14718 If a non-multiple of 1024 is specified, it is rounded up.
14719
14720 For non-SMTP input and for batched SMTP input, the test is done at start-up; on
14721 failure a message is written to stderr and Exim exits with a non-zero code, as
14722 it obviously cannot send an error message of any kind.
14723
14724 There is a slight performance penalty for these checks.
14725 Versions of Exim preceding 4.88 had these disabled by default;
14726 high-rate installations confident they will never run out of resources
14727 may wish to deliberately disable them.
14728
14729 .option chunking_advertise_hosts main "host list&!!" *
14730 .cindex CHUNKING advertisement
14731 .cindex "RFC 3030" "CHUNKING"
14732 The CHUNKING extension (RFC3030) will be advertised in the EHLO message to
14733 these hosts.
14734 Hosts may use the BDAT command as an alternate to DATA.
14735
14736 .option commandline_checks_require_admin main boolean &`false`&
14737 .cindex "restricting access to features"
14738 This option restricts various basic checking features to require an
14739 administrative user.
14740 This affects most of the &%-b*%& options, such as &%-be%&.
14741
14742 .option debug_store main boolean &`false`&
14743 .cindex debugging "memory corruption"
14744 .cindex memory debugging
14745 This option, when true, enables extra checking in Exim's internal memory
14746 management.  For use when a memory corruption issue is being investigated,
14747 it should normally be left as default.
14748
14749 .option daemon_smtp_ports main string &`smtp`&
14750 .cindex "port" "for daemon"
14751 .cindex "TCP/IP" "setting listening ports"
14752 This option specifies one or more default SMTP ports on which the Exim daemon
14753 listens. See chapter &<<CHAPinterfaces>>& for details of how it is used. For
14754 backward compatibility, &%daemon_smtp_port%& (singular) is a synonym.
14755
14756 .option daemon_startup_retries main integer 9
14757 .cindex "daemon startup, retrying"
14758 This option, along with &%daemon_startup_sleep%&, controls the retrying done by
14759 the daemon at startup when it cannot immediately bind a listening socket
14760 (typically because the socket is already in use): &%daemon_startup_retries%&
14761 defines the number of retries after the first failure, and
14762 &%daemon_startup_sleep%& defines the length of time to wait between retries.
14763
14764 .option daemon_startup_sleep main time 30s
14765 See &%daemon_startup_retries%&.
14766
14767 .option delay_warning main "time list" 24h
14768 .cindex "warning of delay"
14769 .cindex "delay warning, specifying"
14770 .cindex "queue" "delay warning"
14771 When a message is delayed, Exim sends a warning message to the sender at
14772 intervals specified by this option. The data is a colon-separated list of times
14773 after which to send warning messages. If the value of the option is an empty
14774 string or a zero time, no warnings are sent. Up to 10 times may be given. If a
14775 message has been on the queue for longer than the last time, the last interval
14776 between the times is used to compute subsequent warning times. For example,
14777 with
14778 .code
14779 delay_warning = 4h:8h:24h
14780 .endd
14781 the first message is sent after 4 hours, the second after 8 hours, and
14782 the third one after 24 hours. After that, messages are sent every 16 hours,
14783 because that is the interval between the last two times on the list. If you set
14784 just one time, it specifies the repeat interval. For example, with:
14785 .code
14786 delay_warning = 6h
14787 .endd
14788 messages are repeated every six hours. To stop warnings after a given time, set
14789 a very large time at the end of the list. For example:
14790 .code
14791 delay_warning = 2h:12h:99d
14792 .endd
14793 Note that the option is only evaluated at the time a delivery attempt fails,
14794 which depends on retry and queue-runner configuration.
14795 Typically retries will be configured more frequently than warning messages.
14796
14797 .option delay_warning_condition main string&!! "see below"
14798 .vindex "&$domain$&"
14799 The string is expanded at the time a warning message might be sent. If all the
14800 deferred addresses have the same domain, it is set in &$domain$& during the
14801 expansion. Otherwise &$domain$& is empty. If the result of the expansion is a
14802 forced failure, an empty string, or a string matching any of &"0"&, &"no"& or
14803 &"false"& (the comparison being done caselessly) then the warning message is
14804 not sent. The default is:
14805 .code
14806 delay_warning_condition = ${if or {\
14807   { !eq{$h_list-id:$h_list-post:$h_list-subscribe:}{} }\
14808   { match{$h_precedence:}{(?i)bulk|list|junk} }\
14809   { match{$h_auto-submitted:}{(?i)auto-generated|auto-replied} }\
14810   } {no}{yes}}
14811 .endd
14812 This suppresses the sending of warnings for messages that contain &'List-ID:'&,
14813 &'List-Post:'&, or &'List-Subscribe:'& headers, or have &"bulk"&, &"list"& or
14814 &"junk"& in a &'Precedence:'& header, or have &"auto-generated"& or
14815 &"auto-replied"& in an &'Auto-Submitted:'& header.
14816
14817 .option deliver_drop_privilege main boolean false
14818 .cindex "unprivileged delivery"
14819 .cindex "delivery" "unprivileged"
14820 If this option is set true, Exim drops its root privilege at the start of a
14821 delivery process, and runs as the Exim user throughout. This severely restricts
14822 the kinds of local delivery that are possible, but is viable in certain types
14823 of configuration. There is a discussion about the use of root privilege in
14824 chapter &<<CHAPsecurity>>&.
14825
14826 .option deliver_queue_load_max main fixed-point unset
14827 .cindex "load average"
14828 .cindex "queue runner" "abandoning"
14829 When this option is set, a queue run is abandoned if the system load average
14830 becomes greater than the value of the option. The option has no effect on
14831 ancient operating systems on which Exim cannot determine the load average.
14832 See also &%queue_only_load%& and &%smtp_load_reserve%&.
14833
14834
14835 .option delivery_date_remove main boolean true
14836 .cindex "&'Delivery-date:'& header line"
14837 Exim's transports have an option for adding a &'Delivery-date:'& header to a
14838 message when it is delivered, in exactly the same way as &'Return-path:'& is
14839 handled. &'Delivery-date:'& records the actual time of delivery. Such headers
14840 should not be present in incoming messages, and this option causes them to be
14841 removed at the time the message is received, to avoid any problems that might
14842 occur when a delivered message is subsequently sent on to some other recipient.
14843
14844 .option disable_fsync main boolean false
14845 .cindex "&[fsync()]&, disabling"
14846 This option is available only if Exim was built with the compile-time option
14847 ENABLE_DISABLE_FSYNC. When this is not set, a reference to &%disable_fsync%& in
14848 a runtime configuration generates an &"unknown option"& error. You should not
14849 build Exim with ENABLE_DISABLE_FSYNC or set &%disable_fsync%& unless you
14850 really, really, really understand what you are doing. &'No pre-compiled
14851 distributions of Exim should ever make this option available.'&
14852
14853 When &%disable_fsync%& is set true, Exim no longer calls &[fsync()]& to force
14854 updated files' data to be written to disc before continuing. Unexpected events
14855 such as crashes and power outages may cause data to be lost or scrambled.
14856 Here be Dragons. &*Beware.*&
14857
14858
14859 .option disable_ipv6 main boolean false
14860 .cindex "IPv6" "disabling"
14861 If this option is set true, even if the Exim binary has IPv6 support, no IPv6
14862 activities take place. AAAA records are never looked up, and any IPv6 addresses
14863 that are listed in &%local_interfaces%&, data for the &%manualroute%& router,
14864 etc. are ignored. If IP literals are enabled, the &(ipliteral)& router declines
14865 to handle IPv6 literal addresses.
14866
14867
14868 .option dkim_verify_signers main "domain list&!!" $dkim_signers
14869 .cindex DKIM "controlling calls to the ACL"
14870 This option gives a list of DKIM domains for which the DKIM ACL is run.
14871 It is expanded after the message is received; by default it runs
14872 the ACL once for each signature in the message.
14873 See section &<<SECDKIMVFY>>&.
14874
14875
14876 .option dns_again_means_nonexist main "domain list&!!" unset
14877 .cindex "DNS" "&""try again""& response; overriding"
14878 DNS lookups give a &"try again"& response for the DNS errors
14879 &"non-authoritative host not found"& and &"SERVERFAIL"&. This can cause Exim to
14880 keep trying to deliver a message, or to give repeated temporary errors to
14881 incoming mail. Sometimes the effect is caused by a badly set up name server and
14882 may persist for a long time. If a domain which exhibits this problem matches
14883 anything in &%dns_again_means_nonexist%&, it is treated as if it did not exist.
14884 This option should be used with care. You can make it apply to reverse lookups
14885 by a setting such as this:
14886 .code
14887 dns_again_means_nonexist = *.in-addr.arpa
14888 .endd
14889 This option applies to all DNS lookups that Exim does. It also applies when the
14890 &[gethostbyname()]& or &[getipnodebyname()]& functions give temporary errors,
14891 since these are most likely to be caused by DNS lookup problems. The
14892 &(dnslookup)& router has some options of its own for controlling what happens
14893 when lookups for MX or SRV records give temporary errors. These more specific
14894 options are applied after this global option.
14895
14896 .option dns_check_names_pattern main string "see below"
14897 .cindex "DNS" "pre-check of name syntax"
14898 When this option is set to a non-empty string, it causes Exim to check domain
14899 names for characters that are not allowed in host names before handing them to
14900 the DNS resolver, because some resolvers give temporary errors for names that
14901 contain unusual characters. If a domain name contains any unwanted characters,
14902 a &"not found"& result is forced, and the resolver is not called. The check is
14903 done by matching the domain name against a regular expression, which is the
14904 value of this option. The default pattern is
14905 .code
14906 dns_check_names_pattern = \
14907   (?i)^(?>(?(1)\.|())[^\W_](?>[a-z0-9/-]*[^\W_])?)+$
14908 .endd
14909 which permits only letters, digits, slashes, and hyphens in components, but
14910 they must start and end with a letter or digit. Slashes are not, in fact,
14911 permitted in host names, but they are found in certain NS records (which can be
14912 accessed in Exim by using a &%dnsdb%& lookup). If you set
14913 &%allow_utf8_domains%&, you must modify this pattern, or set the option to an
14914 empty string.
14915
14916 .option dns_csa_search_limit main integer 5
14917 This option controls the depth of parental searching for CSA SRV records in the
14918 DNS, as described in more detail in section &<<SECTverifyCSA>>&.
14919
14920 .option dns_csa_use_reverse main boolean true
14921 This option controls whether or not an IP address, given as a CSA domain, is
14922 reversed and looked up in the reverse DNS, as described in more detail in
14923 section &<<SECTverifyCSA>>&.
14924
14925 .new
14926 .option dns_cname_loops main integer 1
14927 .cindex DNS "CNAME following"
14928 This option controls the following of CNAME chains, needed if the resolver does
14929 not do it internally.
14930 As of 2018 most should, and the default can be left.
14931 If you have an ancient one, a value of 10 is likely needed.
14932
14933 The default value of one CNAME-follow is needed
14934 thanks to the observed return for an MX request,
14935 given no MX presence but a CNAME to an A, of the CNAME.
14936 .wen
14937
14938
14939 .option dns_dnssec_ok main integer -1
14940 .cindex "DNS" "resolver options"
14941 .cindex "DNS" "DNSSEC"
14942 If this option is set to a non-negative number then Exim will initialise the
14943 DNS resolver library to either use or not use DNSSEC, overriding the system
14944 default. A value of 0 coerces DNSSEC off, a value of 1 coerces DNSSEC on.
14945
14946 If the resolver library does not support DNSSEC then this option has no effect.
14947
14948
14949 .option dns_ipv4_lookup main "domain list&!!" unset
14950 .cindex "IPv6" "DNS lookup for AAAA records"
14951 .cindex "DNS" "IPv6 lookup for AAAA records"
14952 .cindex DNS "IPv6 disabling"
14953 When Exim is compiled with IPv6 support and &%disable_ipv6%& is not set, it
14954 looks for IPv6 address records (AAAA records) as well as IPv4 address records
14955 (A records) when trying to find IP addresses for hosts, unless the host's
14956 domain matches this list.
14957
14958 This is a fudge to help with name servers that give big delays or otherwise do
14959 not work for the AAAA record type. In due course, when the world's name
14960 servers have all been upgraded, there should be no need for this option.
14961
14962
14963 .option dns_retrans main time 0s
14964 .cindex "DNS" "resolver options"
14965 .cindex timeout "dns lookup"
14966 .cindex "DNS" timeout
14967 The options &%dns_retrans%& and &%dns_retry%& can be used to set the
14968 retransmission and retry parameters for DNS lookups. Values of zero (the
14969 defaults) leave the system default settings unchanged. The first value is the
14970 time between retries, and the second is the number of retries. It isn't
14971 totally clear exactly how these settings affect the total time a DNS lookup may
14972 take. I haven't found any documentation about timeouts on DNS lookups; these
14973 parameter values are available in the external resolver interface structure,
14974 but nowhere does it seem to describe how they are used or what you might want
14975 to set in them.
14976 See also the &%slow_lookup_log%& option.
14977
14978
14979 .option dns_retry main integer 0
14980 See &%dns_retrans%& above.
14981
14982
14983 .option dns_trust_aa main "domain list&!!" unset
14984 .cindex "DNS" "resolver options"
14985 .cindex "DNS" "DNSSEC"
14986 If this option is set then lookup results marked with the AA bit
14987 (Authoritative Answer) are trusted the same way as if they were
14988 DNSSEC-verified. The authority section's name of the answer must
14989 match with this expanded domain list.
14990
14991 Use this option only if you talk directly to a resolver that is
14992 authoritative for some zones and does not set the AD (Authentic Data)
14993 bit in the answer. Some DNS servers may have an configuration option to
14994 mark the answers from their own zones as verified (they set the AD bit).
14995 Others do not have this option. It is considered as poor practice using
14996 a resolver that is an authoritative server for some zones.
14997
14998 Use this option only if you really have to (e.g. if you want
14999 to use DANE for remote delivery to a server that is listed in the DNS
15000 zones that your resolver is authoritative for).
15001
15002 If the DNS answer packet has the AA bit set and contains resource record
15003 in the answer section, the name of the first NS record appearing in the
15004 authority section is compared against the list. If the answer packet is
15005 authoritative but the answer section is empty, the name of the first SOA
15006 record in the authoritative section is used instead.
15007
15008 .cindex "DNS" "resolver options"
15009 .option dns_use_edns0 main integer -1
15010 .cindex "DNS" "resolver options"
15011 .cindex "DNS" "EDNS0"
15012 .cindex "DNS" "OpenBSD
15013 If this option is set to a non-negative number then Exim will initialise the
15014 DNS resolver library to either use or not use EDNS0 extensions, overriding
15015 the system default. A value of 0 coerces EDNS0 off, a value of 1 coerces EDNS0
15016 on.
15017
15018 If the resolver library does not support EDNS0 then this option has no effect.
15019
15020 OpenBSD's asr resolver routines are known to ignore the EDNS0 option; this
15021 means that DNSSEC will not work with Exim on that platform either, unless Exim
15022 is linked against an alternative DNS client library.
15023
15024
15025 .option drop_cr main boolean false
15026 This is an obsolete option that is now a no-op. It used to affect the way Exim
15027 handled CR and LF characters in incoming messages. What happens now is
15028 described in section &<<SECTlineendings>>&.
15029
15030 .option dsn_advertise_hosts main "host list&!!" unset
15031 .cindex "bounce messages" "success"
15032 .cindex "DSN" "success"
15033 .cindex "Delivery Status Notification" "success"
15034 DSN extensions (RFC3461) will be advertised in the EHLO message to,
15035 and accepted from, these hosts.
15036 Hosts may use the NOTIFY and ENVID options on RCPT TO commands,
15037 and RET and ORCPT options on MAIL FROM commands.
15038 A NOTIFY=SUCCESS option requests success-DSN messages.
15039 A NOTIFY= option with no argument requests that no delay or failure DSNs
15040 are sent.
15041
15042 .option dsn_from main "string&!!" "see below"
15043 .cindex "&'From:'& header line" "in bounces"
15044 .cindex "bounce messages" "&'From:'& line, specifying"
15045 This option can be used to vary the contents of &'From:'& header lines in
15046 bounces and other automatically generated messages (&"Delivery Status
15047 Notifications"& &-- hence the name of the option). The default setting is:
15048 .code
15049 dsn_from = Mail Delivery System <Mailer-Daemon@$qualify_domain>
15050 .endd
15051 The value is expanded every time it is needed. If the expansion fails, a
15052 panic is logged, and the default value is used.
15053
15054 .option envelope_to_remove main boolean true
15055 .cindex "&'Envelope-to:'& header line"
15056 Exim's transports have an option for adding an &'Envelope-to:'& header to a
15057 message when it is delivered, in exactly the same way as &'Return-path:'& is
15058 handled. &'Envelope-to:'& records the original recipient address from the
15059 message's envelope that caused the delivery to happen. Such headers should not
15060 be present in incoming messages, and this option causes them to be removed at
15061 the time the message is received, to avoid any problems that might occur when a
15062 delivered message is subsequently sent on to some other recipient.
15063
15064
15065 .option errors_copy main "string list&!!" unset
15066 .cindex "bounce message" "copy to other address"
15067 .cindex "copy of bounce message"
15068 Setting this option causes Exim to send bcc copies of bounce messages that it
15069 generates to other addresses. &*Note*&: This does not apply to bounce messages
15070 coming from elsewhere. The value of the option is a colon-separated list of
15071 items. Each item consists of a pattern, terminated by white space, followed by
15072 a comma-separated list of email addresses. If a pattern contains spaces, it
15073 must be enclosed in double quotes.
15074
15075 Each pattern is processed in the same way as a single item in an address list
15076 (see section &<<SECTaddresslist>>&). When a pattern matches the recipient of
15077 the bounce message, the message is copied to the addresses on the list. The
15078 items are scanned in order, and once a matching one is found, no further items
15079 are examined. For example:
15080 .code
15081 errors_copy = spqr@mydomain   postmaster@mydomain.example :\
15082               rqps@mydomain   hostmaster@mydomain.example,\
15083                               postmaster@mydomain.example
15084 .endd
15085 .vindex "&$domain$&"
15086 .vindex "&$local_part$&"
15087 The address list is expanded before use. The expansion variables &$local_part$&
15088 and &$domain$& are set from the original recipient of the error message, and if
15089 there was any wildcard matching in the pattern, the expansion
15090 .cindex "numerical variables (&$1$& &$2$& etc)" "in &%errors_copy%&"
15091 variables &$0$&, &$1$&, etc. are set in the normal way.
15092
15093
15094 .option errors_reply_to main string unset
15095 .cindex "bounce message" "&'Reply-to:'& in"
15096 By default, Exim's bounce and delivery warning messages contain the header line
15097 .display
15098 &`From: Mail Delivery System <Mailer-Daemon@`&&'qualify-domain'&&`>`&
15099 .endd
15100 .oindex &%quota_warn_message%&
15101 where &'qualify-domain'& is the value of the &%qualify_domain%& option.
15102 A warning message that is generated by the &%quota_warn_message%& option in an
15103 &(appendfile)& transport may contain its own &'From:'& header line that
15104 overrides the default.
15105
15106 Experience shows that people reply to bounce messages. If the
15107 &%errors_reply_to%& option is set, a &'Reply-To:'& header is added to bounce
15108 and warning messages. For example:
15109 .code
15110 errors_reply_to = postmaster@my.domain.example
15111 .endd
15112 The value of the option is not expanded. It must specify a valid RFC 2822
15113 address. However, if a warning message that is generated by the
15114 &%quota_warn_message%& option in an &(appendfile)& transport contain its
15115 own &'Reply-To:'& header line, the value of the &%errors_reply_to%& option is
15116 not used.
15117
15118
15119 .option event_action main string&!! unset
15120 .cindex events
15121 This option declares a string to be expanded for Exim's events mechanism.
15122 For details see chapter &<<CHAPevents>>&.
15123
15124
15125 .option exim_group main string "compile-time configured"
15126 .cindex "gid (group id)" "Exim's own"
15127 .cindex "Exim group"
15128 This option changes the gid under which Exim runs when it gives up root
15129 privilege. The default value is compiled into the binary. The value of this
15130 option is used only when &%exim_user%& is also set. Unless it consists entirely
15131 of digits, the string is looked up using &[getgrnam()]&, and failure causes a
15132 configuration error. See chapter &<<CHAPsecurity>>& for a discussion of
15133 security issues.
15134
15135
15136 .option exim_path main string "see below"
15137 .cindex "Exim binary, path name"
15138 This option specifies the path name of the Exim binary, which is used when Exim
15139 needs to re-exec itself. The default is set up to point to the file &'exim'& in
15140 the directory configured at compile time by the BIN_DIRECTORY setting. It
15141 is necessary to change &%exim_path%& if, exceptionally, Exim is run from some
15142 other place.
15143 &*Warning*&: Do not use a macro to define the value of this option, because
15144 you will break those Exim utilities that scan the configuration file to find
15145 where the binary is. (They then use the &%-bP%& option to extract option
15146 settings such as the value of &%spool_directory%&.)
15147
15148
15149 .option exim_user main string "compile-time configured"
15150 .cindex "uid (user id)" "Exim's own"
15151 .cindex "Exim user"
15152 This option changes the uid under which Exim runs when it gives up root
15153 privilege. The default value is compiled into the binary. Ownership of the run
15154 time configuration file and the use of the &%-C%& and &%-D%& command line
15155 options is checked against the values in the binary, not what is set here.
15156
15157 Unless it consists entirely of digits, the string is looked up using
15158 &[getpwnam()]&, and failure causes a configuration error. If &%exim_group%& is
15159 not also supplied, the gid is taken from the result of &[getpwnam()]& if it is
15160 used. See chapter &<<CHAPsecurity>>& for a discussion of security issues.
15161
15162
15163 .option extra_local_interfaces main "string list" unset
15164 This option defines network interfaces that are to be considered local when
15165 routing, but which are not used for listening by the daemon. See section
15166 &<<SECTreclocipadd>>& for details.
15167
15168
15169 . Allow this long option name to split; give it unsplit as a fifth argument
15170 . for the automatic .oindex that is generated by .option.
15171
15172 .option "extract_addresses_remove_arguments" main boolean true &&&
15173          extract_addresses_remove_arguments
15174 .oindex "&%-t%&"
15175 .cindex "command line" "addresses with &%-t%&"
15176 .cindex "Sendmail compatibility" "&%-t%& option"
15177 According to some Sendmail documentation (Sun, IRIX, HP-UX), if any addresses
15178 are present on the command line when the &%-t%& option is used to build an
15179 envelope from a message's &'To:'&, &'Cc:'& and &'Bcc:'& headers, the command
15180 line addresses are removed from the recipients list. This is also how Smail
15181 behaves. However, other Sendmail documentation (the O'Reilly book) states that
15182 command line addresses are added to those obtained from the header lines. When
15183 &%extract_addresses_remove_arguments%& is true (the default), Exim subtracts
15184 argument headers. If it is set false, Exim adds rather than removes argument
15185 addresses.
15186
15187
15188 .option finduser_retries main integer 0
15189 .cindex "NIS, retrying user lookups"
15190 On systems running NIS or other schemes in which user and group information is
15191 distributed from a remote system, there can be times when &[getpwnam()]& and
15192 related functions fail, even when given valid data, because things time out.
15193 Unfortunately these failures cannot be distinguished from genuine &"not found"&
15194 errors. If &%finduser_retries%& is set greater than zero, Exim will try that
15195 many extra times to find a user or a group, waiting for one second between
15196 retries.
15197
15198 .cindex "&_/etc/passwd_&" "multiple reading of"
15199 You should not set this option greater than zero if your user information is in
15200 a traditional &_/etc/passwd_& file, because it will cause Exim needlessly to
15201 search the file multiple times for non-existent users, and also cause delay.
15202
15203
15204
15205 .option freeze_tell main "string list, comma separated" unset
15206 .cindex "freezing messages" "sending a message when freezing"
15207 On encountering certain errors, or when configured to do so in a system filter,
15208 ACL, or special router, Exim freezes a message. This means that no further
15209 delivery attempts take place until an administrator thaws the message, or the
15210 &%auto_thaw%&, &%ignore_bounce_errors_after%&, or &%timeout_frozen_after%&
15211 feature cause it to be processed. If &%freeze_tell%& is set, Exim generates a
15212 warning message whenever it freezes something, unless the message it is
15213 freezing is a locally-generated bounce message. (Without this exception there
15214 is the possibility of looping.) The warning message is sent to the addresses
15215 supplied as the comma-separated value of this option. If several of the
15216 message's addresses cause freezing, only a single message is sent. If the
15217 freezing was automatic, the reason(s) for freezing can be found in the message
15218 log. If you configure freezing in a filter or ACL, you must arrange for any
15219 logging that you require.
15220
15221
15222 .option gecos_name main string&!! unset
15223 .cindex "HP-UX"
15224 .cindex "&""gecos""& field, parsing"
15225 Some operating systems, notably HP-UX, use the &"gecos"& field in the system
15226 password file to hold other information in addition to users' real names. Exim
15227 looks up this field for use when it is creating &'Sender:'& or &'From:'&
15228 headers. If either &%gecos_pattern%& or &%gecos_name%& are unset, the contents
15229 of the field are used unchanged, except that, if an ampersand is encountered,
15230 it is replaced by the user's login name with the first character forced to
15231 upper case, since this is a convention that is observed on many systems.
15232
15233 When these options are set, &%gecos_pattern%& is treated as a regular
15234 expression that is to be applied to the field (again with && replaced by the
15235 login name), and if it matches, &%gecos_name%& is expanded and used as the
15236 user's name.
15237
15238 .cindex "numerical variables (&$1$& &$2$& etc)" "in &%gecos_name%&"
15239 Numeric variables such as &$1$&, &$2$&, etc. can be used in the expansion to
15240 pick up sub-fields that were matched by the pattern. In HP-UX, where the user's
15241 name terminates at the first comma, the following can be used:
15242 .code
15243 gecos_pattern = ([^,]*)
15244 gecos_name = $1
15245 .endd
15246
15247 .option gecos_pattern main string unset
15248 See &%gecos_name%& above.
15249
15250
15251 .option gnutls_compat_mode main boolean unset
15252 This option controls whether GnuTLS is used in compatibility mode in an Exim
15253 server. This reduces security slightly, but improves interworking with older
15254 implementations of TLS.
15255
15256
15257 .option gnutls_allow_auto_pkcs11 main boolean unset
15258 This option will let GnuTLS (2.12.0 or later) autoload PKCS11 modules with
15259 the p11-kit configuration files in &_/etc/pkcs11/modules/_&.
15260
15261 See
15262 &url(https://www.gnutls.org/manual/gnutls.html#Smart-cards-and-HSMs)
15263 for documentation.
15264
15265
15266
15267 .option headers_charset main string "see below"
15268 This option sets a default character set for translating from encoded MIME
15269 &"words"& in header lines, when referenced by an &$h_xxx$& expansion item. The
15270 default is the value of HEADERS_CHARSET in &_Local/Makefile_&. The
15271 ultimate default is ISO-8859-1. For more details see the description of header
15272 insertions in section &<<SECTexpansionitems>>&.
15273
15274
15275
15276 .option header_maxsize main integer "see below"
15277 .cindex "header section" "maximum size of"
15278 .cindex "limit" "size of message header section"
15279 This option controls the overall maximum size of a message's header
15280 section. The default is the value of HEADER_MAXSIZE in
15281 &_Local/Makefile_&; the default for that is 1M. Messages with larger header
15282 sections are rejected.
15283
15284
15285 .option header_line_maxsize main integer 0
15286 .cindex "header lines" "maximum size of"
15287 .cindex "limit" "size of one header line"
15288 This option limits the length of any individual header line in a message, after
15289 all the continuations have been joined together. Messages with individual
15290 header lines that are longer than the limit are rejected. The default value of
15291 zero means &"no limit"&.
15292
15293
15294
15295
15296 .option helo_accept_junk_hosts main "host list&!!" unset
15297 .cindex "HELO" "accepting junk data"
15298 .cindex "EHLO" "accepting junk data"
15299 Exim checks the syntax of HELO and EHLO commands for incoming SMTP
15300 mail, and gives an error response for invalid data. Unfortunately, there are
15301 some SMTP clients that send syntactic junk. They can be accommodated by setting
15302 this option. Note that this is a syntax check only. See &%helo_verify_hosts%&
15303 if you want to do semantic checking.
15304 See also &%helo_allow_chars%& for a way of extending the permitted character
15305 set.
15306
15307
15308 .option helo_allow_chars main string unset
15309 .cindex "HELO" "underscores in"
15310 .cindex "EHLO" "underscores in"
15311 .cindex "underscore in EHLO/HELO"
15312 This option can be set to a string of rogue characters that are permitted in
15313 all EHLO and HELO names in addition to the standard letters, digits,
15314 hyphens, and dots. If you really must allow underscores, you can set
15315 .code
15316 helo_allow_chars = _
15317 .endd
15318 Note that the value is one string, not a list.
15319
15320
15321 .option helo_lookup_domains main "domain list&!!" &`@:@[]`&
15322 .cindex "HELO" "forcing reverse lookup"
15323 .cindex "EHLO" "forcing reverse lookup"
15324 If the domain given by a client in a HELO or EHLO command matches this
15325 list, a reverse lookup is done in order to establish the host's true name. The
15326 default forces a lookup if the client host gives the server's name or any of
15327 its IP addresses (in brackets), something that broken clients have been seen to
15328 do.
15329
15330
15331 .option helo_try_verify_hosts main "host list&!!" unset
15332 .cindex "HELO verifying" "optional"
15333 .cindex "EHLO" "verifying, optional"
15334 By default, Exim just checks the syntax of HELO and EHLO commands (see
15335 &%helo_accept_junk_hosts%& and &%helo_allow_chars%&). However, some sites like
15336 to do more extensive checking of the data supplied by these commands. The ACL
15337 condition &`verify = helo`& is provided to make this possible.
15338 Formerly, it was necessary also to set this option (&%helo_try_verify_hosts%&)
15339 to force the check to occur. From release 4.53 onwards, this is no longer
15340 necessary. If the check has not been done before &`verify = helo`& is
15341 encountered, it is done at that time. Consequently, this option is obsolete.
15342 Its specification is retained here for backwards compatibility.
15343
15344 When an EHLO or HELO command is received, if the calling host matches
15345 &%helo_try_verify_hosts%&, Exim checks that the host name given in the HELO or
15346 EHLO command either:
15347
15348 .ilist
15349 is an IP literal matching the calling address of the host, or
15350 .next
15351 .cindex "DNS" "reverse lookup"
15352 .cindex "reverse DNS lookup"
15353 matches the host name that Exim obtains by doing a reverse lookup of the
15354 calling host address, or
15355 .next
15356 when looked up in DNS yields the calling host address.
15357 .endlist
15358
15359 However, the EHLO or HELO command is not rejected if any of the checks
15360 fail. Processing continues, but the result of the check is remembered, and can
15361 be detected later in an ACL by the &`verify = helo`& condition.
15362
15363 If DNS was used for successful verification, the variable
15364 .cindex "DNS" "DNSSEC"
15365 &$helo_verify_dnssec$& records the DNSSEC status of the lookups.
15366
15367 .option helo_verify_hosts main "host list&!!" unset
15368 .cindex "HELO verifying" "mandatory"
15369 .cindex "EHLO" "verifying, mandatory"
15370 Like &%helo_try_verify_hosts%&, this option is obsolete, and retained only for
15371 backwards compatibility. For hosts that match this option, Exim checks the host
15372 name given in the HELO or EHLO in the same way as for
15373 &%helo_try_verify_hosts%&. If the check fails, the HELO or EHLO command is
15374 rejected with a 550 error, and entries are written to the main and reject logs.
15375 If a MAIL command is received before EHLO or HELO, it is rejected with a 503
15376 error.
15377
15378 .option hold_domains main "domain list&!!" unset
15379 .cindex "domain" "delaying delivery"
15380 .cindex "delivery" "delaying certain domains"
15381 This option allows mail for particular domains to be held on the queue
15382 manually. The option is overridden if a message delivery is forced with the
15383 &%-M%&, &%-qf%&, &%-Rf%& or &%-Sf%& options, and also while testing or
15384 verifying addresses using &%-bt%& or &%-bv%&. Otherwise, if a domain matches an
15385 item in &%hold_domains%&, no routing or delivery for that address is done, and
15386 it is deferred every time the message is looked at.
15387
15388 This option is intended as a temporary operational measure for delaying the
15389 delivery of mail while some problem is being sorted out, or some new
15390 configuration tested. If you just want to delay the processing of some
15391 domains until a queue run occurs, you should use &%queue_domains%& or
15392 &%queue_smtp_domains%&, not &%hold_domains%&.
15393
15394 A setting of &%hold_domains%& does not override Exim's code for removing
15395 messages from the queue if they have been there longer than the longest retry
15396 time in any retry rule. If you want to hold messages for longer than the normal
15397 retry times, insert a dummy retry rule with a long retry time.
15398
15399
15400 .option host_lookup main "host list&!!" unset
15401 .cindex "host name" "lookup, forcing"
15402 Exim does not look up the name of a calling host from its IP address unless it
15403 is required to compare against some host list, or the host matches
15404 &%helo_try_verify_hosts%& or &%helo_verify_hosts%&, or the host matches this
15405 option (which normally contains IP addresses rather than host names). The
15406 default configuration file contains
15407 .code
15408 host_lookup = *
15409 .endd
15410 which causes a lookup to happen for all hosts. If the expense of these lookups
15411 is felt to be too great, the setting can be changed or removed.
15412
15413 After a successful reverse lookup, Exim does a forward lookup on the name it
15414 has obtained, to verify that it yields the IP address that it started with. If
15415 this check fails, Exim behaves as if the name lookup failed.
15416
15417 .vindex "&$host_lookup_failed$&"
15418 .vindex "&$sender_host_name$&"
15419 After any kind of failure, the host name (in &$sender_host_name$&) remains
15420 unset, and &$host_lookup_failed$& is set to the string &"1"&. See also
15421 &%dns_again_means_nonexist%&, &%helo_lookup_domains%&, and
15422 &`verify = reverse_host_lookup`& in ACLs.
15423
15424
15425 .option host_lookup_order main "string list" &`bydns:byaddr`&
15426 This option specifies the order of different lookup methods when Exim is trying
15427 to find a host name from an IP address. The default is to do a DNS lookup
15428 first, and then to try a local lookup (using &[gethostbyaddr()]& or equivalent)
15429 if that fails. You can change the order of these lookups, or omit one entirely,
15430 if you want.
15431
15432 &*Warning*&: The &"byaddr"& method does not always yield aliases when there are
15433 multiple PTR records in the DNS and the IP address is not listed in
15434 &_/etc/hosts_&. Different operating systems give different results in this
15435 case. That is why the default tries a DNS lookup first.
15436
15437
15438
15439 .option host_reject_connection main "host list&!!" unset
15440 .cindex "host" "rejecting connections from"
15441 If this option is set, incoming SMTP calls from the hosts listed are rejected
15442 as soon as the connection is made.
15443 This option is obsolete, and retained only for backward compatibility, because
15444 nowadays the ACL specified by &%acl_smtp_connect%& can also reject incoming
15445 connections immediately.
15446
15447 The ability to give an immediate rejection (either by this option or using an
15448 ACL) is provided for use in unusual cases. Many hosts will just try again,
15449 sometimes without much delay. Normally, it is better to use an ACL to reject
15450 incoming messages at a later stage, such as after RCPT commands. See
15451 chapter &<<CHAPACL>>&.
15452
15453
15454 .option hosts_connection_nolog main "host list&!!" unset
15455 .cindex "host" "not logging connections from"
15456 This option defines a list of hosts for which connection logging does not
15457 happen, even though the &%smtp_connection%& log selector is set. For example,
15458 you might want not to log SMTP connections from local processes, or from
15459 127.0.0.1, or from your local LAN. This option is consulted in the main loop of
15460 the daemon; you should therefore strive to restrict its value to a short inline
15461 list of IP addresses and networks. To disable logging SMTP connections from
15462 local processes, you must create a host list with an empty item. For example:
15463 .code
15464 hosts_connection_nolog = :
15465 .endd
15466 If the &%smtp_connection%& log selector is not set, this option has no effect.
15467
15468
15469
15470 .option hosts_proxy main "host list&!!" unset
15471 .cindex proxy "proxy protocol"
15472 This option enables use of Proxy Protocol proxies for incoming
15473 connections.  For details see section &<<SECTproxyInbound>>&.
15474
15475
15476 .option hosts_treat_as_local main "domain list&!!" unset
15477 .cindex "local host" "domains treated as"
15478 .cindex "host" "treated as local"
15479 If this option is set, any host names that match the domain list are treated as
15480 if they were the local host when Exim is scanning host lists obtained from MX
15481 records
15482 or other sources. Note that the value of this option is a domain list, not a
15483 host list, because it is always used to check host names, not IP addresses.
15484
15485 This option also applies when Exim is matching the special items
15486 &`@mx_any`&, &`@mx_primary`&, and &`@mx_secondary`& in a domain list (see
15487 section &<<SECTdomainlist>>&), and when checking the &%hosts%& option in the
15488 &(smtp)& transport for the local host (see the &%allow_localhost%& option in
15489 that transport). See also &%local_interfaces%&, &%extra_local_interfaces%&, and
15490 chapter &<<CHAPinterfaces>>&, which contains a discussion about local network
15491 interfaces and recognizing the local host.
15492
15493
15494 .option ibase_servers main "string list" unset
15495 .cindex "InterBase" "server list"
15496 This option provides a list of InterBase servers and associated connection data,
15497 to be used in conjunction with &(ibase)& lookups (see section &<<SECID72>>&).
15498 The option is available only if Exim has been built with InterBase support.
15499
15500
15501
15502 .option ignore_bounce_errors_after main time 10w
15503 .cindex "bounce message" "discarding"
15504 .cindex "discarding bounce message"
15505 This option affects the processing of bounce messages that cannot be delivered,
15506 that is, those that suffer a permanent delivery failure. (Bounce messages that
15507 suffer temporary delivery failures are of course retried in the usual way.)
15508
15509 After a permanent delivery failure, bounce messages are frozen,
15510 because there is no sender to whom they can be returned. When a frozen bounce
15511 message has been on the queue for more than the given time, it is unfrozen at
15512 the next queue run, and a further delivery is attempted. If delivery fails
15513 again, the bounce message is discarded. This makes it possible to keep failed
15514 bounce messages around for a shorter time than the normal maximum retry time
15515 for frozen messages. For example,
15516 .code
15517 ignore_bounce_errors_after = 12h
15518 .endd
15519 retries failed bounce message deliveries after 12 hours, discarding any further
15520 failures. If the value of this option is set to a zero time period, bounce
15521 failures are discarded immediately. Setting a very long time (as in the default
15522 value) has the effect of disabling this option. For ways of automatically
15523 dealing with other kinds of frozen message, see &%auto_thaw%& and
15524 &%timeout_frozen_after%&.
15525
15526
15527 .option ignore_fromline_hosts main "host list&!!" unset
15528 .cindex "&""From""& line"
15529 .cindex "UUCP" "&""From""& line"
15530 Some broken SMTP clients insist on sending a UUCP-like &"From&~"& line before
15531 the headers of a message. By default this is treated as the start of the
15532 message's body, which means that any following headers are not recognized as
15533 such. Exim can be made to ignore it by setting &%ignore_fromline_hosts%& to
15534 match those hosts that insist on sending it. If the sender is actually a local
15535 process rather than a remote host, and is using &%-bs%& to inject the messages,
15536 &%ignore_fromline_local%& must be set to achieve this effect.
15537
15538
15539 .option ignore_fromline_local main boolean false
15540 See &%ignore_fromline_hosts%& above.
15541
15542 .option keep_environment main "string list" unset
15543 .cindex "environment" "values from"
15544 This option contains a string list of environment variables to keep.
15545 You have to trust these variables or you have to be sure that
15546 these variables do not impose any security risk. Keep in mind that
15547 during the startup phase Exim is running with an effective UID 0 in most
15548 installations. As the default value is an empty list, the default
15549 environment for using libraries, running embedded Perl code, or running
15550 external binaries is empty, and does not not even contain PATH or HOME.
15551
15552 Actually the list is interpreted as a list of patterns
15553 (&<<SECTlistexpand>>&), except that it is not expanded first.
15554
15555 WARNING: Macro substitution is still done first, so having a macro
15556 FOO and having FOO_HOME in your &%keep_environment%& option may have
15557 unexpected results. You may work around this using a regular expression
15558 that does not match the macro name: ^[F]OO_HOME$.
15559
15560 Current versions of Exim issue a warning during startup if you do not mention
15561 &%keep_environment%& in your runtime configuration file and if your
15562 current environment is not empty. Future versions may not issue that warning
15563 anymore.
15564
15565 See the &%add_environment%& main config option for a way to set
15566 environment variables to a fixed value.  The environment for &(pipe)&
15567 transports is handled separately, see section &<<SECTpipeenv>>& for
15568 details.
15569
15570
15571 .option keep_malformed main time 4d
15572 This option specifies the length of time to keep messages whose spool files
15573 have been corrupted in some way. This should, of course, never happen. At the
15574 next attempt to deliver such a message, it gets removed. The incident is
15575 logged.
15576
15577
15578 .option ldap_ca_cert_dir main string unset
15579 .cindex "LDAP", "TLS CA certificate directory"
15580 .cindex certificate "directory for LDAP"
15581 This option indicates which directory contains CA certificates for verifying
15582 a TLS certificate presented by an LDAP server.
15583 While Exim does not provide a default value, your SSL library may.
15584 Analogous to &%tls_verify_certificates%& but as a client-side option for LDAP
15585 and constrained to be a directory.
15586
15587
15588 .option ldap_ca_cert_file main string unset
15589 .cindex "LDAP", "TLS CA certificate file"
15590 .cindex certificate "file for LDAP"
15591 This option indicates which file contains CA certificates for verifying
15592 a TLS certificate presented by an LDAP server.
15593 While Exim does not provide a default value, your SSL library may.
15594 Analogous to &%tls_verify_certificates%& but as a client-side option for LDAP
15595 and constrained to be a file.
15596
15597
15598 .option ldap_cert_file main string unset
15599 .cindex "LDAP" "TLS client certificate file"
15600 .cindex certificate "file for LDAP"
15601 This option indicates which file contains an TLS client certificate which
15602 Exim should present to the LDAP server during TLS negotiation.
15603 Should be used together with &%ldap_cert_key%&.
15604
15605
15606 .option ldap_cert_key main string unset
15607 .cindex "LDAP" "TLS client key file"
15608 .cindex certificate "key for LDAP"
15609 This option indicates which file contains the secret/private key to use
15610 to prove identity to the LDAP server during TLS negotiation.
15611 Should be used together with &%ldap_cert_file%&, which contains the
15612 identity to be proven.
15613
15614
15615 .option ldap_cipher_suite main string unset
15616 .cindex "LDAP" "TLS cipher suite"
15617 This controls the TLS cipher-suite negotiation during TLS negotiation with
15618 the LDAP server.  See &<<SECTreqciphssl>>& for more details of the format of
15619 cipher-suite options with OpenSSL (as used by LDAP client libraries).
15620
15621
15622 .option ldap_default_servers main "string list" unset
15623 .cindex "LDAP" "default servers"
15624 This option provides a list of LDAP servers which are tried in turn when an
15625 LDAP query does not contain a server. See section &<<SECTforldaque>>& for
15626 details of LDAP queries. This option is available only when Exim has been built
15627 with LDAP support.
15628
15629
15630 .option ldap_require_cert main string unset.
15631 .cindex "LDAP" "policy for LDAP server TLS cert presentation"
15632 This should be one of the values "hard", "demand", "allow", "try" or "never".
15633 A value other than one of these is interpreted as "never".
15634 See the entry "TLS_REQCERT" in your system man page for ldap.conf(5).
15635 Although Exim does not set a default, the LDAP library probably defaults
15636 to hard/demand.
15637
15638
15639 .option ldap_start_tls main boolean false
15640 .cindex "LDAP" "whether or not to negotiate TLS"
15641 If set, Exim will attempt to negotiate TLS with the LDAP server when
15642 connecting on a regular LDAP port.  This is the LDAP equivalent of SMTP's
15643 "STARTTLS".  This is distinct from using "ldaps", which is the LDAP form
15644 of SSL-on-connect.
15645 In the event of failure to negotiate TLS, the action taken is controlled
15646 by &%ldap_require_cert%&.
15647 This option is ignored for &`ldapi`& connections.
15648
15649
15650 .option ldap_version main integer unset
15651 .cindex "LDAP" "protocol version, forcing"
15652 This option can be used to force Exim to set a specific protocol version for
15653 LDAP. If it option is unset, it is shown by the &%-bP%& command line option as
15654 -1. When this is the case, the default is 3 if LDAP_VERSION3 is defined in
15655 the LDAP headers; otherwise it is 2. This option is available only when Exim
15656 has been built with LDAP support.
15657
15658
15659
15660 .option local_from_check main boolean true
15661 .cindex "&'Sender:'& header line" "disabling addition of"
15662 .cindex "&'From:'& header line" "disabling checking of"
15663 When a message is submitted locally (that is, not over a TCP/IP connection) by
15664 an untrusted user, Exim removes any existing &'Sender:'& header line, and
15665 checks that the &'From:'& header line matches the login of the calling user and
15666 the domain specified by &%qualify_domain%&.
15667
15668 &*Note*&: An unqualified address (no domain) in the &'From:'& header in a
15669 locally submitted message is automatically qualified by Exim, unless the
15670 &%-bnq%& command line option is used.
15671
15672 You can use &%local_from_prefix%& and &%local_from_suffix%& to permit affixes
15673 on the local part. If the &'From:'& header line does not match, Exim adds a
15674 &'Sender:'& header with an address constructed from the calling user's login
15675 and the default qualify domain.
15676
15677 If &%local_from_check%& is set false, the &'From:'& header check is disabled,
15678 and no &'Sender:'& header is ever added. If, in addition, you want to retain
15679 &'Sender:'& header lines supplied by untrusted users, you must also set
15680 &%local_sender_retain%& to be true.
15681
15682 .cindex "envelope sender"
15683 These options affect only the header lines in the message. The envelope sender
15684 is still forced to be the login id at the qualify domain unless
15685 &%untrusted_set_sender%& permits the user to supply an envelope sender.
15686
15687 For messages received over TCP/IP, an ACL can specify &"submission mode"& to
15688 request similar header line checking. See section &<<SECTthesenhea>>&, which
15689 has more details about &'Sender:'& processing.
15690
15691
15692
15693
15694 .option local_from_prefix main string unset
15695 When Exim checks the &'From:'& header line of locally submitted messages for
15696 matching the login id (see &%local_from_check%& above), it can be configured to
15697 ignore certain prefixes and suffixes in the local part of the address. This is
15698 done by setting &%local_from_prefix%& and/or &%local_from_suffix%& to
15699 appropriate lists, in the same form as the &%local_part_prefix%& and
15700 &%local_part_suffix%& router options (see chapter &<<CHAProutergeneric>>&). For
15701 example, if
15702 .code
15703 local_from_prefix = *-
15704 .endd
15705 is set, a &'From:'& line containing
15706 .code
15707 From: anything-user@your.domain.example
15708 .endd
15709 will not cause a &'Sender:'& header to be added if &'user@your.domain.example'&
15710 matches the actual sender address that is constructed from the login name and
15711 qualify domain.
15712
15713
15714 .option local_from_suffix main string unset
15715 See &%local_from_prefix%& above.
15716
15717
15718 .option local_interfaces main "string list" "see below"
15719 This option controls which network interfaces are used by the daemon for
15720 listening; they are also used to identify the local host when routing. Chapter
15721 &<<CHAPinterfaces>>& contains a full description of this option and the related
15722 options &%daemon_smtp_ports%&, &%extra_local_interfaces%&,
15723 &%hosts_treat_as_local%&, and &%tls_on_connect_ports%&. The default value for
15724 &%local_interfaces%& is
15725 .code
15726 local_interfaces = 0.0.0.0
15727 .endd
15728 when Exim is built without IPv6 support; otherwise it is
15729 .code
15730 local_interfaces = <; ::0 ; 0.0.0.0
15731 .endd
15732
15733 .option local_scan_timeout main time 5m
15734 .cindex "timeout" "for &[local_scan()]& function"
15735 .cindex "&[local_scan()]& function" "timeout"
15736 This timeout applies to the &[local_scan()]& function (see chapter
15737 &<<CHAPlocalscan>>&). Zero means &"no timeout"&. If the timeout is exceeded,
15738 the incoming message is rejected with a temporary error if it is an SMTP
15739 message. For a non-SMTP message, the message is dropped and Exim ends with a
15740 non-zero code. The incident is logged on the main and reject logs.
15741
15742
15743
15744 .option local_sender_retain main boolean false
15745 .cindex "&'Sender:'& header line" "retaining from local submission"
15746 When a message is submitted locally (that is, not over a TCP/IP connection) by
15747 an untrusted user, Exim removes any existing &'Sender:'& header line. If you
15748 do not want this to happen, you must set &%local_sender_retain%&, and you must
15749 also set &%local_from_check%& to be false (Exim will complain if you do not).
15750 See also the ACL modifier &`control = suppress_local_fixups`&. Section
15751 &<<SECTthesenhea>>& has more details about &'Sender:'& processing.
15752
15753
15754
15755
15756 .option localhost_number main string&!! unset
15757 .cindex "host" "locally unique number for"
15758 .cindex "message ids" "with multiple hosts"
15759 .vindex "&$localhost_number$&"
15760 Exim's message ids are normally unique only within the local host. If
15761 uniqueness among a set of hosts is required, each host must set a different
15762 value for the &%localhost_number%& option. The string is expanded immediately
15763 after reading the configuration file (so that a number can be computed from the
15764 host name, for example) and the result of the expansion must be a number in the
15765 range 0&--16 (or 0&--10 on operating systems with case-insensitive file
15766 systems). This is available in subsequent string expansions via the variable
15767 &$localhost_number$&. When &%localhost_number is set%&, the final two
15768 characters of the message id, instead of just being a fractional part of the
15769 time, are computed from the time and the local host number as described in
15770 section &<<SECTmessiden>>&.
15771
15772
15773
15774 .option log_file_path main "string list&!!" "set at compile time"
15775 .cindex "log" "file path for"
15776 This option sets the path which is used to determine the names of Exim's log
15777 files, or indicates that logging is to be to syslog, or both. It is expanded
15778 when Exim is entered, so it can, for example, contain a reference to the host
15779 name. If no specific path is set for the log files at compile or run time,
15780 or if the option is unset at run time (i.e.  &`log_file_path = `&)
15781 they are written in a sub-directory called &_log_& in Exim's spool directory.
15782 Chapter &<<CHAPlog>>& contains further details about Exim's logging, and
15783 section &<<SECTwhelogwri>>& describes how the contents of &%log_file_path%& are
15784 used. If this string is fixed at your installation (contains no expansion
15785 variables) it is recommended that you do not set this option in the
15786 configuration file, but instead supply the path using LOG_FILE_PATH in
15787 &_Local/Makefile_& so that it is available to Exim for logging errors detected
15788 early on &-- in particular, failure to read the configuration file.
15789
15790
15791 .option log_selector main string unset
15792 .cindex "log" "selectors"
15793 This option can be used to reduce or increase the number of things that Exim
15794 writes to its log files. Its argument is made up of names preceded by plus or
15795 minus characters. For example:
15796 .code
15797 log_selector = +arguments -retry_defer
15798 .endd
15799 A list of possible names and what they control is given in the chapter on
15800 logging, in section &<<SECTlogselector>>&.
15801
15802
15803 .option log_timezone main boolean false
15804 .cindex "log" "timezone for entries"
15805 .vindex "&$tod_log$&"
15806 .vindex "&$tod_zone$&"
15807 By default, the timestamps on log lines are in local time without the
15808 timezone. This means that if your timezone changes twice a year, the timestamps
15809 in log lines are ambiguous for an hour when the clocks go back. One way of
15810 avoiding this problem is to set the timezone to UTC. An alternative is to set
15811 &%log_timezone%& true. This turns on the addition of the timezone offset to
15812 timestamps in log lines. Turning on this option can add quite a lot to the size
15813 of log files because each line is extended by 6 characters. Note that the
15814 &$tod_log$& variable contains the log timestamp without the zone, but there is
15815 another variable called &$tod_zone$& that contains just the timezone offset.
15816
15817
15818 .option lookup_open_max main integer 25
15819 .cindex "too many open files"
15820 .cindex "open files, too many"
15821 .cindex "file" "too many open"
15822 .cindex "lookup" "maximum open files"
15823 .cindex "limit" "open files for lookups"
15824 This option limits the number of simultaneously open files for single-key
15825 lookups that use regular files (that is, &(lsearch)&, &(dbm)&, and &(cdb)&).
15826 Exim normally keeps these files open during routing, because often the same
15827 file is required several times. If the limit is reached, Exim closes the least
15828 recently used file. Note that if you are using the &'ndbm'& library, it
15829 actually opens two files for each logical DBM database, though it still counts
15830 as one for the purposes of &%lookup_open_max%&. If you are getting &"too many
15831 open files"& errors with NDBM, you need to reduce the value of
15832 &%lookup_open_max%&.
15833
15834
15835 .option max_username_length main integer 0
15836 .cindex "length of login name"
15837 .cindex "user name" "maximum length"
15838 .cindex "limit" "user name length"
15839 Some operating systems are broken in that they truncate long arguments to
15840 &[getpwnam()]& to eight characters, instead of returning &"no such user"&. If
15841 this option is set greater than zero, any attempt to call &[getpwnam()]& with
15842 an argument that is longer behaves as if &[getpwnam()]& failed.
15843
15844
15845 .option message_body_newlines main bool false
15846 .cindex "message body" "newlines in variables"
15847 .cindex "newline" "in message body variables"
15848 .vindex "&$message_body$&"
15849 .vindex "&$message_body_end$&"
15850 By default, newlines in the message body are replaced by spaces when setting
15851 the &$message_body$& and &$message_body_end$& expansion variables. If this
15852 option is set true, this no longer happens.
15853
15854
15855 .option message_body_visible main integer 500
15856 .cindex "body of message" "visible size"
15857 .cindex "message body" "visible size"
15858 .vindex "&$message_body$&"
15859 .vindex "&$message_body_end$&"
15860 This option specifies how much of a message's body is to be included in the
15861 &$message_body$& and &$message_body_end$& expansion variables.
15862
15863
15864 .option message_id_header_domain main string&!! unset
15865 .cindex "&'Message-ID:'& header line"
15866 If this option is set, the string is expanded and used as the right hand side
15867 (domain) of the &'Message-ID:'& header that Exim creates if a
15868 locally-originated incoming message does not have one. &"Locally-originated"&
15869 means &"not received over TCP/IP."&
15870 Otherwise, the primary host name is used.
15871 Only letters, digits, dot and hyphen are accepted; any other characters are
15872 replaced by hyphens. If the expansion is forced to fail, or if the result is an
15873 empty string, the option is ignored.
15874
15875
15876 .option message_id_header_text main string&!! unset
15877 If this variable is set, the string is expanded and used to augment the text of
15878 the &'Message-id:'& header that Exim creates if a locally-originated incoming
15879 message does not have one. The text of this header is required by RFC 2822 to
15880 take the form of an address. By default, Exim uses its internal message id as
15881 the local part, and the primary host name as the domain. If this option is set,
15882 it is expanded, and provided the expansion is not forced to fail, and does not
15883 yield an empty string, the result is inserted into the header immediately
15884 before the @, separated from the internal message id by a dot. Any characters
15885 that are illegal in an address are automatically converted into hyphens. This
15886 means that variables such as &$tod_log$& can be used, because the spaces and
15887 colons will become hyphens.
15888
15889
15890 .option message_logs main boolean true
15891 .cindex "message logs" "disabling"
15892 .cindex "log" "message log; disabling"
15893 If this option is turned off, per-message log files are not created in the
15894 &_msglog_& spool sub-directory. This reduces the amount of disk I/O required by
15895 Exim, by reducing the number of files involved in handling a message from a
15896 minimum of four (header spool file, body spool file, delivery journal, and
15897 per-message log) to three. The other major I/O activity is Exim's main log,
15898 which is not affected by this option.
15899
15900
15901 .option message_size_limit main string&!! 50M
15902 .cindex "message" "size limit"
15903 .cindex "limit" "message size"
15904 .cindex "size" "of message, limit"
15905 This option limits the maximum size of message that Exim will process. The
15906 value is expanded for each incoming connection so, for example, it can be made
15907 to depend on the IP address of the remote host for messages arriving via
15908 TCP/IP. After expansion, the value must be a sequence of decimal digits,
15909 optionally followed by K or M.
15910
15911 &*Note*&: This limit cannot be made to depend on a message's sender or any
15912 other properties of an individual message, because it has to be advertised in
15913 the server's response to EHLO. String expansion failure causes a temporary
15914 error. A value of zero means no limit, but its use is not recommended. See also
15915 &%bounce_return_size_limit%&.
15916
15917 Incoming SMTP messages are failed with a 552 error if the limit is
15918 exceeded; locally-generated messages either get a stderr message or a delivery
15919 failure message to the sender, depending on the &%-oe%& setting. Rejection of
15920 an oversized message is logged in both the main and the reject logs. See also
15921 the generic transport option &%message_size_limit%&, which limits the size of
15922 message that an individual transport can process.
15923
15924 If you use a virus-scanner and set this option to to a value larger than the
15925 maximum size that your virus-scanner is configured to support, you may get
15926 failures triggered by large mails.  The right size to configure for the
15927 virus-scanner depends upon what data is passed and the options in use but it's
15928 probably safest to just set it to a little larger than this value.  E.g., with a
15929 default Exim message size of 50M and a default ClamAV StreamMaxLength of 10M,
15930 some problems may result.
15931
15932 A value of 0 will disable size limit checking; Exim will still advertise the
15933 SIZE extension in an EHLO response, but without a limit, so as to permit
15934 SMTP clients to still indicate the message size along with the MAIL verb.
15935
15936
15937 .option move_frozen_messages main boolean false
15938 .cindex "frozen messages" "moving"
15939 This option, which is available only if Exim has been built with the setting
15940 .code
15941 SUPPORT_MOVE_FROZEN_MESSAGES=yes
15942 .endd
15943 in &_Local/Makefile_&, causes frozen messages and their message logs to be
15944 moved from the &_input_& and &_msglog_& directories on the spool to &_Finput_&
15945 and &_Fmsglog_&, respectively. There is currently no support in Exim or the
15946 standard utilities for handling such moved messages, and they do not show up in
15947 lists generated by &%-bp%& or by the Exim monitor.
15948
15949
15950 .option mua_wrapper main boolean false
15951 Setting this option true causes Exim to run in a very restrictive mode in which
15952 it passes messages synchronously to a smart host. Chapter &<<CHAPnonqueueing>>&
15953 contains a full description of this facility.
15954
15955
15956
15957 .option mysql_servers main "string list" unset
15958 .cindex "MySQL" "server list"
15959 This option provides a list of MySQL servers and associated connection data, to
15960 be used in conjunction with &(mysql)& lookups (see section &<<SECID72>>&). The
15961 option is available only if Exim has been built with MySQL support.
15962
15963
15964 .option never_users main "string list&!!" unset
15965 This option is expanded just once, at the start of Exim's processing. Local
15966 message deliveries are normally run in processes that are setuid to the
15967 recipient, and remote deliveries are normally run under Exim's own uid and gid.
15968 It is usually desirable to prevent any deliveries from running as root, as a
15969 safety precaution.
15970
15971 When Exim is built, an option called FIXED_NEVER_USERS can be set to a
15972 list of users that must not be used for local deliveries. This list is fixed in
15973 the binary and cannot be overridden by the configuration file. By default, it
15974 contains just the single user name &"root"&. The &%never_users%& runtime option
15975 can be used to add more users to the fixed list.
15976
15977 If a message is to be delivered as one of the users on the fixed list or the
15978 &%never_users%& list, an error occurs, and delivery is deferred. A common
15979 example is
15980 .code
15981 never_users = root:daemon:bin
15982 .endd
15983 Including root is redundant if it is also on the fixed list, but it does no
15984 harm. This option overrides the &%pipe_as_creator%& option of the &(pipe)&
15985 transport driver.
15986
15987
15988 .option openssl_options main "string list" "+no_sslv2 +single_dh_use +no_ticket"
15989 .cindex "OpenSSL "compatibility options"
15990 This option allows an administrator to adjust the SSL options applied
15991 by OpenSSL to connections.  It is given as a space-separated list of items,
15992 each one to be +added or -subtracted from the current value.
15993
15994 This option is only available if Exim is built against OpenSSL.  The values
15995 available for this option vary according to the age of your OpenSSL install.
15996 The &"all"& value controls a subset of flags which are available, typically
15997 the bug workaround options.  The &'SSL_CTX_set_options'& man page will
15998 list the values known on your system and Exim should support all the
15999 &"bug workaround"& options and many of the &"modifying"& options.  The Exim
16000 names lose the leading &"SSL_OP_"& and are lower-cased.
16001
16002 Note that adjusting the options can have severe impact upon the security of
16003 SSL as used by Exim.  It is possible to disable safety checks and shoot
16004 yourself in the foot in various unpleasant ways.  This option should not be
16005 adjusted lightly.  An unrecognised item will be detected at startup, by
16006 invoking Exim with the &%-bV%& flag.
16007
16008 The option affects Exim operating both as a server and as a client.
16009
16010 Historical note: prior to release 4.80, Exim defaulted this value to
16011 "+dont_insert_empty_fragments", which may still be needed for compatibility
16012 with some clients, but which lowers security by increasing exposure to
16013 some now infamous attacks.
16014
16015 Examples:
16016 .code
16017 # Make both old MS and old Eudora happy:
16018 openssl_options = -all +microsoft_big_sslv3_buffer \
16019                        +dont_insert_empty_fragments
16020
16021 # Disable older protocol versions:
16022 openssl_options = +no_sslv2 +no_sslv3
16023 .endd
16024
16025 Possible options may include:
16026 .ilist
16027 &`all`&
16028 .next
16029 &`allow_unsafe_legacy_renegotiation`&
16030 .next
16031 &`cipher_server_preference`&
16032 .next
16033 &`dont_insert_empty_fragments`&
16034 .next
16035 &`ephemeral_rsa`&
16036 .next
16037 &`legacy_server_connect`&
16038 .next
16039 &`microsoft_big_sslv3_buffer`&
16040 .next
16041 &`microsoft_sess_id_bug`&
16042 .next
16043 &`msie_sslv2_rsa_padding`&
16044 .next
16045 &`netscape_challenge_bug`&
16046 .next
16047 &`netscape_reuse_cipher_change_bug`&
16048 .next
16049 &`no_compression`&
16050 .next
16051 &`no_session_resumption_on_renegotiation`&
16052 .next
16053 &`no_sslv2`&
16054 .next
16055 &`no_sslv3`&
16056 .next
16057 &`no_ticket`&
16058 .next
16059 &`no_tlsv1`&
16060 .next
16061 &`no_tlsv1_1`&
16062 .next
16063 &`no_tlsv1_2`&
16064 .next
16065 &`safari_ecdhe_ecdsa_bug`&
16066 .next
16067 &`single_dh_use`&
16068 .next
16069 &`single_ecdh_use`&
16070 .next
16071 &`ssleay_080_client_dh_bug`&
16072 .next
16073 &`sslref2_reuse_cert_type_bug`&
16074 .next
16075 &`tls_block_padding_bug`&
16076 .next
16077 &`tls_d5_bug`&
16078 .next
16079 &`tls_rollback_bug`&
16080 .endlist
16081
16082 As an aside, the &`safari_ecdhe_ecdsa_bug`& item is a misnomer and affects
16083 all clients connecting using the MacOS SecureTransport TLS facility prior
16084 to MacOS 10.8.4, including email clients.  If you see old MacOS clients failing
16085 to negotiate TLS then this option value might help, provided that your OpenSSL
16086 release is new enough to contain this work-around.  This may be a situation
16087 where you have to upgrade OpenSSL to get buggy clients working.
16088
16089
16090 .option oracle_servers main "string list" unset
16091 .cindex "Oracle" "server list"
16092 This option provides a list of Oracle servers and associated connection data,
16093 to be used in conjunction with &(oracle)& lookups (see section &<<SECID72>>&).
16094 The option is available only if Exim has been built with Oracle support.
16095
16096
16097 .option percent_hack_domains main "domain list&!!" unset
16098 .cindex "&""percent hack""&"
16099 .cindex "source routing" "in email address"
16100 .cindex "address" "source-routed"
16101 The &"percent hack"& is the convention whereby a local part containing a
16102 percent sign is re-interpreted as a new email address, with the percent
16103 replaced by @. This is sometimes called &"source routing"&, though that term is
16104 also applied to RFC 2822 addresses that begin with an @ character. If this
16105 option is set, Exim implements the percent facility for those domains listed,
16106 but no others. This happens before an incoming SMTP address is tested against
16107 an ACL.
16108
16109 &*Warning*&: The &"percent hack"& has often been abused by people who are
16110 trying to get round relaying restrictions. For this reason, it is best avoided
16111 if at all possible. Unfortunately, a number of less security-conscious MTAs
16112 implement it unconditionally. If you are running Exim on a gateway host, and
16113 routing mail through to internal MTAs without processing the local parts, it is
16114 a good idea to reject recipient addresses with percent characters in their
16115 local parts. Exim's default configuration does this.
16116
16117
16118 .option perl_at_start main boolean false
16119 .cindex "Perl"
16120 This option is available only when Exim is built with an embedded Perl
16121 interpreter. See chapter &<<CHAPperl>>& for details of its use.
16122
16123
16124 .option perl_startup main string unset
16125 .cindex "Perl"
16126 This option is available only when Exim is built with an embedded Perl
16127 interpreter. See chapter &<<CHAPperl>>& for details of its use.
16128
16129 .option perl_startup main boolean false
16130 .cindex "Perl"
16131 This Option enables the taint mode of the embedded Perl interpreter.
16132
16133
16134 .option pgsql_servers main "string list" unset
16135 .cindex "PostgreSQL lookup type" "server list"
16136 This option provides a list of PostgreSQL servers and associated connection
16137 data, to be used in conjunction with &(pgsql)& lookups (see section
16138 &<<SECID72>>&). The option is available only if Exim has been built with
16139 PostgreSQL support.
16140
16141
16142 .option pid_file_path main string&!! "set at compile time"
16143 .cindex "daemon" "pid file path"
16144 .cindex "pid file, path for"
16145 This option sets the name of the file to which the Exim daemon writes its
16146 process id. The string is expanded, so it can contain, for example, references
16147 to the host name:
16148 .code
16149 pid_file_path = /var/log/$primary_hostname/exim.pid
16150 .endd
16151 If no path is set, the pid is written to the file &_exim-daemon.pid_& in Exim's
16152 spool directory.
16153 The value set by the option can be overridden by the &%-oP%& command line
16154 option. A pid file is not written if a &"non-standard"& daemon is run by means
16155 of the &%-oX%& option, unless a path is explicitly supplied by &%-oP%&.
16156
16157
16158 .option pipelining_advertise_hosts main "host list&!!" *
16159 .cindex "PIPELINING" "suppressing advertising"
16160 This option can be used to suppress the advertisement of the SMTP
16161 PIPELINING extension to specific hosts. See also the &*no_pipelining*&
16162 control in section &<<SECTcontrols>>&. When PIPELINING is not advertised and
16163 &%smtp_enforce_sync%& is true, an Exim server enforces strict synchronization
16164 for each SMTP command and response. When PIPELINING is advertised, Exim assumes
16165 that clients will use it; &"out of order"& commands that are &"expected"& do
16166 not count as protocol errors (see &%smtp_max_synprot_errors%&).
16167
16168
16169 .option prdr_enable main boolean false
16170 .cindex "PRDR" "enabling on server"
16171 This option can be used to enable the Per-Recipient Data Response extension
16172 to SMTP, defined by Eric Hall.
16173 If the option is set, PRDR is advertised by Exim when operating as a server.
16174 If the client requests PRDR, and more than one recipient, for a message
16175 an additional ACL is called for each recipient after the message content
16176 is received.  See section &<<SECTPRDRACL>>&.
16177
16178 .option preserve_message_logs main boolean false
16179 .cindex "message logs" "preserving"
16180 If this option is set, message log files are not deleted when messages are
16181 completed. Instead, they are moved to a sub-directory of the spool directory
16182 called &_msglog.OLD_&, where they remain available for statistical or debugging
16183 purposes. This is a dangerous option to set on systems with any appreciable
16184 volume of mail. Use with care!
16185
16186
16187 .option primary_hostname main string "see below"
16188 .cindex "name" "of local host"
16189 .cindex "host" "name of local"
16190 .cindex "local host" "name of"
16191 .vindex "&$primary_hostname$&"
16192 This specifies the name of the current host. It is used in the default EHLO or
16193 HELO command for outgoing SMTP messages (changeable via the &%helo_data%&
16194 option in the &(smtp)& transport), and as the default for &%qualify_domain%&.
16195 The value is also used by default in some SMTP response messages from an Exim
16196 server. This can be changed dynamically by setting &%smtp_active_hostname%&.
16197
16198 If &%primary_hostname%& is not set, Exim calls &[uname()]& to find the host
16199 name. If this fails, Exim panics and dies. If the name returned by &[uname()]&
16200 contains only one component, Exim passes it to &[gethostbyname()]& (or
16201 &[getipnodebyname()]& when available) in order to obtain the fully qualified
16202 version. The variable &$primary_hostname$& contains the host name, whether set
16203 explicitly by this option, or defaulted.
16204
16205
16206 .option print_topbitchars main boolean false
16207 .cindex "printing characters"
16208 .cindex "8-bit characters"
16209 By default, Exim considers only those characters whose codes lie in the range
16210 32&--126 to be printing characters. In a number of circumstances (for example,
16211 when writing log entries) non-printing characters are converted into escape
16212 sequences, primarily to avoid messing up the layout. If &%print_topbitchars%&
16213 is set, code values of 128 and above are also considered to be printing
16214 characters.
16215
16216 This option also affects the header syntax checks performed by the
16217 &(autoreply)& transport, and whether Exim uses RFC 2047 encoding of
16218 the user's full name when constructing From: and Sender: addresses (as
16219 described in section &<<SECTconstr>>&). Setting this option can cause
16220 Exim to generate eight bit message headers that do not conform to the
16221 standards.
16222
16223
16224 .option process_log_path main string unset
16225 .cindex "process log path"
16226 .cindex "log" "process log"
16227 .cindex "&'exiwhat'&"
16228 This option sets the name of the file to which an Exim process writes its
16229 &"process log"& when sent a USR1 signal. This is used by the &'exiwhat'&
16230 utility script. If this option is unset, the file called &_exim-process.info_&
16231 in Exim's spool directory is used. The ability to specify the name explicitly
16232 can be useful in environments where two different Exims are running, using
16233 different spool directories.
16234
16235
16236 .option prod_requires_admin main boolean true
16237 .cindex "restricting access to features"
16238 .oindex "&%-M%&"
16239 .oindex "&%-R%&"
16240 .oindex "&%-q%&"
16241 The &%-M%&, &%-R%&, and &%-q%& command-line options require the caller to be an
16242 admin user unless &%prod_requires_admin%& is set false. See also
16243 &%queue_list_requires_admin%& and &%commandline_checks_require_admin%&.
16244
16245
16246 .option qualify_domain main string "see below"
16247 .cindex "domain" "for qualifying addresses"
16248 .cindex "address" "qualification"
16249 This option specifies the domain name that is added to any envelope sender
16250 addresses that do not have a domain qualification. It also applies to
16251 recipient addresses if &%qualify_recipient%& is not set. Unqualified addresses
16252 are accepted by default only for locally-generated messages. Qualification is
16253 also applied to addresses in header lines such as &'From:'& and &'To:'& for
16254 locally-generated messages, unless the &%-bnq%& command line option is used.
16255
16256 Messages from external sources must always contain fully qualified addresses,
16257 unless the sending host matches &%sender_unqualified_hosts%& or
16258 &%recipient_unqualified_hosts%& (as appropriate), in which case incoming
16259 addresses are qualified with &%qualify_domain%& or &%qualify_recipient%& as
16260 necessary. Internally, Exim always works with fully qualified envelope
16261 addresses. If &%qualify_domain%& is not set, it defaults to the
16262 &%primary_hostname%& value.
16263
16264
16265 .option qualify_recipient main string "see below"
16266 This option allows you to specify a different domain for qualifying recipient
16267 addresses to the one that is used for senders. See &%qualify_domain%& above.
16268
16269
16270
16271 .option queue_domains main "domain list&!!" unset
16272 .cindex "domain" "specifying non-immediate delivery"
16273 .cindex "queueing incoming messages"
16274 .cindex "message" "queueing certain domains"
16275 This option lists domains for which immediate delivery is not required.
16276 A delivery process is started whenever a message is received, but only those
16277 domains that do not match are processed. All other deliveries wait until the
16278 next queue run. See also &%hold_domains%& and &%queue_smtp_domains%&.
16279
16280
16281 .option queue_list_requires_admin main boolean true
16282 .cindex "restricting access to features"
16283 .oindex "&%-bp%&"
16284 The &%-bp%& command-line option, which lists the messages that are on the
16285 queue, requires the caller to be an admin user unless
16286 &%queue_list_requires_admin%& is set false.
16287 See also &%prod_requires_admin%& and &%commandline_checks_require_admin%&.
16288
16289
16290 .option queue_only main boolean false
16291 .cindex "queueing incoming messages"
16292 .cindex "message" "queueing unconditionally"
16293 If &%queue_only%& is set, a delivery process is not automatically started
16294 whenever a message is received. Instead, the message waits on the queue for the
16295 next queue run. Even if &%queue_only%& is false, incoming messages may not get
16296 delivered immediately when certain conditions (such as heavy load) occur.
16297
16298 The &%-odq%& command line has the same effect as &%queue_only%&. The &%-odb%&
16299 and &%-odi%& command line options override &%queue_only%& unless
16300 &%queue_only_override%& is set false. See also &%queue_only_file%&,
16301 &%queue_only_load%&, and &%smtp_accept_queue%&.
16302
16303
16304 .option queue_only_file main string unset
16305 .cindex "queueing incoming messages"
16306 .cindex "message" "queueing by file existence"
16307 This option can be set to a colon-separated list of absolute path names, each
16308 one optionally preceded by &"smtp"&. When Exim is receiving a message,
16309 it tests for the existence of each listed path using a call to &[stat()]&. For
16310 each path that exists, the corresponding queueing option is set.
16311 For paths with no prefix, &%queue_only%& is set; for paths prefixed by
16312 &"smtp"&, &%queue_smtp_domains%& is set to match all domains. So, for example,
16313 .code
16314 queue_only_file = smtp/some/file
16315 .endd
16316 causes Exim to behave as if &%queue_smtp_domains%& were set to &"*"& whenever
16317 &_/some/file_& exists.
16318
16319
16320 .option queue_only_load main fixed-point unset
16321 .cindex "load average"
16322 .cindex "queueing incoming messages"
16323 .cindex "message" "queueing by load"
16324 If the system load average is higher than this value, incoming messages from
16325 all sources are queued, and no automatic deliveries are started. If this
16326 happens during local or remote SMTP input, all subsequent messages received on
16327 the same SMTP connection are queued by default, whatever happens to the load in
16328 the meantime, but this can be changed by setting &%queue_only_load_latch%&
16329 false.
16330
16331 Deliveries will subsequently be performed by queue runner processes. This
16332 option has no effect on ancient operating systems on which Exim cannot
16333 determine the load average. See also &%deliver_queue_load_max%& and
16334 &%smtp_load_reserve%&.
16335
16336
16337 .option queue_only_load_latch main boolean true
16338 .cindex "load average" "re-evaluating per message"
16339 When this option is true (the default), once one message has been queued
16340 because the load average is higher than the value set by &%queue_only_load%&,
16341 all subsequent messages received on the same SMTP connection are also queued.
16342 This is a deliberate choice; even though the load average may fall below the
16343 threshold, it doesn't seem right to deliver later messages on the same
16344 connection when not delivering earlier ones. However, there are special
16345 circumstances such as very long-lived connections from scanning appliances
16346 where this is not the best strategy. In such cases, &%queue_only_load_latch%&
16347 should be set false. This causes the value of the load average to be
16348 re-evaluated for each message.
16349
16350
16351 .option queue_only_override main boolean true
16352 .cindex "queueing incoming messages"
16353 When this option is true, the &%-od%&&'x'& command line options override the
16354 setting of &%queue_only%& or &%queue_only_file%& in the configuration file. If
16355 &%queue_only_override%& is set false, the &%-od%&&'x'& options cannot be used
16356 to override; they are accepted, but ignored.
16357
16358
16359 .option queue_run_in_order main boolean false
16360 .cindex "queue runner" "processing messages in order"
16361 If this option is set, queue runs happen in order of message arrival instead of
16362 in an arbitrary order. For this to happen, a complete list of the entire queue
16363 must be set up before the deliveries start. When the queue is all held in a
16364 single directory (the default), a single list is created for both the ordered
16365 and the non-ordered cases. However, if &%split_spool_directory%& is set, a
16366 single list is not created when &%queue_run_in_order%& is false. In this case,
16367 the sub-directories are processed one at a time (in a random order), and this
16368 avoids setting up one huge list for the whole queue. Thus, setting
16369 &%queue_run_in_order%& with &%split_spool_directory%& may degrade performance
16370 when the queue is large, because of the extra work in setting up the single,
16371 large list. In most situations, &%queue_run_in_order%& should not be set.
16372
16373
16374
16375 .option queue_run_max main integer&!! 5
16376 .cindex "queue runner" "maximum number of"
16377 This controls the maximum number of queue runner processes that an Exim daemon
16378 can run simultaneously. This does not mean that it starts them all at once,
16379 but rather that if the maximum number are still running when the time comes to
16380 start another one, it refrains from starting another one. This can happen with
16381 very large queues and/or very sluggish deliveries. This option does not,
16382 however, interlock with other processes, so additional queue runners can be
16383 started by other means, or by killing and restarting the daemon.
16384
16385 Setting this option to zero does not suppress queue runs; rather, it disables
16386 the limit, allowing any number of simultaneous queue runner processes to be
16387 run. If you do not want queue runs to occur, omit the &%-q%&&'xx'& setting on
16388 the daemon's command line.
16389
16390 .cindex queues named
16391 .cindex "named queues"
16392 To set limits for different named queues use
16393 an expansion depending on the &$queue_name$& variable.
16394
16395 .option queue_smtp_domains main "domain list&!!" unset
16396 .cindex "queueing incoming messages"
16397 .cindex "message" "queueing remote deliveries"
16398 When this option is set, a delivery process is started whenever a message is
16399 received, routing is performed, and local deliveries take place.
16400 However, if any SMTP deliveries are required for domains that match
16401 &%queue_smtp_domains%&, they are not immediately delivered, but instead the
16402 message waits on the queue for the next queue run. Since routing of the message
16403 has taken place, Exim knows to which remote hosts it must be delivered, and so
16404 when the queue run happens, multiple messages for the same host are delivered
16405 over a single SMTP connection. The &%-odqs%& command line option causes all
16406 SMTP deliveries to be queued in this way, and is equivalent to setting
16407 &%queue_smtp_domains%& to &"*"&. See also &%hold_domains%& and
16408 &%queue_domains%&.
16409
16410
16411 .option receive_timeout main time 0s
16412 .cindex "timeout" "for non-SMTP input"
16413 This option sets the timeout for accepting a non-SMTP message, that is, the
16414 maximum time that Exim waits when reading a message on the standard input. If
16415 the value is zero, it will wait for ever. This setting is overridden by the
16416 &%-or%& command line option. The timeout for incoming SMTP messages is
16417 controlled by &%smtp_receive_timeout%&.
16418
16419 .option received_header_text main string&!! "see below"
16420 .cindex "customizing" "&'Received:'& header"
16421 .cindex "&'Received:'& header line" "customizing"
16422 This string defines the contents of the &'Received:'& message header that is
16423 added to each message, except for the timestamp, which is automatically added
16424 on at the end (preceded by a semicolon). The string is expanded each time it is
16425 used. If the expansion yields an empty string, no &'Received:'& header line is
16426 added to the message. Otherwise, the string should start with the text
16427 &"Received:"& and conform to the RFC 2822 specification for &'Received:'&
16428 header lines. The default setting is:
16429
16430 .code
16431 received_header_text = Received: \
16432   ${if def:sender_rcvhost {from $sender_rcvhost\n\t}\
16433   {${if def:sender_ident \
16434   {from ${quote_local_part:$sender_ident} }}\
16435   ${if def:sender_helo_name {(helo=$sender_helo_name)\n\t}}}}\
16436   by $primary_hostname \
16437   ${if def:received_protocol {with $received_protocol}} \
16438   ${if def:tls_in_cipher {($tls_in_cipher)\n\t}}\
16439   (Exim $version_number)\n\t\
16440   ${if def:sender_address \
16441   {(envelope-from <$sender_address>)\n\t}}\
16442   id $message_exim_id\
16443   ${if def:received_for {\n\tfor $received_for}}
16444 .endd
16445
16446 The reference to the TLS cipher is omitted when Exim is built without TLS
16447 support. The use of conditional expansions ensures that this works for both
16448 locally generated messages and messages received from remote hosts, giving
16449 header lines such as the following:
16450 .code
16451 Received: from scrooge.carol.example ([192.168.12.25] ident=root)
16452 by marley.carol.example with esmtp (Exim 4.00)
16453 (envelope-from <bob@carol.example>)
16454 id 16IOWa-00019l-00
16455 for chas@dickens.example; Tue, 25 Dec 2001 14:43:44 +0000
16456 Received: by scrooge.carol.example with local (Exim 4.00)
16457 id 16IOWW-000083-00; Tue, 25 Dec 2001 14:43:41 +0000
16458 .endd
16459 Until the body of the message has been received, the timestamp is the time when
16460 the message started to be received. Once the body has arrived, and all policy
16461 checks have taken place, the timestamp is updated to the time at which the
16462 message was accepted.
16463
16464
16465 .option received_headers_max main integer 30
16466 .cindex "loop" "prevention"
16467 .cindex "mail loop prevention"
16468 .cindex "&'Received:'& header line" "counting"
16469 When a message is to be delivered, the number of &'Received:'& headers is
16470 counted, and if it is greater than this parameter, a mail loop is assumed to
16471 have occurred, the delivery is abandoned, and an error message is generated.
16472 This applies to both local and remote deliveries.
16473
16474
16475 .option recipient_unqualified_hosts main "host list&!!" unset
16476 .cindex "unqualified addresses"
16477 .cindex "host" "unqualified addresses from"
16478 This option lists those hosts from which Exim is prepared to accept unqualified
16479 recipient addresses in message envelopes. The addresses are made fully
16480 qualified by the addition of the &%qualify_recipient%& value. This option also
16481 affects message header lines. Exim does not reject unqualified recipient
16482 addresses in headers, but it qualifies them only if the message came from a
16483 host that matches &%recipient_unqualified_hosts%&,
16484 or if the message was submitted locally (not using TCP/IP), and the &%-bnq%&
16485 option was not set.
16486
16487
16488 .option recipients_max main integer 0
16489 .cindex "limit" "number of recipients"
16490 .cindex "recipient" "maximum number"
16491 If this option is set greater than zero, it specifies the maximum number of
16492 original recipients for any message. Additional recipients that are generated
16493 by aliasing or forwarding do not count. SMTP messages get a 452 response for
16494 all recipients over the limit; earlier recipients are delivered as normal.
16495 Non-SMTP messages with too many recipients are failed, and no deliveries are
16496 done.
16497
16498 .cindex "RCPT" "maximum number of incoming"
16499 &*Note*&: The RFCs specify that an SMTP server should accept at least 100
16500 RCPT commands in a single message.
16501
16502
16503 .option recipients_max_reject main boolean false
16504 If this option is set true, Exim rejects SMTP messages containing too many
16505 recipients by giving 552 errors to the surplus RCPT commands, and a 554
16506 error to the eventual DATA command. Otherwise (the default) it gives a 452
16507 error to the surplus RCPT commands and accepts the message on behalf of the
16508 initial set of recipients. The remote server should then re-send the message
16509 for the remaining recipients at a later time.
16510
16511
16512 .option remote_max_parallel main integer 2
16513 .cindex "delivery" "parallelism for remote"
16514 This option controls parallel delivery of one message to a number of remote
16515 hosts. If the value is less than 2, parallel delivery is disabled, and Exim
16516 does all the remote deliveries for a message one by one. Otherwise, if a single
16517 message has to be delivered to more than one remote host, or if several copies
16518 have to be sent to the same remote host, up to &%remote_max_parallel%&
16519 deliveries are done simultaneously. If more than &%remote_max_parallel%&
16520 deliveries are required, the maximum number of processes are started, and as
16521 each one finishes, another is begun. The order of starting processes is the
16522 same as if sequential delivery were being done, and can be controlled by the
16523 &%remote_sort_domains%& option. If parallel delivery takes place while running
16524 with debugging turned on, the debugging output from each delivery process is
16525 tagged with its process id.
16526
16527 This option controls only the maximum number of parallel deliveries for one
16528 message in one Exim delivery process. Because Exim has no central queue
16529 manager, there is no way of controlling the total number of simultaneous
16530 deliveries if the configuration allows a delivery attempt as soon as a message
16531 is received.
16532
16533 .cindex "number of deliveries"
16534 .cindex "delivery" "maximum number of"
16535 If you want to control the total number of deliveries on the system, you
16536 need to set the &%queue_only%& option. This ensures that all incoming messages
16537 are added to the queue without starting a delivery process. Then set up an Exim
16538 daemon to start queue runner processes at appropriate intervals (probably
16539 fairly often, for example, every minute), and limit the total number of queue
16540 runners by setting the &%queue_run_max%& parameter. Because each queue runner
16541 delivers only one message at a time, the maximum number of deliveries that can
16542 then take place at once is &%queue_run_max%& multiplied by
16543 &%remote_max_parallel%&.
16544
16545 If it is purely remote deliveries you want to control, use
16546 &%queue_smtp_domains%& instead of &%queue_only%&. This has the added benefit of
16547 doing the SMTP routing before queueing, so that several messages for the same
16548 host will eventually get delivered down the same connection.
16549
16550
16551 .option remote_sort_domains main "domain list&!!" unset
16552 .cindex "sorting remote deliveries"
16553 .cindex "delivery" "sorting remote"
16554 When there are a number of remote deliveries for a message, they are sorted by
16555 domain into the order given by this list. For example,
16556 .code
16557 remote_sort_domains = *.cam.ac.uk:*.uk
16558 .endd
16559 would attempt to deliver to all addresses in the &'cam.ac.uk'& domain first,
16560 then to those in the &%uk%& domain, then to any others.
16561
16562
16563 .option retry_data_expire main time 7d
16564 .cindex "hints database" "data expiry"
16565 This option sets a &"use before"& time on retry information in Exim's hints
16566 database. Any older retry data is ignored. This means that, for example, once a
16567 host has not been tried for 7 days, Exim behaves as if it has no knowledge of
16568 past failures.
16569
16570
16571 .option retry_interval_max main time 24h
16572 .cindex "retry" "limit on interval"
16573 .cindex "limit" "on retry interval"
16574 Chapter &<<CHAPretry>>& describes Exim's mechanisms for controlling the
16575 intervals between delivery attempts for messages that cannot be delivered
16576 straight away. This option sets an overall limit to the length of time between
16577 retries. It cannot be set greater than 24 hours; any attempt to do so forces
16578 the default value.
16579
16580
16581 .option return_path_remove main boolean true
16582 .cindex "&'Return-path:'& header line" "removing"
16583 RFC 2821, section 4.4, states that an SMTP server must insert a
16584 &'Return-path:'& header line into a message when it makes a &"final delivery"&.
16585 The &'Return-path:'& header preserves the sender address as received in the
16586 MAIL command. This description implies that this header should not be present
16587 in an incoming message. If &%return_path_remove%& is true, any existing
16588 &'Return-path:'& headers are removed from messages at the time they are
16589 received. Exim's transports have options for adding &'Return-path:'& headers at
16590 the time of delivery. They are normally used only for final local deliveries.
16591
16592
16593 .option return_size_limit main integer 100K
16594 This option is an obsolete synonym for &%bounce_return_size_limit%&.
16595
16596
16597 .option rfc1413_hosts main "host list&!!" @[]
16598 .cindex "RFC 1413"
16599 .cindex "host" "for RFC 1413 calls"
16600 RFC 1413 identification calls are made to any client host which matches
16601 an item in the list.
16602 The default value specifies just this host, being any local interface
16603 for the system.
16604
16605 .option rfc1413_query_timeout main time 0s
16606 .cindex "RFC 1413" "query timeout"
16607 .cindex "timeout" "for RFC 1413 call"
16608 This sets the timeout on RFC 1413 identification calls. If it is set to zero,
16609 no RFC 1413 calls are ever made.
16610
16611
16612 .option sender_unqualified_hosts main "host list&!!" unset
16613 .cindex "unqualified addresses"
16614 .cindex "host" "unqualified addresses from"
16615 This option lists those hosts from which Exim is prepared to accept unqualified
16616 sender addresses. The addresses are made fully qualified by the addition of
16617 &%qualify_domain%&. This option also affects message header lines. Exim does
16618 not reject unqualified addresses in headers that contain sender addresses, but
16619 it qualifies them only if the message came from a host that matches
16620 &%sender_unqualified_hosts%&, or if the message was submitted locally (not
16621 using TCP/IP), and the &%-bnq%& option was not set.
16622
16623 .option set_environment main "string list" empty
16624 .cindex "environment"
16625 This option allows to set individual environment variables that the
16626 currently linked libraries and programs in child processes use. The
16627 default list is empty,
16628
16629
16630 .option slow_lookup_log main integer 0
16631 .cindex "logging" "slow lookups"
16632 .cindex "dns" "logging slow lookups"
16633 This option controls logging of slow lookups.
16634 If the value is nonzero it is taken as a number of milliseconds
16635 and lookups taking longer than this are logged.
16636 Currently this applies only to DNS lookups.
16637
16638
16639
16640 .option smtp_accept_keepalive main boolean true
16641 .cindex "keepalive" "on incoming connection"
16642 This option controls the setting of the SO_KEEPALIVE option on incoming
16643 TCP/IP socket connections. When set, it causes the kernel to probe idle
16644 connections periodically, by sending packets with &"old"& sequence numbers. The
16645 other end of the connection should send an acknowledgment if the connection is
16646 still okay or a reset if the connection has been aborted. The reason for doing
16647 this is that it has the beneficial effect of freeing up certain types of
16648 connection that can get stuck when the remote host is disconnected without
16649 tidying up the TCP/IP call properly. The keepalive mechanism takes several
16650 hours to detect unreachable hosts.
16651
16652
16653
16654 .option smtp_accept_max main integer 20
16655 .cindex "limit" "incoming SMTP connections"
16656 .cindex "SMTP" "incoming connection count"
16657 .cindex "inetd"
16658 This option specifies the maximum number of simultaneous incoming SMTP calls
16659 that Exim will accept. It applies only to the listening daemon; there is no
16660 control (in Exim) when incoming SMTP is being handled by &'inetd'&. If the
16661 value is set to zero, no limit is applied. However, it is required to be
16662 non-zero if either &%smtp_accept_max_per_host%& or &%smtp_accept_queue%& is
16663 set. See also &%smtp_accept_reserve%& and &%smtp_load_reserve%&.
16664
16665 A new SMTP connection is immediately rejected if the &%smtp_accept_max%& limit
16666 has been reached. If not, Exim first checks &%smtp_accept_max_per_host%&. If
16667 that limit has not been reached for the client host, &%smtp_accept_reserve%&
16668 and &%smtp_load_reserve%& are then checked before accepting the connection.
16669
16670
16671 .option smtp_accept_max_nonmail main integer 10
16672 .cindex "limit" "non-mail SMTP commands"
16673 .cindex "SMTP" "limiting non-mail commands"
16674 Exim counts the number of &"non-mail"& commands in an SMTP session, and drops
16675 the connection if there are too many. This option defines &"too many"&. The
16676 check catches some denial-of-service attacks, repeated failing AUTHs, or a mad
16677 client looping sending EHLO, for example. The check is applied only if the
16678 client host matches &%smtp_accept_max_nonmail_hosts%&.
16679
16680 When a new message is expected, one occurrence of RSET is not counted. This
16681 allows a client to send one RSET between messages (this is not necessary,
16682 but some clients do it). Exim also allows one uncounted occurrence of HELO
16683 or EHLO, and one occurrence of STARTTLS between messages. After
16684 starting up a TLS session, another EHLO is expected, and so it too is not
16685 counted. The first occurrence of AUTH in a connection, or immediately
16686 following STARTTLS is not counted. Otherwise, all commands other than
16687 MAIL, RCPT, DATA, and QUIT are counted.
16688
16689
16690 .option smtp_accept_max_nonmail_hosts main "host list&!!" *
16691 You can control which hosts are subject to the &%smtp_accept_max_nonmail%&
16692 check by setting this option. The default value makes it apply to all hosts. By
16693 changing the value, you can exclude any badly-behaved hosts that you have to
16694 live with.
16695
16696
16697 . Allow this long option name to split; give it unsplit as a fifth argument
16698 . for the automatic .oindex that is generated by .option.
16699 . We insert " &~&~" which is both pretty nasty visually and results in
16700 . non-searchable text.  HowItWorks.txt mentions an option for inserting
16701 . zero-width-space, which would be nicer visually and results in (at least)
16702 . html that Firefox will split on when it's forced to reflow (rather than
16703 . inserting a horizontal scrollbar).  However, the text is still not
16704 . searchable.  NM changed this occurrence for bug 1197 to no longer allow
16705 . the option name to split.
16706
16707 .option "smtp_accept_max_per_connection" main integer 1000 &&&
16708          smtp_accept_max_per_connection
16709 .cindex "SMTP" "limiting incoming message count"
16710 .cindex "limit" "messages per SMTP connection"
16711 The value of this option limits the number of MAIL commands that Exim is
16712 prepared to accept over a single SMTP connection, whether or not each command
16713 results in the transfer of a message. After the limit is reached, a 421
16714 response is given to subsequent MAIL commands. This limit is a safety
16715 precaution against a client that goes mad (incidents of this type have been
16716 seen).
16717
16718
16719 .option smtp_accept_max_per_host main string&!! unset
16720 .cindex "limit" "SMTP connections from one host"
16721 .cindex "host" "limiting SMTP connections from"
16722 This option restricts the number of simultaneous IP connections from a single
16723 host (strictly, from a single IP address) to the Exim daemon. The option is
16724 expanded, to enable different limits to be applied to different hosts by
16725 reference to &$sender_host_address$&. Once the limit is reached, additional
16726 connection attempts from the same host are rejected with error code 421. This
16727 is entirely independent of &%smtp_accept_reserve%&. The option's default value
16728 of zero imposes no limit. If this option is set greater than zero, it is
16729 required that &%smtp_accept_max%& be non-zero.
16730
16731 &*Warning*&: When setting this option you should not use any expansion
16732 constructions that take an appreciable amount of time. The expansion and test
16733 happen in the main daemon loop, in order to reject additional connections
16734 without forking additional processes (otherwise a denial-of-service attack
16735 could cause a vast number or processes to be created). While the daemon is
16736 doing this processing, it cannot accept any other incoming connections.
16737
16738
16739
16740 .option smtp_accept_queue main integer 0
16741 .cindex "SMTP" "incoming connection count"
16742 .cindex "queueing incoming messages"
16743 .cindex "message" "queueing by SMTP connection count"
16744 If the number of simultaneous incoming SMTP connections being handled via the
16745 listening daemon exceeds this value, messages received by SMTP are just placed
16746 on the queue; no delivery processes are started automatically. The count is
16747 fixed at the start of an SMTP connection. It cannot be updated in the
16748 subprocess that receives messages, and so the queueing or not queueing applies
16749 to all messages received in the same connection.
16750
16751 A value of zero implies no limit, and clearly any non-zero value is useful only
16752 if it is less than the &%smtp_accept_max%& value (unless that is zero). See
16753 also &%queue_only%&, &%queue_only_load%&, &%queue_smtp_domains%&, and the
16754 various &%-od%&&'x'& command line options.
16755
16756
16757 . See the comment on smtp_accept_max_per_connection
16758
16759 .option "smtp_accept_queue_per_connection" main integer 10 &&&
16760          smtp_accept_queue_per_connection
16761 .cindex "queueing incoming messages"
16762 .cindex "message" "queueing by message count"
16763 This option limits the number of delivery processes that Exim starts
16764 automatically when receiving messages via SMTP, whether via the daemon or by
16765 the use of &%-bs%& or &%-bS%&. If the value of the option is greater than zero,
16766 and the number of messages received in a single SMTP session exceeds this
16767 number, subsequent messages are placed on the queue, but no delivery processes
16768 are started. This helps to limit the number of Exim processes when a server
16769 restarts after downtime and there is a lot of mail waiting for it on other
16770 systems. On large systems, the default should probably be increased, and on
16771 dial-in client systems it should probably be set to zero (that is, disabled).
16772
16773
16774 .option smtp_accept_reserve main integer 0
16775 .cindex "SMTP" "incoming call count"
16776 .cindex "host" "reserved"
16777 When &%smtp_accept_max%& is set greater than zero, this option specifies a
16778 number of SMTP connections that are reserved for connections from the hosts
16779 that are specified in &%smtp_reserve_hosts%&. The value set in
16780 &%smtp_accept_max%& includes this reserve pool. The specified hosts are not
16781 restricted to this number of connections; the option specifies a minimum number
16782 of connection slots for them, not a maximum. It is a guarantee that this group
16783 of hosts can always get at least &%smtp_accept_reserve%& connections. However,
16784 the limit specified by &%smtp_accept_max_per_host%& is still applied to each
16785 individual host.
16786
16787 For example, if &%smtp_accept_max%& is set to 50 and &%smtp_accept_reserve%& is
16788 set to 5, once there are 45 active connections (from any hosts), new
16789 connections are accepted only from hosts listed in &%smtp_reserve_hosts%&,
16790 provided the other criteria for acceptance are met.
16791
16792
16793 .option smtp_active_hostname main string&!! unset
16794 .cindex "host" "name in SMTP responses"
16795 .cindex "SMTP" "host name in responses"
16796 .vindex "&$primary_hostname$&"
16797 This option is provided for multi-homed servers that want to masquerade as
16798 several different hosts. At the start of an incoming SMTP connection, its value
16799 is expanded and used instead of the value of &$primary_hostname$& in SMTP
16800 responses. For example, it is used as domain name in the response to an
16801 incoming HELO or EHLO command.
16802
16803 .vindex "&$smtp_active_hostname$&"
16804 The active hostname is placed in the &$smtp_active_hostname$& variable, which
16805 is saved with any messages that are received. It is therefore available for use
16806 in routers and transports when the message is later delivered.
16807
16808 If this option is unset, or if its expansion is forced to fail, or if the
16809 expansion results in an empty string, the value of &$primary_hostname$& is
16810 used. Other expansion failures cause a message to be written to the main and
16811 panic logs, and the SMTP command receives a temporary error. Typically, the
16812 value of &%smtp_active_hostname%& depends on the incoming interface address.
16813 For example:
16814 .code
16815 smtp_active_hostname = ${if eq{$received_ip_address}{10.0.0.1}\
16816   {cox.mydomain}{box.mydomain}}
16817 .endd
16818
16819 Although &$smtp_active_hostname$& is primarily concerned with incoming
16820 messages, it is also used as the default for HELO commands in callout
16821 verification if there is no remote transport from which to obtain a
16822 &%helo_data%& value.
16823
16824 .option smtp_banner main string&!! "see below"
16825 .cindex "SMTP" "welcome banner"
16826 .cindex "banner for SMTP"
16827 .cindex "welcome banner for SMTP"
16828 .cindex "customizing" "SMTP banner"
16829 This string, which is expanded every time it is used, is output as the initial
16830 positive response to an SMTP connection. The default setting is:
16831 .code
16832 smtp_banner = $smtp_active_hostname ESMTP Exim \
16833   $version_number $tod_full
16834 .endd
16835 Failure to expand the string causes a panic error. If you want to create a
16836 multiline response to the initial SMTP connection, use &"\n"& in the string at
16837 appropriate points, but not at the end. Note that the 220 code is not included
16838 in this string. Exim adds it automatically (several times in the case of a
16839 multiline response).
16840
16841
16842 .option smtp_check_spool_space main boolean true
16843 .cindex "checking disk space"
16844 .cindex "disk space, checking"
16845 .cindex "spool directory" "checking space"
16846 When this option is set, if an incoming SMTP session encounters the SIZE
16847 option on a MAIL command, it checks that there is enough space in the
16848 spool directory's partition to accept a message of that size, while still
16849 leaving free the amount specified by &%check_spool_space%& (even if that value
16850 is zero). If there isn't enough space, a temporary error code is returned.
16851
16852
16853 .option smtp_connect_backlog main integer 20
16854 .cindex "connection backlog"
16855 .cindex "SMTP" "connection backlog"
16856 .cindex "backlog of connections"
16857 This option specifies a maximum number of waiting SMTP connections. Exim passes
16858 this value to the TCP/IP system when it sets up its listener. Once this number
16859 of connections are waiting for the daemon's attention, subsequent connection
16860 attempts are refused at the TCP/IP level. At least, that is what the manuals
16861 say; in some circumstances such connection attempts have been observed to time
16862 out instead. For large systems it is probably a good idea to increase the
16863 value (to 50, say). It also gives some protection against denial-of-service
16864 attacks by SYN flooding.
16865
16866
16867 .option smtp_enforce_sync main boolean true
16868 .cindex "SMTP" "synchronization checking"
16869 .cindex "synchronization checking in SMTP"
16870 The SMTP protocol specification requires the client to wait for a response from
16871 the server at certain points in the dialogue. Without PIPELINING these
16872 synchronization points are after every command; with PIPELINING they are
16873 fewer, but they still exist.
16874
16875 Some spamming sites send out a complete set of SMTP commands without waiting
16876 for any response. Exim protects against this by rejecting a message if the
16877 client has sent further input when it should not have. The error response &"554
16878 SMTP synchronization error"& is sent, and the connection is dropped. Testing
16879 for this error cannot be perfect because of transmission delays (unexpected
16880 input may be on its way but not yet received when Exim checks). However, it
16881 does detect many instances.
16882
16883 The check can be globally disabled by setting &%smtp_enforce_sync%& false.
16884 If you want to disable the check selectively (for example, only for certain
16885 hosts), you can do so by an appropriate use of a &%control%& modifier in an ACL
16886 (see section &<<SECTcontrols>>&). See also &%pipelining_advertise_hosts%&.
16887
16888
16889
16890 .option smtp_etrn_command main string&!! unset
16891 .cindex "ETRN" "command to be run"
16892 .vindex "&$domain$&"
16893 If this option is set, the given command is run whenever an SMTP ETRN
16894 command is received from a host that is permitted to issue such commands (see
16895 chapter &<<CHAPACL>>&). The string is split up into separate arguments which
16896 are independently expanded. The expansion variable &$domain$& is set to the
16897 argument of the ETRN command, and no syntax checking is done on it. For
16898 example:
16899 .code
16900 smtp_etrn_command = /etc/etrn_command $domain \
16901                     $sender_host_address
16902 .endd
16903 A new process is created to run the command, but Exim does not wait for it to
16904 complete. Consequently, its status cannot be checked. If the command cannot be
16905 run, a line is written to the panic log, but the ETRN caller still receives
16906 a 250 success response. Exim is normally running under its own uid when
16907 receiving SMTP, so it is not possible for it to change the uid before running
16908 the command.
16909
16910
16911 .option smtp_etrn_serialize main boolean true
16912 .cindex "ETRN" "serializing"
16913 When this option is set, it prevents the simultaneous execution of more than
16914 one identical command as a result of ETRN in an SMTP connection. See
16915 section &<<SECTETRN>>& for details.
16916
16917
16918 .option smtp_load_reserve main fixed-point unset
16919 .cindex "load average"
16920 If the system load average ever gets higher than this, incoming SMTP calls are
16921 accepted only from those hosts that match an entry in &%smtp_reserve_hosts%&.
16922 If &%smtp_reserve_hosts%& is not set, no incoming SMTP calls are accepted when
16923 the load is over the limit. The option has no effect on ancient operating
16924 systems on which Exim cannot determine the load average. See also
16925 &%deliver_queue_load_max%& and &%queue_only_load%&.
16926
16927
16928
16929 .option smtp_max_synprot_errors main integer 3
16930 .cindex "SMTP" "limiting syntax and protocol errors"
16931 .cindex "limit" "SMTP syntax and protocol errors"
16932 Exim rejects SMTP commands that contain syntax or protocol errors. In
16933 particular, a syntactically invalid email address, as in this command:
16934 .code
16935 RCPT TO:<abc xyz@a.b.c>
16936 .endd
16937 causes immediate rejection of the command, before any other tests are done.
16938 (The ACL cannot be run if there is no valid address to set up for it.) An
16939 example of a protocol error is receiving RCPT before MAIL. If there are
16940 too many syntax or protocol errors in one SMTP session, the connection is
16941 dropped. The limit is set by this option.
16942
16943 .cindex "PIPELINING" "expected errors"
16944 When the PIPELINING extension to SMTP is in use, some protocol errors are
16945 &"expected"&, for instance, a RCPT command after a rejected MAIL command.
16946 Exim assumes that PIPELINING will be used if it advertises it (see
16947 &%pipelining_advertise_hosts%&), and in this situation, &"expected"& errors do
16948 not count towards the limit.
16949
16950
16951
16952 .option smtp_max_unknown_commands main integer 3
16953 .cindex "SMTP" "limiting unknown commands"
16954 .cindex "limit" "unknown SMTP commands"
16955 If there are too many unrecognized commands in an incoming SMTP session, an
16956 Exim server drops the connection. This is a defence against some kinds of abuse
16957 that subvert web
16958 clients
16959 into making connections to SMTP ports; in these circumstances, a number of
16960 non-SMTP command lines are sent first.
16961
16962
16963
16964 .option smtp_ratelimit_hosts main "host list&!!" unset
16965 .cindex "SMTP" "rate limiting"
16966 .cindex "limit" "rate of message arrival"
16967 .cindex "RCPT" "rate limiting"
16968 Some sites find it helpful to be able to limit the rate at which certain hosts
16969 can send them messages, and the rate at which an individual message can specify
16970 recipients.
16971
16972 Exim has two rate-limiting facilities. This section describes the older
16973 facility, which can limit rates within a single connection. The newer
16974 &%ratelimit%& ACL condition can limit rates across all connections. See section
16975 &<<SECTratelimiting>>& for details of the newer facility.
16976
16977 When a host matches &%smtp_ratelimit_hosts%&, the values of
16978 &%smtp_ratelimit_mail%& and &%smtp_ratelimit_rcpt%& are used to control the
16979 rate of acceptance of MAIL and RCPT commands in a single SMTP session,
16980 respectively. Each option, if set, must contain a set of four comma-separated
16981 values:
16982
16983 .ilist
16984 A threshold, before which there is no rate limiting.
16985 .next
16986 An initial time delay. Unlike other times in Exim, numbers with decimal
16987 fractional parts are allowed here.
16988 .next
16989 A factor by which to increase the delay each time.
16990 .next
16991 A maximum value for the delay. This should normally be less than 5 minutes,
16992 because after that time, the client is liable to timeout the SMTP command.
16993 .endlist
16994
16995 For example, these settings have been used successfully at the site which
16996 first suggested this feature, for controlling mail from their customers:
16997 .code
16998 smtp_ratelimit_mail = 2,0.5s,1.05,4m
16999 smtp_ratelimit_rcpt = 4,0.25s,1.015,4m
17000 .endd
17001 The first setting specifies delays that are applied to MAIL commands after
17002 two have been received over a single connection. The initial delay is 0.5
17003 seconds, increasing by a factor of 1.05 each time. The second setting applies
17004 delays to RCPT commands when more than four occur in a single message.
17005
17006
17007 .option smtp_ratelimit_mail main string unset
17008 See &%smtp_ratelimit_hosts%& above.
17009
17010
17011 .option smtp_ratelimit_rcpt main string unset
17012 See &%smtp_ratelimit_hosts%& above.
17013
17014
17015 .option smtp_receive_timeout main time&!! 5m
17016 .cindex "timeout" "for SMTP input"
17017 .cindex "SMTP" "input timeout"
17018 This sets a timeout value for SMTP reception. It applies to all forms of SMTP
17019 input, including batch SMTP. If a line of input (either an SMTP command or a
17020 data line) is not received within this time, the SMTP connection is dropped and
17021 the message is abandoned.
17022 A line is written to the log containing one of the following messages:
17023 .code
17024 SMTP command timeout on connection from...
17025 SMTP data timeout on connection from...
17026 .endd
17027 The former means that Exim was expecting to read an SMTP command; the latter
17028 means that it was in the DATA phase, reading the contents of a message.
17029
17030 If the first character of the option is a &"$"& the option is
17031 expanded before use and may depend on
17032 &$sender_host_name$&, &$sender_host_address$& and &$sender_host_port$&.
17033
17034
17035 .oindex "&%-os%&"
17036 The value set by this option can be overridden by the
17037 &%-os%& command-line option. A setting of zero time disables the timeout, but
17038 this should never be used for SMTP over TCP/IP. (It can be useful in some cases
17039 of local input using &%-bs%& or &%-bS%&.) For non-SMTP input, the reception
17040 timeout is controlled by &%receive_timeout%& and &%-or%&.
17041
17042
17043 .option smtp_reserve_hosts main "host list&!!" unset
17044 This option defines hosts for which SMTP connections are reserved; see
17045 &%smtp_accept_reserve%& and &%smtp_load_reserve%& above.
17046
17047
17048 .option smtp_return_error_details main boolean false
17049 .cindex "SMTP" "details policy failures"
17050 .cindex "policy control" "rejection, returning details"
17051 In the default state, Exim uses bland messages such as
17052 &"Administrative prohibition"& when it rejects SMTP commands for policy
17053 reasons. Many sysadmins like this because it gives away little information
17054 to spammers. However, some other sysadmins who are applying strict checking
17055 policies want to give out much fuller information about failures. Setting
17056 &%smtp_return_error_details%& true causes Exim to be more forthcoming. For
17057 example, instead of &"Administrative prohibition"&, it might give:
17058 .code
17059 550-Rejected after DATA: '>' missing at end of address:
17060 550 failing address in "From" header is: <user@dom.ain
17061 .endd
17062
17063
17064 .option smtputf8_advertise_hosts main "host list&!!" *
17065 .cindex "SMTPUTF8" "advertising"
17066 When Exim is built with support for internationalised mail names,
17067 the availability thereof is advertised in
17068 response to EHLO only to those client hosts that match this option. See
17069 chapter &<<CHAPi18n>>& for details of Exim's support for internationalisation.
17070
17071
17072 .option spamd_address main string "127.0.0.1 783"
17073 This option is available when Exim is compiled with the content-scanning
17074 extension. It specifies how Exim connects to SpamAssassin's &%spamd%& daemon.
17075 See section &<<SECTscanspamass>>& for more details.
17076
17077
17078
17079 .option spf_guess main string "v=spf1 a/24 mx/24 ptr ?all"
17080 This option is available when Exim is compiled with SPF support.
17081 See section &<<SECSPF>>& for more details.
17082
17083
17084
17085 .option split_spool_directory main boolean false
17086 .cindex "multiple spool directories"
17087 .cindex "spool directory" "split"
17088 .cindex "directories, multiple"
17089 If this option is set, it causes Exim to split its input directory into 62
17090 subdirectories, each with a single alphanumeric character as its name. The
17091 sixth character of the message id is used to allocate messages to
17092 subdirectories; this is the least significant base-62 digit of the time of
17093 arrival of the message.
17094
17095 Splitting up the spool in this way may provide better performance on systems
17096 where there are long mail queues, by reducing the number of files in any one
17097 directory. The msglog directory is also split up in a similar way to the input
17098 directory; however, if &%preserve_message_logs%& is set, all old msglog files
17099 are still placed in the single directory &_msglog.OLD_&.
17100
17101 It is not necessary to take any special action for existing messages when
17102 changing &%split_spool_directory%&. Exim notices messages that are in the
17103 &"wrong"& place, and continues to process them. If the option is turned off
17104 after a period of being on, the subdirectories will eventually empty and be
17105 automatically deleted.
17106
17107 When &%split_spool_directory%& is set, the behaviour of queue runner processes
17108 changes. Instead of creating a list of all messages in the queue, and then
17109 trying to deliver each one in turn, it constructs a list of those in one
17110 sub-directory and tries to deliver them, before moving on to the next
17111 sub-directory. The sub-directories are processed in a random order. This
17112 spreads out the scanning of the input directories, and uses less memory. It is
17113 particularly beneficial when there are lots of messages on the queue. However,
17114 if &%queue_run_in_order%& is set, none of this new processing happens. The
17115 entire queue has to be scanned and sorted before any deliveries can start.
17116
17117
17118 .option spool_directory main string&!! "set at compile time"
17119 .cindex "spool directory" "path to"
17120 This defines the directory in which Exim keeps its spool, that is, the messages
17121 it is waiting to deliver. The default value is taken from the compile-time
17122 configuration setting, if there is one. If not, this option must be set. The
17123 string is expanded, so it can contain, for example, a reference to
17124 &$primary_hostname$&.
17125
17126 If the spool directory name is fixed on your installation, it is recommended
17127 that you set it at build time rather than from this option, particularly if the
17128 log files are being written to the spool directory (see &%log_file_path%&).
17129 Otherwise log files cannot be used for errors that are detected early on, such
17130 as failures in the configuration file.
17131
17132 By using this option to override the compiled-in path, it is possible to run
17133 tests of Exim without using the standard spool.
17134
17135 .option spool_wireformat main boolean false
17136 .cindex "spool directory" "file formats"
17137 If this option is set, Exim may for some messages use an alternative format
17138 for data-files in the spool which matches the wire format.
17139 Doing this permits more efficient message reception and transmission.
17140 Currently it is only done for messages received using the ESMTP CHUNKING
17141 option.
17142
17143 The following variables will not have useful values:
17144 .code
17145 $max_received_linelength
17146 $body_linecount
17147 $body_zerocount
17148 .endd
17149
17150 Users of the local_scan() API (see &<<CHAPlocalscan>>&),
17151 and any external programs which are passed a reference to a message data file
17152 (except via the &"regex"&, &"malware"& or &"spam"&) ACL conditions)
17153 will need to be aware of the different formats potentially available.
17154
17155 Using any of the ACL conditions noted will negate the reception benefit
17156 (as a Unix-mbox-format file is constructed for them).
17157 The transmission benefit is maintained.
17158
17159 .option sqlite_lock_timeout main time 5s
17160 .cindex "sqlite lookup type" "lock timeout"
17161 This option controls the timeout that the &(sqlite)& lookup uses when trying to
17162 access an SQLite database. See section &<<SECTsqlite>>& for more details.
17163
17164 .option strict_acl_vars main boolean false
17165 .cindex "&ACL;" "variables, handling unset"
17166 This option controls what happens if a syntactically valid but undefined ACL
17167 variable is referenced. If it is false (the default), an empty string
17168 is substituted; if it is true, an error is generated. See section
17169 &<<SECTaclvariables>>& for details of ACL variables.
17170
17171 .option strip_excess_angle_brackets main boolean false
17172 .cindex "angle brackets, excess"
17173 If this option is set, redundant pairs of angle brackets round &"route-addr"&
17174 items in addresses are stripped. For example, &'<<xxx@a.b.c.d>>'& is
17175 treated as &'<xxx@a.b.c.d>'&. If this is in the envelope and the message is
17176 passed on to another MTA, the excess angle brackets are not passed on. If this
17177 option is not set, multiple pairs of angle brackets cause a syntax error.
17178
17179
17180 .option strip_trailing_dot main boolean false
17181 .cindex "trailing dot on domain"
17182 .cindex "dot" "trailing on domain"
17183 If this option is set, a trailing dot at the end of a domain in an address is
17184 ignored. If this is in the envelope and the message is passed on to another
17185 MTA, the dot is not passed on. If this option is not set, a dot at the end of a
17186 domain causes a syntax error.
17187 However, addresses in header lines are checked only when an ACL requests header
17188 syntax checking.
17189
17190
17191 .option syslog_duplication main boolean true
17192 .cindex "syslog" "duplicate log lines; suppressing"
17193 When Exim is logging to syslog, it writes the log lines for its three
17194 separate logs at different syslog priorities so that they can in principle
17195 be separated on the logging hosts. Some installations do not require this
17196 separation, and in those cases, the duplication of certain log lines is a
17197 nuisance. If &%syslog_duplication%& is set false, only one copy of any
17198 particular log line is written to syslog. For lines that normally go to
17199 both the main log and the reject log, the reject log version (possibly
17200 containing message header lines) is written, at LOG_NOTICE priority.
17201 Lines that normally go to both the main and the panic log are written at
17202 the LOG_ALERT priority.
17203
17204
17205 .option syslog_facility main string unset
17206 .cindex "syslog" "facility; setting"
17207 This option sets the syslog &"facility"& name, used when Exim is logging to
17208 syslog. The value must be one of the strings &"mail"&, &"user"&, &"news"&,
17209 &"uucp"&, &"daemon"&, or &"local&'x'&"& where &'x'& is a digit between 0 and 7.
17210 If this option is unset, &"mail"& is used. See chapter &<<CHAPlog>>& for
17211 details of Exim's logging.
17212
17213
17214 .option syslog_pid main boolean true
17215 .cindex "syslog" "pid"
17216 If &%syslog_pid%& is set false, the PID on Exim's log lines are
17217 omitted when these lines are sent to syslog. (Syslog normally prefixes
17218 the log lines with the PID of the logging process automatically.) You need
17219 to enable the &`+pid`& log selector item, if you want Exim to write it's PID
17220 into the logs.) See chapter &<<CHAPlog>>& for details of Exim's logging.
17221
17222
17223
17224 .option syslog_processname main string &`exim`&
17225 .cindex "syslog" "process name; setting"
17226 This option sets the syslog &"ident"& name, used when Exim is logging to
17227 syslog. The value must be no longer than 32 characters. See chapter
17228 &<<CHAPlog>>& for details of Exim's logging.
17229
17230
17231
17232 .option syslog_timestamp main boolean true
17233 .cindex "syslog" "timestamps"
17234 If &%syslog_timestamp%& is set false, the timestamps on Exim's log lines are
17235 omitted when these lines are sent to syslog. See chapter &<<CHAPlog>>& for
17236 details of Exim's logging.
17237
17238
17239 .option system_filter main string&!! unset
17240 .cindex "filter" "system filter"
17241 .cindex "system filter" "specifying"
17242 .cindex "Sieve filter" "not available for system filter"
17243 This option specifies an Exim filter file that is applied to all messages at
17244 the start of each delivery attempt, before any routing is done. System filters
17245 must be Exim filters; they cannot be Sieve filters. If the system filter
17246 generates any deliveries to files or pipes, or any new mail messages, the
17247 appropriate &%system_filter_..._transport%& option(s) must be set, to define
17248 which transports are to be used. Details of this facility are given in chapter
17249 &<<CHAPsystemfilter>>&.
17250 A forced expansion failure results in no filter operation.
17251
17252
17253 .option system_filter_directory_transport main string&!! unset
17254 .vindex "&$address_file$&"
17255 This sets the name of the transport driver that is to be used when the
17256 &%save%& command in a system message filter specifies a path ending in &"/"&,
17257 implying delivery of each message into a separate file in some directory.
17258 During the delivery, the variable &$address_file$& contains the path name.
17259
17260
17261 .option system_filter_file_transport main string&!! unset
17262 .cindex "file" "transport for system filter"
17263 This sets the name of the transport driver that is to be used when the &%save%&
17264 command in a system message filter specifies a path not ending in &"/"&. During
17265 the delivery, the variable &$address_file$& contains the path name.
17266
17267 .option system_filter_group main string unset
17268 .cindex "gid (group id)" "system filter"
17269 This option is used only when &%system_filter_user%& is also set. It sets the
17270 gid under which the system filter is run, overriding any gid that is associated
17271 with the user. The value may be numerical or symbolic.
17272
17273 .option system_filter_pipe_transport main string&!! unset
17274 .cindex "&(pipe)& transport" "for system filter"
17275 .vindex "&$address_pipe$&"
17276 This specifies the transport driver that is to be used when a &%pipe%& command
17277 is used in a system filter. During the delivery, the variable &$address_pipe$&
17278 contains the pipe command.
17279
17280
17281 .option system_filter_reply_transport main string&!! unset
17282 .cindex "&(autoreply)& transport" "for system filter"
17283 This specifies the transport driver that is to be used when a &%mail%& command
17284 is used in a system filter.
17285
17286
17287 .option system_filter_user main string unset
17288 .cindex "uid (user id)" "system filter"
17289 If this option is set to root, the system filter is run in the main Exim
17290 delivery process, as root.  Otherwise, the system filter runs in a separate
17291 process, as the given user, defaulting to the Exim run-time user.
17292 Unless the string consists entirely of digits, it
17293 is looked up in the password data. Failure to find the named user causes a
17294 configuration error. The gid is either taken from the password data, or
17295 specified by &%system_filter_group%&. When the uid is specified numerically,
17296 &%system_filter_group%& is required to be set.
17297
17298 If the system filter generates any pipe, file, or reply deliveries, the uid
17299 under which the filter is run is used when transporting them, unless a
17300 transport option overrides.
17301
17302
17303 .option tcp_nodelay main boolean true
17304 .cindex "daemon" "TCP_NODELAY on sockets"
17305 .cindex "Nagle algorithm"
17306 .cindex "TCP_NODELAY on listening sockets"
17307 If this option is set false, it stops the Exim daemon setting the
17308 TCP_NODELAY option on its listening sockets. Setting TCP_NODELAY
17309 turns off the &"Nagle algorithm"&, which is a way of improving network
17310 performance in interactive (character-by-character) situations. Turning it off
17311 should improve Exim's performance a bit, so that is what happens by default.
17312 However, it appears that some broken clients cannot cope, and time out. Hence
17313 this option. It affects only those sockets that are set up for listening by the
17314 daemon. Sockets created by the smtp transport for delivering mail always set
17315 TCP_NODELAY.
17316
17317
17318 .option timeout_frozen_after main time 0s
17319 .cindex "frozen messages" "timing out"
17320 .cindex "timeout" "frozen messages"
17321 If &%timeout_frozen_after%& is set to a time greater than zero, a frozen
17322 message of any kind that has been on the queue for longer than the given time
17323 is automatically cancelled at the next queue run. If the frozen message is a
17324 bounce message, it is just discarded; otherwise, a bounce is sent to the
17325 sender, in a similar manner to cancellation by the &%-Mg%& command line option.
17326 If you want to timeout frozen bounce messages earlier than other kinds of
17327 frozen message, see &%ignore_bounce_errors_after%&.
17328
17329 &*Note:*& the default value of zero means no timeouts; with this setting,
17330 frozen messages remain on the queue forever (except for any frozen bounce
17331 messages that are released by &%ignore_bounce_errors_after%&).
17332
17333
17334 .option timezone main string unset
17335 .cindex "timezone, setting"
17336 .cindex "environment" "values from"
17337 The value of &%timezone%& is used to set the environment variable TZ while
17338 running Exim (if it is different on entry). This ensures that all timestamps
17339 created by Exim are in the required timezone. If you want all your timestamps
17340 to be in UTC (aka GMT) you should set
17341 .code
17342 timezone = UTC
17343 .endd
17344 The default value is taken from TIMEZONE_DEFAULT in &_Local/Makefile_&,
17345 or, if that is not set, from the value of the TZ environment variable when Exim
17346 is built. If &%timezone%& is set to the empty string, either at build or run
17347 time, any existing TZ variable is removed from the environment when Exim
17348 runs. This is appropriate behaviour for obtaining wall-clock time on some, but
17349 unfortunately not all, operating systems.
17350
17351
17352 .option tls_advertise_hosts main "host list&!!" *
17353 .cindex "TLS" "advertising"
17354 .cindex "encryption" "on SMTP connection"
17355 .cindex "SMTP" "encrypted connection"
17356 When Exim is built with support for TLS encrypted connections, the availability
17357 of the STARTTLS command to set up an encrypted session is advertised in
17358 response to EHLO only to those client hosts that match this option. See
17359 chapter &<<CHAPTLS>>& for details of Exim's support for TLS.
17360 Note that the default value requires that a certificate be supplied
17361 using the &%tls_certificate%& option.  If TLS support for incoming connections
17362 is not required the &%tls_advertise_hosts%& option should be set empty.
17363
17364
17365 .option tls_certificate main string list&!! unset
17366 .cindex "TLS" "server certificate; location of"
17367 .cindex "certificate" "server, location of"
17368 The value of this option is expanded, and must then be a list of absolute paths to
17369 files which contains the server's certificates.  Commonly only one file is
17370 needed.
17371 The server's private key is also
17372 assumed to be in this file if &%tls_privatekey%& is unset. See chapter
17373 &<<CHAPTLS>>& for further details.
17374
17375 &*Note*&: The certificates defined by this option are used only when Exim is
17376 receiving incoming messages as a server. If you want to supply certificates for
17377 use when sending messages as a client, you must set the &%tls_certificate%&
17378 option in the relevant &(smtp)& transport.
17379
17380 &*Note*&: If you use filenames based on IP addresses, change the list
17381 separator in the usual way to avoid confusion under IPv6.
17382
17383 &*Note*&: Under versions of OpenSSL preceding 1.1.1,
17384 when a list of more than one
17385 file is used, the &$tls_in_ourcert$& variable is unreliable.
17386
17387 &*Note*&: OCSP stapling is not usable under OpenSSL
17388 when a list of more than one file is used.
17389
17390 If the option contains &$tls_out_sni$& and Exim is built against OpenSSL, then
17391 if the OpenSSL build supports TLS extensions and the TLS client sends the
17392 Server Name Indication extension, then this option and others documented in
17393 &<<SECTtlssni>>& will be re-expanded.
17394
17395 If this option is unset or empty a fresh self-signed certificate will be
17396 generated for every connection.
17397
17398 .option tls_crl main string&!! unset
17399 .cindex "TLS" "server certificate revocation list"
17400 .cindex "certificate" "revocation list for server"
17401 This option specifies a certificate revocation list. The expanded value must
17402 be the name of a file that contains CRLs in PEM format.
17403
17404 Under OpenSSL the option can specify a directory with CRL files.
17405
17406 &*Note:*& Under OpenSSL the option must, if given, supply a CRL
17407 for each signing element of the certificate chain (i.e. all but the leaf).
17408 For the file variant this can be multiple PEM blocks in the one file.
17409
17410 See &<<SECTtlssni>>& for discussion of when this option might be re-expanded.
17411
17412
17413 .option tls_dh_max_bits main integer 2236
17414 .cindex "TLS" "D-H bit count"
17415 The number of bits used for Diffie-Hellman key-exchange may be suggested by
17416 the chosen TLS library.  That value might prove to be too high for
17417 interoperability.  This option provides a maximum clamp on the value
17418 suggested, trading off security for interoperability.
17419
17420 The value must be at least 1024.
17421
17422 The value 2236 was chosen because, at time of adding the option, it was the
17423 hard-coded maximum value supported by the NSS cryptographic library, as used
17424 by Thunderbird, while GnuTLS was suggesting 2432 bits as normal.
17425
17426 If you prefer more security and are willing to break some clients, raise this
17427 number.
17428
17429 Note that the value passed to GnuTLS for *generating* a new prime may be a
17430 little less than this figure, because GnuTLS is inexact and may produce a
17431 larger prime than requested.
17432
17433
17434 .option tls_dhparam main string&!! unset
17435 .cindex "TLS" "D-H parameters for server"
17436 The value of this option is expanded and indicates the source of DH parameters
17437 to be used by Exim.
17438
17439 &*Note: The Exim Maintainers strongly recommend using a filename with site-generated
17440 local DH parameters*&, which has been supported across all versions of Exim.  The
17441 other specific constants available are a fallback so that even when
17442 "unconfigured", Exim can offer Perfect Forward Secrecy in older ciphersuites in TLS.
17443
17444 If &%tls_dhparam%& is a filename starting with a &`/`&,
17445 then it names a file from which DH
17446 parameters should be loaded.  If the file exists, it should hold a PEM-encoded
17447 PKCS#3 representation of the DH prime.  If the file does not exist, for
17448 OpenSSL it is an error.  For GnuTLS, Exim will attempt to create the file and
17449 fill it with a generated DH prime.  For OpenSSL, if the DH bit-count from
17450 loading the file is greater than &%tls_dh_max_bits%& then it will be ignored,
17451 and treated as though the &%tls_dhparam%& were set to "none".
17452
17453 If this option expands to the string "none", then no DH parameters will be
17454 loaded by Exim.
17455
17456 If this option expands to the string "historic" and Exim is using GnuTLS, then
17457 Exim will attempt to load a file from inside the spool directory.  If the file
17458 does not exist, Exim will attempt to create it.
17459 See section &<<SECTgnutlsparam>>& for further details.
17460
17461 If Exim is using OpenSSL and this option is empty or unset, then Exim will load
17462 a default DH prime; the default is Exim-specific but lacks verifiable provenance.
17463
17464 In older versions of Exim the default was the 2048 bit prime described in section
17465 2.2 of RFC 5114, "2048-bit MODP Group with 224-bit Prime Order Subgroup", which
17466 in IKE is assigned number 23.
17467
17468 Otherwise, the option must expand to the name used by Exim for any of a number
17469 of DH primes specified in RFC 2409, RFC 3526, RFC 5114, RFC 7919, or from other
17470 sources.  As names, Exim uses a standard specified name, else "ike" followed by
17471 the number used by IKE, or "default" which corresponds to
17472 &`exim.dev.20160529.3`&.
17473
17474 The available standard primes are:
17475 &`ffdhe2048`&, &`ffdhe3072`&, &`ffdhe4096`&, &`ffdhe6144`&, &`ffdhe8192`&,
17476 &`ike1`&, &`ike2`&, &`ike5`&,
17477 &`ike14`&, &`ike15`&, &`ike16`&, &`ike17`&, &`ike18`&,
17478 &`ike22`&, &`ike23`& and &`ike24`&.
17479
17480 The available additional primes are:
17481 &`exim.dev.20160529.1`&, &`exim.dev.20160529.2`& and &`exim.dev.20160529.3`&.
17482
17483 Some of these will be too small to be accepted by clients.
17484 Some may be too large to be accepted by clients.
17485 The open cryptographic community has suspicions about the integrity of some
17486 of the later IKE values, which led into RFC7919 providing new fixed constants
17487 (the "ffdhe" identifiers).
17488
17489 At this point, all of the "ike" values should be considered obsolete;
17490 they're still in Exim to avoid breaking unusual configurations, but are
17491 candidates for removal the next time we have backwards-incompatible changes.
17492
17493 The TLS protocol does not negotiate an acceptable size for this; clients tend
17494 to hard-drop connections if what is offered by the server is unacceptable,
17495 whether too large or too small, and there's no provision for the client to
17496 tell the server what these constraints are.  Thus, as a server operator, you
17497 need to make an educated guess as to what is most likely to work for your
17498 userbase.
17499
17500 Some known size constraints suggest that a bit-size in the range 2048 to 2236
17501 is most likely to maximise interoperability.  The upper bound comes from
17502 applications using the Mozilla Network Security Services (NSS) library, which
17503 used to set its &`DH_MAX_P_BITS`& upper-bound to 2236.  This affects many
17504 mail user agents (MUAs). The lower bound comes from Debian installs of Exim4
17505 prior to the 4.80 release, as Debian used to patch Exim to raise the minimum
17506 acceptable bound from 1024 to 2048.
17507
17508
17509 .option tls_eccurve main string&!! &`auto`&
17510 .cindex TLS "EC cryptography"
17511 This option selects a EC curve for use by Exim when used with OpenSSL.
17512 It has no effect when Exim is used with GnuTLS.
17513
17514 After expansion it must contain a valid EC curve parameter, such as
17515 &`prime256v1`&, &`secp384r1`&, or &`P-512`&. Consult your OpenSSL manual
17516 for valid selections.
17517
17518 For OpenSSL versions before (and not including) 1.0.2, the string
17519 &`auto`& selects &`prime256v1`&. For more recent OpenSSL versions
17520 &`auto`& tells the library to choose.
17521
17522 If the option expands to an empty string, no EC curves will be enabled.
17523
17524
17525 .option tls_ocsp_file main string&!! unset
17526 .cindex TLS "certificate status"
17527 .cindex TLS "OCSP proof file"
17528 This option
17529 must if set expand to the absolute path to a file which contains a current
17530 status proof for the server's certificate, as obtained from the
17531 Certificate Authority.
17532
17533 Usable for GnuTLS 3.4.4 or 3.3.17 or OpenSSL 1.1.0 (or later).
17534
17535 For GnuTLS 3.5.6 or later the expanded value of this option can be a list
17536 of files, to match a list given for the &%tls_certificate%& option.
17537 The ordering of the two lists must match.
17538
17539
17540 .option tls_on_connect_ports main "string list" unset
17541 .cindex SSMTP
17542 .cindex SMTPS
17543 This option specifies a list of incoming SSMTP (aka SMTPS) ports that should
17544 operate the SSMTP (SMTPS) protocol, where a TLS session is immediately
17545 set up without waiting for the client to issue a STARTTLS command. For
17546 further details, see section &<<SECTsupobssmt>>&.
17547
17548
17549
17550 .option tls_privatekey main string list&!! unset
17551 .cindex "TLS" "server private key; location of"
17552 The value of this option is expanded, and must then be a list of absolute paths to
17553 files which contains the server's private keys.
17554 If this option is unset, or if
17555 the expansion is forced to fail, or the result is an empty string, the private
17556 key is assumed to be in the same file as the server's certificates. See chapter
17557 &<<CHAPTLS>>& for further details.
17558
17559 See &<<SECTtlssni>>& for discussion of when this option might be re-expanded.
17560
17561
17562 .option tls_remember_esmtp main boolean false
17563 .cindex "TLS" "esmtp state; remembering"
17564 .cindex "TLS" "broken clients"
17565 If this option is set true, Exim violates the RFCs by remembering that it is in
17566 &"esmtp"& state after successfully negotiating a TLS session. This provides
17567 support for broken clients that fail to send a new EHLO after starting a
17568 TLS session.
17569
17570
17571 .option tls_require_ciphers main string&!! unset
17572 .cindex "TLS" "requiring specific ciphers"
17573 .cindex "cipher" "requiring specific"
17574 This option controls which ciphers can be used for incoming TLS connections.
17575 The &(smtp)& transport has an option of the same name for controlling outgoing
17576 connections. This option is expanded for each connection, so can be varied for
17577 different clients if required. The value of this option must be a list of
17578 permitted cipher suites. The OpenSSL and GnuTLS libraries handle cipher control
17579 in somewhat different ways. If GnuTLS is being used, the client controls the
17580 preference order of the available ciphers. Details are given in sections
17581 &<<SECTreqciphssl>>& and &<<SECTreqciphgnu>>&.
17582
17583
17584 .option tls_try_verify_hosts main "host list&!!" unset
17585 .cindex "TLS" "client certificate verification"
17586 .cindex "certificate" "verification of client"
17587 See &%tls_verify_hosts%& below.
17588
17589
17590 .option tls_verify_certificates main string&!! system
17591 .cindex "TLS" "client certificate verification"
17592 .cindex "certificate" "verification of client"
17593 The value of this option is expanded, and must then be either the
17594 word "system"
17595 or the absolute path to
17596 a file or directory containing permitted certificates for clients that
17597 match &%tls_verify_hosts%& or &%tls_try_verify_hosts%&.
17598
17599 The "system" value for the option will use a
17600 system default location compiled into the SSL library.
17601 This is not available for GnuTLS versions preceding 3.0.20,
17602 and will be taken as empty; an explicit location
17603 must be specified.
17604
17605 The use of a directory for the option value is not available for GnuTLS versions
17606 preceding 3.3.6 and a single file must be used.
17607
17608 With OpenSSL the certificates specified
17609 explicitly
17610 either by file or directory
17611 are added to those given by the system default location.
17612
17613 These certificates should be for the certificate authorities trusted, rather
17614 than the public cert of individual clients.  With both OpenSSL and GnuTLS, if
17615 the value is a file then the certificates are sent by Exim as a server to
17616 connecting clients, defining the list of accepted certificate authorities.
17617 Thus the values defined should be considered public data.  To avoid this,
17618 use the explicit directory version.
17619
17620 See &<<SECTtlssni>>& for discussion of when this option might be re-expanded.
17621
17622 A forced expansion failure or setting to an empty string is equivalent to
17623 being unset.
17624
17625
17626 .option tls_verify_hosts main "host list&!!" unset
17627 .cindex "TLS" "client certificate verification"
17628 .cindex "certificate" "verification of client"
17629 This option, along with &%tls_try_verify_hosts%&, controls the checking of
17630 certificates from clients. The expected certificates are defined by
17631 &%tls_verify_certificates%&, which must be set. A configuration error occurs if
17632 either &%tls_verify_hosts%& or &%tls_try_verify_hosts%& is set and
17633 &%tls_verify_certificates%& is not set.
17634
17635 Any client that matches &%tls_verify_hosts%& is constrained by
17636 &%tls_verify_certificates%&. When the client initiates a TLS session, it must
17637 present one of the listed certificates. If it does not, the connection is
17638 aborted. &*Warning*&: Including a host in &%tls_verify_hosts%& does not require
17639 the host to use TLS. It can still send SMTP commands through unencrypted
17640 connections. Forcing a client to use TLS has to be done separately using an
17641 ACL to reject inappropriate commands when the connection is not encrypted.
17642
17643 A weaker form of checking is provided by &%tls_try_verify_hosts%&. If a client
17644 matches this option (but not &%tls_verify_hosts%&), Exim requests a
17645 certificate and checks it against &%tls_verify_certificates%&, but does not
17646 abort the connection if there is no certificate or if it does not match. This
17647 state can be detected in an ACL, which makes it possible to implement policies
17648 such as &"accept for relay only if a verified certificate has been received,
17649 but accept for local delivery if encrypted, even without a verified
17650 certificate"&.
17651
17652 Client hosts that match neither of these lists are not asked to present
17653 certificates.
17654
17655
17656 .option trusted_groups main "string list&!!" unset
17657 .cindex "trusted groups"
17658 .cindex "groups" "trusted"
17659 This option is expanded just once, at the start of Exim's processing. If this
17660 option is set, any process that is running in one of the listed groups, or
17661 which has one of them as a supplementary group, is trusted. The groups can be
17662 specified numerically or by name. See section &<<SECTtrustedadmin>>& for
17663 details of what trusted callers are permitted to do. If neither
17664 &%trusted_groups%& nor &%trusted_users%& is set, only root and the Exim user
17665 are trusted.
17666
17667 .option trusted_users main "string list&!!" unset
17668 .cindex "trusted users"
17669 .cindex "user" "trusted"
17670 This option is expanded just once, at the start of Exim's processing. If this
17671 option is set, any process that is running as one of the listed users is
17672 trusted. The users can be specified numerically or by name. See section
17673 &<<SECTtrustedadmin>>& for details of what trusted callers are permitted to do.
17674 If neither &%trusted_groups%& nor &%trusted_users%& is set, only root and the
17675 Exim user are trusted.
17676
17677 .option unknown_login main string&!! unset
17678 .cindex "uid (user id)" "unknown caller"
17679 .vindex "&$caller_uid$&"
17680 This is a specialized feature for use in unusual configurations. By default, if
17681 the uid of the caller of Exim cannot be looked up using &[getpwuid()]&, Exim
17682 gives up. The &%unknown_login%& option can be used to set a login name to be
17683 used in this circumstance. It is expanded, so values like &%user$caller_uid%&
17684 can be set. When &%unknown_login%& is used, the value of &%unknown_username%&
17685 is used for the user's real name (gecos field), unless this has been set by the
17686 &%-F%& option.
17687
17688 .option unknown_username main string unset
17689 See &%unknown_login%&.
17690
17691 .option untrusted_set_sender main "address list&!!" unset
17692 .cindex "trusted users"
17693 .cindex "sender" "setting by untrusted user"
17694 .cindex "untrusted user setting sender"
17695 .cindex "user" "untrusted setting sender"
17696 .cindex "envelope sender"
17697 When an untrusted user submits a message to Exim using the standard input, Exim
17698 normally creates an envelope sender address from the user's login and the
17699 default qualification domain. Data from the &%-f%& option (for setting envelope
17700 senders on non-SMTP messages) or the SMTP MAIL command (if &%-bs%& or &%-bS%&
17701 is used) is ignored.
17702
17703 However, untrusted users are permitted to set an empty envelope sender address,
17704 to declare that a message should never generate any bounces. For example:
17705 .code
17706 exim -f '<>' user@domain.example
17707 .endd
17708 .vindex "&$sender_ident$&"
17709 The &%untrusted_set_sender%& option allows you to permit untrusted users to set
17710 other envelope sender addresses in a controlled way. When it is set, untrusted
17711 users are allowed to set envelope sender addresses that match any of the
17712 patterns in the list. Like all address lists, the string is expanded. The
17713 identity of the user is in &$sender_ident$&, so you can, for example, restrict
17714 users to setting senders that start with their login ids
17715 followed by a hyphen
17716 by a setting like this:
17717 .code
17718 untrusted_set_sender = ^$sender_ident-
17719 .endd
17720 If you want to allow untrusted users to set envelope sender addresses without
17721 restriction, you can use
17722 .code
17723 untrusted_set_sender = *
17724 .endd
17725 The &%untrusted_set_sender%& option applies to all forms of local input, but
17726 only to the setting of the envelope sender. It does not permit untrusted users
17727 to use the other options which trusted user can use to override message
17728 parameters. Furthermore, it does not stop Exim from removing an existing
17729 &'Sender:'& header in the message, or from adding a &'Sender:'& header if
17730 necessary. See &%local_sender_retain%& and &%local_from_check%& for ways of
17731 overriding these actions. The handling of the &'Sender:'& header is also
17732 described in section &<<SECTthesenhea>>&.
17733
17734 The log line for a message's arrival shows the envelope sender following
17735 &"<="&. For local messages, the user's login always follows, after &"U="&. In
17736 &%-bp%& displays, and in the Exim monitor, if an untrusted user sets an
17737 envelope sender address, the user's login is shown in parentheses after the
17738 sender address.
17739
17740
17741 .option uucp_from_pattern main string "see below"
17742 .cindex "&""From""& line"
17743 .cindex "UUCP" "&""From""& line"
17744 Some applications that pass messages to an MTA via a command line interface use
17745 an initial line starting with &"From&~"& to pass the envelope sender. In
17746 particular, this is used by UUCP software. Exim recognizes such a line by means
17747 of a regular expression that is set in &%uucp_from_pattern%&. When the pattern
17748 matches, the sender address is constructed by expanding the contents of
17749 &%uucp_from_sender%&, provided that the caller of Exim is a trusted user. The
17750 default pattern recognizes lines in the following two forms:
17751 .code
17752 From ph10 Fri Jan  5 12:35 GMT 1996
17753 From ph10 Fri, 7 Jan 97 14:00:00 GMT
17754 .endd
17755 The pattern can be seen by running
17756 .code
17757 exim -bP uucp_from_pattern
17758 .endd
17759 It checks only up to the hours and minutes, and allows for a 2-digit or 4-digit
17760 year in the second case. The first word after &"From&~"& is matched in the
17761 regular expression by a parenthesized subpattern. The default value for
17762 &%uucp_from_sender%& is &"$1"&, which therefore just uses this first word
17763 (&"ph10"& in the example above) as the message's sender. See also
17764 &%ignore_fromline_hosts%&.
17765
17766
17767 .option uucp_from_sender main string&!! &`$1`&
17768 See &%uucp_from_pattern%& above.
17769
17770
17771 .option warn_message_file main string unset
17772 .cindex "warning of delay" "customizing the message"
17773 .cindex "customizing" "warning message"
17774 This option defines a template file containing paragraphs of text to be used
17775 for constructing the warning message which is sent by Exim when a message has
17776 been on the queue for a specified amount of time, as specified by
17777 &%delay_warning%&. Details of the file's contents are given in chapter
17778 &<<CHAPemsgcust>>&. See also &%bounce_message_file%&.
17779
17780
17781 .option write_rejectlog main boolean true
17782 .cindex "reject log" "disabling"
17783 If this option is set false, Exim no longer writes anything to the reject log.
17784 See chapter &<<CHAPlog>>& for details of what Exim writes to its logs.
17785 .ecindex IIDconfima
17786 .ecindex IIDmaiconf
17787
17788
17789
17790
17791 . ////////////////////////////////////////////////////////////////////////////
17792 . ////////////////////////////////////////////////////////////////////////////
17793
17794 .chapter "Generic options for routers" "CHAProutergeneric"
17795 .scindex IIDgenoprou1 "options" "generic; for routers"
17796 .scindex IIDgenoprou2 "generic options" "router"
17797 This chapter describes the generic options that apply to all routers.
17798 Those that are preconditions are marked with &Dagger; in the &"use"& field.
17799
17800 For a general description of how a router operates, see sections
17801 &<<SECTrunindrou>>& and &<<SECTrouprecon>>&. The latter specifies the order in
17802 which the preconditions are tested. The order of expansion of the options that
17803 provide data for a transport is: &%errors_to%&, &%headers_add%&,
17804 &%headers_remove%&, &%transport%&.
17805
17806
17807
17808 .option address_data routers string&!! unset
17809 .cindex "router" "data attached to address"
17810 The string is expanded just before the router is run, that is, after all the
17811 precondition tests have succeeded. If the expansion is forced to fail, the
17812 router declines, the value of &%address_data%& remains unchanged, and the
17813 &%more%& option controls what happens next. Other expansion failures cause
17814 delivery of the address to be deferred.
17815
17816 .vindex "&$address_data$&"
17817 When the expansion succeeds, the value is retained with the address, and can be
17818 accessed using the variable &$address_data$& in the current router, subsequent
17819 routers, and the eventual transport.
17820
17821 &*Warning*&: If the current or any subsequent router is a &(redirect)& router
17822 that runs a user's filter file, the contents of &$address_data$& are accessible
17823 in the filter. This is not normally a problem, because such data is usually
17824 either not confidential or it &"belongs"& to the current user, but if you do
17825 put confidential data into &$address_data$& you need to remember this point.
17826
17827 Even if the router declines or passes, the value of &$address_data$& remains
17828 with the address, though it can be changed by another &%address_data%& setting
17829 on a subsequent router. If a router generates child addresses, the value of
17830 &$address_data$& propagates to them. This also applies to the special kind of
17831 &"child"& that is generated by a router with the &%unseen%& option.
17832
17833 The idea of &%address_data%& is that you can use it to look up a lot of data
17834 for the address once, and then pick out parts of the data later. For example,
17835 you could use a single LDAP lookup to return a string of the form
17836 .code
17837 uid=1234 gid=5678 mailbox=/mail/xyz forward=/home/xyz/.forward
17838 .endd
17839 In the transport you could pick out the mailbox by a setting such as
17840 .code
17841 file = ${extract{mailbox}{$address_data}}
17842 .endd
17843 This makes the configuration file less messy, and also reduces the number of
17844 lookups (though Exim does cache lookups).
17845
17846 .vindex "&$sender_address_data$&"
17847 .vindex "&$address_data$&"
17848 The &%address_data%& facility is also useful as a means of passing information
17849 from one router to another, and from a router to a transport. In addition, if
17850 &$address_data$& is set by a router when verifying a recipient address from an
17851 ACL, it remains available for use in the rest of the ACL statement. After
17852 verifying a sender, the value is transferred to &$sender_address_data$&.
17853
17854
17855
17856 .option address_test routers&!? boolean true
17857 .oindex "&%-bt%&"
17858 .cindex "router" "skipping when address testing"
17859 If this option is set false, the router is skipped when routing is being tested
17860 by means of the &%-bt%& command line option. This can be a convenience when
17861 your first router sends messages to an external scanner, because it saves you
17862 having to set the &"already scanned"& indicator when testing real address
17863 routing.
17864
17865
17866
17867 .option cannot_route_message routers string&!! unset
17868 .cindex "router" "customizing &""cannot route""& message"
17869 .cindex "customizing" "&""cannot route""& message"
17870 This option specifies a text message that is used when an address cannot be
17871 routed because Exim has run out of routers. The default message is
17872 &"Unrouteable address"&. This option is useful only on routers that have
17873 &%more%& set false, or on the very last router in a configuration, because the
17874 value that is used is taken from the last router that is considered. This
17875 includes a router that is skipped because its preconditions are not met, as
17876 well as a router that declines. For example, using the default configuration,
17877 you could put:
17878 .code
17879 cannot_route_message = Remote domain not found in DNS
17880 .endd
17881 on the first router, which is a &(dnslookup)& router with &%more%& set false,
17882 and
17883 .code
17884 cannot_route_message = Unknown local user
17885 .endd
17886 on the final router that checks for local users. If string expansion fails for
17887 this option, the default message is used. Unless the expansion failure was
17888 explicitly forced, a message about the failure is written to the main and panic
17889 logs, in addition to the normal message about the routing failure.
17890
17891
17892 .option caseful_local_part routers boolean false
17893 .cindex "case of local parts"
17894 .cindex "router" "case of local parts"
17895 By default, routers handle the local parts of addresses in a case-insensitive
17896 manner, though the actual case is preserved for transmission with the message.
17897 If you want the case of letters to be significant in a router, you must set
17898 this option true. For individual router options that contain address or local
17899 part lists (for example, &%local_parts%&), case-sensitive matching can be
17900 turned on by &"+caseful"& as a list item. See section &<<SECTcasletadd>>& for
17901 more details.
17902
17903 .vindex "&$local_part$&"
17904 .vindex "&$original_local_part$&"
17905 .vindex "&$parent_local_part$&"
17906 The value of the &$local_part$& variable is forced to lower case while a
17907 router is running unless &%caseful_local_part%& is set. When a router assigns
17908 an address to a transport, the value of &$local_part$& when the transport runs
17909 is the same as it was in the router. Similarly, when a router generates child
17910 addresses by aliasing or forwarding, the values of &$original_local_part$&
17911 and &$parent_local_part$& are those that were used by the redirecting router.
17912
17913 This option applies to the processing of an address by a router. When a
17914 recipient address is being processed in an ACL, there is a separate &%control%&
17915 modifier that can be used to specify case-sensitive processing within the ACL
17916 (see section &<<SECTcontrols>>&).
17917
17918
17919
17920 .option check_local_user routers&!? boolean false
17921 .cindex "local user, checking in router"
17922 .cindex "router" "checking for local user"
17923 .cindex "&_/etc/passwd_&"
17924 .vindex "&$home$&"
17925 When this option is true, Exim checks that the local part of the recipient
17926 address (with affixes removed if relevant) is the name of an account on the
17927 local system. The check is done by calling the &[getpwnam()]& function rather
17928 than trying to read &_/etc/passwd_& directly. This means that other methods of
17929 holding password data (such as NIS) are supported. If the local part is a local
17930 user, &$home$& is set from the password data, and can be tested in other
17931 preconditions that are evaluated after this one (the order of evaluation is
17932 given in section &<<SECTrouprecon>>&). However, the value of &$home$& can be
17933 overridden by &%router_home_directory%&. If the local part is not a local user,
17934 the router is skipped.
17935
17936 If you want to check that the local part is either the name of a local user
17937 or matches something else, you cannot combine &%check_local_user%& with a
17938 setting of &%local_parts%&, because that specifies the logical &'and'& of the
17939 two conditions. However, you can use a &(passwd)& lookup in a &%local_parts%&
17940 setting to achieve this. For example:
17941 .code
17942 local_parts = passwd;$local_part : lsearch;/etc/other/users
17943 .endd
17944 Note, however, that the side effects of &%check_local_user%& (such as setting
17945 up a home directory) do not occur when a &(passwd)& lookup is used in a
17946 &%local_parts%& (or any other) precondition.
17947
17948
17949
17950 .option condition routers&!? string&!! unset
17951 .cindex "router" "customized precondition"
17952 This option specifies a general precondition test that has to succeed for the
17953 router to be called. The &%condition%& option is the last precondition to be
17954 evaluated (see section &<<SECTrouprecon>>&). The string is expanded, and if the
17955 result is a forced failure, or an empty string, or one of the strings &"0"& or
17956 &"no"& or &"false"& (checked without regard to the case of the letters), the
17957 router is skipped, and the address is offered to the next one.
17958
17959 If the result is any other value, the router is run (as this is the last
17960 precondition to be evaluated, all the other preconditions must be true).
17961
17962 This option is unusual in that multiple &%condition%& options may be present.
17963 All &%condition%& options must succeed.
17964
17965 The &%condition%& option provides a means of applying custom conditions to the
17966 running of routers. Note that in the case of a simple conditional expansion,
17967 the default expansion values are exactly what is wanted. For example:
17968 .code
17969 condition = ${if >{$message_age}{600}}
17970 .endd
17971 Because of the default behaviour of the string expansion, this is equivalent to
17972 .code
17973 condition = ${if >{$message_age}{600}{true}{}}
17974 .endd
17975
17976 A multiple condition example, which succeeds:
17977 .code
17978 condition = ${if >{$message_age}{600}}
17979 condition = ${if !eq{${lc:$local_part}}{postmaster}}
17980 condition = foobar
17981 .endd
17982
17983 If the expansion fails (other than forced failure) delivery is deferred. Some
17984 of the other precondition options are common special cases that could in fact
17985 be specified using &%condition%&.
17986
17987 Historical note: We have &%condition%& on ACLs and on Routers.  Routers
17988 are far older, and use one set of semantics.  ACLs are newer and when
17989 they were created, the ACL &%condition%& process was given far stricter
17990 parse semantics.  The &%bool{}%& expansion condition uses the same rules as
17991 ACLs.  The &%bool_lax{}%& expansion condition uses the same rules as
17992 Routers.  More pointedly, the &%bool_lax{}%& was written to match the existing
17993 Router rules processing behavior.
17994
17995 This is best illustrated in an example:
17996 .code
17997 # If used in an ACL condition will fail with a syntax error, but
17998 # in a router condition any extra characters are treated as a string
17999
18000 $ exim -be '${if eq {${lc:GOOGLE.com}} {google.com}} {yes} {no}}'
18001 true {yes} {no}}
18002
18003 $ exim -be '${if eq {${lc:WHOIS.com}} {google.com}} {yes} {no}}'
18004  {yes} {no}}
18005 .endd
18006 In each example above, the &%if%& statement actually ends after
18007 &"{google.com}}"&.  Since no true or false braces were defined, the
18008 default &%if%& behavior is to return a boolean true or a null answer
18009 (which evaluates to false). The rest of the line is then treated as a
18010 string. So the first example resulted in the boolean answer &"true"&
18011 with the string &" {yes} {no}}"& appended to it. The second example
18012 resulted in the null output (indicating false) with the string
18013 &" {yes} {no}}"& appended to it.
18014
18015 In fact you can put excess forward braces in too.  In the router
18016 &%condition%&, Exim's parser only looks for &"{"& symbols when they
18017 mean something, like after a &"$"& or when required as part of a
18018 conditional.  But otherwise &"{"& and &"}"& are treated as ordinary
18019 string characters.
18020
18021 Thus, in a Router, the above expansion strings will both always evaluate
18022 true, as the result of expansion is a non-empty string which doesn't
18023 match an explicit false value.  This can be tricky to debug.  By
18024 contrast, in an ACL either of those strings will always result in an
18025 expansion error because the result doesn't look sufficiently boolean.
18026
18027
18028 .option debug_print routers string&!! unset
18029 .cindex "testing" "variables in drivers"
18030 If this option is set and debugging is enabled (see the &%-d%& command line
18031 option) or in address-testing mode (see the &%-bt%& command line option),
18032 the string is expanded and included in the debugging output.
18033 If expansion of the string fails, the error message is written to the debugging
18034 output, and Exim carries on processing.
18035 This option is provided to help with checking out the values of variables and
18036 so on when debugging router configurations. For example, if a &%condition%&
18037 option appears not to be working, &%debug_print%& can be used to output the
18038 variables it references. The output happens after checks for &%domains%&,
18039 &%local_parts%&, and &%check_local_user%& but before any other preconditions
18040 are tested. A newline is added to the text if it does not end with one.
18041 The variable &$router_name$& contains the name of the router.
18042
18043
18044
18045 .option disable_logging routers boolean false
18046 If this option is set true, nothing is logged for any routing errors
18047 or for any deliveries caused by this router. You should not set this option
18048 unless you really, really know what you are doing. See also the generic
18049 transport option of the same name.
18050
18051 .option dnssec_request_domains routers "domain list&!!" unset
18052 .cindex "MX record" "security"
18053 .cindex "DNSSEC" "MX lookup"
18054 .cindex "security" "MX lookup"
18055 .cindex "DNS" "DNSSEC"
18056 DNS lookups for domains matching &%dnssec_request_domains%& will be done with
18057 the dnssec request bit set.
18058 This applies to all of the SRV, MX, AAAA, A lookup sequence.
18059
18060 .option dnssec_require_domains routers "domain list&!!" unset
18061 .cindex "MX record" "security"
18062 .cindex "DNSSEC" "MX lookup"
18063 .cindex "security" "MX lookup"
18064 .cindex "DNS" "DNSSEC"
18065 DNS lookups for domains matching &%dnssec_require_domains%& will be done with
18066 the dnssec request bit set.  Any returns not having the Authenticated Data bit
18067 (AD bit) set will be ignored and logged as a host-lookup failure.
18068 This applies to all of the SRV, MX, AAAA, A lookup sequence.
18069
18070
18071 .option domains routers&!? "domain list&!!" unset
18072 .cindex "router" "restricting to specific domains"
18073 .vindex "&$domain_data$&"
18074 If this option is set, the router is skipped unless the current domain matches
18075 the list. If the match is achieved by means of a file lookup, the data that the
18076 lookup returned for the domain is placed in &$domain_data$& for use in string
18077 expansions of the driver's private options. See section &<<SECTrouprecon>>& for
18078 a list of the order in which preconditions are evaluated.
18079
18080
18081
18082 .option driver routers string unset
18083 This option must always be set. It specifies which of the available routers is
18084 to be used.
18085
18086
18087 .option dsn_lasthop routers boolean false
18088 .cindex "DSN" "success"
18089 .cindex "Delivery Status Notification" "success"
18090 If this option is set true, and extended DSN (RFC3461) processing is in effect,
18091 Exim will not pass on DSN requests to downstream DSN-aware hosts but will
18092 instead send a success DSN as if the next hop does not support DSN.
18093 Not effective on redirect routers.
18094
18095
18096
18097 .option errors_to routers string&!! unset
18098 .cindex "envelope sender"
18099 .cindex "router" "changing address for errors"
18100 If a router successfully handles an address, it may assign the address to a
18101 transport for delivery or it may generate child addresses. In both cases, if
18102 there is a delivery problem during later processing, the resulting bounce
18103 message is sent to the address that results from expanding this string,
18104 provided that the address verifies successfully. The &%errors_to%& option is
18105 expanded before &%headers_add%&, &%headers_remove%&, and &%transport%&.
18106
18107 The &%errors_to%& setting associated with an address can be overridden if it
18108 subsequently passes through other routers that have their own &%errors_to%&
18109 settings, or if the message is delivered by a transport with a &%return_path%&
18110 setting.
18111
18112 If &%errors_to%& is unset, or the expansion is forced to fail, or the result of
18113 the expansion fails to verify, the errors address associated with the incoming
18114 address is used. At top level, this is the envelope sender. A non-forced
18115 expansion failure causes delivery to be deferred.
18116
18117 If an address for which &%errors_to%& has been set ends up being delivered over
18118 SMTP, the envelope sender for that delivery is the &%errors_to%& value, so that
18119 any bounces that are generated by other MTAs on the delivery route are also
18120 sent there. You can set &%errors_to%& to the empty string by either of these
18121 settings:
18122 .code
18123 errors_to =
18124 errors_to = ""
18125 .endd
18126 An expansion item that yields an empty string has the same effect. If you do
18127 this, a locally detected delivery error for addresses processed by this router
18128 no longer gives rise to a bounce message; the error is discarded. If the
18129 address is delivered to a remote host, the return path is set to &`<>`&, unless
18130 overridden by the &%return_path%& option on the transport.
18131
18132 .vindex "&$address_data$&"
18133 If for some reason you want to discard local errors, but use a non-empty
18134 MAIL command for remote delivery, you can preserve the original return
18135 path in &$address_data$& in the router, and reinstate it in the transport by
18136 setting &%return_path%&.
18137
18138 The most common use of &%errors_to%& is to direct mailing list bounces to the
18139 manager of the list, as described in section &<<SECTmailinglists>>&, or to
18140 implement VERP (Variable Envelope Return Paths) (see section &<<SECTverp>>&).
18141
18142
18143
18144 .option expn routers&!? boolean true
18145 .cindex "address" "testing"
18146 .cindex "testing" "addresses"
18147 .cindex "EXPN" "router skipping"
18148 .cindex "router" "skipping for EXPN"
18149 If this option is turned off, the router is skipped when testing an address
18150 as a result of processing an SMTP EXPN command. You might, for example,
18151 want to turn it off on a router for users' &_.forward_& files, while leaving it
18152 on for the system alias file.
18153 See section &<<SECTrouprecon>>& for a list of the order in which preconditions
18154 are evaluated.
18155
18156 The use of the SMTP EXPN command is controlled by an ACL (see chapter
18157 &<<CHAPACL>>&). When Exim is running an EXPN command, it is similar to testing
18158 an address with &%-bt%&. Compare VRFY, whose counterpart is &%-bv%&.
18159
18160
18161
18162 .option fail_verify routers boolean false
18163 .cindex "router" "forcing verification failure"
18164 Setting this option has the effect of setting both &%fail_verify_sender%& and
18165 &%fail_verify_recipient%& to the same value.
18166
18167
18168
18169 .option fail_verify_recipient routers boolean false
18170 If this option is true and an address is accepted by this router when
18171 verifying a recipient, verification fails.
18172
18173
18174
18175 .option fail_verify_sender routers boolean false
18176 If this option is true and an address is accepted by this router when
18177 verifying a sender, verification fails.
18178
18179
18180
18181 .option fallback_hosts routers "string list" unset
18182 .cindex "router" "fallback hosts"
18183 .cindex "fallback" "hosts specified on router"
18184 String expansion is not applied to this option. The argument must be a
18185 colon-separated list of host names or IP addresses. The list separator can be
18186 changed (see section &<<SECTlistconstruct>>&), and a port can be specified with
18187 each name or address. In fact, the format of each item is exactly the same as
18188 defined for the list of hosts in a &(manualroute)& router (see section
18189 &<<SECTformatonehostitem>>&).
18190
18191 If a router queues an address for a remote transport, this host list is
18192 associated with the address, and used instead of the transport's fallback host
18193 list. If &%hosts_randomize%& is set on the transport, the order of the list is
18194 randomized for each use. See the &%fallback_hosts%& option of the &(smtp)&
18195 transport for further details.
18196
18197
18198 .option group routers string&!! "see below"
18199 .cindex "gid (group id)" "local delivery"
18200 .cindex "local transports" "uid and gid"
18201 .cindex "transport" "local"
18202 .cindex "router" "setting group"
18203 When a router queues an address for a transport, and the transport does not
18204 specify a group, the group given here is used when running the delivery
18205 process.
18206 The group may be specified numerically or by name. If expansion fails, the
18207 error is logged and delivery is deferred.
18208 The default is unset, unless &%check_local_user%& is set, when the default
18209 is taken from the password information. See also &%initgroups%& and &%user%&
18210 and the discussion in chapter &<<CHAPenvironment>>&.
18211
18212
18213
18214 .option headers_add routers list&!! unset
18215 .cindex "header lines" "adding"
18216 .cindex "router" "adding header lines"
18217 This option specifies a list of text headers,
18218 newline-separated (by default, changeable in the usual way),
18219 that is associated with any addresses that are accepted by the router.
18220 Each item is separately expanded, at routing time.  However, this
18221 option has no effect when an address is just being verified. The way in which
18222 the text is used to add header lines at transport time is described in section
18223 &<<SECTheadersaddrem>>&. New header lines are not actually added until the
18224 message is in the process of being transported. This means that references to
18225 header lines in string expansions in the transport's configuration do not
18226 &"see"& the added header lines.
18227
18228 The &%headers_add%& option is expanded after &%errors_to%&, but before
18229 &%headers_remove%& and &%transport%&. If an item is empty, or if
18230 an item expansion is forced to fail, the item has no effect. Other expansion
18231 failures are treated as configuration errors.
18232
18233 Unlike most options, &%headers_add%& can be specified multiple times
18234 for a router; all listed headers are added.
18235
18236 &*Warning 1*&: The &%headers_add%& option cannot be used for a &(redirect)&
18237 router that has the &%one_time%& option set.
18238
18239 .cindex "duplicate addresses"
18240 .oindex "&%unseen%&"
18241 &*Warning 2*&: If the &%unseen%& option is set on the router, all header
18242 additions are deleted when the address is passed on to subsequent routers.
18243 For a &%redirect%& router, if a generated address is the same as the incoming
18244 address, this can lead to duplicate addresses with different header
18245 modifications. Exim does not do duplicate deliveries (except, in certain
18246 circumstances, to pipes -- see section &<<SECTdupaddr>>&), but it is undefined
18247 which of the duplicates is discarded, so this ambiguous situation should be
18248 avoided. The &%repeat_use%& option of the &%redirect%& router may be of help.
18249
18250
18251
18252 .option headers_remove routers list&!! unset
18253 .cindex "header lines" "removing"
18254 .cindex "router" "removing header lines"
18255 This option specifies a list of text headers,
18256 colon-separated (by default, changeable in the usual way),
18257 that is associated with any addresses that are accepted by the router.
18258 Each item is separately expanded, at routing time.  However, this
18259 option has no effect when an address is just being verified. The way in which
18260 the text is used to remove header lines at transport time is described in
18261 section &<<SECTheadersaddrem>>&. Header lines are not actually removed until
18262 the message is in the process of being transported. This means that references
18263 to header lines in string expansions in the transport's configuration still
18264 &"see"& the original header lines.
18265
18266 The &%headers_remove%& option is expanded after &%errors_to%& and
18267 &%headers_add%&, but before &%transport%&. If an item expansion is forced to fail,
18268 the item has no effect. Other expansion failures are treated as configuration
18269 errors.
18270
18271 Unlike most options, &%headers_remove%& can be specified multiple times
18272 for a router; all listed headers are removed.
18273
18274 &*Warning 1*&: The &%headers_remove%& option cannot be used for a &(redirect)&
18275 router that has the &%one_time%& option set.
18276
18277 &*Warning 2*&: If the &%unseen%& option is set on the router, all header
18278 removal requests are deleted when the address is passed on to subsequent
18279 routers, and this can lead to problems with duplicates -- see the similar
18280 warning for &%headers_add%& above.
18281
18282 &*Warning 3*&: Because of the separate expansion of the list items,
18283 items that contain a list separator must have it doubled.
18284 To avoid this, change the list separator (&<<SECTlistsepchange>>&).
18285
18286
18287
18288 .option ignore_target_hosts routers "host list&!!" unset
18289 .cindex "IP address" "discarding"
18290 .cindex "router" "discarding IP addresses"
18291 Although this option is a host list, it should normally contain IP address
18292 entries rather than names. If any host that is looked up by the router has an
18293 IP address that matches an item in this list, Exim behaves as if that IP
18294 address did not exist. This option allows you to cope with rogue DNS entries
18295 like
18296 .code
18297 remote.domain.example.  A  127.0.0.1
18298 .endd
18299 by setting
18300 .code
18301 ignore_target_hosts = 127.0.0.1
18302 .endd
18303 on the relevant router. If all the hosts found by a &(dnslookup)& router are
18304 discarded in this way, the router declines. In a conventional configuration, an
18305 attempt to mail to such a domain would normally provoke the &"unrouteable
18306 domain"& error, and an attempt to verify an address in the domain would fail.
18307 Similarly, if &%ignore_target_hosts%& is set on an &(ipliteral)& router, the
18308 router declines if presented with one of the listed addresses.
18309
18310 You can use this option to disable the use of IPv4 or IPv6 for mail delivery by
18311 means of the first or the second of the following settings, respectively:
18312 .code
18313 ignore_target_hosts = 0.0.0.0/0
18314 ignore_target_hosts = <; 0::0/0
18315 .endd
18316 The pattern in the first line matches all IPv4 addresses, whereas the pattern
18317 in the second line matches all IPv6 addresses.
18318
18319 This option may also be useful for ignoring link-local and site-local IPv6
18320 addresses. Because, like all host lists, the value of &%ignore_target_hosts%&
18321 is expanded before use as a list, it is possible to make it dependent on the
18322 domain that is being routed.
18323
18324 .vindex "&$host_address$&"
18325 During its expansion, &$host_address$& is set to the IP address that is being
18326 checked.
18327
18328 .option initgroups routers boolean false
18329 .cindex "additional groups"
18330 .cindex "groups" "additional"
18331 .cindex "local transports" "uid and gid"
18332 .cindex "transport" "local"
18333 If the router queues an address for a transport, and this option is true, and
18334 the uid supplied by the router is not overridden by the transport, the
18335 &[initgroups()]& function is called when running the transport to ensure that
18336 any additional groups associated with the uid are set up. See also &%group%&
18337 and &%user%& and the discussion in chapter &<<CHAPenvironment>>&.
18338
18339
18340
18341 .option local_part_prefix routers&!? "string list" unset
18342 .cindex affix "router precondition"
18343 .cindex "router" "prefix for local part"
18344 .cindex "prefix" "for local part, used in router"
18345 If this option is set, the router is skipped unless the local part starts with
18346 one of the given strings, or &%local_part_prefix_optional%& is true. See
18347 section &<<SECTrouprecon>>& for a list of the order in which preconditions are
18348 evaluated.
18349
18350 The list is scanned from left to right, and the first prefix that matches is
18351 used. A limited form of wildcard is available; if the prefix begins with an
18352 asterisk, it matches the longest possible sequence of arbitrary characters at
18353 the start of the local part. An asterisk should therefore always be followed by
18354 some character that does not occur in normal local parts.
18355 .cindex "multiple mailboxes"
18356 .cindex "mailbox" "multiple"
18357 Wildcarding can be used to set up multiple user mailboxes, as described in
18358 section &<<SECTmulbox>>&.
18359
18360 .vindex "&$local_part$&"
18361 .vindex "&$local_part_prefix$&"
18362 During the testing of the &%local_parts%& option, and while the router is
18363 running, the prefix is removed from the local part, and is available in the
18364 expansion variable &$local_part_prefix$&. When a message is being delivered, if
18365 the router accepts the address, this remains true during subsequent delivery by
18366 a transport. In particular, the local part that is transmitted in the RCPT
18367 command for LMTP, SMTP, and BSMTP deliveries has the prefix removed by default.
18368 This behaviour can be overridden by setting &%rcpt_include_affixes%& true on
18369 the relevant transport.
18370
18371 When an address is being verified, &%local_part_prefix%& affects only the
18372 behaviour of the router. If the callout feature of verification is in use, this
18373 means that the full address, including the prefix, will be used during the
18374 callout.
18375
18376 The prefix facility is commonly used to handle local parts of the form
18377 &%owner-something%&. Another common use is to support local parts of the form
18378 &%real-username%& to bypass a user's &_.forward_& file &-- helpful when trying
18379 to tell a user their forwarding is broken &-- by placing a router like this one
18380 immediately before the router that handles &_.forward_& files:
18381 .code
18382 real_localuser:
18383   driver = accept
18384   local_part_prefix = real-
18385   check_local_user
18386   transport = local_delivery
18387 .endd
18388 For security, it would probably be a good idea to restrict the use of this
18389 router to locally-generated messages, using a condition such as this:
18390 .code
18391   condition = ${if match {$sender_host_address}\
18392                          {\N^(|127\.0\.0\.1)$\N}}
18393 .endd
18394
18395 If both &%local_part_prefix%& and &%local_part_suffix%& are set for a router,
18396 both conditions must be met if not optional. Care must be taken if wildcards
18397 are used in both a prefix and a suffix on the same router. Different
18398 separator characters must be used to avoid ambiguity.
18399
18400
18401 .option local_part_prefix_optional routers boolean false
18402 See &%local_part_prefix%& above.
18403
18404
18405
18406 .option local_part_suffix routers&!? "string list" unset
18407 .cindex "router" "suffix for local part"
18408 .cindex "suffix for local part" "used in router"
18409 This option operates in the same way as &%local_part_prefix%&, except that the
18410 local part must end (rather than start) with the given string, the
18411 &%local_part_suffix_optional%& option determines whether the suffix is
18412 mandatory, and the wildcard * character, if present, must be the last
18413 character of the suffix. This option facility is commonly used to handle local
18414 parts of the form &%something-request%& and multiple user mailboxes of the form
18415 &%username-foo%&.
18416
18417
18418 .option local_part_suffix_optional routers boolean false
18419 See &%local_part_suffix%& above.
18420
18421
18422
18423 .option local_parts routers&!? "local part list&!!" unset
18424 .cindex "router" "restricting to specific local parts"
18425 .cindex "local part" "checking in router"
18426 The router is run only if the local part of the address matches the list.
18427 See section &<<SECTrouprecon>>& for a list of the order in which preconditions
18428 are evaluated, and
18429 section &<<SECTlocparlis>>& for a discussion of local part lists. Because the
18430 string is expanded, it is possible to make it depend on the domain, for
18431 example:
18432 .code
18433 local_parts = dbm;/usr/local/specials/$domain
18434 .endd
18435 .vindex "&$local_part_data$&"
18436 If the match is achieved by a lookup, the data that the lookup returned
18437 for the local part is placed in the variable &$local_part_data$& for use in
18438 expansions of the router's private options. You might use this option, for
18439 example, if you have a large number of local virtual domains, and you want to
18440 send all postmaster mail to the same place without having to set up an alias in
18441 each virtual domain:
18442 .code
18443 postmaster:
18444   driver = redirect
18445   local_parts = postmaster
18446   data = postmaster@real.domain.example
18447 .endd
18448
18449
18450 .option log_as_local routers boolean "see below"
18451 .cindex "log" "delivery line"
18452 .cindex "delivery" "log line format"
18453 Exim has two logging styles for delivery, the idea being to make local
18454 deliveries stand out more visibly from remote ones. In the &"local"& style, the
18455 recipient address is given just as the local part, without a domain. The use of
18456 this style is controlled by this option. It defaults to true for the &(accept)&
18457 router, and false for all the others. This option applies only when a
18458 router assigns an address to a transport. It has no effect on routers that
18459 redirect addresses.
18460
18461
18462
18463 .option more routers boolean&!! true
18464 The result of string expansion for this option must be a valid boolean value,
18465 that is, one of the strings &"yes"&, &"no"&, &"true"&, or &"false"&. Any other
18466 result causes an error, and delivery is deferred. If the expansion is forced to
18467 fail, the default value for the option (true) is used. Other failures cause
18468 delivery to be deferred.
18469
18470 If this option is set false, and the router declines to handle the address, no
18471 further routers are tried, routing fails, and the address is bounced.
18472 .oindex "&%self%&"
18473 However, if the router explicitly passes an address to the following router by
18474 means of the setting
18475 .code
18476 self = pass
18477 .endd
18478 or otherwise, the setting of &%more%& is ignored. Also, the setting of &%more%&
18479 does not affect the behaviour if one of the precondition tests fails. In that
18480 case, the address is always passed to the next router.
18481
18482 Note that &%address_data%& is not considered to be a precondition. If its
18483 expansion is forced to fail, the router declines, and the value of &%more%&
18484 controls what happens next.
18485
18486
18487 .option pass_on_timeout routers boolean false
18488 .cindex "timeout" "of router"
18489 .cindex "router" "timeout"
18490 If a router times out during a host lookup, it normally causes deferral of the
18491 address. If &%pass_on_timeout%& is set, the address is passed on to the next
18492 router, overriding &%no_more%&. This may be helpful for systems that are
18493 intermittently connected to the Internet, or those that want to pass to a smart
18494 host any messages that cannot immediately be delivered.
18495
18496 There are occasional other temporary errors that can occur while doing DNS
18497 lookups. They are treated in the same way as a timeout, and this option
18498 applies to all of them.
18499
18500
18501
18502 .option pass_router routers string unset
18503 .cindex "router" "go to after &""pass""&"
18504 Routers that recognize the generic &%self%& option (&(dnslookup)&,
18505 &(ipliteral)&, and &(manualroute)&) are able to return &"pass"&, forcing
18506 routing to continue, and overriding a false setting of &%more%&. When one of
18507 these routers returns &"pass"&, the address is normally handed on to the next
18508 router in sequence. This can be changed by setting &%pass_router%& to the name
18509 of another router. However (unlike &%redirect_router%&) the named router must
18510 be below the current router, to avoid loops. Note that this option applies only
18511 to the special case of &"pass"&. It does not apply when a router returns
18512 &"decline"& because it cannot handle an address.
18513
18514
18515
18516 .option redirect_router routers string unset
18517 .cindex "router" "start at after redirection"
18518 Sometimes an administrator knows that it is pointless to reprocess addresses
18519 generated from alias or forward files with the same router again. For
18520 example, if an alias file translates real names into login ids there is no
18521 point searching the alias file a second time, especially if it is a large file.
18522
18523 The &%redirect_router%& option can be set to the name of any router instance.
18524 It causes the routing of any generated addresses to start at the named router
18525 instead of at the first router. This option has no effect if the router in
18526 which it is set does not generate new addresses.
18527
18528
18529
18530 .option require_files routers&!? "string list&!!" unset
18531 .cindex "file" "requiring for router"
18532 .cindex "router" "requiring file existence"
18533 This option provides a general mechanism for predicating the running of a
18534 router on the existence or non-existence of certain files or directories.
18535 Before running a router, as one of its precondition tests, Exim works its way
18536 through the &%require_files%& list, expanding each item separately.
18537
18538 Because the list is split before expansion, any colons in expansion items must
18539 be doubled, or the facility for using a different list separator must be used.
18540 If any expansion is forced to fail, the item is ignored. Other expansion
18541 failures cause routing of the address to be deferred.
18542
18543 If any expanded string is empty, it is ignored. Otherwise, except as described
18544 below, each string must be a fully qualified file path, optionally preceded by
18545 &"!"&. The paths are passed to the &[stat()]& function to test for the
18546 existence of the files or directories. The router is skipped if any paths not
18547 preceded by &"!"& do not exist, or if any paths preceded by &"!"& do exist.
18548
18549 .cindex "NFS"
18550 If &[stat()]& cannot determine whether a file exists or not, delivery of
18551 the message is deferred. This can happen when NFS-mounted filesystems are
18552 unavailable.
18553
18554 This option is checked after the &%domains%&, &%local_parts%&, and &%senders%&
18555 options, so you cannot use it to check for the existence of a file in which to
18556 look up a domain, local part, or sender. (See section &<<SECTrouprecon>>& for a
18557 full list of the order in which preconditions are evaluated.) However, as
18558 these options are all expanded, you can use the &%exists%& expansion condition
18559 to make such tests. The &%require_files%& option is intended for checking files
18560 that the router may be going to use internally, or which are needed by a
18561 transport (for example &_.procmailrc_&).
18562
18563 During delivery, the &[stat()]& function is run as root, but there is a
18564 facility for some checking of the accessibility of a file by another user.
18565 This is not a proper permissions check, but just a &"rough"& check that
18566 operates as follows:
18567
18568 If an item in a &%require_files%& list does not contain any forward slash
18569 characters, it is taken to be the user (and optional group, separated by a
18570 comma) to be checked for subsequent files in the list. If no group is specified
18571 but the user is specified symbolically, the gid associated with the uid is
18572 used. For example:
18573 .code
18574 require_files = mail:/some/file
18575 require_files = $local_part:$home/.procmailrc
18576 .endd
18577 If a user or group name in a &%require_files%& list does not exist, the
18578 &%require_files%& condition fails.
18579
18580 Exim performs the check by scanning along the components of the file path, and
18581 checking the access for the given uid and gid. It checks for &"x"& access on
18582 directories, and &"r"& access on the final file. Note that this means that file
18583 access control lists, if the operating system has them, are ignored.
18584
18585 &*Warning 1*&: When the router is being run to verify addresses for an
18586 incoming SMTP message, Exim is not running as root, but under its own uid. This
18587 may affect the result of a &%require_files%& check. In particular, &[stat()]&
18588 may yield the error EACCES (&"Permission denied"&). This means that the Exim
18589 user is not permitted to read one of the directories on the file's path.
18590
18591 &*Warning 2*&: Even when Exim is running as root while delivering a message,
18592 &[stat()]& can yield EACCES for a file in an NFS directory that is mounted
18593 without root access. In this case, if a check for access by a particular user
18594 is requested, Exim creates a subprocess that runs as that user, and tries the
18595 check again in that process.
18596
18597 The default action for handling an unresolved EACCES is to consider it to
18598 be caused by a configuration error, and routing is deferred because the
18599 existence or non-existence of the file cannot be determined. However, in some
18600 circumstances it may be desirable to treat this condition as if the file did
18601 not exist. If the file name (or the exclamation mark that precedes the file
18602 name for non-existence) is preceded by a plus sign, the EACCES error is treated
18603 as if the file did not exist. For example:
18604 .code
18605 require_files = +/some/file
18606 .endd
18607 If the router is not an essential part of verification (for example, it
18608 handles users' &_.forward_& files), another solution is to set the &%verify%&
18609 option false so that the router is skipped when verifying.
18610
18611
18612
18613 .option retry_use_local_part routers boolean "see below"
18614 .cindex "hints database" "retry keys"
18615 .cindex "local part" "in retry keys"
18616 When a delivery suffers a temporary routing failure, a retry record is created
18617 in Exim's hints database. For addresses whose routing depends only on the
18618 domain, the key for the retry record should not involve the local part, but for
18619 other addresses, both the domain and the local part should be included.
18620 Usually, remote routing is of the former kind, and local routing is of the
18621 latter kind.
18622
18623 This option controls whether the local part is used to form the key for retry
18624 hints for addresses that suffer temporary errors while being handled by this
18625 router. The default value is true for any router that has &%check_local_user%&
18626 set, and false otherwise. Note that this option does not apply to hints keys
18627 for transport delays; they are controlled by a generic transport option of the
18628 same name.
18629
18630 The setting of &%retry_use_local_part%& applies only to the router on which it
18631 appears. If the router generates child addresses, they are routed
18632 independently; this setting does not become attached to them.
18633
18634
18635
18636 .option router_home_directory routers string&!! unset
18637 .cindex "router" "home directory for"
18638 .cindex "home directory" "for router"
18639 .vindex "&$home$&"
18640 This option sets a home directory for use while the router is running. (Compare
18641 &%transport_home_directory%&, which sets a home directory for later
18642 transporting.) In particular, if used on a &(redirect)& router, this option
18643 sets a value for &$home$& while a filter is running. The value is expanded;
18644 forced expansion failure causes the option to be ignored &-- other failures
18645 cause the router to defer.
18646
18647 Expansion of &%router_home_directory%& happens immediately after the
18648 &%check_local_user%& test (if configured), before any further expansions take
18649 place.
18650 (See section &<<SECTrouprecon>>& for a list of the order in which preconditions
18651 are evaluated.)
18652 While the router is running, &%router_home_directory%& overrides the value of
18653 &$home$& that came from &%check_local_user%&.
18654
18655 When a router accepts an address and assigns it to a local transport (including
18656 the cases when a &(redirect)& router generates a pipe, file, or autoreply
18657 delivery), the home directory setting for the transport is taken from the first
18658 of these values that is set:
18659
18660 .ilist
18661 The &%home_directory%& option on the transport;
18662 .next
18663 The &%transport_home_directory%& option on the router;
18664 .next
18665 The password data if &%check_local_user%& is set on the router;
18666 .next
18667 The &%router_home_directory%& option on the router.
18668 .endlist
18669
18670 In other words, &%router_home_directory%& overrides the password data for the
18671 router, but not for the transport.
18672
18673
18674
18675 .option self routers string freeze
18676 .cindex "MX record" "pointing to local host"
18677 .cindex "local host" "MX pointing to"
18678 This option applies to those routers that use a recipient address to find a
18679 list of remote hosts. Currently, these are the &(dnslookup)&, &(ipliteral)&,
18680 and &(manualroute)& routers.
18681 Certain configurations of the &(queryprogram)& router can also specify a list
18682 of remote hosts.
18683 Usually such routers are configured to send the message to a remote host via an
18684 &(smtp)& transport. The &%self%& option specifies what happens when the first
18685 host on the list turns out to be the local host.
18686 The way in which Exim checks for the local host is described in section
18687 &<<SECTreclocipadd>>&.
18688
18689 Normally this situation indicates either an error in Exim's configuration (for
18690 example, the router should be configured not to process this domain), or an
18691 error in the DNS (for example, the MX should not point to this host). For this
18692 reason, the default action is to log the incident, defer the address, and
18693 freeze the message. The following alternatives are provided for use in special
18694 cases:
18695
18696 .vlist
18697 .vitem &%defer%&
18698 Delivery of the message is tried again later, but the message is not frozen.
18699
18700 .vitem "&%reroute%&: <&'domain'&>"
18701 The domain is changed to the given domain, and the address is passed back to
18702 be reprocessed by the routers. No rewriting of headers takes place. This
18703 behaviour is essentially a redirection.
18704
18705 .vitem "&%reroute: rewrite:%& <&'domain'&>"
18706 The domain is changed to the given domain, and the address is passed back to be
18707 reprocessed by the routers. Any headers that contain the original domain are
18708 rewritten.
18709
18710 .vitem &%pass%&
18711 .oindex "&%more%&"
18712 .vindex "&$self_hostname$&"
18713 The router passes the address to the next router, or to the router named in the
18714 &%pass_router%& option if it is set. This overrides &%no_more%&. During
18715 subsequent routing and delivery, the variable &$self_hostname$& contains the
18716 name of the local host that the router encountered. This can be used to
18717 distinguish between different cases for hosts with multiple names. The
18718 combination
18719 .code
18720 self = pass
18721 no_more
18722 .endd
18723 ensures that only those addresses that routed to the local host are passed on.
18724 Without &%no_more%&, addresses that were declined for other reasons would also
18725 be passed to the next router.
18726
18727 .vitem &%fail%&
18728 Delivery fails and an error report is generated.
18729
18730 .vitem &%send%&
18731 .cindex "local host" "sending to"
18732 The anomaly is ignored and the address is queued for the transport. This
18733 setting should be used with extreme caution. For an &(smtp)& transport, it
18734 makes sense only in cases where the program that is listening on the SMTP port
18735 is not this version of Exim. That is, it must be some other MTA, or Exim with a
18736 different configuration file that handles the domain in another way.
18737 .endlist
18738
18739
18740
18741 .option senders routers&!? "address list&!!" unset
18742 .cindex "router" "checking senders"
18743 If this option is set, the router is skipped unless the message's sender
18744 address matches something on the list.
18745 See section &<<SECTrouprecon>>& for a list of the order in which preconditions
18746 are evaluated.
18747
18748 There are issues concerning verification when the running of routers is
18749 dependent on the sender. When Exim is verifying the address in an &%errors_to%&
18750 setting, it sets the sender to the null string. When using the &%-bt%& option
18751 to check a configuration file, it is necessary also to use the &%-f%& option to
18752 set an appropriate sender. For incoming mail, the sender is unset when
18753 verifying the sender, but is available when verifying any recipients. If the
18754 SMTP VRFY command is enabled, it must be used after MAIL if the sender address
18755 matters.
18756
18757
18758 .option translate_ip_address routers string&!! unset
18759 .cindex "IP address" "translating"
18760 .cindex "packet radio"
18761 .cindex "router" "IP address translation"
18762 There exist some rare networking situations (for example, packet radio) where
18763 it is helpful to be able to translate IP addresses generated by normal routing
18764 mechanisms into other IP addresses, thus performing a kind of manual IP
18765 routing. This should be done only if the normal IP routing of the TCP/IP stack
18766 is inadequate or broken. Because this is an extremely uncommon requirement, the
18767 code to support this option is not included in the Exim binary unless
18768 SUPPORT_TRANSLATE_IP_ADDRESS=yes is set in &_Local/Makefile_&.
18769
18770 .vindex "&$host_address$&"
18771 The &%translate_ip_address%& string is expanded for every IP address generated
18772 by the router, with the generated address set in &$host_address$&. If the
18773 expansion is forced to fail, no action is taken.
18774 For any other expansion error, delivery of the message is deferred.
18775 If the result of the expansion is an IP address, that replaces the original
18776 address; otherwise the result is assumed to be a host name &-- this is looked
18777 up using &[gethostbyname()]& (or &[getipnodebyname()]& when available) to
18778 produce one or more replacement IP addresses. For example, to subvert all IP
18779 addresses in some specific networks, this could be added to a router:
18780 .code
18781 translate_ip_address = \
18782   ${lookup{${mask:$host_address/26}}lsearch{/some/file}\
18783     {$value}fail}}
18784 .endd
18785 The file would contain lines like
18786 .code
18787 10.2.3.128/26    some.host
18788 10.8.4.34/26     10.44.8.15
18789 .endd
18790 You should not make use of this facility unless you really understand what you
18791 are doing.
18792
18793
18794
18795 .option transport routers string&!! unset
18796 This option specifies the transport to be used when a router accepts an address
18797 and sets it up for delivery. A transport is never needed if a router is used
18798 only for verification. The value of the option is expanded at routing time,
18799 after the expansion of &%errors_to%&, &%headers_add%&, and &%headers_remove%&,
18800 and result must be the name of one of the configured transports. If it is not,
18801 delivery is deferred.
18802
18803 The &%transport%& option is not used by the &(redirect)& router, but it does
18804 have some private options that set up transports for pipe and file deliveries
18805 (see chapter &<<CHAPredirect>>&).
18806
18807
18808
18809 .option transport_current_directory routers string&!! unset
18810 .cindex "current directory for local transport"
18811 This option associates a current directory with any address that is routed
18812 to a local transport. This can happen either because a transport is
18813 explicitly configured for the router, or because it generates a delivery to a
18814 file or a pipe. During the delivery process (that is, at transport time), this
18815 option string is expanded and is set as the current directory, unless
18816 overridden by a setting on the transport.
18817 If the expansion fails for any reason, including forced failure, an error is
18818 logged, and delivery is deferred.
18819 See chapter &<<CHAPenvironment>>& for details of the local delivery
18820 environment.
18821
18822
18823
18824
18825 .option transport_home_directory routers string&!! "see below"
18826 .cindex "home directory" "for local transport"
18827 This option associates a home directory with any address that is routed to a
18828 local transport. This can happen either because a transport is explicitly
18829 configured for the router, or because it generates a delivery to a file or a
18830 pipe. During the delivery process (that is, at transport time), the option
18831 string is expanded and is set as the home directory, unless overridden by a
18832 setting of &%home_directory%& on the transport.
18833 If the expansion fails for any reason, including forced failure, an error is
18834 logged, and delivery is deferred.
18835
18836 If the transport does not specify a home directory, and
18837 &%transport_home_directory%& is not set for the router, the home directory for
18838 the transport is taken from the password data if &%check_local_user%& is set for
18839 the router. Otherwise it is taken from &%router_home_directory%& if that option
18840 is set; if not, no home directory is set for the transport.
18841
18842 See chapter &<<CHAPenvironment>>& for further details of the local delivery
18843 environment.
18844
18845
18846
18847
18848 .option unseen routers boolean&!! false
18849 .cindex "router" "carrying on after success"
18850 The result of string expansion for this option must be a valid boolean value,
18851 that is, one of the strings &"yes"&, &"no"&, &"true"&, or &"false"&. Any other
18852 result causes an error, and delivery is deferred. If the expansion is forced to
18853 fail, the default value for the option (false) is used. Other failures cause
18854 delivery to be deferred.
18855
18856 When this option is set true, routing does not cease if the router accepts the
18857 address. Instead, a copy of the incoming address is passed to the next router,
18858 overriding a false setting of &%more%&. There is little point in setting
18859 &%more%& false if &%unseen%& is always true, but it may be useful in cases when
18860 the value of &%unseen%& contains expansion items (and therefore, presumably, is
18861 sometimes true and sometimes false).
18862
18863 .cindex "copy of message (&%unseen%& option)"
18864 Setting the &%unseen%& option has a similar effect to the &%unseen%& command
18865 qualifier in filter files. It can be used to cause copies of messages to be
18866 delivered to some other destination, while also carrying out a normal delivery.
18867 In effect, the current address is made into a &"parent"& that has two children
18868 &-- one that is delivered as specified by this router, and a clone that goes on
18869 to be routed further. For this reason, &%unseen%& may not be combined with the
18870 &%one_time%& option in a &(redirect)& router.
18871
18872 &*Warning*&: Header lines added to the address (or specified for removal) by
18873 this router or by previous routers affect the &"unseen"& copy of the message
18874 only. The clone that continues to be processed by further routers starts with
18875 no added headers and none specified for removal. For a &%redirect%& router, if
18876 a generated address is the same as the incoming address, this can lead to
18877 duplicate addresses with different header modifications. Exim does not do
18878 duplicate deliveries (except, in certain circumstances, to pipes -- see section
18879 &<<SECTdupaddr>>&), but it is undefined which of the duplicates is discarded,
18880 so this ambiguous situation should be avoided. The &%repeat_use%& option of the
18881 &%redirect%& router may be of help.
18882
18883 Unlike the handling of header modifications, any data that was set by the
18884 &%address_data%& option in the current or previous routers &'is'& passed on to
18885 subsequent routers.
18886
18887
18888 .option user routers string&!! "see below"
18889 .cindex "uid (user id)" "local delivery"
18890 .cindex "local transports" "uid and gid"
18891 .cindex "transport" "local"
18892 .cindex "router" "user for filter processing"
18893 .cindex "filter" "user for processing"
18894 When a router queues an address for a transport, and the transport does not
18895 specify a user, the user given here is used when running the delivery process.
18896 The user may be specified numerically or by name. If expansion fails, the
18897 error is logged and delivery is deferred.
18898 This user is also used by the &(redirect)& router when running a filter file.
18899 The default is unset, except when &%check_local_user%& is set. In this case,
18900 the default is taken from the password information. If the user is specified as
18901 a name, and &%group%& is not set, the group associated with the user is used.
18902 See also &%initgroups%& and &%group%& and the discussion in chapter
18903 &<<CHAPenvironment>>&.
18904
18905
18906
18907 .option verify routers&!? boolean true
18908 Setting this option has the effect of setting &%verify_sender%& and
18909 &%verify_recipient%& to the same value.
18910
18911
18912 .option verify_only routers&!? boolean false
18913 .cindex "EXPN" "with &%verify_only%&"
18914 .oindex "&%-bv%&"
18915 .cindex "router" "used only when verifying"
18916 If this option is set, the router is used only when verifying an address,
18917 delivering in cutthrough mode or
18918 testing with the &%-bv%& option, not when actually doing a delivery, testing
18919 with the &%-bt%& option, or running the SMTP EXPN command. It can be further
18920 restricted to verifying only senders or recipients by means of
18921 &%verify_sender%& and &%verify_recipient%&.
18922
18923 &*Warning*&: When the router is being run to verify addresses for an incoming
18924 SMTP message, Exim is not running as root, but under its own uid. If the router
18925 accesses any files, you need to make sure that they are accessible to the Exim
18926 user or group.
18927
18928
18929 .option verify_recipient routers&!? boolean true
18930 If this option is false, the router is skipped when verifying recipient
18931 addresses,
18932 delivering in cutthrough mode
18933 or testing recipient verification using &%-bv%&.
18934 See section &<<SECTrouprecon>>& for a list of the order in which preconditions
18935 are evaluated.
18936 See also the &$verify_mode$& variable.
18937
18938
18939 .option verify_sender routers&!? boolean true
18940 If this option is false, the router is skipped when verifying sender addresses
18941 or testing sender verification using &%-bvs%&.
18942 See section &<<SECTrouprecon>>& for a list of the order in which preconditions
18943 are evaluated.
18944 See also the &$verify_mode$& variable.
18945 .ecindex IIDgenoprou1
18946 .ecindex IIDgenoprou2
18947
18948
18949
18950
18951
18952
18953 . ////////////////////////////////////////////////////////////////////////////
18954 . ////////////////////////////////////////////////////////////////////////////
18955
18956 .chapter "The accept router" "CHID4"
18957 .cindex "&(accept)& router"
18958 .cindex "routers" "&(accept)&"
18959 The &(accept)& router has no private options of its own. Unless it is being
18960 used purely for verification (see &%verify_only%&) a transport is required to
18961 be defined by the generic &%transport%& option. If the preconditions that are
18962 specified by generic options are met, the router accepts the address and queues
18963 it for the given transport. The most common use of this router is for setting
18964 up deliveries to local mailboxes. For example:
18965 .code
18966 localusers:
18967   driver = accept
18968   domains = mydomain.example
18969   check_local_user
18970   transport = local_delivery
18971 .endd
18972 The &%domains%& condition in this example checks the domain of the address, and
18973 &%check_local_user%& checks that the local part is the login of a local user.
18974 When both preconditions are met, the &(accept)& router runs, and queues the
18975 address for the &(local_delivery)& transport.
18976
18977
18978
18979
18980
18981
18982 . ////////////////////////////////////////////////////////////////////////////
18983 . ////////////////////////////////////////////////////////////////////////////
18984
18985 .chapter "The dnslookup router" "CHAPdnslookup"
18986 .scindex IIDdnsrou1 "&(dnslookup)& router"
18987 .scindex IIDdnsrou2 "routers" "&(dnslookup)&"
18988 The &(dnslookup)& router looks up the hosts that handle mail for the
18989 recipient's domain in the DNS. A transport must always be set for this router,
18990 unless &%verify_only%& is set.
18991
18992 If SRV support is configured (see &%check_srv%& below), Exim first searches for
18993 SRV records. If none are found, or if SRV support is not configured,
18994 MX records are looked up. If no MX records exist, address records are sought.
18995 However, &%mx_domains%& can be set to disable the direct use of address
18996 records.
18997
18998 MX records of equal priority are sorted by Exim into a random order. Exim then
18999 looks for address records for the host names obtained from MX or SRV records.
19000 When a host has more than one IP address, they are sorted into a random order,
19001 except that IPv6 addresses are sorted before IPv4 addresses. If all the
19002 IP addresses found are discarded by a setting of the &%ignore_target_hosts%&
19003 generic option, the router declines.
19004
19005 Unless they have the highest priority (lowest MX value), MX records that point
19006 to the local host, or to any host name that matches &%hosts_treat_as_local%&,
19007 are discarded, together with any other MX records of equal or lower priority.
19008
19009 .cindex "MX record" "pointing to local host"
19010 .cindex "local host" "MX pointing to"
19011 .oindex "&%self%&" "in &(dnslookup)& router"
19012 If the host pointed to by the highest priority MX record, or looked up as an
19013 address record, is the local host, or matches &%hosts_treat_as_local%&, what
19014 happens is controlled by the generic &%self%& option.
19015
19016
19017 .section "Problems with DNS lookups" "SECTprowitdnsloo"
19018 There have been problems with DNS servers when SRV records are looked up.
19019 Some misbehaving servers return a DNS error or timeout when a non-existent
19020 SRV record is sought. Similar problems have in the past been reported for
19021 MX records. The global &%dns_again_means_nonexist%& option can help with this
19022 problem, but it is heavy-handed because it is a global option.
19023
19024 For this reason, there are two options, &%srv_fail_domains%& and
19025 &%mx_fail_domains%&, that control what happens when a DNS lookup in a
19026 &(dnslookup)& router results in a DNS failure or a &"try again"& response. If
19027 an attempt to look up an SRV or MX record causes one of these results, and the
19028 domain matches the relevant list, Exim behaves as if the DNS had responded &"no
19029 such record"&. In the case of an SRV lookup, this means that the router
19030 proceeds to look for MX records; in the case of an MX lookup, it proceeds to
19031 look for A or AAAA records, unless the domain matches &%mx_domains%&, in which
19032 case routing fails.
19033
19034
19035 .section "Declining addresses by dnslookup" "SECTdnslookupdecline"
19036 .cindex "&(dnslookup)& router" "declines"
19037 There are a few cases where a &(dnslookup)& router will decline to accept
19038 an address; if such a router is expected to handle "all remaining non-local
19039 domains", then it is important to set &%no_more%&.
19040
19041 The router will defer rather than decline if the domain
19042 is found in the &%fail_defer_domains%& router option.
19043
19044 Reasons for a &(dnslookup)& router to decline currently include:
19045 .ilist
19046 The domain does not exist in DNS
19047 .next
19048 The domain exists but the MX record's host part is just "."; this is a common
19049 convention (borrowed from SRV) used to indicate that there is no such service
19050 for this domain and to not fall back to trying A/AAAA records.
19051 .next
19052 Ditto, but for SRV records, when &%check_srv%& is set on this router.
19053 .next
19054 MX record points to a non-existent host.
19055 .next
19056 MX record points to an IP address and the main section option
19057 &%allow_mx_to_ip%& is not set.
19058 .next
19059 MX records exist and point to valid hosts, but all hosts resolve only to
19060 addresses blocked by the &%ignore_target_hosts%& generic option on this router.
19061 .next
19062 The domain is not syntactically valid (see also &%allow_utf8_domains%& and
19063 &%dns_check_names_pattern%& for handling one variant of this)
19064 .next
19065 &%check_secondary_mx%& is set on this router but the local host can
19066 not be found in the MX records (see below)
19067 .endlist
19068
19069
19070
19071
19072 .section "Private options for dnslookup" "SECID118"
19073 .cindex "options" "&(dnslookup)& router"
19074 The private options for the &(dnslookup)& router are as follows:
19075
19076 .option check_secondary_mx dnslookup boolean false
19077 .cindex "MX record" "checking for secondary"
19078 If this option is set, the router declines unless the local host is found in
19079 (and removed from) the list of hosts obtained by MX lookup. This can be used to
19080 process domains for which the local host is a secondary mail exchanger
19081 differently to other domains. The way in which Exim decides whether a host is
19082 the local host is described in section &<<SECTreclocipadd>>&.
19083
19084
19085 .option check_srv dnslookup string&!! unset
19086 .cindex "SRV record" "enabling use of"
19087 The &(dnslookup)& router supports the use of SRV records (see RFC 2782) in
19088 addition to MX and address records. The support is disabled by default. To
19089 enable SRV support, set the &%check_srv%& option to the name of the service
19090 required. For example,
19091 .code
19092 check_srv = smtp
19093 .endd
19094 looks for SRV records that refer to the normal smtp service. The option is
19095 expanded, so the service name can vary from message to message or address
19096 to address. This might be helpful if SRV records are being used for a
19097 submission service. If the expansion is forced to fail, the &%check_srv%&
19098 option is ignored, and the router proceeds to look for MX records in the
19099 normal way.
19100
19101 When the expansion succeeds, the router searches first for SRV records for
19102 the given service (it assumes TCP protocol). A single SRV record with a
19103 host name that consists of just a single dot indicates &"no such service for
19104 this domain"&; if this is encountered, the router declines. If other kinds of
19105 SRV record are found, they are used to construct a host list for delivery
19106 according to the rules of RFC 2782. MX records are not sought in this case.
19107
19108 When no SRV records are found, MX records (and address records) are sought in
19109 the traditional way. In other words, SRV records take precedence over MX
19110 records, just as MX records take precedence over address records. Note that
19111 this behaviour is not sanctioned by RFC 2782, though a previous draft RFC
19112 defined it. It is apparently believed that MX records are sufficient for email
19113 and that SRV records should not be used for this purpose. However, SRV records
19114 have an additional &"weight"& feature which some people might find useful when
19115 trying to split an SMTP load between hosts of different power.
19116
19117 See section &<<SECTprowitdnsloo>>& above for a discussion of Exim's behaviour
19118 when there is a DNS lookup error.
19119
19120
19121
19122
19123 .option fail_defer_domains dnslookup "domain list&!!" unset
19124 .cindex "MX record" "not found"
19125 DNS lookups for domains matching &%fail_defer_domains%&
19126 which find no matching record will cause the router to defer
19127 rather than the default behaviour of decline.
19128 This maybe be useful for queueing messages for a newly created
19129 domain while the DNS configuration is not ready.
19130 However, it will result in any message with mistyped domains
19131 also being queued.
19132
19133
19134 .option ipv4_only "string&!!" unset
19135 .cindex IPv6 disabling
19136 .cindex DNS "IPv6 disabling"
19137 The string is expanded, and if the result is anything but a forced failure,
19138 or an empty string, or one of the strings “0” or “no” or “false”
19139 (checked without regard to the case of the letters),
19140 only A records are used.
19141
19142 .option ipv4_prefer "string&!!" unset
19143 .cindex IPv4 preference
19144 .cindex DNS "IPv4 preference"
19145 The string is expanded, and if the result is anything but a forced failure,
19146 or an empty string, or one of the strings “0” or “no” or “false”
19147 (checked without regard to the case of the letters),
19148 A records are sorted before AAAA records (inverting the default).
19149
19150 .option mx_domains dnslookup "domain list&!!" unset
19151 .cindex "MX record" "required to exist"
19152 .cindex "SRV record" "required to exist"
19153 A domain that matches &%mx_domains%& is required to have either an MX or an SRV
19154 record in order to be recognized. (The name of this option could be improved.)
19155 For example, if all the mail hosts in &'fict.example'& are known to have MX
19156 records, except for those in &'discworld.fict.example'&, you could use this
19157 setting:
19158 .code
19159 mx_domains = ! *.discworld.fict.example : *.fict.example
19160 .endd
19161 This specifies that messages addressed to a domain that matches the list but
19162 has no MX record should be bounced immediately instead of being routed using
19163 the address record.
19164
19165
19166 .option mx_fail_domains dnslookup "domain list&!!" unset
19167 If the DNS lookup for MX records for one of the domains in this list causes a
19168 DNS lookup error, Exim behaves as if no MX records were found. See section
19169 &<<SECTprowitdnsloo>>& for more discussion.
19170
19171
19172
19173
19174 .option qualify_single dnslookup boolean true
19175 .cindex "DNS" "resolver options"
19176 .cindex "DNS" "qualifying single-component names"
19177 When this option is true, the resolver option RES_DEFNAMES is set for DNS
19178 lookups. Typically, but not standardly, this causes the resolver to qualify
19179 single-component names with the default domain. For example, on a machine
19180 called &'dictionary.ref.example'&, the domain &'thesaurus'& would be changed to
19181 &'thesaurus.ref.example'& inside the resolver. For details of what your
19182 resolver actually does, consult your man pages for &'resolver'& and
19183 &'resolv.conf'&.
19184
19185
19186
19187 .option rewrite_headers dnslookup boolean true
19188 .cindex "rewriting" "header lines"
19189 .cindex "header lines" "rewriting"
19190 If the domain name in the address that is being processed is not fully
19191 qualified, it may be expanded to its full form by a DNS lookup. For example, if
19192 an address is specified as &'dormouse@teaparty'&, the domain might be
19193 expanded to &'teaparty.wonderland.fict.example'&. Domain expansion can also
19194 occur as a result of setting the &%widen_domains%& option. If
19195 &%rewrite_headers%& is true, all occurrences of the abbreviated domain name in
19196 any &'Bcc:'&, &'Cc:'&, &'From:'&, &'Reply-to:'&, &'Sender:'&, and &'To:'&
19197 header lines of the message are rewritten with the full domain name.
19198
19199 This option should be turned off only when it is known that no message is
19200 ever going to be sent outside an environment where the abbreviation makes
19201 sense.
19202
19203 When an MX record is looked up in the DNS and matches a wildcard record, name
19204 servers normally return a record containing the name that has been looked up,
19205 making it impossible to detect whether a wildcard was present or not. However,
19206 some name servers have recently been seen to return the wildcard entry. If the
19207 name returned by a DNS lookup begins with an asterisk, it is not used for
19208 header rewriting.
19209
19210
19211 .option same_domain_copy_routing dnslookup boolean false
19212 .cindex "address" "copying routing"
19213 Addresses with the same domain are normally routed by the &(dnslookup)& router
19214 to the same list of hosts. However, this cannot be presumed, because the router
19215 options and preconditions may refer to the local part of the address. By
19216 default, therefore, Exim routes each address in a message independently. DNS
19217 servers run caches, so repeated DNS lookups are not normally expensive, and in
19218 any case, personal messages rarely have more than a few recipients.
19219
19220 If you are running mailing lists with large numbers of subscribers at the same
19221 domain, and you are using a &(dnslookup)& router which is independent of the
19222 local part, you can set &%same_domain_copy_routing%& to bypass repeated DNS
19223 lookups for identical domains in one message. In this case, when &(dnslookup)&
19224 routes an address to a remote transport, any other unrouted addresses in the
19225 message that have the same domain are automatically given the same routing
19226 without processing them independently,
19227 provided the following conditions are met:
19228
19229 .ilist
19230 No router that processed the address specified &%headers_add%& or
19231 &%headers_remove%&.
19232 .next
19233 The router did not change the address in any way, for example, by &"widening"&
19234 the domain.
19235 .endlist
19236
19237
19238
19239
19240 .option search_parents dnslookup boolean false
19241 .cindex "DNS" "resolver options"
19242 When this option is true, the resolver option RES_DNSRCH is set for DNS
19243 lookups. This is different from the &%qualify_single%& option in that it
19244 applies to domains containing dots. Typically, but not standardly, it causes
19245 the resolver to search for the name in the current domain and in parent
19246 domains. For example, on a machine in the &'fict.example'& domain, if looking
19247 up &'teaparty.wonderland'& failed, the resolver would try
19248 &'teaparty.wonderland.fict.example'&. For details of what your resolver
19249 actually does, consult your man pages for &'resolver'& and &'resolv.conf'&.
19250
19251 Setting this option true can cause problems in domains that have a wildcard MX
19252 record, because any domain that does not have its own MX record matches the
19253 local wildcard.
19254
19255
19256
19257 .option srv_fail_domains dnslookup "domain list&!!" unset
19258 If the DNS lookup for SRV records for one of the domains in this list causes a
19259 DNS lookup error, Exim behaves as if no SRV records were found. See section
19260 &<<SECTprowitdnsloo>>& for more discussion.
19261
19262
19263
19264
19265 .option widen_domains dnslookup "string list" unset
19266 .cindex "domain" "partial; widening"
19267 If a DNS lookup fails and this option is set, each of its strings in turn is
19268 added onto the end of the domain, and the lookup is tried again. For example,
19269 if
19270 .code
19271 widen_domains = fict.example:ref.example
19272 .endd
19273 is set and a lookup of &'klingon.dictionary'& fails,
19274 &'klingon.dictionary.fict.example'& is looked up, and if this fails,
19275 &'klingon.dictionary.ref.example'& is tried. Note that the &%qualify_single%&
19276 and &%search_parents%& options can cause some widening to be undertaken inside
19277 the DNS resolver. &%widen_domains%& is not applied to sender addresses
19278 when verifying, unless &%rewrite_headers%& is false (not the default).
19279
19280
19281 .section "Effect of qualify_single and search_parents" "SECID119"
19282 When a domain from an envelope recipient is changed by the resolver as a result
19283 of the &%qualify_single%& or &%search_parents%& options, Exim rewrites the
19284 corresponding address in the message's header lines unless &%rewrite_headers%&
19285 is set false. Exim then re-routes the address, using the full domain.
19286
19287 These two options affect only the DNS lookup that takes place inside the router
19288 for the domain of the address that is being routed. They do not affect lookups
19289 such as that implied by
19290 .code
19291 domains = @mx_any
19292 .endd
19293 that may happen while processing a router precondition before the router is
19294 entered. No widening ever takes place for these lookups.
19295 .ecindex IIDdnsrou1
19296 .ecindex IIDdnsrou2
19297
19298
19299
19300
19301
19302
19303
19304
19305
19306 . ////////////////////////////////////////////////////////////////////////////
19307 . ////////////////////////////////////////////////////////////////////////////
19308
19309 .chapter "The ipliteral router" "CHID5"
19310 .cindex "&(ipliteral)& router"
19311 .cindex "domain literal" "routing"
19312 .cindex "routers" "&(ipliteral)&"
19313 This router has no private options. Unless it is being used purely for
19314 verification (see &%verify_only%&) a transport is required to be defined by the
19315 generic &%transport%& option. The router accepts the address if its domain part
19316 takes the form of an RFC 2822 domain literal. For example, the &(ipliteral)&
19317 router handles the address
19318 .code
19319 root@[192.168.1.1]
19320 .endd
19321 by setting up delivery to the host with that IP address. IPv4 domain literals
19322 consist of an IPv4 address enclosed in square brackets. IPv6 domain literals
19323 are similar, but the address is preceded by &`ipv6:`&. For example:
19324 .code
19325 postmaster@[ipv6:fe80::a00:20ff:fe86:a061.5678]
19326 .endd
19327 Exim allows &`ipv4:`& before IPv4 addresses, for consistency, and on the
19328 grounds that sooner or later somebody will try it.
19329
19330 .oindex "&%self%&" "in &(ipliteral)& router"
19331 If the IP address matches something in &%ignore_target_hosts%&, the router
19332 declines. If an IP literal turns out to refer to the local host, the generic
19333 &%self%& option determines what happens.
19334
19335 The RFCs require support for domain literals; however, their use is
19336 controversial in today's Internet. If you want to use this router, you must
19337 also set the main configuration option &%allow_domain_literals%&. Otherwise,
19338 Exim will not recognize the domain literal syntax in addresses.
19339
19340
19341
19342 . ////////////////////////////////////////////////////////////////////////////
19343 . ////////////////////////////////////////////////////////////////////////////
19344
19345 .chapter "The iplookup router" "CHID6"
19346 .cindex "&(iplookup)& router"
19347 .cindex "routers" "&(iplookup)&"
19348 The &(iplookup)& router was written to fulfil a specific requirement in
19349 Cambridge University (which in fact no longer exists). For this reason, it is
19350 not included in the binary of Exim by default. If you want to include it, you
19351 must set
19352 .code
19353 ROUTER_IPLOOKUP=yes
19354 .endd
19355 in your &_Local/Makefile_& configuration file.
19356
19357 The &(iplookup)& router routes an address by sending it over a TCP or UDP
19358 connection to one or more specific hosts. The host can then return the same or
19359 a different address &-- in effect rewriting the recipient address in the
19360 message's envelope. The new address is then passed on to subsequent routers. If
19361 this process fails, the address can be passed on to other routers, or delivery
19362 can be deferred. Since &(iplookup)& is just a rewriting router, a transport
19363 must not be specified for it.
19364
19365 .cindex "options" "&(iplookup)& router"
19366 .option hosts iplookup string unset
19367 This option must be supplied. Its value is a colon-separated list of host
19368 names. The hosts are looked up using &[gethostbyname()]&
19369 (or &[getipnodebyname()]& when available)
19370 and are tried in order until one responds to the query. If none respond, what
19371 happens is controlled by &%optional%&.
19372
19373
19374 .option optional iplookup boolean false
19375 If &%optional%& is true, if no response is obtained from any host, the address
19376 is passed to the next router, overriding &%no_more%&. If &%optional%& is false,
19377 delivery to the address is deferred.
19378
19379
19380 .option port iplookup integer 0
19381 .cindex "port" "&(iplookup)& router"
19382 This option must be supplied. It specifies the port number for the TCP or UDP
19383 call.
19384
19385
19386 .option protocol iplookup string udp
19387 This option can be set to &"udp"& or &"tcp"& to specify which of the two
19388 protocols is to be used.
19389
19390
19391 .option query iplookup string&!! "see below"
19392 This defines the content of the query that is sent to the remote hosts. The
19393 default value is:
19394 .code
19395 $local_part@$domain $local_part@$domain
19396 .endd
19397 The repetition serves as a way of checking that a response is to the correct
19398 query in the default case (see &%response_pattern%& below).
19399
19400
19401 .option reroute iplookup string&!! unset
19402 If this option is not set, the rerouted address is precisely the byte string
19403 returned by the remote host, up to the first white space, if any. If set, the
19404 string is expanded to form the rerouted address. It can include parts matched
19405 in the response by &%response_pattern%& by means of numeric variables such as
19406 &$1$&, &$2$&, etc. The variable &$0$& refers to the entire input string,
19407 whether or not a pattern is in use. In all cases, the rerouted address must end
19408 up in the form &'local_part@domain'&.
19409
19410
19411 .option response_pattern iplookup string unset
19412 This option can be set to a regular expression that is applied to the string
19413 returned from the remote host. If the pattern does not match the response, the
19414 router declines. If &%response_pattern%& is not set, no checking of the
19415 response is done, unless the query was defaulted, in which case there is a
19416 check that the text returned after the first white space is the original
19417 address. This checks that the answer that has been received is in response to
19418 the correct question. For example, if the response is just a new domain, the
19419 following could be used:
19420 .code
19421 response_pattern = ^([^@]+)$
19422 reroute = $local_part@$1
19423 .endd
19424
19425 .option timeout iplookup time 5s
19426 This specifies the amount of time to wait for a response from the remote
19427 machine. The same timeout is used for the &[connect()]& function for a TCP
19428 call. It does not apply to UDP.
19429
19430
19431
19432
19433 . ////////////////////////////////////////////////////////////////////////////
19434 . ////////////////////////////////////////////////////////////////////////////
19435
19436 .chapter "The manualroute router" "CHID7"
19437 .scindex IIDmanrou1 "&(manualroute)& router"
19438 .scindex IIDmanrou2 "routers" "&(manualroute)&"
19439 .cindex "domain" "manually routing"
19440 The &(manualroute)& router is so-called because it provides a way of manually
19441 routing an address according to its domain. It is mainly used when you want to
19442 route addresses to remote hosts according to your own rules, bypassing the
19443 normal DNS routing that looks up MX records. However, &(manualroute)& can also
19444 route to local transports, a facility that may be useful if you want to save
19445 messages for dial-in hosts in local files.
19446
19447 The &(manualroute)& router compares a list of domain patterns with the domain
19448 it is trying to route. If there is no match, the router declines. Each pattern
19449 has associated with it a list of hosts and some other optional data, which may
19450 include a transport. The combination of a pattern and its data is called a
19451 &"routing rule"&. For patterns that do not have an associated transport, the
19452 generic &%transport%& option must specify a transport, unless the router is
19453 being used purely for verification (see &%verify_only%&).
19454
19455 .vindex "&$host$&"
19456 In the case of verification, matching the domain pattern is sufficient for the
19457 router to accept the address. When actually routing an address for delivery,
19458 an address that matches a domain pattern is queued for the associated
19459 transport. If the transport is not a local one, a host list must be associated
19460 with the pattern; IP addresses are looked up for the hosts, and these are
19461 passed to the transport along with the mail address. For local transports, a
19462 host list is optional. If it is present, it is passed in &$host$& as a single
19463 text string.
19464
19465 The list of routing rules can be provided as an inline string in
19466 &%route_list%&, or the data can be obtained by looking up the domain in a file
19467 or database by setting &%route_data%&. Only one of these settings may appear in
19468 any one instance of &(manualroute)&. The format of routing rules is described
19469 below, following the list of private options.
19470
19471
19472 .section "Private options for manualroute" "SECTprioptman"
19473
19474 .cindex "options" "&(manualroute)& router"
19475 The private options for the &(manualroute)& router are as follows:
19476
19477 .option host_all_ignored manualroute string defer
19478 See &%host_find_failed%&.
19479
19480 .option host_find_failed manualroute string freeze
19481 This option controls what happens when &(manualroute)& tries to find an IP
19482 address for a host, and the host does not exist. The option can be set to one
19483 of the following values:
19484 .code
19485 decline
19486 defer
19487 fail
19488 freeze
19489 ignore
19490 pass
19491 .endd
19492 The default (&"freeze"&) assumes that this state is a serious configuration
19493 error. The difference between &"pass"& and &"decline"& is that the former
19494 forces the address to be passed to the next router (or the router defined by
19495 &%pass_router%&),
19496 .oindex "&%more%&"
19497 overriding &%no_more%&, whereas the latter passes the address to the next
19498 router only if &%more%& is true.
19499
19500 The value &"ignore"& causes Exim to completely ignore a host whose IP address
19501 cannot be found. If all the hosts in the list are ignored, the behaviour is
19502 controlled by the &%host_all_ignored%& option. This takes the same values
19503 as &%host_find_failed%&, except that it cannot be set to &"ignore"&.
19504
19505 The &%host_find_failed%& option applies only to a definite &"does not exist"&
19506 state; if a host lookup gets a temporary error, delivery is deferred unless the
19507 generic &%pass_on_timeout%& option is set.
19508
19509
19510 .option hosts_randomize manualroute boolean false
19511 .cindex "randomized host list"
19512 .cindex "host" "list of; randomized"
19513 If this option is set, the order of the items in a host list in a routing rule
19514 is randomized each time the list is used, unless an option in the routing rule
19515 overrides (see below). Randomizing the order of a host list can be used to do
19516 crude load sharing. However, if more than one mail address is routed by the
19517 same router to the same host list, the host lists are considered to be the same
19518 (even though they may be randomized into different orders) for the purpose of
19519 deciding whether to batch the deliveries into a single SMTP transaction.
19520
19521 When &%hosts_randomize%& is true, a host list may be split
19522 into groups whose order is separately randomized. This makes it possible to
19523 set up MX-like behaviour. The boundaries between groups are indicated by an
19524 item that is just &`+`& in the host list. For example:
19525 .code
19526 route_list = * host1:host2:host3:+:host4:host5
19527 .endd
19528 The order of the first three hosts and the order of the last two hosts is
19529 randomized for each use, but the first three always end up before the last two.
19530 If &%hosts_randomize%& is not set, a &`+`& item in the list is ignored. If a
19531 randomized host list is passed to an &(smtp)& transport that also has
19532 &%hosts_randomize set%&, the list is not re-randomized.
19533
19534
19535 .option route_data manualroute string&!! unset
19536 If this option is set, it must expand to yield the data part of a routing rule.
19537 Typically, the expansion string includes a lookup based on the domain. For
19538 example:
19539 .code
19540 route_data = ${lookup{$domain}dbm{/etc/routes}}
19541 .endd
19542 If the expansion is forced to fail, or the result is an empty string, the
19543 router declines. Other kinds of expansion failure cause delivery to be
19544 deferred.
19545
19546
19547 .option route_list manualroute "string list" unset
19548 This string is a list of routing rules, in the form defined below. Note that,
19549 unlike most string lists, the items are separated by semicolons. This is so
19550 that they may contain colon-separated host lists.
19551
19552
19553 .option same_domain_copy_routing manualroute boolean false
19554 .cindex "address" "copying routing"
19555 Addresses with the same domain are normally routed by the &(manualroute)&
19556 router to the same list of hosts. However, this cannot be presumed, because the
19557 router options and preconditions may refer to the local part of the address. By
19558 default, therefore, Exim routes each address in a message independently. DNS
19559 servers run caches, so repeated DNS lookups are not normally expensive, and in
19560 any case, personal messages rarely have more than a few recipients.
19561
19562 If you are running mailing lists with large numbers of subscribers at the same
19563 domain, and you are using a &(manualroute)& router which is independent of the
19564 local part, you can set &%same_domain_copy_routing%& to bypass repeated DNS
19565 lookups for identical domains in one message. In this case, when
19566 &(manualroute)& routes an address to a remote transport, any other unrouted
19567 addresses in the message that have the same domain are automatically given the
19568 same routing without processing them independently. However, this is only done
19569 if &%headers_add%& and &%headers_remove%& are unset.
19570
19571
19572
19573
19574 .section "Routing rules in route_list" "SECID120"
19575 The value of &%route_list%& is a string consisting of a sequence of routing
19576 rules, separated by semicolons. If a semicolon is needed in a rule, it can be
19577 entered as two semicolons. Alternatively, the list separator can be changed as
19578 described (for colon-separated lists) in section &<<SECTlistconstruct>>&.
19579 Empty rules are ignored. The format of each rule is
19580 .display
19581 <&'domain pattern'&>  <&'list of hosts'&>  <&'options'&>
19582 .endd
19583 The following example contains two rules, each with a simple domain pattern and
19584 no options:
19585 .code
19586 route_list = \
19587   dict.ref.example  mail-1.ref.example:mail-2.ref.example ; \
19588   thes.ref.example  mail-3.ref.example:mail-4.ref.example
19589 .endd
19590 The three parts of a rule are separated by white space. The pattern and the
19591 list of hosts can be enclosed in quotes if necessary, and if they are, the
19592 usual quoting rules apply. Each rule in a &%route_list%& must start with a
19593 single domain pattern, which is the only mandatory item in the rule. The
19594 pattern is in the same format as one item in a domain list (see section
19595 &<<SECTdomainlist>>&),
19596 except that it may not be the name of an interpolated file.
19597 That is, it may be wildcarded, or a regular expression, or a file or database
19598 lookup (with semicolons doubled, because of the use of semicolon as a separator
19599 in a &%route_list%&).
19600
19601 The rules in &%route_list%& are searched in order until one of the patterns
19602 matches the domain that is being routed. The list of hosts and then options are
19603 then used as described below. If there is no match, the router declines. When
19604 &%route_list%& is set, &%route_data%& must not be set.
19605
19606
19607
19608 .section "Routing rules in route_data" "SECID121"
19609 The use of &%route_list%& is convenient when there are only a small number of
19610 routing rules. For larger numbers, it is easier to use a file or database to
19611 hold the routing information, and use the &%route_data%& option instead.
19612 The value of &%route_data%& is a list of hosts, followed by (optional) options.
19613 Most commonly, &%route_data%& is set as a string that contains an
19614 expansion lookup. For example, suppose we place two routing rules in a file
19615 like this:
19616 .code
19617 dict.ref.example:  mail-1.ref.example:mail-2.ref.example
19618 thes.ref.example:  mail-3.ref.example:mail-4.ref.example
19619 .endd
19620 This data can be accessed by setting
19621 .code
19622 route_data = ${lookup{$domain}lsearch{/the/file/name}}
19623 .endd
19624 Failure of the lookup results in an empty string, causing the router to
19625 decline. However, you do not have to use a lookup in &%route_data%&. The only
19626 requirement is that the result of expanding the string is a list of hosts,
19627 possibly followed by options, separated by white space. The list of hosts must
19628 be enclosed in quotes if it contains white space.
19629
19630
19631
19632
19633 .section "Format of the list of hosts" "SECID122"
19634 A list of hosts, whether obtained via &%route_data%& or &%route_list%&, is
19635 always separately expanded before use. If the expansion fails, the router
19636 declines. The result of the expansion must be a colon-separated list of names
19637 and/or IP addresses, optionally also including ports.
19638 If the list is written with spaces, it must be protected with quotes.
19639 The format of each item
19640 in the list is described in the next section. The list separator can be changed
19641 as described in section &<<SECTlistconstruct>>&.
19642
19643 If the list of hosts was obtained from a &%route_list%& item, the following
19644 variables are set during its expansion:
19645
19646 .ilist
19647 .cindex "numerical variables (&$1$& &$2$&  etc)" "in &(manualroute)& router"
19648 If the domain was matched against a regular expression, the numeric variables
19649 &$1$&, &$2$&, etc. may be set. For example:
19650 .code
19651 route_list = ^domain(\d+)   host-$1.text.example
19652 .endd
19653 .next
19654 &$0$& is always set to the entire domain.
19655 .next
19656 &$1$& is also set when partial matching is done in a file lookup.
19657
19658 .next
19659 .vindex "&$value$&"
19660 If the pattern that matched the domain was a lookup item, the data that was
19661 looked up is available in the expansion variable &$value$&. For example:
19662 .code
19663 route_list = lsearch;;/some/file.routes  $value
19664 .endd
19665 .endlist
19666
19667 Note the doubling of the semicolon in the pattern that is necessary because
19668 semicolon is the default route list separator.
19669
19670
19671
19672 .section "Format of one host item" "SECTformatonehostitem"
19673 Each item in the list of hosts is either a host name or an IP address,
19674 optionally with an attached port number. When no port is given, an IP address
19675 is not enclosed in brackets. When a port is specified, it overrides the port
19676 specification on the transport. The port is separated from the name or address
19677 by a colon. This leads to some complications:
19678
19679 .ilist
19680 Because colon is the default separator for the list of hosts, either
19681 the colon that specifies a port must be doubled, or the list separator must
19682 be changed. The following two examples have the same effect:
19683 .code
19684 route_list = * "host1.tld::1225 : host2.tld::1226"
19685 route_list = * "<+ host1.tld:1225 + host2.tld:1226"
19686 .endd
19687 .next
19688 When IPv6 addresses are involved, it gets worse, because they contain
19689 colons of their own. To make this case easier, it is permitted to
19690 enclose an IP address (either v4 or v6) in square brackets if a port
19691 number follows. For example:
19692 .code
19693 route_list = * "</ [10.1.1.1]:1225 / [::1]:1226"
19694 .endd
19695 .endlist
19696
19697 .section "How the list of hosts is used" "SECThostshowused"
19698 When an address is routed to an &(smtp)& transport by &(manualroute)&, each of
19699 the hosts is tried, in the order specified, when carrying out the SMTP
19700 delivery. However, the order can be changed by setting the &%hosts_randomize%&
19701 option, either on the router (see section &<<SECTprioptman>>& above), or on the
19702 transport.
19703
19704 Hosts may be listed by name or by IP address. An unadorned name in the list of
19705 hosts is interpreted as a host name. A name that is followed by &`/MX`& is
19706 interpreted as an indirection to a sublist of hosts obtained by looking up MX
19707 records in the DNS. For example:
19708 .code
19709 route_list = *  x.y.z:p.q.r/MX:e.f.g
19710 .endd
19711 If this feature is used with a port specifier, the port must come last. For
19712 example:
19713 .code
19714 route_list = *  dom1.tld/mx::1225
19715 .endd
19716 If the &%hosts_randomize%& option is set, the order of the items in the list is
19717 randomized before any lookups are done. Exim then scans the list; for any name
19718 that is not followed by &`/MX`& it looks up an IP address. If this turns out to
19719 be an interface on the local host and the item is not the first in the list,
19720 Exim discards it and any subsequent items. If it is the first item, what
19721 happens is controlled by the
19722 .oindex "&%self%&" "in &(manualroute)& router"
19723 &%self%& option of the router.
19724
19725 A name on the list that is followed by &`/MX`& is replaced with the list of
19726 hosts obtained by looking up MX records for the name. This is always a DNS
19727 lookup; the &%bydns%& and &%byname%& options (see section &<<SECThowoptused>>&
19728 below) are not relevant here. The order of these hosts is determined by the
19729 preference values in the MX records, according to the usual rules. Because
19730 randomizing happens before the MX lookup, it does not affect the order that is
19731 defined by MX preferences.
19732
19733 If the local host is present in the sublist obtained from MX records, but is
19734 not the most preferred host in that list, it and any equally or less
19735 preferred hosts are removed before the sublist is inserted into the main list.
19736
19737 If the local host is the most preferred host in the MX list, what happens
19738 depends on where in the original list of hosts the &`/MX`& item appears. If it
19739 is not the first item (that is, there are previous hosts in the main list),
19740 Exim discards this name and any subsequent items in the main list.
19741
19742 If the MX item is first in the list of hosts, and the local host is the
19743 most preferred host, what happens is controlled by the &%self%& option of the
19744 router.
19745
19746 DNS failures when lookup up the MX records are treated in the same way as DNS
19747 failures when looking up IP addresses: &%pass_on_timeout%& and
19748 &%host_find_failed%& are used when relevant.
19749
19750 The generic &%ignore_target_hosts%& option applies to all hosts in the list,
19751 whether obtained from an MX lookup or not.
19752
19753
19754
19755 .section "How the options are used" "SECThowoptused"
19756 The options are a sequence of words, space-separated.
19757 One of the words can be the name of a transport; this overrides the
19758 &%transport%& option on the router for this particular routing rule only. The
19759 other words (if present) control randomization of the list of hosts on a
19760 per-rule basis, and how the IP addresses of the hosts are to be found when
19761 routing to a remote transport. These options are as follows:
19762
19763 .ilist
19764 &%randomize%&: randomize the order of the hosts in this list, overriding the
19765 setting of &%hosts_randomize%& for this routing rule only.
19766 .next
19767 &%no_randomize%&: do not randomize the order of the hosts in this list,
19768 overriding the setting of &%hosts_randomize%& for this routing rule only.
19769 .next
19770 &%byname%&: use &[getipnodebyname()]& (&[gethostbyname()]& on older systems) to
19771 find IP addresses. This function may ultimately cause a DNS lookup, but it may
19772 also look in &_/etc/hosts_& or other sources of information.
19773 .next
19774 &%bydns%&: look up address records for the hosts directly in the DNS; fail if
19775 no address records are found. If there is a temporary DNS error (such as a
19776 timeout), delivery is deferred.
19777 .next
19778 &%ipv4_only%&: in direct DNS lookups, look up only A records.
19779 .next
19780 &%ipv4_prefer%&: in direct DNS lookups, sort A records before AAAA records.
19781 .endlist
19782
19783 For example:
19784 .code
19785 route_list = domain1  host1:host2:host3  randomize bydns;\
19786              domain2  host4:host5
19787 .endd
19788 If neither &%byname%& nor &%bydns%& is given, Exim behaves as follows: First, a
19789 DNS lookup is done. If this yields anything other than HOST_NOT_FOUND, that
19790 result is used. Otherwise, Exim goes on to try a call to &[getipnodebyname()]&
19791 or &[gethostbyname()]&, and the result of the lookup is the result of that
19792 call.
19793
19794 &*Warning*&: It has been discovered that on some systems, if a DNS lookup
19795 called via &[getipnodebyname()]& times out, HOST_NOT_FOUND is returned
19796 instead of TRY_AGAIN. That is why the default action is to try a DNS
19797 lookup first. Only if that gives a definite &"no such host"& is the local
19798 function called.
19799
19800 &*Compatibility*&: From Exim 4.85 until fixed for 4.90, there was an
19801 inadvertent constraint that a transport name as an option had to be the last
19802 option specified.
19803
19804
19805
19806 If no IP address for a host can be found, what happens is controlled by the
19807 &%host_find_failed%& option.
19808
19809 .vindex "&$host$&"
19810 When an address is routed to a local transport, IP addresses are not looked up.
19811 The host list is passed to the transport in the &$host$& variable.
19812
19813
19814
19815 .section "Manualroute examples" "SECID123"
19816 In some of the examples that follow, the presence of the &%remote_smtp%&
19817 transport, as defined in the default configuration file, is assumed:
19818
19819 .ilist
19820 .cindex "smart host" "example router"
19821 The &(manualroute)& router can be used to forward all external mail to a
19822 &'smart host'&. If you have set up, in the main part of the configuration, a
19823 named domain list that contains your local domains, for example:
19824 .code
19825 domainlist local_domains = my.domain.example
19826 .endd
19827 You can arrange for all other domains to be routed to a smart host by making
19828 your first router something like this:
19829 .code
19830 smart_route:
19831   driver = manualroute
19832   domains = !+local_domains
19833   transport = remote_smtp
19834   route_list = * smarthost.ref.example
19835 .endd
19836 This causes all non-local addresses to be sent to the single host
19837 &'smarthost.ref.example'&. If a colon-separated list of smart hosts is given,
19838 they are tried in order
19839 (but you can use &%hosts_randomize%& to vary the order each time).
19840 Another way of configuring the same thing is this:
19841 .code
19842 smart_route:
19843   driver = manualroute
19844   transport = remote_smtp
19845   route_list = !+local_domains  smarthost.ref.example
19846 .endd
19847 There is no difference in behaviour between these two routers as they stand.
19848 However, they behave differently if &%no_more%& is added to them. In the first
19849 example, the router is skipped if the domain does not match the &%domains%&
19850 precondition; the following router is always tried. If the router runs, it
19851 always matches the domain and so can never decline. Therefore, &%no_more%&
19852 would have no effect. In the second case, the router is never skipped; it
19853 always runs. However, if it doesn't match the domain, it declines. In this case
19854 &%no_more%& would prevent subsequent routers from running.
19855
19856 .next
19857 .cindex "mail hub example"
19858 A &'mail hub'& is a host which receives mail for a number of domains via MX
19859 records in the DNS and delivers it via its own private routing mechanism. Often
19860 the final destinations are behind a firewall, with the mail hub being the one
19861 machine that can connect to machines both inside and outside the firewall. The
19862 &(manualroute)& router is usually used on a mail hub to route incoming messages
19863 to the correct hosts. For a small number of domains, the routing can be inline,
19864 using the &%route_list%& option, but for a larger number a file or database
19865 lookup is easier to manage.
19866
19867 If the domain names are in fact the names of the machines to which the mail is
19868 to be sent by the mail hub, the configuration can be quite simple. For
19869 example:
19870 .code
19871 hub_route:
19872   driver = manualroute
19873   transport = remote_smtp
19874   route_list = *.rhodes.tvs.example  $domain
19875 .endd
19876 This configuration routes domains that match &`*.rhodes.tvs.example`& to hosts
19877 whose names are the same as the mail domains. A similar approach can be taken
19878 if the host name can be obtained from the domain name by a string manipulation
19879 that the expansion facilities can handle. Otherwise, a lookup based on the
19880 domain can be used to find the host:
19881 .code
19882 through_firewall:
19883   driver = manualroute
19884   transport = remote_smtp
19885   route_data = ${lookup {$domain} cdb {/internal/host/routes}}
19886 .endd
19887 The result of the lookup must be the name or IP address of the host (or
19888 hosts) to which the address is to be routed. If the lookup fails, the route
19889 data is empty, causing the router to decline. The address then passes to the
19890 next router.
19891
19892 .next
19893 .cindex "batched SMTP output example"
19894 .cindex "SMTP" "batched outgoing; example"
19895 You can use &(manualroute)& to deliver messages to pipes or files in batched
19896 SMTP format for onward transportation by some other means. This is one way of
19897 storing mail for a dial-up host when it is not connected. The route list entry
19898 can be as simple as a single domain name in a configuration like this:
19899 .code
19900 save_in_file:
19901   driver = manualroute
19902   transport = batchsmtp_appendfile
19903   route_list = saved.domain.example
19904 .endd
19905 though often a pattern is used to pick up more than one domain. If there are
19906 several domains or groups of domains with different transport requirements,
19907 different transports can be listed in the routing information:
19908 .code
19909 save_in_file:
19910   driver = manualroute
19911   route_list = \
19912     *.saved.domain1.example  $domain  batch_appendfile; \
19913     *.saved.domain2.example  \
19914       ${lookup{$domain}dbm{/domain2/hosts}{$value}fail} \
19915       batch_pipe
19916 .endd
19917 .vindex "&$domain$&"
19918 .vindex "&$host$&"
19919 The first of these just passes the domain in the &$host$& variable, which
19920 doesn't achieve much (since it is also in &$domain$&), but the second does a
19921 file lookup to find a value to pass, causing the router to decline to handle
19922 the address if the lookup fails.
19923
19924 .next
19925 .cindex "UUCP" "example of router for"
19926 Routing mail directly to UUCP software is a specific case of the use of
19927 &(manualroute)& in a gateway to another mail environment. This is an example of
19928 one way it can be done:
19929 .code
19930 # Transport
19931 uucp:
19932   driver = pipe
19933   user = nobody
19934   command = /usr/local/bin/uux -r - \
19935     ${substr_-5:$host}!rmail ${local_part}
19936   return_fail_output = true
19937
19938 # Router
19939 uucphost:
19940   transport = uucp
19941   driver = manualroute
19942   route_data = \
19943     ${lookup{$domain}lsearch{/usr/local/exim/uucphosts}}
19944 .endd
19945 The file &_/usr/local/exim/uucphosts_& contains entries like
19946 .code
19947 darksite.ethereal.example:           darksite.UUCP
19948 .endd
19949 It can be set up more simply without adding and removing &".UUCP"& but this way
19950 makes clear the distinction between the domain name
19951 &'darksite.ethereal.example'& and the UUCP host name &'darksite'&.
19952 .endlist
19953 .ecindex IIDmanrou1
19954 .ecindex IIDmanrou2
19955
19956
19957
19958
19959
19960
19961
19962
19963 . ////////////////////////////////////////////////////////////////////////////
19964 . ////////////////////////////////////////////////////////////////////////////
19965
19966 .chapter "The queryprogram router" "CHAPdriverlast"
19967 .scindex IIDquerou1 "&(queryprogram)& router"
19968 .scindex IIDquerou2 "routers" "&(queryprogram)&"
19969 .cindex "routing" "by external program"
19970 The &(queryprogram)& router routes an address by running an external command
19971 and acting on its output. This is an expensive way to route, and is intended
19972 mainly for use in lightly-loaded systems, or for performing experiments.
19973 However, if it is possible to use the precondition options (&%domains%&,
19974 &%local_parts%&, etc) to skip this router for most addresses, it could sensibly
19975 be used in special cases, even on a busy host. There are the following private
19976 options:
19977 .cindex "options" "&(queryprogram)& router"
19978
19979 .option command queryprogram string&!! unset
19980 This option must be set. It specifies the command that is to be run. The
19981 command is split up into a command name and arguments, and then each is
19982 expanded separately (exactly as for a &(pipe)& transport, described in chapter
19983 &<<CHAPpipetransport>>&).
19984
19985
19986 .option command_group queryprogram string unset
19987 .cindex "gid (group id)" "in &(queryprogram)& router"
19988 This option specifies a gid to be set when running the command while routing an
19989 address for deliver. It must be set if &%command_user%& specifies a numerical
19990 uid. If it begins with a digit, it is interpreted as the numerical value of the
19991 gid. Otherwise it is looked up using &[getgrnam()]&.
19992
19993
19994 .option command_user queryprogram string unset
19995 .cindex "uid (user id)" "for &(queryprogram)&"
19996 This option must be set. It specifies the uid which is set when running the
19997 command while routing an address for delivery. If the value begins with a digit,
19998 it is interpreted as the numerical value of the uid. Otherwise, it is looked up
19999 using &[getpwnam()]& to obtain a value for the uid and, if &%command_group%& is
20000 not set, a value for the gid also.
20001
20002 &*Warning:*& Changing uid and gid is possible only when Exim is running as
20003 root, which it does during a normal delivery in a conventional configuration.
20004 However, when an address is being verified during message reception, Exim is
20005 usually running as the Exim user, not as root. If the &(queryprogram)& router
20006 is called from a non-root process, Exim cannot change uid or gid before running
20007 the command. In this circumstance the command runs under the current uid and
20008 gid.
20009
20010
20011 .option current_directory queryprogram string /
20012 This option specifies an absolute path which is made the current directory
20013 before running the command.
20014
20015
20016 .option timeout queryprogram time 1h
20017 If the command does not complete within the timeout period, its process group
20018 is killed and the message is frozen. A value of zero time specifies no
20019 timeout.
20020
20021
20022 The standard output of the command is connected to a pipe, which is read when
20023 the command terminates. It should consist of a single line of output,
20024 containing up to five fields, separated by white space. The maximum length of
20025 the line is 1023 characters. Longer lines are silently truncated. The first
20026 field is one of the following words (case-insensitive):
20027
20028 .ilist
20029 &'Accept'&: routing succeeded; the remaining fields specify what to do (see
20030 below).
20031 .next
20032 &'Decline'&: the router declines; pass the address to the next router, unless
20033 &%no_more%& is set.
20034 .next
20035 &'Fail'&: routing failed; do not pass the address to any more routers. Any
20036 subsequent text on the line is an error message. If the router is run as part
20037 of address verification during an incoming SMTP message, the message is
20038 included in the SMTP response.
20039 .next
20040 &'Defer'&: routing could not be completed at this time; try again later. Any
20041 subsequent text on the line is an error message which is logged. It is not
20042 included in any SMTP response.
20043 .next
20044 &'Freeze'&: the same as &'defer'&, except that the message is frozen.
20045 .next
20046 &'Pass'&: pass the address to the next router (or the router specified by
20047 &%pass_router%&), overriding &%no_more%&.
20048 .next
20049 &'Redirect'&: the message is redirected. The remainder of the line is a list of
20050 new addresses, which are routed independently, starting with the first router,
20051 or the router specified by &%redirect_router%&, if set.
20052 .endlist
20053
20054 When the first word is &'accept'&, the remainder of the line consists of a
20055 number of keyed data values, as follows (split into two lines here, to fit on
20056 the page):
20057 .code
20058 ACCEPT TRANSPORT=<transport> HOSTS=<list of hosts>
20059 LOOKUP=byname|bydns DATA=<text>
20060 .endd
20061 The data items can be given in any order, and all are optional. If no transport
20062 is included, the transport specified by the generic &%transport%& option is
20063 used. The list of hosts and the lookup type are needed only if the transport is
20064 an &(smtp)& transport that does not itself supply a list of hosts.
20065
20066 The format of the list of hosts is the same as for the &(manualroute)& router.
20067 As well as host names and IP addresses with optional port numbers, as described
20068 in section &<<SECTformatonehostitem>>&, it may contain names followed by
20069 &`/MX`& to specify sublists of hosts that are obtained by looking up MX records
20070 (see section &<<SECThostshowused>>&).
20071
20072 If the lookup type is not specified, Exim behaves as follows when trying to
20073 find an IP address for each host: First, a DNS lookup is done. If this yields
20074 anything other than HOST_NOT_FOUND, that result is used. Otherwise, Exim
20075 goes on to try a call to &[getipnodebyname()]& or &[gethostbyname()]&, and the
20076 result of the lookup is the result of that call.
20077
20078 .vindex "&$address_data$&"
20079 If the DATA field is set, its value is placed in the &$address_data$&
20080 variable. For example, this return line
20081 .code
20082 accept hosts=x1.y.example:x2.y.example data="rule1"
20083 .endd
20084 routes the address to the default transport, passing a list of two hosts. When
20085 the transport runs, the string &"rule1"& is in &$address_data$&.
20086 .ecindex IIDquerou1
20087 .ecindex IIDquerou2
20088
20089
20090
20091
20092 . ////////////////////////////////////////////////////////////////////////////
20093 . ////////////////////////////////////////////////////////////////////////////
20094
20095 .chapter "The redirect router" "CHAPredirect"
20096 .scindex IIDredrou1 "&(redirect)& router"
20097 .scindex IIDredrou2 "routers" "&(redirect)&"
20098 .cindex "alias file" "in a &(redirect)& router"
20099 .cindex "address redirection" "&(redirect)& router"
20100 The &(redirect)& router handles several kinds of address redirection. Its most
20101 common uses are for resolving local part aliases from a central alias file
20102 (usually called &_/etc/aliases_&) and for handling users' personal &_.forward_&
20103 files, but it has many other potential uses. The incoming address can be
20104 redirected in several different ways:
20105
20106 .ilist
20107 It can be replaced by one or more new addresses which are themselves routed
20108 independently.
20109 .next
20110 It can be routed to be delivered to a given file or directory.
20111 .next
20112 It can be routed to be delivered to a specified pipe command.
20113 .next
20114 It can cause an automatic reply to be generated.
20115 .next
20116 It can be forced to fail, optionally with a custom error message.
20117 .next
20118 It can be temporarily deferred, optionally with a custom message.
20119 .next
20120 It can be discarded.
20121 .endlist
20122
20123 The generic &%transport%& option must not be set for &(redirect)& routers.
20124 However, there are some private options which define transports for delivery to
20125 files and pipes, and for generating autoreplies. See the &%file_transport%&,
20126 &%pipe_transport%& and &%reply_transport%& descriptions below.
20127
20128 If success DSNs have been requested
20129 .cindex "DSN" "success"
20130 .cindex "Delivery Status Notification" "success"
20131 redirection triggers one and the DSN options are not passed any further.
20132
20133
20134
20135 .section "Redirection data" "SECID124"
20136 The router operates by interpreting a text string which it obtains either by
20137 expanding the contents of the &%data%& option, or by reading the entire
20138 contents of a file whose name is given in the &%file%& option. These two
20139 options are mutually exclusive. The first is commonly used for handling system
20140 aliases, in a configuration like this:
20141 .code
20142 system_aliases:
20143   driver = redirect
20144   data = ${lookup{$local_part}lsearch{/etc/aliases}}
20145 .endd
20146 If the lookup fails, the expanded string in this example is empty. When the
20147 expansion of &%data%& results in an empty string, the router declines. A forced
20148 expansion failure also causes the router to decline; other expansion failures
20149 cause delivery to be deferred.
20150
20151 A configuration using &%file%& is commonly used for handling users'
20152 &_.forward_& files, like this:
20153 .code
20154 userforward:
20155   driver = redirect
20156   check_local_user
20157   file = $home/.forward
20158   no_verify
20159 .endd
20160 If the file does not exist, or causes no action to be taken (for example, it is
20161 empty or consists only of comments), the router declines. &*Warning*&: This
20162 is not the case when the file contains syntactically valid items that happen to
20163 yield empty addresses, for example, items containing only RFC 2822 address
20164 comments.
20165
20166
20167
20168 .section "Forward files and address verification" "SECID125"
20169 .cindex "address redirection" "while verifying"
20170 It is usual to set &%no_verify%& on &(redirect)& routers which handle users'
20171 &_.forward_& files, as in the example above. There are two reasons for this:
20172
20173 .ilist
20174 When Exim is receiving an incoming SMTP message from a remote host, it is
20175 running under the Exim uid, not as root. Exim is unable to change uid to read
20176 the file as the user, and it may not be able to read it as the Exim user. So in
20177 practice the router may not be able to operate.
20178 .next
20179 However, even when the router can operate, the existence of a &_.forward_& file
20180 is unimportant when verifying an address. What should be checked is whether the
20181 local part is a valid user name or not. Cutting out the redirection processing
20182 saves some resources.
20183 .endlist
20184
20185
20186
20187
20188
20189
20190 .section "Interpreting redirection data" "SECID126"
20191 .cindex "Sieve filter" "specifying in redirection data"
20192 .cindex "filter" "specifying in redirection data"
20193 The contents of the data string, whether obtained from &%data%& or &%file%&,
20194 can be interpreted in two different ways:
20195
20196 .ilist
20197 If the &%allow_filter%& option is set true, and the data begins with the text
20198 &"#Exim filter"& or &"#Sieve filter"&, it is interpreted as a list of
20199 &'filtering'& instructions in the form of an Exim or Sieve filter file,
20200 respectively. Details of the syntax and semantics of filter files are described
20201 in a separate document entitled &'Exim's interfaces to mail filtering'&; this
20202 document is intended for use by end users.
20203 .next
20204 Otherwise, the data must be a comma-separated list of redirection items, as
20205 described in the next section.
20206 .endlist
20207
20208 When a message is redirected to a file (a &"mail folder"&), the file name given
20209 in a non-filter redirection list must always be an absolute path. A filter may
20210 generate a relative path &-- how this is handled depends on the transport's
20211 configuration. See section &<<SECTfildiropt>>& for a discussion of this issue
20212 for the &(appendfile)& transport.
20213
20214
20215
20216 .section "Items in a non-filter redirection list" "SECTitenonfilred"
20217 .cindex "address redirection" "non-filter list items"
20218 When the redirection data is not an Exim or Sieve filter, for example, if it
20219 comes from a conventional alias or forward file, it consists of a list of
20220 addresses, file names, pipe commands, or certain special items (see section
20221 &<<SECTspecitredli>>& below). The special items can be individually enabled or
20222 disabled by means of options whose names begin with &%allow_%& or &%forbid_%&,
20223 depending on their default values. The items in the list are separated by
20224 commas or newlines.
20225 If a comma is required in an item, the entire item must be enclosed in double
20226 quotes.
20227
20228 Lines starting with a # character are comments, and are ignored, and # may
20229 also appear following a comma, in which case everything between the # and the
20230 next newline character is ignored.
20231
20232 If an item is entirely enclosed in double quotes, these are removed. Otherwise
20233 double quotes are retained because some forms of mail address require their use
20234 (but never to enclose the entire address). In the following description,
20235 &"item"& refers to what remains after any surrounding double quotes have been
20236 removed.
20237
20238 .vindex "&$local_part$&"
20239 &*Warning*&: If you use an Exim expansion to construct a redirection address,
20240 and the expansion contains a reference to &$local_part$&, you should make use
20241 of the &%quote_local_part%& expansion operator, in case the local part contains
20242 special characters. For example, to redirect all mail for the domain
20243 &'obsolete.example'&, retaining the existing local part, you could use this
20244 setting:
20245 .code
20246 data = ${quote_local_part:$local_part}@newdomain.example
20247 .endd
20248
20249
20250 .section "Redirecting to a local mailbox" "SECTredlocmai"
20251 .cindex "routing" "loops in"
20252 .cindex "loop" "while routing, avoidance of"
20253 .cindex "address redirection" "to local mailbox"
20254 A redirection item may safely be the same as the address currently under
20255 consideration. This does not cause a routing loop, because a router is
20256 automatically skipped if any ancestor of the address that is being processed
20257 is the same as the current address and was processed by the current router.
20258 Such an address is therefore passed to the following routers, so it is handled
20259 as if there were no redirection. When making this loop-avoidance test, the
20260 complete local part, including any prefix or suffix, is used.
20261
20262 .cindex "address redirection" "local part without domain"
20263 Specifying the same local part without a domain is a common usage in personal
20264 filter files when the user wants to have messages delivered to the local
20265 mailbox and also forwarded elsewhere. For example, the user whose login is
20266 &'cleo'& might have a &_.forward_& file containing this:
20267 .code
20268 cleo, cleopatra@egypt.example
20269 .endd
20270 .cindex "backslash in alias file"
20271 .cindex "alias file" "backslash in"
20272 For compatibility with other MTAs, such unqualified local parts may be
20273 preceded by &"\"&, but this is not a requirement for loop prevention. However,
20274 it does make a difference if more than one domain is being handled
20275 synonymously.
20276
20277 If an item begins with &"\"& and the rest of the item parses as a valid RFC
20278 2822 address that does not include a domain, the item is qualified using the
20279 domain of the incoming address. In the absence of a leading &"\"&, unqualified
20280 addresses are qualified using the value in &%qualify_recipient%&, but you can
20281 force the incoming domain to be used by setting &%qualify_preserve_domain%&.
20282
20283 Care must be taken if there are alias names for local users.
20284 Consider an MTA handling a single local domain where the system alias file
20285 contains:
20286 .code
20287 Sam.Reman: spqr
20288 .endd
20289 Now suppose that Sam (whose login id is &'spqr'&) wants to save copies of
20290 messages in the local mailbox, and also forward copies elsewhere. He creates
20291 this forward file:
20292 .code
20293 Sam.Reman, spqr@reme.elsewhere.example
20294 .endd
20295 With these settings, an incoming message addressed to &'Sam.Reman'& fails. The
20296 &(redirect)& router for system aliases does not process &'Sam.Reman'& the
20297 second time round, because it has previously routed it,
20298 and the following routers presumably cannot handle the alias. The forward file
20299 should really contain
20300 .code
20301 spqr, spqr@reme.elsewhere.example
20302 .endd
20303 but because this is such a common error, the &%check_ancestor%& option (see
20304 below) exists to provide a way to get round it. This is normally set on a
20305 &(redirect)& router that is handling users' &_.forward_& files.
20306
20307
20308
20309 .section "Special items in redirection lists" "SECTspecitredli"
20310 In addition to addresses, the following types of item may appear in redirection
20311 lists (that is, in non-filter redirection data):
20312
20313 .ilist
20314 .cindex "pipe" "in redirection list"
20315 .cindex "address redirection" "to pipe"
20316 An item is treated as a pipe command if it begins with &"|"& and does not parse
20317 as a valid RFC 2822 address that includes a domain. A transport for running the
20318 command must be specified by the &%pipe_transport%& option.
20319 Normally, either the router or the transport specifies a user and a group under
20320 which to run the delivery. The default is to use the Exim user and group.
20321
20322 Single or double quotes can be used for enclosing the individual arguments of
20323 the pipe command; no interpretation of escapes is done for single quotes. If
20324 the command contains a comma character, it is necessary to put the whole item
20325 in double quotes, for example:
20326 .code
20327 "|/some/command ready,steady,go"
20328 .endd
20329 since items in redirection lists are terminated by commas. Do not, however,
20330 quote just the command. An item such as
20331 .code
20332 |"/some/command ready,steady,go"
20333 .endd
20334 is interpreted as a pipe with a rather strange command name, and no arguments.
20335
20336 Note that the above example assumes that the text comes from a lookup source
20337 of some sort, so that the quotes are part of the data.  If composing a
20338 redirect router with a &%data%& option directly specifying this command, the
20339 quotes will be used by the configuration parser to define the extent of one
20340 string, but will not be passed down into the redirect router itself.  There
20341 are two main approaches to get around this: escape quotes to be part of the
20342 data itself, or avoid using this mechanism and instead create a custom
20343 transport with the &%command%& option set and reference that transport from
20344 an &%accept%& router.
20345
20346 .next
20347 .cindex "file" "in redirection list"
20348 .cindex "address redirection" "to file"
20349 An item is interpreted as a path name if it begins with &"/"& and does not
20350 parse as a valid RFC 2822 address that includes a domain. For example,
20351 .code
20352 /home/world/minbari
20353 .endd
20354 is treated as a file name, but
20355 .code
20356 /s=molari/o=babylon/@x400gate.way
20357 .endd
20358 is treated as an address. For a file name, a transport must be specified using
20359 the &%file_transport%& option. However, if the generated path name ends with a
20360 forward slash character, it is interpreted as a directory name rather than a
20361 file name, and &%directory_transport%& is used instead.
20362
20363 Normally, either the router or the transport specifies a user and a group under
20364 which to run the delivery. The default is to use the Exim user and group.
20365
20366 .cindex "&_/dev/null_&"
20367 However, if a redirection item is the path &_/dev/null_&, delivery to it is
20368 bypassed at a high level, and the log entry shows &"**bypassed**"&
20369 instead of a transport name. In this case the user and group are not used.
20370
20371 .next
20372 .cindex "included address list"
20373 .cindex "address redirection" "included external list"
20374 If an item is of the form
20375 .code
20376 :include:<path name>
20377 .endd
20378 a list of further items is taken from the given file and included at that
20379 point. &*Note*&: Such a file can not be a filter file; it is just an
20380 out-of-line addition to the list. The items in the included list are separated
20381 by commas or newlines and are not subject to expansion. If this is the first
20382 item in an alias list in an &(lsearch)& file, a colon must be used to terminate
20383 the alias name. This example is incorrect:
20384 .code
20385 list1    :include:/opt/lists/list1
20386 .endd
20387 It must be given as
20388 .code
20389 list1:   :include:/opt/lists/list1
20390 .endd
20391 .next
20392 .cindex "address redirection" "to black hole"
20393 .cindex "delivery" "discard"
20394 .cindex "delivery" "blackhole"
20395 .cindex "black hole"
20396 .cindex "abandoning mail"
20397 Sometimes you want to throw away mail to a particular local part.  Making the
20398 &%data%& option expand to an empty string does not work, because that causes
20399 the router to decline. Instead, the alias item
20400 .code
20401 :blackhole:
20402 .endd
20403 can be used. It does what its name implies. No delivery is
20404 done, and no error message is generated. This has the same effect as specifying
20405 &_/dev/null_& as a destination, but it can be independently disabled.
20406
20407 &*Warning*&: If &':blackhole:'& appears anywhere in a redirection list, no
20408 delivery is done for the original local part, even if other redirection items
20409 are present. If you are generating a multi-item list (for example, by reading a
20410 database) and need the ability to provide a no-op item, you must use
20411 &_/dev/null_&.
20412
20413 .next
20414 .cindex "delivery" "forcing failure"
20415 .cindex "delivery" "forcing deferral"
20416 .cindex "failing delivery" "forcing"
20417 .cindex "deferred delivery, forcing"
20418 .cindex "customizing" "failure message"
20419 An attempt to deliver a particular address can be deferred or forced to fail by
20420 redirection items of the form
20421 .code
20422 :defer:
20423 :fail:
20424 .endd
20425 respectively. When a redirection list contains such an item, it applies
20426 to the entire redirection; any other items in the list are ignored. Any
20427 text following &':fail:'& or &':defer:'& is placed in the error text
20428 associated with the failure. For example, an alias file might contain:
20429 .code
20430 X.Employee:  :fail: Gone away, no forwarding address
20431 .endd
20432 In the case of an address that is being verified from an ACL or as the subject
20433 of a
20434 .cindex "VRFY" "error text, display of"
20435 VRFY command, the text is included in the SMTP error response by
20436 default.
20437 .cindex "EXPN" "error text, display of"
20438 The text is not included in the response to an EXPN command. In non-SMTP cases
20439 the text is included in the error message that Exim generates.
20440
20441 .cindex "SMTP" "error codes"
20442 By default, Exim sends a 451 SMTP code for a &':defer:'&, and 550 for
20443 &':fail:'&. However, if the message starts with three digits followed by a
20444 space, optionally followed by an extended code of the form &'n.n.n'&, also
20445 followed by a space, and the very first digit is the same as the default error
20446 code, the code from the message is used instead. If the very first digit is
20447 incorrect, a panic error is logged, and the default code is used. You can
20448 suppress the use of the supplied code in a redirect router by setting the
20449 &%forbid_smtp_code%& option true. In this case, any SMTP code is quietly
20450 ignored.
20451
20452 .vindex "&$acl_verify_message$&"
20453 In an ACL, an explicitly provided message overrides the default, but the
20454 default message is available in the variable &$acl_verify_message$& and can
20455 therefore be included in a custom message if this is desired.
20456
20457 Normally the error text is the rest of the redirection list &-- a comma does
20458 not terminate it &-- but a newline does act as a terminator. Newlines are not
20459 normally present in alias expansions. In &(lsearch)& lookups they are removed
20460 as part of the continuation process, but they may exist in other kinds of
20461 lookup and in &':include:'& files.
20462
20463 During routing for message delivery (as opposed to verification), a redirection
20464 containing &':fail:'& causes an immediate failure of the incoming address,
20465 whereas &':defer:'& causes the message to remain on the queue so that a
20466 subsequent delivery attempt can happen at a later time. If an address is
20467 deferred for too long, it will ultimately fail, because the normal retry
20468 rules still apply.
20469
20470 .next
20471 .cindex "alias file" "exception to default"
20472 Sometimes it is useful to use a single-key search type with a default (see
20473 chapter &<<CHAPfdlookup>>&) to look up aliases. However, there may be a need
20474 for exceptions to the default. These can be handled by aliasing them to
20475 &':unknown:'&. This differs from &':fail:'& in that it causes the &(redirect)&
20476 router to decline, whereas &':fail:'& forces routing to fail. A lookup which
20477 results in an empty redirection list has the same effect.
20478 .endlist
20479
20480
20481 .section "Duplicate addresses" "SECTdupaddr"
20482 .cindex "duplicate addresses"
20483 .cindex "address duplicate, discarding"
20484 .cindex "pipe" "duplicated"
20485 Exim removes duplicate addresses from the list to which it is delivering, so as
20486 to deliver just one copy to each address. This does not apply to deliveries
20487 routed to pipes by different immediate parent addresses, but an indirect
20488 aliasing scheme of the type
20489 .code
20490 pipe:       |/some/command $local_part
20491 localpart1: pipe
20492 localpart2: pipe
20493 .endd
20494 does not work with a message that is addressed to both local parts, because
20495 when the second is aliased to the intermediate local part &"pipe"& it gets
20496 discarded as being the same as a previously handled address. However, a scheme
20497 such as
20498 .code
20499 localpart1: |/some/command $local_part
20500 localpart2: |/some/command $local_part
20501 .endd
20502 does result in two different pipe deliveries, because the immediate parents of
20503 the pipes are distinct.
20504
20505
20506
20507 .section "Repeated redirection expansion" "SECID128"
20508 .cindex "repeated redirection expansion"
20509 .cindex "address redirection" "repeated for each delivery attempt"
20510 When a message cannot be delivered to all of its recipients immediately,
20511 leading to two or more delivery attempts, redirection expansion is carried out
20512 afresh each time for those addresses whose children were not all previously
20513 delivered. If redirection is being used as a mailing list, this can lead to new
20514 members of the list receiving copies of old messages. The &%one_time%& option
20515 can be used to avoid this.
20516
20517
20518 .section "Errors in redirection lists" "SECID129"
20519 .cindex "address redirection" "errors"
20520 If &%skip_syntax_errors%& is set, a malformed address that causes a parsing
20521 error is skipped, and an entry is written to the main log. This may be useful
20522 for mailing lists that are automatically managed. Otherwise, if an error is
20523 detected while generating the list of new addresses, the original address is
20524 deferred. See also &%syntax_errors_to%&.
20525
20526
20527
20528 .section "Private options for the redirect router" "SECID130"
20529
20530 .cindex "options" "&(redirect)& router"
20531 The private options for the &(redirect)& router are as follows:
20532
20533
20534 .option allow_defer redirect boolean false
20535 Setting this option allows the use of &':defer:'& in non-filter redirection
20536 data, or the &%defer%& command in an Exim filter file.
20537
20538
20539 .option allow_fail redirect boolean false
20540 .cindex "failing delivery" "from filter"
20541 If this option is true, the &':fail:'& item can be used in a redirection list,
20542 and the &%fail%& command may be used in an Exim filter file.
20543
20544
20545 .option allow_filter redirect boolean false
20546 .cindex "filter" "enabling use of"
20547 .cindex "Sieve filter" "enabling use of"
20548 Setting this option allows Exim to interpret redirection data that starts with
20549 &"#Exim filter"& or &"#Sieve filter"& as a set of filtering instructions. There
20550 are some features of Exim filter files that some administrators may wish to
20551 lock out; see the &%forbid_filter_%&&'xxx'& options below.
20552
20553 It is also possible to lock out Exim filters or Sieve filters while allowing
20554 the other type; see &%forbid_exim_filter%& and &%forbid_sieve_filter%&.
20555
20556
20557 The filter is run using the uid and gid set by the generic &%user%& and
20558 &%group%& options. These take their defaults from the password data if
20559 &%check_local_user%& is set, so in the normal case of users' personal filter
20560 files, the filter is run as the relevant user. When &%allow_filter%& is set
20561 true, Exim insists that either &%check_local_user%& or &%user%& is set.
20562
20563
20564
20565 .option allow_freeze redirect boolean false
20566 .cindex "freezing messages" "allowing in filter"
20567 Setting this option allows the use of the &%freeze%& command in an Exim filter.
20568 This command is more normally encountered in system filters, and is disabled by
20569 default for redirection filters because it isn't something you usually want to
20570 let ordinary users do.
20571
20572
20573
20574 .option check_ancestor redirect boolean false
20575 This option is concerned with handling generated addresses that are the same
20576 as some address in the list of redirection ancestors of the current address.
20577 Although it is turned off by default in the code, it is set in the default
20578 configuration file for handling users' &_.forward_& files. It is recommended
20579 for this use of the &(redirect)& router.
20580
20581 When &%check_ancestor%& is set, if a generated address (including the domain)
20582 is the same as any ancestor of the current address, it is replaced by a copy of
20583 the current address. This helps in the case where local part A is aliased to B,
20584 and B has a &_.forward_& file pointing back to A. For example, within a single
20585 domain, the local part &"Joe.Bloggs"& is aliased to &"jb"& and
20586 &_&~jb/.forward_& contains:
20587 .code
20588 \Joe.Bloggs, <other item(s)>
20589 .endd
20590 Without the &%check_ancestor%& setting, either local part (&"jb"& or
20591 &"joe.bloggs"&) gets processed once by each router and so ends up as it was
20592 originally. If &"jb"& is the real mailbox name, mail to &"jb"& gets delivered
20593 (having been turned into &"joe.bloggs"& by the &_.forward_& file and back to
20594 &"jb"& by the alias), but mail to &"joe.bloggs"& fails. Setting
20595 &%check_ancestor%& on the &(redirect)& router that handles the &_.forward_&
20596 file prevents it from turning &"jb"& back into &"joe.bloggs"& when that was the
20597 original address. See also the &%repeat_use%& option below.
20598
20599
20600 .option check_group redirect boolean "see below"
20601 When the &%file%& option is used, the group owner of the file is checked only
20602 when this option is set. The permitted groups are those listed in the
20603 &%owngroups%& option, together with the user's default group if
20604 &%check_local_user%& is set. If the file has the wrong group, routing is
20605 deferred. The default setting for this option is true if &%check_local_user%&
20606 is set and the &%modemask%& option permits the group write bit, or if the
20607 &%owngroups%& option is set. Otherwise it is false, and no group check occurs.
20608
20609
20610
20611 .option check_owner redirect boolean "see below"
20612 When the &%file%& option is used, the owner of the file is checked only when
20613 this option is set. If &%check_local_user%& is set, the local user is
20614 permitted; otherwise the owner must be one of those listed in the &%owners%&
20615 option. The default value for this option is true if &%check_local_user%& or
20616 &%owners%& is set. Otherwise the default is false, and no owner check occurs.
20617
20618
20619 .option data redirect string&!! unset
20620 This option is mutually exclusive with &%file%&. One or other of them must be
20621 set, but not both. The contents of &%data%& are expanded, and then used as the
20622 list of forwarding items, or as a set of filtering instructions. If the
20623 expansion is forced to fail, or the result is an empty string or a string that
20624 has no effect (consists entirely of comments), the router declines.
20625
20626 When filtering instructions are used, the string must begin with &"#Exim
20627 filter"&, and all comments in the string, including this initial one, must be
20628 terminated with newline characters. For example:
20629 .code
20630 data = #Exim filter\n\
20631        if $h_to: contains Exim then save $home/mail/exim endif
20632 .endd
20633 If you are reading the data from a database where newlines cannot be included,
20634 you can use the &${sg}$& expansion item to turn the escape string of your
20635 choice into a newline.
20636
20637
20638 .option directory_transport redirect string&!! unset
20639 A &(redirect)& router sets up a direct delivery to a directory when a path name
20640 ending with a slash is specified as a new &"address"&. The transport used is
20641 specified by this option, which, after expansion, must be the name of a
20642 configured transport. This should normally be an &(appendfile)& transport.
20643
20644
20645 .option file redirect string&!! unset
20646 This option specifies the name of a file that contains the redirection data. It
20647 is mutually exclusive with the &%data%& option. The string is expanded before
20648 use; if the expansion is forced to fail, the router declines. Other expansion
20649 failures cause delivery to be deferred. The result of a successful expansion
20650 must be an absolute path. The entire file is read and used as the redirection
20651 data. If the data is an empty string or a string that has no effect (consists
20652 entirely of comments), the router declines.
20653
20654 .cindex "NFS" "checking for file existence"
20655 If the attempt to open the file fails with a &"does not exist"& error, Exim
20656 runs a check on the containing directory,
20657 unless &%ignore_enotdir%& is true (see below).
20658 If the directory does not appear to exist, delivery is deferred. This can
20659 happen when users' &_.forward_& files are in NFS-mounted directories, and there
20660 is a mount problem. If the containing directory does exist, but the file does
20661 not, the router declines.
20662
20663
20664 .option file_transport redirect string&!! unset
20665 .vindex "&$address_file$&"
20666 A &(redirect)& router sets up a direct delivery to a file when a path name not
20667 ending in a slash is specified as a new &"address"&. The transport used is
20668 specified by this option, which, after expansion, must be the name of a
20669 configured transport. This should normally be an &(appendfile)& transport. When
20670 it is running, the file name is in &$address_file$&.
20671
20672
20673 .option filter_prepend_home redirect boolean true
20674 When this option is true, if a &(save)& command in an Exim filter specifies a
20675 relative path, and &$home$& is defined, it is automatically prepended to the
20676 relative path. If this option is set false, this action does not happen. The
20677 relative path is then passed to the transport unmodified.
20678
20679
20680 .option forbid_blackhole redirect boolean false
20681 .cindex "restricting access to features"
20682 .cindex "filter" "locking out certain features"
20683 If this option is true, the &':blackhole:'& item may not appear in a
20684 redirection list.
20685
20686
20687 .option forbid_exim_filter redirect boolean false
20688 .cindex "restricting access to features"
20689 .cindex "filter" "locking out certain features"
20690 If this option is set true, only Sieve filters are permitted when
20691 &%allow_filter%& is true.
20692
20693
20694
20695
20696 .option forbid_file redirect boolean false
20697 .cindex "restricting access to features"
20698 .cindex "delivery" "to file; forbidding"
20699 .cindex "filter" "locking out certain features"
20700 .cindex "Sieve filter" "forbidding delivery to a file"
20701 .cindex "Sieve filter" "&""keep""& facility; disabling"
20702 If this option is true, this router may not generate a new address that
20703 specifies delivery to a local file or directory, either from a filter or from a
20704 conventional forward file. This option is forced to be true if &%one_time%& is
20705 set. It applies to Sieve filters as well as to Exim filters, but if true, it
20706 locks out the Sieve's &"keep"& facility.
20707
20708
20709 .option forbid_filter_dlfunc redirect boolean false
20710 .cindex "restricting access to features"
20711 .cindex "filter" "locking out certain features"
20712 If this option is true, string expansions in Exim filters are not allowed to
20713 make use of the &%dlfunc%& expansion facility to run dynamically loaded
20714 functions.
20715
20716 .option forbid_filter_existstest redirect boolean false
20717 .cindex "restricting access to features"
20718 .cindex "filter" "locking out certain features"
20719 .cindex "expansion" "statting a file"
20720 If this option is true, string expansions in Exim filters are not allowed to
20721 make use of the &%exists%& condition or the &%stat%& expansion item.
20722
20723 .option forbid_filter_logwrite redirect boolean false
20724 .cindex "restricting access to features"
20725 .cindex "filter" "locking out certain features"
20726 If this option is true, use of the logging facility in Exim filters is not
20727 permitted. Logging is in any case available only if the filter is being run
20728 under some unprivileged uid (which is normally the case for ordinary users'
20729 &_.forward_& files).
20730
20731
20732 .option forbid_filter_lookup redirect boolean false
20733 .cindex "restricting access to features"
20734 .cindex "filter" "locking out certain features"
20735 If this option is true, string expansions in Exim filter files are not allowed
20736 to make use of &%lookup%& items.
20737
20738
20739 .option forbid_filter_perl redirect boolean false
20740 .cindex "restricting access to features"
20741 .cindex "filter" "locking out certain features"
20742 This option has an effect only if Exim is built with embedded Perl support. If
20743 it is true, string expansions in Exim filter files are not allowed to make use
20744 of the embedded Perl support.
20745
20746
20747 .option forbid_filter_readfile redirect boolean false
20748 .cindex "restricting access to features"
20749 .cindex "filter" "locking out certain features"
20750 If this option is true, string expansions in Exim filter files are not allowed
20751 to make use of &%readfile%& items.
20752
20753
20754 .option forbid_filter_readsocket redirect boolean false
20755 .cindex "restricting access to features"
20756 .cindex "filter" "locking out certain features"
20757 If this option is true, string expansions in Exim filter files are not allowed
20758 to make use of &%readsocket%& items.
20759
20760
20761 .option forbid_filter_reply redirect boolean false
20762 .cindex "restricting access to features"
20763 .cindex "filter" "locking out certain features"
20764 If this option is true, this router may not generate an automatic reply
20765 message. Automatic replies can be generated only from Exim or Sieve filter
20766 files, not from traditional forward files. This option is forced to be true if
20767 &%one_time%& is set.
20768
20769
20770 .option forbid_filter_run redirect boolean false
20771 .cindex "restricting access to features"
20772 .cindex "filter" "locking out certain features"
20773 If this option is true, string expansions in Exim filter files are not allowed
20774 to make use of &%run%& items.
20775
20776
20777 .option forbid_include redirect boolean false
20778 .cindex "restricting access to features"
20779 .cindex "filter" "locking out certain features"
20780 If this option is true, items of the form
20781 .code
20782 :include:<path name>
20783 .endd
20784 are not permitted in non-filter redirection lists.
20785
20786
20787 .option forbid_pipe redirect boolean false
20788 .cindex "restricting access to features"
20789 .cindex "filter" "locking out certain features"
20790 .cindex "delivery" "to pipe; forbidding"
20791 If this option is true, this router may not generate a new address which
20792 specifies delivery to a pipe, either from an Exim filter or from a conventional
20793 forward file. This option is forced to be true if &%one_time%& is set.
20794
20795
20796 .option forbid_sieve_filter redirect boolean false
20797 .cindex "restricting access to features"
20798 .cindex "filter" "locking out certain features"
20799 If this option is set true, only Exim filters are permitted when
20800 &%allow_filter%& is true.
20801
20802
20803 .cindex "SMTP" "error codes"
20804 .option forbid_smtp_code redirect boolean false
20805 If this option is set true, any SMTP error codes that are present at the start
20806 of messages specified for &`:defer:`& or &`:fail:`& are quietly ignored, and
20807 the default codes (451 and 550, respectively) are always used.
20808
20809
20810
20811
20812 .option hide_child_in_errmsg redirect boolean false
20813 .cindex "bounce message" "redirection details; suppressing"
20814 If this option is true, it prevents Exim from quoting a child address if it
20815 generates a bounce or delay message for it. Instead it says &"an address
20816 generated from <&'the top level address'&>"&. Of course, this applies only to
20817 bounces generated locally. If a message is forwarded to another host, &'its'&
20818 bounce may well quote the generated address.
20819
20820
20821 .option ignore_eacces redirect boolean false
20822 .cindex "EACCES"
20823 If this option is set and an attempt to open a redirection file yields the
20824 EACCES error (permission denied), the &(redirect)& router behaves as if the
20825 file did not exist.
20826
20827
20828 .option ignore_enotdir redirect boolean false
20829 .cindex "ENOTDIR"
20830 If this option is set and an attempt to open a redirection file yields the
20831 ENOTDIR error (something on the path is not a directory), the &(redirect)&
20832 router behaves as if the file did not exist.
20833
20834 Setting &%ignore_enotdir%& has another effect as well: When a &(redirect)&
20835 router that has the &%file%& option set discovers that the file does not exist
20836 (the ENOENT error), it tries to &[stat()]& the parent directory, as a check
20837 against unmounted NFS directories. If the parent can not be statted, delivery
20838 is deferred. However, it seems wrong to do this check when &%ignore_enotdir%&
20839 is set, because that option tells Exim to ignore &"something on the path is not
20840 a directory"& (the ENOTDIR error). This is a confusing area, because it seems
20841 that some operating systems give ENOENT where others give ENOTDIR.
20842
20843
20844
20845 .option include_directory redirect string unset
20846 If this option is set, the path names of any &':include:'& items in a
20847 redirection list must start with this directory.
20848
20849
20850 .option modemask redirect "octal integer" 022
20851 This specifies mode bits which must not be set for a file specified by the
20852 &%file%& option. If any of the forbidden bits are set, delivery is deferred.
20853
20854
20855 .option one_time redirect boolean false
20856 .cindex "one-time aliasing/forwarding expansion"
20857 .cindex "alias file" "one-time expansion"
20858 .cindex "forward file" "one-time expansion"
20859 .cindex "mailing lists" "one-time expansion"
20860 .cindex "address redirection" "one-time expansion"
20861 Sometimes the fact that Exim re-evaluates aliases and reprocesses redirection
20862 files each time it tries to deliver a message causes a problem when one or more
20863 of the generated addresses fails be delivered at the first attempt. The problem
20864 is not one of duplicate delivery &-- Exim is clever enough to handle that &--
20865 but of what happens when the redirection list changes during the time that the
20866 message is on Exim's queue. This is particularly true in the case of mailing
20867 lists, where new subscribers might receive copies of messages that were posted
20868 before they subscribed.
20869
20870 If &%one_time%& is set and any addresses generated by the router fail to
20871 deliver at the first attempt, the failing addresses are added to the message as
20872 &"top level"& addresses, and the parent address that generated them is marked
20873 &"delivered"&. Thus, redirection does not happen again at the next delivery
20874 attempt.
20875
20876 &*Warning 1*&: Any header line addition or removal that is specified by this
20877 router would be lost if delivery did not succeed at the first attempt. For this
20878 reason, the &%headers_add%& and &%headers_remove%& generic options are not
20879 permitted when &%one_time%& is set.
20880
20881 &*Warning 2*&: To ensure that the router generates only addresses (as opposed
20882 to pipe or file deliveries or auto-replies) &%forbid_file%&, &%forbid_pipe%&,
20883 and &%forbid_filter_reply%& are forced to be true when &%one_time%& is set.
20884
20885 &*Warning 3*&: The &%unseen%& generic router option may not be set with
20886 &%one_time%&.
20887
20888 The original top-level address is remembered with each of the generated
20889 addresses, and is output in any log messages. However, any intermediate parent
20890 addresses are not recorded. This makes a difference to the log only if
20891 &%all_parents%& log selector is set. It is expected that &%one_time%& will
20892 typically be used for mailing lists, where there is normally just one level of
20893 expansion.
20894
20895
20896 .option owners redirect "string list" unset
20897 .cindex "ownership" "alias file"
20898 .cindex "ownership" "forward file"
20899 .cindex "alias file" "ownership"
20900 .cindex "forward file" "ownership"
20901 This specifies a list of permitted owners for the file specified by &%file%&.
20902 This list is in addition to the local user when &%check_local_user%& is set.
20903 See &%check_owner%& above.
20904
20905
20906 .option owngroups redirect "string list" unset
20907 This specifies a list of permitted groups for the file specified by &%file%&.
20908 The list is in addition to the local user's primary group when
20909 &%check_local_user%& is set. See &%check_group%& above.
20910
20911
20912 .option pipe_transport redirect string&!! unset
20913 .vindex "&$address_pipe$&"
20914 A &(redirect)& router sets up a direct delivery to a pipe when a string
20915 starting with a vertical bar character is specified as a new &"address"&. The
20916 transport used is specified by this option, which, after expansion, must be the
20917 name of a configured transport. This should normally be a &(pipe)& transport.
20918 When the transport is run, the pipe command is in &$address_pipe$&.
20919
20920
20921 .option qualify_domain redirect string&!! unset
20922 .vindex "&$qualify_recipient$&"
20923 If this option is set, and an unqualified address (one without a domain) is
20924 generated, and that address would normally be qualified by the global setting
20925 in &%qualify_recipient%&, it is instead qualified with the domain specified by
20926 expanding this string. If the expansion fails, the router declines. If you want
20927 to revert to the default, you can have the expansion generate
20928 &$qualify_recipient$&.
20929
20930 This option applies to all unqualified addresses generated by Exim filters,
20931 but for traditional &_.forward_& files, it applies only to addresses that are
20932 not preceded by a backslash. Sieve filters cannot generate unqualified
20933 addresses.
20934
20935 .option qualify_preserve_domain redirect boolean false
20936 .cindex "domain" "in redirection; preserving"
20937 .cindex "preserving domain in redirection"
20938 .cindex "address redirection" "domain; preserving"
20939 If this option is set, the router's local &%qualify_domain%& option must not be
20940 set (a configuration error occurs if it is). If an unqualified address (one
20941 without a domain) is generated, it is qualified with the domain of the parent
20942 address (the immediately preceding ancestor) instead of the global
20943 &%qualify_recipient%& value. In the case of a traditional &_.forward_& file,
20944 this applies whether or not the address is preceded by a backslash.
20945
20946
20947 .option repeat_use redirect boolean true
20948 If this option is set false, the router is skipped for a child address that has
20949 any ancestor that was routed by this router. This test happens before any of
20950 the other preconditions are tested. Exim's default anti-looping rules skip
20951 only when the ancestor is the same as the current address. See also
20952 &%check_ancestor%& above and the generic &%redirect_router%& option.
20953
20954
20955 .option reply_transport redirect string&!! unset
20956 A &(redirect)& router sets up an automatic reply when a &%mail%& or
20957 &%vacation%& command is used in a filter file. The transport used is specified
20958 by this option, which, after expansion, must be the name of a configured
20959 transport. This should normally be an &(autoreply)& transport. Other transports
20960 are unlikely to do anything sensible or useful.
20961
20962
20963 .option rewrite redirect boolean true
20964 .cindex "address redirection" "disabling rewriting"
20965 If this option is set false, addresses generated by the router are not
20966 subject to address rewriting. Otherwise, they are treated like new addresses
20967 and are rewritten according to the global rewriting rules.
20968
20969
20970 .option sieve_subaddress redirect string&!! unset
20971 The value of this option is passed to a Sieve filter to specify the
20972 :subaddress part of an address.
20973
20974 .option sieve_useraddress redirect string&!! unset
20975 The value of this option is passed to a Sieve filter to specify the :user part
20976 of an address. However, if it is unset, the entire original local part
20977 (including any prefix or suffix) is used for :user.
20978
20979
20980 .option sieve_vacation_directory redirect string&!! unset
20981 .cindex "Sieve filter" "vacation directory"
20982 To enable the &"vacation"& extension for Sieve filters, you must set
20983 &%sieve_vacation_directory%& to the directory where vacation databases are held
20984 (do not put anything else in that directory), and ensure that the
20985 &%reply_transport%& option refers to an &(autoreply)& transport. Each user
20986 needs their own directory; Exim will create it if necessary.
20987
20988
20989
20990 .option skip_syntax_errors redirect boolean false
20991 .cindex "forward file" "broken"
20992 .cindex "address redirection" "broken files"
20993 .cindex "alias file" "broken"
20994 .cindex "broken alias or forward files"
20995 .cindex "ignoring faulty addresses"
20996 .cindex "skipping faulty addresses"
20997 .cindex "error" "skipping bad syntax"
20998 If &%skip_syntax_errors%& is set, syntactically malformed addresses in
20999 non-filter redirection data are skipped, and each failing address is logged. If
21000 &%syntax_errors_to%& is set, a message is sent to the address it defines,
21001 giving details of the failures. If &%syntax_errors_text%& is set, its contents
21002 are expanded and placed at the head of the error message generated by
21003 &%syntax_errors_to%&. Usually it is appropriate to set &%syntax_errors_to%& to
21004 be the same address as the generic &%errors_to%& option. The
21005 &%skip_syntax_errors%& option is often used when handling mailing lists.
21006
21007 If all the addresses in a redirection list are skipped because of syntax
21008 errors, the router declines to handle the original address, and it is passed to
21009 the following routers.
21010
21011 If &%skip_syntax_errors%& is set when an Exim filter is interpreted, any syntax
21012 error in the filter causes filtering to be abandoned without any action being
21013 taken. The incident is logged, and the router declines to handle the address,
21014 so it is passed to the following routers.
21015
21016 .cindex "Sieve filter" "syntax errors in"
21017 Syntax errors in a Sieve filter file cause the &"keep"& action to occur. This
21018 action is specified by RFC 3028. The values of &%skip_syntax_errors%&,
21019 &%syntax_errors_to%&, and &%syntax_errors_text%& are not used.
21020
21021 &%skip_syntax_errors%& can be used to specify that errors in users' forward
21022 lists or filter files should not prevent delivery. The &%syntax_errors_to%&
21023 option, used with an address that does not get redirected, can be used to
21024 notify users of these errors, by means of a router like this:
21025 .code
21026 userforward:
21027   driver = redirect
21028   allow_filter
21029   check_local_user
21030   file = $home/.forward
21031   file_transport = address_file
21032   pipe_transport = address_pipe
21033   reply_transport = address_reply
21034   no_verify
21035   skip_syntax_errors
21036   syntax_errors_to = real-$local_part@$domain
21037   syntax_errors_text = \
21038    This is an automatically generated message. An error has\n\
21039    been found in your .forward file. Details of the error are\n\
21040    reported below. While this error persists, you will receive\n\
21041    a copy of this message for every message that is addressed\n\
21042    to you. If your .forward file is a filter file, or if it is\n\
21043    a non-filter file containing no valid forwarding addresses,\n\
21044    a copy of each incoming message will be put in your normal\n\
21045    mailbox. If a non-filter file contains at least one valid\n\
21046    forwarding address, forwarding to the valid addresses will\n\
21047    happen, and those will be the only deliveries that occur.
21048 .endd
21049 You also need a router to ensure that local addresses that are prefixed by
21050 &`real-`& are recognized, but not forwarded or filtered. For example, you could
21051 put this immediately before the &(userforward)& router:
21052 .code
21053 real_localuser:
21054   driver = accept
21055   check_local_user
21056   local_part_prefix = real-
21057   transport = local_delivery
21058 .endd
21059 For security, it would probably be a good idea to restrict the use of this
21060 router to locally-generated messages, using a condition such as this:
21061 .code
21062   condition = ${if match {$sender_host_address}\
21063                          {\N^(|127\.0\.0\.1)$\N}}
21064 .endd
21065
21066
21067 .option syntax_errors_text redirect string&!! unset
21068 See &%skip_syntax_errors%& above.
21069
21070
21071 .option syntax_errors_to redirect string unset
21072 See &%skip_syntax_errors%& above.
21073 .ecindex IIDredrou1
21074 .ecindex IIDredrou2
21075
21076
21077
21078
21079
21080
21081 . ////////////////////////////////////////////////////////////////////////////
21082 . ////////////////////////////////////////////////////////////////////////////
21083
21084 .chapter "Environment for running local transports" "CHAPenvironment" &&&
21085          "Environment for local transports"
21086 .scindex IIDenvlotra1 "local transports" "environment for"
21087 .scindex IIDenvlotra2 "environment" "local transports"
21088 .scindex IIDenvlotra3 "transport" "local; environment for"
21089 Local transports handle deliveries to files and pipes. (The &(autoreply)&
21090 transport can be thought of as similar to a pipe.) Exim always runs transports
21091 in subprocesses, under specified uids and gids. Typical deliveries to local
21092 mailboxes run under the uid and gid of the local user.
21093
21094 Exim also sets a specific current directory while running the transport; for
21095 some transports a home directory setting is also relevant. The &(pipe)&
21096 transport is the only one that sets up environment variables; see section
21097 &<<SECTpipeenv>>& for details.
21098
21099 The values used for the uid, gid, and the directories may come from several
21100 different places. In many cases, the router that handles the address associates
21101 settings with that address as a result of its &%check_local_user%&, &%group%&,
21102 or &%user%& options. However, values may also be given in the transport's own
21103 configuration, and these override anything that comes from the router.
21104
21105
21106
21107 .section "Concurrent deliveries" "SECID131"
21108 .cindex "concurrent deliveries"
21109 .cindex "simultaneous deliveries"
21110 If two different messages for the same local recipient arrive more or less
21111 simultaneously, the two delivery processes are likely to run concurrently. When
21112 the &(appendfile)& transport is used to write to a file, Exim applies locking
21113 rules to stop concurrent processes from writing to the same file at the same
21114 time.
21115
21116 However, when you use a &(pipe)& transport, it is up to you to arrange any
21117 locking that is needed. Here is a silly example:
21118 .code
21119 my_transport:
21120   driver = pipe
21121   command = /bin/sh -c 'cat >>/some/file'
21122 .endd
21123 This is supposed to write the message at the end of the file. However, if two
21124 messages arrive at the same time, the file will be scrambled. You can use the
21125 &%exim_lock%& utility program (see section &<<SECTmailboxmaint>>&) to lock a
21126 file using the same algorithm that Exim itself uses.
21127
21128
21129
21130
21131 .section "Uids and gids" "SECTenvuidgid"
21132 .cindex "local transports" "uid and gid"
21133 .cindex "transport" "local; uid and gid"
21134 All transports have the options &%group%& and &%user%&. If &%group%& is set, it
21135 overrides any group that the router set in the address, even if &%user%& is not
21136 set for the transport. This makes it possible, for example, to run local mail
21137 delivery under the uid of the recipient (set by the router), but in a special
21138 group (set by the transport). For example:
21139 .code
21140 # Routers ...
21141 # User/group are set by check_local_user in this router
21142 local_users:
21143   driver = accept
21144   check_local_user
21145   transport = group_delivery
21146
21147 # Transports ...
21148 # This transport overrides the group
21149 group_delivery:
21150   driver = appendfile
21151   file = /var/spool/mail/$local_part
21152   group = mail
21153 .endd
21154 If &%user%& is set for a transport, its value overrides what is set in the
21155 address by the router. If &%user%& is non-numeric and &%group%& is not set, the
21156 gid associated with the user is used. If &%user%& is numeric, &%group%& must be
21157 set.
21158
21159 .oindex "&%initgroups%&"
21160 When the uid is taken from the transport's configuration, the &[initgroups()]&
21161 function is called for the groups associated with that uid if the
21162 &%initgroups%& option is set for the transport. When the uid is not specified
21163 by the transport, but is associated with the address by a router, the option
21164 for calling &[initgroups()]& is taken from the router configuration.
21165
21166 .cindex "&(pipe)& transport" "uid for"
21167 The &(pipe)& transport contains the special option &%pipe_as_creator%&. If this
21168 is set and &%user%& is not set, the uid of the process that called Exim to
21169 receive the message is used, and if &%group%& is not set, the corresponding
21170 original gid is also used.
21171
21172 This is the detailed preference order for obtaining a gid; the first of the
21173 following that is set is used:
21174
21175 .ilist
21176 A &%group%& setting of the transport;
21177 .next
21178 A &%group%& setting of the router;
21179 .next
21180 A gid associated with a user setting of the router, either as a result of
21181 &%check_local_user%& or an explicit non-numeric &%user%& setting;
21182 .next
21183 The group associated with a non-numeric &%user%& setting of the transport;
21184 .next
21185 In a &(pipe)& transport, the creator's gid if &%deliver_as_creator%& is set and
21186 the uid is the creator's uid;
21187 .next
21188 The Exim gid if the Exim uid is being used as a default.
21189 .endlist
21190
21191 If, for example, the user is specified numerically on the router and there are
21192 no group settings, no gid is available. In this situation, an error occurs.
21193 This is different for the uid, for which there always is an ultimate default.
21194 The first of the following that is set is used:
21195
21196 .ilist
21197 A &%user%& setting of the transport;
21198 .next
21199 In a &(pipe)& transport, the creator's uid if &%deliver_as_creator%& is set;
21200 .next
21201 A &%user%& setting of the router;
21202 .next
21203 A &%check_local_user%& setting of the router;
21204 .next
21205 The Exim uid.
21206 .endlist
21207
21208 Of course, an error will still occur if the uid that is chosen is on the
21209 &%never_users%& list.
21210
21211
21212
21213
21214
21215 .section "Current and home directories" "SECID132"
21216 .cindex "current directory for local transport"
21217 .cindex "home directory" "for local transport"
21218 .cindex "transport" "local; home directory for"
21219 .cindex "transport" "local; current directory for"
21220 Routers may set current and home directories for local transports by means of
21221 the &%transport_current_directory%& and &%transport_home_directory%& options.
21222 However, if the transport's &%current_directory%& or &%home_directory%& options
21223 are set, they override the router's values. In detail, the home directory
21224 for a local transport is taken from the first of these values that is set:
21225
21226 .ilist
21227 The &%home_directory%& option on the transport;
21228 .next
21229 The &%transport_home_directory%& option on the router;
21230 .next
21231 The password data if &%check_local_user%& is set on the router;
21232 .next
21233 The &%router_home_directory%& option on the router.
21234 .endlist
21235
21236 The current directory is taken from the first of these values that is set:
21237
21238 .ilist
21239 The &%current_directory%& option on the transport;
21240 .next
21241 The &%transport_current_directory%& option on the router.
21242 .endlist
21243
21244
21245 If neither the router nor the transport sets a current directory, Exim uses the
21246 value of the home directory, if it is set. Otherwise it sets the current
21247 directory to &_/_& before running a local transport.
21248
21249
21250
21251 .section "Expansion variables derived from the address" "SECID133"
21252 .vindex "&$domain$&"
21253 .vindex "&$local_part$&"
21254 .vindex "&$original_domain$&"
21255 Normally a local delivery is handling a single address, and in that case the
21256 variables such as &$domain$& and &$local_part$& are set during local
21257 deliveries. However, in some circumstances more than one address may be handled
21258 at once (for example, while writing batch SMTP for onward transmission by some
21259 other means). In this case, the variables associated with the local part are
21260 never set, &$domain$& is set only if all the addresses have the same domain,
21261 and &$original_domain$& is never set.
21262 .ecindex IIDenvlotra1
21263 .ecindex IIDenvlotra2
21264 .ecindex IIDenvlotra3
21265
21266
21267
21268
21269
21270
21271
21272 . ////////////////////////////////////////////////////////////////////////////
21273 . ////////////////////////////////////////////////////////////////////////////
21274
21275 .chapter "Generic options for transports" "CHAPtransportgeneric"
21276 .scindex IIDgenoptra1 "generic options" "transport"
21277 .scindex IIDgenoptra2 "options" "generic; for transports"
21278 .scindex IIDgenoptra3 "transport" "generic options for"
21279 The following generic options apply to all transports:
21280
21281
21282 .option body_only transports boolean false
21283 .cindex "transport" "body only"
21284 .cindex "message" "transporting body only"
21285 .cindex "body of message" "transporting"
21286 If this option is set, the message's headers are not transported. It is
21287 mutually exclusive with &%headers_only%&. If it is used with the &(appendfile)&
21288 or &(pipe)& transports, the settings of &%message_prefix%& and
21289 &%message_suffix%& should be checked, because this option does not
21290 automatically suppress them.
21291
21292
21293 .option current_directory transports string&!! unset
21294 .cindex "transport" "current directory for"
21295 This specifies the current directory that is to be set while running the
21296 transport, overriding any value that may have been set by the router.
21297 If the expansion fails for any reason, including forced failure, an error is
21298 logged, and delivery is deferred.
21299
21300
21301 .option disable_logging transports boolean false
21302 If this option is set true, nothing is logged for any
21303 deliveries by the transport or for any
21304 transport errors. You should not set this option unless you really, really know
21305 what you are doing.
21306
21307
21308 .option debug_print transports string&!! unset
21309 .cindex "testing" "variables in drivers"
21310 If this option is set and debugging is enabled (see the &%-d%& command line
21311 option), the string is expanded and included in the debugging output when the
21312 transport is run.
21313 If expansion of the string fails, the error message is written to the debugging
21314 output, and Exim carries on processing.
21315 This facility is provided to help with checking out the values of variables and
21316 so on when debugging driver configurations. For example, if a &%headers_add%&
21317 option is not working properly, &%debug_print%& could be used to output the
21318 variables it references. A newline is added to the text if it does not end with
21319 one.
21320 The variables &$transport_name$& and &$router_name$& contain the name of the
21321 transport and the router that called it.
21322
21323 .option delivery_date_add transports boolean false
21324 .cindex "&'Delivery-date:'& header line"
21325 If this option is true, a &'Delivery-date:'& header is added to the message.
21326 This gives the actual time the delivery was made. As this is not a standard
21327 header, Exim has a configuration option (&%delivery_date_remove%&) which
21328 requests its removal from incoming messages, so that delivered messages can
21329 safely be resent to other recipients.
21330
21331
21332 .option driver transports string unset
21333 This specifies which of the available transport drivers is to be used.
21334 There is no default, and this option must be set for every transport.
21335
21336
21337 .option envelope_to_add transports boolean false
21338 .cindex "&'Envelope-to:'& header line"
21339 If this option is true, an &'Envelope-to:'& header is added to the message.
21340 This gives the original address(es) in the incoming envelope that caused this
21341 delivery to happen. More than one address may be present if the transport is
21342 configured to handle several addresses at once, or if more than one original
21343 address was redirected to the same final address. As this is not a standard
21344 header, Exim has a configuration option (&%envelope_to_remove%&) which requests
21345 its removal from incoming messages, so that delivered messages can safely be
21346 resent to other recipients.
21347
21348
21349 .option event_action transports string&!! unset
21350 .cindex events
21351 This option declares a string to be expanded for Exim's events mechanism.
21352 For details see chapter &<<CHAPevents>>&.
21353
21354
21355 .option group transports string&!! "Exim group"
21356 .cindex "transport" "group; specifying"
21357 This option specifies a gid for running the transport process, overriding any
21358 value that the router supplies, and also overriding any value associated with
21359 &%user%& (see below).
21360
21361
21362 .option headers_add transports list&!! unset
21363 .cindex "header lines" "adding in transport"
21364 .cindex "transport" "header lines; adding"
21365 This option specifies a list of text headers,
21366 newline-separated (by default, changeable in the usual way),
21367 which are (separately) expanded and added to the header
21368 portion of a message as it is transported, as described in section
21369 &<<SECTheadersaddrem>>&. Additional header lines can also be specified by
21370 routers. If the result of the expansion is an empty string, or if the expansion
21371 is forced to fail, no action is taken. Other expansion failures are treated as
21372 errors and cause the delivery to be deferred.
21373
21374 Unlike most options, &%headers_add%& can be specified multiple times
21375 for a transport; all listed headers are added.
21376
21377
21378 .option headers_only transports boolean false
21379 .cindex "transport" "header lines only"
21380 .cindex "message" "transporting headers only"
21381 .cindex "header lines" "transporting"
21382 If this option is set, the message's body is not transported. It is mutually
21383 exclusive with &%body_only%&. If it is used with the &(appendfile)& or &(pipe)&
21384 transports, the settings of &%message_prefix%& and &%message_suffix%& should be
21385 checked, since this option does not automatically suppress them.
21386
21387
21388 .option headers_remove transports list&!! unset
21389 .cindex "header lines" "removing"
21390 .cindex "transport" "header lines; removing"
21391 This option specifies a list of header names,
21392 colon-separated (by default, changeable in the usual way);
21393 these headers are omitted from the message as it is transported, as described
21394 in section &<<SECTheadersaddrem>>&. Header removal can also be specified by
21395 routers.
21396 Each list item is separately expanded.
21397 If the result of the expansion is an empty string, or if the expansion
21398 is forced to fail, no action is taken. Other expansion failures are treated as
21399 errors and cause the delivery to be deferred.
21400
21401 Unlike most options, &%headers_remove%& can be specified multiple times
21402 for a transport; all listed headers are removed.
21403
21404 &*Warning*&: Because of the separate expansion of the list items,
21405 items that contain a list separator must have it doubled.
21406 To avoid this, change the list separator (&<<SECTlistsepchange>>&).
21407
21408
21409
21410 .option headers_rewrite transports string unset
21411 .cindex "transport" "header lines; rewriting"
21412 .cindex "rewriting" "at transport time"
21413 This option allows addresses in header lines to be rewritten at transport time,
21414 that is, as the message is being copied to its destination. The contents of the
21415 option are a colon-separated list of rewriting rules. Each rule is in exactly
21416 the same form as one of the general rewriting rules that are applied when a
21417 message is received. These are described in chapter &<<CHAPrewrite>>&. For
21418 example,
21419 .code
21420 headers_rewrite = a@b c@d f : \
21421                   x@y w@z
21422 .endd
21423 changes &'a@b'& into &'c@d'& in &'From:'& header lines, and &'x@y'& into
21424 &'w@z'& in all address-bearing header lines. The rules are applied to the
21425 header lines just before they are written out at transport time, so they affect
21426 only those copies of the message that pass through the transport. However, only
21427 the message's original header lines, and any that were added by a system
21428 filter, are rewritten. If a router or transport adds header lines, they are not
21429 affected by this option. These rewriting rules are &'not'& applied to the
21430 envelope. You can change the return path using &%return_path%&, but you cannot
21431 change envelope recipients at this time.
21432
21433
21434 .option home_directory transports string&!! unset
21435 .cindex "transport" "home directory for"
21436 .vindex "&$home$&"
21437 This option specifies a home directory setting for a local transport,
21438 overriding any value that may be set by the router. The home directory is
21439 placed in &$home$& while expanding the transport's private options. It is also
21440 used as the current directory if no current directory is set by the
21441 &%current_directory%& option on the transport or the
21442 &%transport_current_directory%& option on the router. If the expansion fails
21443 for any reason, including forced failure, an error is logged, and delivery is
21444 deferred.
21445
21446
21447 .option initgroups transports boolean false
21448 .cindex "additional groups"
21449 .cindex "groups" "additional"
21450 .cindex "transport" "group; additional"
21451 If this option is true and the uid for the delivery process is provided by the
21452 transport, the &[initgroups()]& function is called when running the transport
21453 to ensure that any additional groups associated with the uid are set up.
21454
21455
21456 .option max_parallel transports integer&!! unset
21457 .cindex limit "transport parallelism"
21458 .cindex transport "parallel processes"
21459 .cindex transport "concurrency limit"
21460 .cindex "delivery" "parallelism for transport"
21461 If this option is set and expands to an integer greater than zero
21462 it limits the number of concurrent runs of the transport.
21463 The control does not apply to shadow transports.
21464
21465 .cindex "hints database" "transport concurrency control"
21466 Exim implements this control by means of a hints database in which a record is
21467 incremented whenever a transport process is being created. The record
21468 is decremented and possibly removed when the process terminates.
21469 Obviously there is scope for
21470 records to get left lying around if there is a system or program crash. To
21471 guard against this, Exim ignores any records that are more than six hours old.
21472
21473 If you use this option, you should also arrange to delete the
21474 relevant hints database whenever your system reboots. The names of the files
21475 start with &_misc_& and they are kept in the &_spool/db_& directory. There
21476 may be one or two files, depending on the type of DBM in use. The same files
21477 are used for ETRN and smtp transport serialization.
21478
21479
21480 .option message_size_limit transports string&!! 0
21481 .cindex "limit" "message size per transport"
21482 .cindex "size" "of message, limit"
21483 .cindex "transport" "message size; limiting"
21484 This option controls the size of messages passed through the transport. It is
21485 expanded before use; the result of the expansion must be a sequence of decimal
21486 digits, optionally followed by K or M. If the expansion fails for any reason,
21487 including forced failure, or if the result is not of the required form,
21488 delivery is deferred. If the value is greater than zero and the size of a
21489 message exceeds this limit, the address is failed. If there is any chance that
21490 the resulting bounce message could be routed to the same transport, you should
21491 ensure that &%return_size_limit%& is less than the transport's
21492 &%message_size_limit%&, as otherwise the bounce message will fail to get
21493 delivered.
21494
21495
21496
21497 .option rcpt_include_affixes transports boolean false
21498 .cindex "prefix" "for local part, including in envelope"
21499 .cindex "suffix for local part" "including in envelope"
21500 .cindex "local part" "prefix"
21501 .cindex "local part" "suffix"
21502 When this option is false (the default), and an address that has had any
21503 affixes (prefixes or suffixes) removed from the local part is delivered by any
21504 form of SMTP or LMTP, the affixes are not included. For example, if a router
21505 that contains
21506 .code
21507 local_part_prefix = *-
21508 .endd
21509 routes the address &'abc-xyz@some.domain'& to an SMTP transport, the envelope
21510 is delivered with
21511 .code
21512 RCPT TO:<xyz@some.domain>
21513 .endd
21514 This is also the case when an ACL-time callout is being used to verify a
21515 recipient address. However, if &%rcpt_include_affixes%& is set true, the
21516 whole local part is included in the RCPT command. This option applies to BSMTP
21517 deliveries by the &(appendfile)& and &(pipe)& transports as well as to the
21518 &(lmtp)& and &(smtp)& transports.
21519
21520
21521 .option retry_use_local_part transports boolean "see below"
21522 .cindex "hints database" "retry keys"
21523 When a delivery suffers a temporary failure, a retry record is created
21524 in Exim's hints database. For remote deliveries, the key for the retry record
21525 is based on the name and/or IP address of the failing remote host. For local
21526 deliveries, the key is normally the entire address, including both the local
21527 part and the domain. This is suitable for most common cases of local delivery
21528 temporary failure &-- for example, exceeding a mailbox quota should delay only
21529 deliveries to that mailbox, not to the whole domain.
21530
21531 However, in some special cases you may want to treat a temporary local delivery
21532 as a failure associated with the domain, and not with a particular local part.
21533 (For example, if you are storing all mail for some domain in files.) You can do
21534 this by setting &%retry_use_local_part%& false.
21535
21536 For all the local transports, its default value is true. For remote transports,
21537 the default value is false for tidiness, but changing the value has no effect
21538 on a remote transport in the current implementation.
21539
21540
21541 .option return_path transports string&!! unset
21542 .cindex "envelope sender"
21543 .cindex "transport" "return path; changing"
21544 .cindex "return path" "changing in transport"
21545 If this option is set, the string is expanded at transport time and replaces
21546 the existing return path (envelope sender) value in the copy of the message
21547 that is being delivered. An empty return path is permitted. This feature is
21548 designed for remote deliveries, where the value of this option is used in the
21549 SMTP MAIL command. If you set &%return_path%& for a local transport, the
21550 only effect is to change the address that is placed in the &'Return-path:'&
21551 header line, if one is added to the message (see the next option).
21552
21553 &*Note:*& A changed return path is not logged unless you add
21554 &%return_path_on_delivery%& to the log selector.
21555
21556 .vindex "&$return_path$&"
21557 The expansion can refer to the existing value via &$return_path$&. This is
21558 either the message's envelope sender, or an address set by the
21559 &%errors_to%& option on a router. If the expansion is forced to fail, no
21560 replacement occurs; if it fails for another reason, delivery is deferred. This
21561 option can be used to support VERP (Variable Envelope Return Paths) &-- see
21562 section &<<SECTverp>>&.
21563
21564 &*Note*&: If a delivery error is detected locally, including the case when a
21565 remote server rejects a message at SMTP time, the bounce message is not sent to
21566 the value of this option. It is sent to the previously set errors address.
21567 This defaults to the incoming sender address, but can be changed by setting
21568 &%errors_to%& in a router.
21569
21570
21571
21572 .option return_path_add transports boolean false
21573 .cindex "&'Return-path:'& header line"
21574 If this option is true, a &'Return-path:'& header is added to the message.
21575 Although the return path is normally available in the prefix line of BSD
21576 mailboxes, this is commonly not displayed by MUAs, and so the user does not
21577 have easy access to it.
21578
21579 RFC 2821 states that the &'Return-path:'& header is added to a message &"when
21580 the delivery SMTP server makes the final delivery"&. This implies that this
21581 header should not be present in incoming messages. Exim has a configuration
21582 option, &%return_path_remove%&, which requests removal of this header from
21583 incoming messages, so that delivered messages can safely be resent to other
21584 recipients.
21585
21586
21587 .option shadow_condition transports string&!! unset
21588 See &%shadow_transport%& below.
21589
21590
21591 .option shadow_transport transports string unset
21592 .cindex "shadow transport"
21593 .cindex "transport" "shadow"
21594 A local transport may set the &%shadow_transport%& option to the name of
21595 another local transport. Shadow remote transports are not supported.
21596
21597 Whenever a delivery to the main transport succeeds, and either
21598 &%shadow_condition%& is unset, or its expansion does not result in the empty
21599 string or one of the strings &"0"& or &"no"& or &"false"&, the message is also
21600 passed to the shadow transport, with the same delivery address or addresses. If
21601 expansion fails, no action is taken except that non-forced expansion failures
21602 cause a log line to be written.
21603
21604 The result of the shadow transport is discarded and does not affect the
21605 subsequent processing of the message. Only a single level of shadowing is
21606 provided; the &%shadow_transport%& option is ignored on any transport when it
21607 is running as a shadow. Options concerned with output from pipes are also
21608 ignored. The log line for the successful delivery has an item added on the end,
21609 of the form
21610 .code
21611 ST=<shadow transport name>
21612 .endd
21613 If the shadow transport did not succeed, the error message is put in
21614 parentheses afterwards. Shadow transports can be used for a number of different
21615 purposes, including keeping more detailed log information than Exim normally
21616 provides, and implementing automatic acknowledgment policies based on message
21617 headers that some sites insist on.
21618
21619
21620 .option transport_filter transports string&!! unset
21621 .cindex "transport" "filter"
21622 .cindex "filter" "transport filter"
21623 This option sets up a filtering (in the Unix shell sense) process for messages
21624 at transport time. It should not be confused with mail filtering as set up by
21625 individual users or via a system filter.
21626 If unset, or expanding to an empty string, no filtering is done.
21627
21628 When the message is about to be written out, the command specified by
21629 &%transport_filter%& is started up in a separate, parallel process, and
21630 the entire message, including the header lines, is passed to it on its standard
21631 input (this in fact is done from a third process, to avoid deadlock). The
21632 command must be specified as an absolute path.
21633
21634 The lines of the message that are written to the transport filter are
21635 terminated by newline (&"\n"&). The message is passed to the filter before any
21636 SMTP-specific processing, such as turning &"\n"& into &"\r\n"& and escaping
21637 lines beginning with a dot, and also before any processing implied by the
21638 settings of &%check_string%& and &%escape_string%& in the &(appendfile)& or
21639 &(pipe)& transports.
21640
21641 The standard error for the filter process is set to the same destination as its
21642 standard output; this is read and written to the message's ultimate
21643 destination. The process that writes the message to the filter, the
21644 filter itself, and the original process that reads the result and delivers it
21645 are all run in parallel, like a shell pipeline.
21646
21647 The filter can perform any transformations it likes, but of course should take
21648 care not to break RFC 2822 syntax. Exim does not check the result, except to
21649 test for a final newline when SMTP is in use. All messages transmitted over
21650 SMTP must end with a newline, so Exim supplies one if it is missing.
21651
21652 .cindex "content scanning" "per user"
21653 A transport filter can be used to provide content-scanning on a per-user basis
21654 at delivery time if the only required effect of the scan is to modify the
21655 message. For example, a content scan could insert a new header line containing
21656 a spam score. This could be interpreted by a filter in the user's MUA. It is
21657 not possible to discard a message at this stage.
21658
21659 .cindex "SMTP" "SIZE"
21660 A problem might arise if the filter increases the size of a message that is
21661 being sent down an SMTP connection. If the receiving SMTP server has indicated
21662 support for the SIZE parameter, Exim will have sent the size of the message
21663 at the start of the SMTP session. If what is actually sent is substantially
21664 more, the server might reject the message. This can be worked round by setting
21665 the &%size_addition%& option on the &(smtp)& transport, either to allow for
21666 additions to the message, or to disable the use of SIZE altogether.
21667
21668 .vindex "&$pipe_addresses$&"
21669 The value of the &%transport_filter%& option is the command string for starting
21670 the filter, which is run directly from Exim, not under a shell. The string is
21671 parsed by Exim in the same way as a command string for the &(pipe)& transport:
21672 Exim breaks it up into arguments and then expands each argument separately (see
21673 section &<<SECThowcommandrun>>&). Any kind of expansion failure causes delivery
21674 to be deferred. The special argument &$pipe_addresses$& is replaced by a number
21675 of arguments, one for each address that applies to this delivery. (This isn't
21676 an ideal name for this feature here, but as it was already implemented for the
21677 &(pipe)& transport, it seemed sensible not to change it.)
21678
21679 .vindex "&$host$&"
21680 .vindex "&$host_address$&"
21681 The expansion variables &$host$& and &$host_address$& are available when the
21682 transport is a remote one. They contain the name and IP address of the host to
21683 which the message is being sent. For example:
21684 .code
21685 transport_filter = /some/directory/transport-filter.pl \
21686   $host $host_address $sender_address $pipe_addresses
21687 .endd
21688
21689 Two problems arise if you want to use more complicated expansion items to
21690 generate transport filter commands, both of which due to the fact that the
21691 command is split up &'before'& expansion.
21692 .ilist
21693 If an expansion item contains white space, you must quote it, so that it is all
21694 part of the same command item. If the entire option setting is one such
21695 expansion item, you have to take care what kind of quoting you use. For
21696 example:
21697 .code
21698 transport_filter = '/bin/cmd${if eq{$host}{a.b.c}{1}{2}}'
21699 .endd
21700 This runs the command &(/bin/cmd1)& if the host name is &'a.b.c'&, and
21701 &(/bin/cmd2)& otherwise. If double quotes had been used, they would have been
21702 stripped by Exim when it read the option's value. When the value is used, if
21703 the single quotes were missing, the line would be split into two items,
21704 &`/bin/cmd${if`& and &`eq{$host}{a.b.c}{1}{2}`&, and an error would occur when
21705 Exim tried to expand the first one.
21706 .next
21707 Except for the special case of &$pipe_addresses$& that is mentioned above, an
21708 expansion cannot generate multiple arguments, or a command name followed by
21709 arguments. Consider this example:
21710 .code
21711 transport_filter = ${lookup{$host}lsearch{/a/file}\
21712                     {$value}{/bin/cat}}
21713 .endd
21714 The result of the lookup is interpreted as the name of the command, even
21715 if it contains white space. The simplest way round this is to use a shell:
21716 .code
21717 transport_filter = /bin/sh -c ${lookup{$host}lsearch{/a/file}\
21718                                {$value}{/bin/cat}}
21719 .endd
21720 .endlist
21721
21722 The filter process is run under the same uid and gid as the normal delivery.
21723 For remote deliveries this is the Exim uid/gid by default. The command should
21724 normally yield a zero return code. Transport filters are not supposed to fail.
21725 A non-zero code is taken to mean that the transport filter encountered some
21726 serious problem. Delivery of the message is deferred; the message remains on
21727 the queue and is tried again later. It is not possible to cause a message to be
21728 bounced from a transport filter.
21729
21730 If a transport filter is set on an autoreply transport, the original message is
21731 passed through the filter as it is being copied into the newly generated
21732 message, which happens if the &%return_message%& option is set.
21733
21734
21735 .option transport_filter_timeout transports time 5m
21736 .cindex "transport" "filter, timeout"
21737 When Exim is reading the output of a transport filter, it applies a timeout
21738 that can be set by this option. Exceeding the timeout is normally treated as a
21739 temporary delivery failure. However, if a transport filter is used with a
21740 &(pipe)& transport, a timeout in the transport filter is treated in the same
21741 way as a timeout in the pipe command itself. By default, a timeout is a hard
21742 error, but if the &(pipe)& transport's &%timeout_defer%& option is set true, it
21743 becomes a temporary error.
21744
21745
21746 .option user transports string&!! "Exim user"
21747 .cindex "uid (user id)" "local delivery"
21748 .cindex "transport" "user, specifying"
21749 This option specifies the user under whose uid the delivery process is to be
21750 run, overriding any uid that may have been set by the router. If the user is
21751 given as a name, the uid is looked up from the password data, and the
21752 associated group is taken as the value of the gid to be used if the &%group%&
21753 option is not set.
21754
21755 For deliveries that use local transports, a user and group are normally
21756 specified explicitly or implicitly (for example, as a result of
21757 &%check_local_user%&) by the router or transport.
21758
21759 .cindex "hints database" "access by remote transport"
21760 For remote transports, you should leave this option unset unless you really are
21761 sure you know what you are doing. When a remote transport is running, it needs
21762 to be able to access Exim's hints databases, because each host may have its own
21763 retry data.
21764 .ecindex IIDgenoptra1
21765 .ecindex IIDgenoptra2
21766 .ecindex IIDgenoptra3
21767
21768
21769
21770
21771
21772
21773 . ////////////////////////////////////////////////////////////////////////////
21774 . ////////////////////////////////////////////////////////////////////////////
21775
21776 .chapter "Address batching in local transports" "CHAPbatching" &&&
21777          "Address batching"
21778 .cindex "transport" "local; address batching in"
21779 The only remote transport (&(smtp)&) is normally configured to handle more than
21780 one address at a time, so that when several addresses are routed to the same
21781 remote host, just one copy of the message is sent. Local transports, however,
21782 normally handle one address at a time. That is, a separate instance of the
21783 transport is run for each address that is routed to the transport. A separate
21784 copy of the message is delivered each time.
21785
21786 .cindex "batched local delivery"
21787 .oindex "&%batch_max%&"
21788 .oindex "&%batch_id%&"
21789 In special cases, it may be desirable to handle several addresses at once in a
21790 local transport, for example:
21791
21792 .ilist
21793 In an &(appendfile)& transport, when storing messages in files for later
21794 delivery by some other means, a single copy of the message with multiple
21795 recipients saves space.
21796 .next
21797 In an &(lmtp)& transport, when delivering over &"local SMTP"& to some process,
21798 a single copy saves time, and is the normal way LMTP is expected to work.
21799 .next
21800 In a &(pipe)& transport, when passing the message
21801 to a scanner program or
21802 to some other delivery mechanism such as UUCP, multiple recipients may be
21803 acceptable.
21804 .endlist
21805
21806 These three local transports all have the same options for controlling multiple
21807 (&"batched"&) deliveries, namely &%batch_max%& and &%batch_id%&. To save
21808 repeating the information for each transport, these options are described here.
21809
21810 The &%batch_max%& option specifies the maximum number of addresses that can be
21811 delivered together in a single run of the transport. Its default value is one
21812 (no batching). When more than one address is routed to a transport that has a
21813 &%batch_max%& value greater than one, the addresses are delivered in a batch
21814 (that is, in a single run of the transport with multiple recipients), subject
21815 to certain conditions:
21816
21817 .ilist
21818 .vindex "&$local_part$&"
21819 If any of the transport's options contain a reference to &$local_part$&, no
21820 batching is possible.
21821 .next
21822 .vindex "&$domain$&"
21823 If any of the transport's options contain a reference to &$domain$&, only
21824 addresses with the same domain are batched.
21825 .next
21826 .cindex "customizing" "batching condition"
21827 If &%batch_id%& is set, it is expanded for each address, and only those
21828 addresses with the same expanded value are batched. This allows you to specify
21829 customized batching conditions. Failure of the expansion for any reason,
21830 including forced failure, disables batching, but it does not stop the delivery
21831 from taking place.
21832 .next
21833 Batched addresses must also have the same errors address (where to send
21834 delivery errors), the same header additions and removals, the same user and
21835 group for the transport, and if a host list is present, the first host must
21836 be the same.
21837 .endlist
21838
21839 In the case of the &(appendfile)& and &(pipe)& transports, batching applies
21840 both when the file or pipe command is specified in the transport, and when it
21841 is specified by a &(redirect)& router, but all the batched addresses must of
21842 course be routed to the same file or pipe command. These two transports have an
21843 option called &%use_bsmtp%&, which causes them to deliver the message in
21844 &"batched SMTP"& format, with the envelope represented as SMTP commands. The
21845 &%check_string%& and &%escape_string%& options are forced to the values
21846 .code
21847 check_string = "."
21848 escape_string = ".."
21849 .endd
21850 when batched SMTP is in use. A full description of the batch SMTP mechanism is
21851 given in section &<<SECTbatchSMTP>>&. The &(lmtp)& transport does not have a
21852 &%use_bsmtp%& option, because it always delivers using the SMTP protocol.
21853
21854 .cindex "&'Envelope-to:'& header line"
21855 If the generic &%envelope_to_add%& option is set for a batching transport, the
21856 &'Envelope-to:'& header that is added to the message contains all the addresses
21857 that are being processed together. If you are using a batching &(appendfile)&
21858 transport without &%use_bsmtp%&, the only way to preserve the recipient
21859 addresses is to set the &%envelope_to_add%& option.
21860
21861 .cindex "&(pipe)& transport" "with multiple addresses"
21862 .vindex "&$pipe_addresses$&"
21863 If you are using a &(pipe)& transport without BSMTP, and setting the
21864 transport's &%command%& option, you can include &$pipe_addresses$& as part of
21865 the command. This is not a true variable; it is a bit of magic that causes each
21866 of the recipient addresses to be inserted into the command as a separate
21867 argument. This provides a way of accessing all the addresses that are being
21868 delivered in the batch. &*Note:*& This is not possible for pipe commands that
21869 are specified by a &(redirect)& router.
21870
21871
21872
21873
21874 . ////////////////////////////////////////////////////////////////////////////
21875 . ////////////////////////////////////////////////////////////////////////////
21876
21877 .chapter "The appendfile transport" "CHAPappendfile"
21878 .scindex IIDapptra1 "&(appendfile)& transport"
21879 .scindex IIDapptra2 "transports" "&(appendfile)&"
21880 .cindex "directory creation"
21881 .cindex "creating directories"
21882 The &(appendfile)& transport delivers a message by appending it to an existing
21883 file, or by creating an entirely new file in a specified directory. Single
21884 files to which messages are appended can be in the traditional Unix mailbox
21885 format, or optionally in the MBX format supported by the Pine MUA and
21886 University of Washington IMAP daemon, &'inter alia'&. When each message is
21887 being delivered as a separate file, &"maildir"& format can optionally be used
21888 to give added protection against failures that happen part-way through the
21889 delivery. A third form of separate-file delivery known as &"mailstore"& is also
21890 supported. For all file formats, Exim attempts to create as many levels of
21891 directory as necessary, provided that &%create_directory%& is set.
21892
21893 The code for the optional formats is not included in the Exim binary by
21894 default. It is necessary to set SUPPORT_MBX, SUPPORT_MAILDIR and/or
21895 SUPPORT_MAILSTORE in &_Local/Makefile_& to have the appropriate code
21896 included.
21897
21898 .cindex "quota" "system"
21899 Exim recognizes system quota errors, and generates an appropriate message. Exim
21900 also supports its own quota control within the transport, for use when the
21901 system facility is unavailable or cannot be used for some reason.
21902
21903 If there is an error while appending to a file (for example, quota exceeded or
21904 partition filled), Exim attempts to reset the file's length and last
21905 modification time back to what they were before. If there is an error while
21906 creating an entirely new file, the new file is removed.
21907
21908 Before appending to a file, a number of security checks are made, and the
21909 file is locked. A detailed description is given below, after the list of
21910 private options.
21911
21912 The &(appendfile)& transport is most commonly used for local deliveries to
21913 users' mailboxes. However, it can also be used as a pseudo-remote transport for
21914 putting messages into files for remote delivery by some means other than Exim.
21915 &"Batch SMTP"& format is often used in this case (see the &%use_bsmtp%&
21916 option).
21917
21918
21919
21920 .section "The file and directory options" "SECTfildiropt"
21921 The &%file%& option specifies a single file, to which the message is appended;
21922 the &%directory%& option specifies a directory, in which a new file containing
21923 the message is created. Only one of these two options can be set, and for
21924 normal deliveries to mailboxes, one of them &'must'& be set.
21925
21926 .vindex "&$address_file$&"
21927 .vindex "&$local_part$&"
21928 However, &(appendfile)& is also used for delivering messages to files or
21929 directories whose names (or parts of names) are obtained from alias,
21930 forwarding, or filtering operations (for example, a &%save%& command in a
21931 user's Exim filter). When such a transport is running, &$local_part$& contains
21932 the local part that was aliased or forwarded, and &$address_file$& contains the
21933 name (or partial name) of the file or directory generated by the redirection
21934 operation. There are two cases:
21935
21936 .ilist
21937 If neither &%file%& nor &%directory%& is set, the redirection operation
21938 must specify an absolute path (one that begins with &`/`&). This is the most
21939 common case when users with local accounts use filtering to sort mail into
21940 different folders. See for example, the &(address_file)& transport in the
21941 default configuration. If the path ends with a slash, it is assumed to be the
21942 name of a directory. A delivery to a directory can also be forced by setting
21943 &%maildir_format%& or &%mailstore_format%&.
21944 .next
21945 If &%file%& or &%directory%& is set for a delivery from a redirection, it is
21946 used to determine the file or directory name for the delivery. Normally, the
21947 contents of &$address_file$& are used in some way in the string expansion.
21948 .endlist
21949
21950
21951 .cindex "Sieve filter" "configuring &(appendfile)&"
21952 .cindex "Sieve filter" "relative mailbox path handling"
21953 As an example of the second case, consider an environment where users do not
21954 have home directories. They may be permitted to use Exim filter commands of the
21955 form:
21956 .code
21957 save folder23
21958 .endd
21959 or Sieve filter commands of the form:
21960 .code
21961 require "fileinto";
21962 fileinto "folder23";
21963 .endd
21964 In this situation, the expansion of &%file%& or &%directory%& in the transport
21965 must transform the relative path into an appropriate absolute file name. In the
21966 case of Sieve filters, the name &'inbox'& must be handled. It is the name that
21967 is used as a result of a &"keep"& action in the filter. This example shows one
21968 way of handling this requirement:
21969 .code
21970 file = ${if eq{$address_file}{inbox} \
21971             {/var/mail/$local_part} \
21972             {${if eq{${substr_0_1:$address_file}}{/} \
21973                   {$address_file} \
21974                   {$home/mail/$address_file} \
21975             }} \
21976        }
21977 .endd
21978 With this setting of &%file%&, &'inbox'& refers to the standard mailbox
21979 location, absolute paths are used without change, and other folders are in the
21980 &_mail_& directory within the home directory.
21981
21982 &*Note 1*&: While processing an Exim filter, a relative path such as
21983 &_folder23_& is turned into an absolute path if a home directory is known to
21984 the router. In particular, this is the case if &%check_local_user%& is set. If
21985 you want to prevent this happening at routing time, you can set
21986 &%router_home_directory%& empty. This forces the router to pass the relative
21987 path to the transport.
21988
21989 &*Note 2*&: An absolute path in &$address_file$& is not treated specially;
21990 the &%file%& or &%directory%& option is still used if it is set.
21991
21992
21993
21994
21995 .section "Private options for appendfile" "SECID134"
21996 .cindex "options" "&(appendfile)& transport"
21997
21998
21999
22000 .option allow_fifo appendfile boolean false
22001 .cindex "fifo (named pipe)"
22002 .cindex "named pipe (fifo)"
22003 .cindex "pipe" "named (fifo)"
22004 Setting this option permits delivery to named pipes (FIFOs) as well as to
22005 regular files. If no process is reading the named pipe at delivery time, the
22006 delivery is deferred.
22007
22008
22009 .option allow_symlink appendfile boolean false
22010 .cindex "symbolic link" "to mailbox"
22011 .cindex "mailbox" "symbolic link"
22012 By default, &(appendfile)& will not deliver if the path name for the file is
22013 that of a symbolic link. Setting this option relaxes that constraint, but there
22014 are security issues involved in the use of symbolic links. Be sure you know
22015 what you are doing if you set this. Details of exactly what this option affects
22016 are included in the discussion which follows this list of options.
22017
22018
22019 .option batch_id appendfile string&!! unset
22020 See the description of local delivery batching in chapter &<<CHAPbatching>>&.
22021 However, batching is automatically disabled for &(appendfile)& deliveries that
22022 happen as a result of forwarding or aliasing or other redirection directly to a
22023 file.
22024
22025
22026 .option batch_max appendfile integer 1
22027 See the description of local delivery batching in chapter &<<CHAPbatching>>&.
22028
22029
22030 .option check_group appendfile boolean false
22031 When this option is set, the group owner of the file defined by the &%file%&
22032 option is checked to see that it is the same as the group under which the
22033 delivery process is running. The default setting is false because the default
22034 file mode is 0600, which means that the group is irrelevant.
22035
22036
22037 .option check_owner appendfile boolean true
22038 When this option is set, the owner of the file defined by the &%file%& option
22039 is checked to ensure that it is the same as the user under which the delivery
22040 process is running.
22041
22042
22043 .option check_string appendfile string "see below"
22044 .cindex "&""From""& line"
22045 As &(appendfile)& writes the message, the start of each line is tested for
22046 matching &%check_string%&, and if it does, the initial matching characters are
22047 replaced by the contents of &%escape_string%&. The value of &%check_string%& is
22048 a literal string, not a regular expression, and the case of any letters it
22049 contains is significant.
22050
22051 If &%use_bsmtp%& is set the values of &%check_string%& and &%escape_string%&
22052 are forced to &"."& and &".."& respectively, and any settings in the
22053 configuration are ignored. Otherwise, they default to &"From&~"& and
22054 &">From&~"& when the &%file%& option is set, and unset when any of the
22055 &%directory%&, &%maildir%&, or &%mailstore%& options are set.
22056
22057 The default settings, along with &%message_prefix%& and &%message_suffix%&, are
22058 suitable for traditional &"BSD"& mailboxes, where a line beginning with
22059 &"From&~"& indicates the start of a new message. All four options need changing
22060 if another format is used. For example, to deliver to mailboxes in MMDF format:
22061 .cindex "MMDF format mailbox"
22062 .cindex "mailbox" "MMDF format"
22063 .code
22064 check_string = "\1\1\1\1\n"
22065 escape_string = "\1\1\1\1 \n"
22066 message_prefix = "\1\1\1\1\n"
22067 message_suffix = "\1\1\1\1\n"
22068 .endd
22069 .option create_directory appendfile boolean true
22070 .cindex "directory creation"
22071 When this option is true, Exim attempts to create any missing superior
22072 directories for the file that it is about to write. A created directory's mode
22073 is given by the &%directory_mode%& option.
22074
22075 The group ownership of a newly created directory is highly dependent on the
22076 operating system (and possibly the file system) that is being used. For
22077 example, in Solaris, if the parent directory has the setgid bit set, its group
22078 is propagated to the child; if not, the currently set group is used. However,
22079 in FreeBSD, the parent's group is always used.
22080
22081
22082
22083 .option create_file appendfile string anywhere
22084 This option constrains the location of files and directories that are created
22085 by this transport. It applies to files defined by the &%file%& option and
22086 directories defined by the &%directory%& option. In the case of maildir
22087 delivery, it applies to the top level directory, not the maildir directories
22088 beneath.
22089
22090 The option must be set to one of the words &"anywhere"&, &"inhome"&, or
22091 &"belowhome"&. In the second and third cases, a home directory must have been
22092 set for the transport. This option is not useful when an explicit file name is
22093 given for normal mailbox deliveries. It is intended for the case when file
22094 names are generated from users' &_.forward_& files. These are usually handled
22095 by an &(appendfile)& transport called &%address_file%&. See also
22096 &%file_must_exist%&.
22097
22098
22099 .option directory appendfile string&!! unset
22100 This option is mutually exclusive with the &%file%& option, but one of &%file%&
22101 or &%directory%& must be set, unless the delivery is the direct result of a
22102 redirection (see section &<<SECTfildiropt>>&).
22103
22104 When &%directory%& is set, the string is expanded, and the message is delivered
22105 into a new file or files in or below the given directory, instead of being
22106 appended to a single mailbox file. A number of different formats are provided
22107 (see &%maildir_format%& and &%mailstore_format%&), and see section
22108 &<<SECTopdir>>& for further details of this form of delivery.
22109
22110
22111 .option directory_file appendfile string&!! "see below"
22112 .cindex "base62"
22113 .vindex "&$inode$&"
22114 When &%directory%& is set, but neither &%maildir_format%& nor
22115 &%mailstore_format%& is set, &(appendfile)& delivers each message into a file
22116 whose name is obtained by expanding this string. The default value is:
22117 .code
22118 q${base62:$tod_epoch}-$inode
22119 .endd
22120 This generates a unique name from the current time, in base 62 form, and the
22121 inode of the file. The variable &$inode$& is available only when expanding this
22122 option.
22123
22124
22125 .option directory_mode appendfile "octal integer" 0700
22126 If &(appendfile)& creates any directories as a result of the
22127 &%create_directory%& option, their mode is specified by this option.
22128
22129
22130 .option escape_string appendfile string "see description"
22131 See &%check_string%& above.
22132
22133
22134 .option file appendfile string&!! unset
22135 This option is mutually exclusive with the &%directory%& option, but one of
22136 &%file%& or &%directory%& must be set, unless the delivery is the direct result
22137 of a redirection (see section &<<SECTfildiropt>>&). The &%file%& option
22138 specifies a single file, to which the message is appended. One or more of
22139 &%use_fcntl_lock%&, &%use_flock_lock%&, or &%use_lockfile%& must be set with
22140 &%file%&.
22141
22142 .cindex "NFS" "lock file"
22143 .cindex "locking files"
22144 .cindex "lock files"
22145 If you are using more than one host to deliver over NFS into the same
22146 mailboxes, you should always use lock files.
22147
22148 The string value is expanded for each delivery, and must yield an absolute
22149 path. The most common settings of this option are variations on one of these
22150 examples:
22151 .code
22152 file = /var/spool/mail/$local_part
22153 file = /home/$local_part/inbox
22154 file = $home/inbox
22155 .endd
22156 .cindex "&""sticky""& bit"
22157 In the first example, all deliveries are done into the same directory. If Exim
22158 is configured to use lock files (see &%use_lockfile%& below) it must be able to
22159 create a file in the directory, so the &"sticky"& bit must be turned on for
22160 deliveries to be possible, or alternatively the &%group%& option can be used to
22161 run the delivery under a group id which has write access to the directory.
22162
22163
22164
22165 .option file_format appendfile string unset
22166 .cindex "file" "mailbox; checking existing format"
22167 This option requests the transport to check the format of an existing file
22168 before adding to it. The check consists of matching a specific string at the
22169 start of the file. The value of the option consists of an even number of
22170 colon-separated strings. The first of each pair is the test string, and the
22171 second is the name of a transport. If the transport associated with a matched
22172 string is not the current transport, control is passed over to the other
22173 transport. For example, suppose the standard &(local_delivery)& transport has
22174 this added to it:
22175 .code
22176 file_format = "From       : local_delivery :\
22177                \1\1\1\1\n : local_mmdf_delivery"
22178 .endd
22179 Mailboxes that begin with &"From"& are still handled by this transport, but if
22180 a mailbox begins with four binary ones followed by a newline, control is passed
22181 to a transport called &%local_mmdf_delivery%&, which presumably is configured
22182 to do the delivery in MMDF format. If a mailbox does not exist or is empty, it
22183 is assumed to match the current transport. If the start of a mailbox doesn't
22184 match any string, or if the transport named for a given string is not defined,
22185 delivery is deferred.
22186
22187
22188 .option file_must_exist appendfile boolean false
22189 If this option is true, the file specified by the &%file%& option must exist.
22190 A temporary error occurs if it does not, causing delivery to be deferred.
22191 If this option is false, the file is created if it does not exist.
22192
22193
22194 .option lock_fcntl_timeout appendfile time 0s
22195 .cindex "timeout" "mailbox locking"
22196 .cindex "mailbox" "locking, blocking and non-blocking"
22197 .cindex "locking files"
22198 By default, the &(appendfile)& transport uses non-blocking calls to &[fcntl()]&
22199 when locking an open mailbox file. If the call fails, the delivery process
22200 sleeps for &%lock_interval%& and tries again, up to &%lock_retries%& times.
22201 Non-blocking calls are used so that the file is not kept open during the wait
22202 for the lock; the reason for this is to make it as safe as possible for
22203 deliveries over NFS in the case when processes might be accessing an NFS
22204 mailbox without using a lock file. This should not be done, but
22205 misunderstandings and hence misconfigurations are not unknown.
22206
22207 On a busy system, however, the performance of a non-blocking lock approach is
22208 not as good as using a blocking lock with a timeout. In this case, the waiting
22209 is done inside the system call, and Exim's delivery process acquires the lock
22210 and can proceed as soon as the previous lock holder releases it.
22211
22212 If &%lock_fcntl_timeout%& is set to a non-zero time, blocking locks, with that
22213 timeout, are used. There may still be some retrying: the maximum number of
22214 retries is
22215 .code
22216 (lock_retries * lock_interval) / lock_fcntl_timeout
22217 .endd
22218 rounded up to the next whole number. In other words, the total time during
22219 which &(appendfile)& is trying to get a lock is roughly the same, unless
22220 &%lock_fcntl_timeout%& is set very large.
22221
22222 You should consider setting this option if you are getting a lot of delayed
22223 local deliveries because of errors of the form
22224 .code
22225 failed to lock mailbox /some/file (fcntl)
22226 .endd
22227
22228 .option lock_flock_timeout appendfile time 0s
22229 This timeout applies to file locking when using &[flock()]& (see
22230 &%use_flock%&); the timeout operates in a similar manner to
22231 &%lock_fcntl_timeout%&.
22232
22233
22234 .option lock_interval appendfile time 3s
22235 This specifies the time to wait between attempts to lock the file. See below
22236 for details of locking.
22237
22238
22239 .option lock_retries appendfile integer 10
22240 This specifies the maximum number of attempts to lock the file. A value of zero
22241 is treated as 1. See below for details of locking.
22242
22243
22244 .option lockfile_mode appendfile "octal integer" 0600
22245 This specifies the mode of the created lock file, when a lock file is being
22246 used (see &%use_lockfile%& and &%use_mbx_lock%&).
22247
22248
22249 .option lockfile_timeout appendfile time 30m
22250 .cindex "timeout" "mailbox locking"
22251 When a lock file is being used (see &%use_lockfile%&), if a lock file already
22252 exists and is older than this value, it is assumed to have been left behind by
22253 accident, and Exim attempts to remove it.
22254
22255
22256 .option mailbox_filecount appendfile string&!! unset
22257 .cindex "mailbox" "specifying size of"
22258 .cindex "size" "of mailbox"
22259 If this option is set, it is expanded, and the result is taken as the current
22260 number of files in the mailbox. It must be a decimal number, optionally
22261 followed by K or M. This provides a way of obtaining this information from an
22262 external source that maintains the data.
22263
22264
22265 .option mailbox_size appendfile string&!! unset
22266 .cindex "mailbox" "specifying size of"
22267 .cindex "size" "of mailbox"
22268 If this option is set, it is expanded, and the result is taken as the current
22269 size the mailbox. It must be a decimal number, optionally followed by K or M.
22270 This provides a way of obtaining this information from an external source that
22271 maintains the data. This is likely to be helpful for maildir deliveries where
22272 it is computationally expensive to compute the size of a mailbox.
22273
22274
22275
22276 .option maildir_format appendfile boolean false
22277 .cindex "maildir format" "specifying"
22278 If this option is set with the &%directory%& option, the delivery is into a new
22279 file, in the &"maildir"& format that is used by other mail software. When the
22280 transport is activated directly from a &(redirect)& router (for example, the
22281 &(address_file)& transport in the default configuration), setting
22282 &%maildir_format%& causes the path received from the router to be treated as a
22283 directory, whether or not it ends with &`/`&. This option is available only if
22284 SUPPORT_MAILDIR is present in &_Local/Makefile_&. See section
22285 &<<SECTmaildirdelivery>>& below for further details.
22286
22287
22288 .option maildir_quota_directory_regex appendfile string "See below"
22289 .cindex "maildir format" "quota; directories included in"
22290 .cindex "quota" "maildir; directories included in"
22291 This option is relevant only when &%maildir_use_size_file%& is set. It defines
22292 a regular expression for specifying directories, relative to the quota
22293 directory (see &%quota_directory%&), that should be included in the quota
22294 calculation. The default value is:
22295 .code
22296 maildir_quota_directory_regex = ^(?:cur|new|\..*)$
22297 .endd
22298 This includes the &_cur_& and &_new_& directories, and any maildir++ folders
22299 (directories whose names begin with a dot). If you want to exclude the
22300 &_Trash_&
22301 folder from the count (as some sites do), you need to change this setting to
22302 .code
22303 maildir_quota_directory_regex = ^(?:cur|new|\.(?!Trash).*)$
22304 .endd
22305 This uses a negative lookahead in the regular expression to exclude the
22306 directory whose name is &_.Trash_&. When a directory is excluded from quota
22307 calculations, quota processing is bypassed for any messages that are delivered
22308 directly into that directory.
22309
22310
22311 .option maildir_retries appendfile integer 10
22312 This option specifies the number of times to retry when writing a file in
22313 &"maildir"& format. See section &<<SECTmaildirdelivery>>& below.
22314
22315
22316 .option maildir_tag appendfile string&!! unset
22317 This option applies only to deliveries in maildir format, and is described in
22318 section &<<SECTmaildirdelivery>>& below.
22319
22320
22321 .option maildir_use_size_file appendfile&!! boolean false
22322 .cindex "maildir format" "&_maildirsize_& file"
22323 The result of string expansion for this option must be a valid boolean value.
22324 If it is true, it enables support for &_maildirsize_& files. Exim
22325 creates a &_maildirsize_& file in a maildir if one does not exist, taking the
22326 quota from the &%quota%& option of the transport. If &%quota%& is unset, the
22327 value is zero. See &%maildir_quota_directory_regex%& above and section
22328 &<<SECTmaildirdelivery>>& below for further details.
22329
22330 .option maildirfolder_create_regex appendfile string unset
22331 .cindex "maildir format" "&_maildirfolder_& file"
22332 .cindex "&_maildirfolder_&, creating"
22333 The value of this option is a regular expression. If it is unset, it has no
22334 effect. Otherwise, before a maildir delivery takes place, the pattern is
22335 matched against the name of the maildir directory, that is, the directory
22336 containing the &_new_& and &_tmp_& subdirectories that will be used for the
22337 delivery. If there is a match, Exim checks for the existence of a file called
22338 &_maildirfolder_& in the directory, and creates it if it does not exist.
22339 See section &<<SECTmaildirdelivery>>& for more details.
22340
22341
22342 .option mailstore_format appendfile boolean false
22343 .cindex "mailstore format" "specifying"
22344 If this option is set with the &%directory%& option, the delivery is into two
22345 new files in  &"mailstore"& format. The option is available only if
22346 SUPPORT_MAILSTORE is present in &_Local/Makefile_&. See section &<<SECTopdir>>&
22347 below for further details.
22348
22349
22350 .option mailstore_prefix appendfile string&!! unset
22351 This option applies only to deliveries in mailstore format, and is described in
22352 section &<<SECTopdir>>& below.
22353
22354
22355 .option mailstore_suffix appendfile string&!! unset
22356 This option applies only to deliveries in mailstore format, and is described in
22357 section &<<SECTopdir>>& below.
22358
22359
22360 .option mbx_format appendfile boolean false
22361 .cindex "locking files"
22362 .cindex "file" "locking"
22363 .cindex "file" "MBX format"
22364 .cindex "MBX format, specifying"
22365 This option is available only if Exim has been compiled with SUPPORT_MBX
22366 set in &_Local/Makefile_&. If &%mbx_format%& is set with the &%file%& option,
22367 the message is appended to the mailbox file in MBX format instead of
22368 traditional Unix format. This format is supported by Pine4 and its associated
22369 IMAP and POP daemons, by means of the &'c-client'& library that they all use.
22370
22371 &*Note*&: The &%message_prefix%& and &%message_suffix%& options are not
22372 automatically changed by the use of &%mbx_format%&. They should normally be set
22373 empty when using MBX format, so this option almost always appears in this
22374 combination:
22375 .code
22376 mbx_format = true
22377 message_prefix =
22378 message_suffix =
22379 .endd
22380 If none of the locking options are mentioned in the configuration,
22381 &%use_mbx_lock%& is assumed and the other locking options default to false. It
22382 is possible to specify the other kinds of locking with &%mbx_format%&, but
22383 &%use_fcntl_lock%& and &%use_mbx_lock%& are mutually exclusive. MBX locking
22384 interworks with &'c-client'&, providing for shared access to the mailbox. It
22385 should not be used if any program that does not use this form of locking is
22386 going to access the mailbox, nor should it be used if the mailbox file is NFS
22387 mounted, because it works only when the mailbox is accessed from a single host.
22388
22389 If you set &%use_fcntl_lock%& with an MBX-format mailbox, you cannot use
22390 the standard version of &'c-client'&, because as long as it has a mailbox open
22391 (this means for the whole of a Pine or IMAP session), Exim will not be able to
22392 append messages to it.
22393
22394
22395 .option message_prefix appendfile string&!! "see below"
22396 .cindex "&""From""& line"
22397 The string specified here is expanded and output at the start of every message.
22398 The default is unset unless &%file%& is specified and &%use_bsmtp%& is not set,
22399 in which case it is:
22400 .code
22401 message_prefix = "From ${if def:return_path{$return_path}\
22402   {MAILER-DAEMON}} $tod_bsdinbox\n"
22403 .endd
22404 &*Note:*& If you set &%use_crlf%& true, you must change any occurrences of
22405 &`\n`& to &`\r\n`& in &%message_prefix%&.
22406
22407 .option message_suffix appendfile string&!! "see below"
22408 The string specified here is expanded and output at the end of every message.
22409 The default is unset unless &%file%& is specified and &%use_bsmtp%& is not set,
22410 in which case it is a single newline character. The suffix can be suppressed by
22411 setting
22412 .code
22413 message_suffix =
22414 .endd
22415 &*Note:*& If you set &%use_crlf%& true, you must change any occurrences of
22416 &`\n`& to &`\r\n`& in &%message_suffix%&.
22417
22418 .option mode appendfile "octal integer" 0600
22419 If the output file is created, it is given this mode. If it already exists and
22420 has wider permissions, they are reduced to this mode. If it has narrower
22421 permissions, an error occurs unless &%mode_fail_narrower%& is false. However,
22422 if the delivery is the result of a &%save%& command in a filter file specifying
22423 a particular mode, the mode of the output file is always forced to take that
22424 value, and this option is ignored.
22425
22426
22427 .option mode_fail_narrower appendfile boolean true
22428 This option applies in the case when an existing mailbox file has a narrower
22429 mode than that specified by the &%mode%& option. If &%mode_fail_narrower%& is
22430 true, the delivery is deferred (&"mailbox has the wrong mode"&); otherwise Exim
22431 continues with the delivery attempt, using the existing mode of the file.
22432
22433
22434 .option notify_comsat appendfile boolean false
22435 If this option is true, the &'comsat'& daemon is notified after every
22436 successful delivery to a user mailbox. This is the daemon that notifies logged
22437 on users about incoming mail.
22438
22439
22440 .option quota appendfile string&!! unset
22441 .cindex "quota" "imposed by Exim"
22442 This option imposes a limit on the size of the file to which Exim is appending,
22443 or to the total space used in the directory tree when the &%directory%& option
22444 is set. In the latter case, computation of the space used is expensive, because
22445 all the files in the directory (and any sub-directories) have to be
22446 individually inspected and their sizes summed. (See &%quota_size_regex%& and
22447 &%maildir_use_size_file%& for ways to avoid this in environments where users
22448 have no shell access to their mailboxes).
22449
22450 As there is no interlock against two simultaneous deliveries into a
22451 multi-file mailbox, it is possible for the quota to be overrun in this case.
22452 For single-file mailboxes, of course, an interlock is a necessity.
22453
22454 A file's size is taken as its &'used'& value. Because of blocking effects, this
22455 may be a lot less than the actual amount of disk space allocated to the file.
22456 If the sizes of a number of files are being added up, the rounding effect can
22457 become quite noticeable, especially on systems that have large block sizes.
22458 Nevertheless, it seems best to stick to the &'used'& figure, because this is
22459 the obvious value which users understand most easily.
22460
22461 The value of the option is expanded, and must then be a numerical value
22462 (decimal point allowed), optionally followed by one of the letters K, M, or G,
22463 for kilobytes, megabytes, or gigabytes, optionally followed by a slash
22464 and further option modifiers. If Exim is running on a system with
22465 large file support (Linux and FreeBSD have this), mailboxes larger than 2G can
22466 be handled.
22467
22468 The option modifier &%no_check%& can be used to force delivery even if the over
22469 quota condition is met. The quota gets updated as usual.
22470
22471 &*Note*&: A value of zero is interpreted as &"no quota"&.
22472
22473 The expansion happens while Exim is running as root, before it changes uid for
22474 the delivery. This means that files that are inaccessible to the end user can
22475 be used to hold quota values that are looked up in the expansion. When delivery
22476 fails because this quota is exceeded, the handling of the error is as for
22477 system quota failures.
22478
22479 By default, Exim's quota checking mimics system quotas, and restricts the
22480 mailbox to the specified maximum size, though the value is not accurate to the
22481 last byte, owing to separator lines and additional headers that may get added
22482 during message delivery. When a mailbox is nearly full, large messages may get
22483 refused even though small ones are accepted, because the size of the current
22484 message is added to the quota when the check is made. This behaviour can be
22485 changed by setting &%quota_is_inclusive%& false. When this is done, the check
22486 for exceeding the quota does not include the current message. Thus, deliveries
22487 continue until the quota has been exceeded; thereafter, no further messages are
22488 delivered. See also &%quota_warn_threshold%&.
22489
22490
22491 .option quota_directory appendfile string&!! unset
22492 This option defines the directory to check for quota purposes when delivering
22493 into individual files. The default is the delivery directory, or, if a file
22494 called &_maildirfolder_& exists in a maildir directory, the parent of the
22495 delivery directory.
22496
22497
22498 .option quota_filecount appendfile string&!! 0
22499 This option applies when the &%directory%& option is set. It limits the total
22500 number of files in the directory (compare the inode limit in system quotas). It
22501 can only be used if &%quota%& is also set. The value is expanded; an expansion
22502 failure causes delivery to be deferred. A value of zero is interpreted as
22503 &"no quota"&.
22504
22505 The option modifier &%no_check%& can be used to force delivery even if the over
22506 quota condition is met. The quota gets updated as usual.
22507
22508 .option quota_is_inclusive appendfile boolean true
22509 See &%quota%& above.
22510
22511
22512 .option quota_size_regex appendfile string unset
22513 This option applies when one of the delivery modes that writes a separate file
22514 for each message is being used. When Exim wants to find the size of one of
22515 these files in order to test the quota, it first checks &%quota_size_regex%&.
22516 If this is set to a regular expression that matches the file name, and it
22517 captures one string, that string is interpreted as a representation of the
22518 file's size. The value of &%quota_size_regex%& is not expanded.
22519
22520 This feature is useful only when users have no shell access to their mailboxes
22521 &-- otherwise they could defeat the quota simply by renaming the files. This
22522 facility can be used with maildir deliveries, by setting &%maildir_tag%& to add
22523 the file length to the file name. For example:
22524 .code
22525 maildir_tag = ,S=$message_size
22526 quota_size_regex = ,S=(\d+)
22527 .endd
22528 An alternative to &$message_size$& is &$message_linecount$&, which contains the
22529 number of lines in the message.
22530
22531 The regular expression should not assume that the length is at the end of the
22532 file name (even though &%maildir_tag%& puts it there) because maildir MUAs
22533 sometimes add other information onto the ends of message file names.
22534
22535 Section &<<SECID136>>& contains further information.
22536
22537
22538 .option quota_warn_message appendfile string&!! "see below"
22539 See below for the use of this option. If it is not set when
22540 &%quota_warn_threshold%& is set, it defaults to
22541 .code
22542 quota_warn_message = "\
22543   To: $local_part@$domain\n\
22544   Subject: Your mailbox\n\n\
22545   This message is automatically created \
22546   by mail delivery software.\n\n\
22547   The size of your mailbox has exceeded \
22548   a warning threshold that is\n\
22549   set by the system administrator.\n"
22550 .endd
22551
22552
22553 .option quota_warn_threshold appendfile string&!! 0
22554 .cindex "quota" "warning threshold"
22555 .cindex "mailbox" "size warning"
22556 .cindex "size" "of mailbox"
22557 This option is expanded in the same way as &%quota%& (see above). If the
22558 resulting value is greater than zero, and delivery of the message causes the
22559 size of the file or total space in the directory tree to cross the given
22560 threshold, a warning message is sent. If &%quota%& is also set, the threshold
22561 may be specified as a percentage of it by following the value with a percent
22562 sign. For example:
22563 .code
22564 quota = 10M
22565 quota_warn_threshold = 75%
22566 .endd
22567 If &%quota%& is not set, a setting of &%quota_warn_threshold%& that ends with a
22568 percent sign is ignored.
22569
22570 The warning message itself is specified by the &%quota_warn_message%& option,
22571 and it must start with a &'To:'& header line containing the recipient(s) of the
22572 warning message. These do not necessarily have to include the recipient(s) of
22573 the original message. A &'Subject:'& line should also normally be supplied. You
22574 can include any other header lines that you want. If you do not include a
22575 &'From:'& line, the default is:
22576 .code
22577 From: Mail Delivery System <mailer-daemon@$qualify_domain_sender>
22578 .endd
22579 .oindex &%errors_reply_to%&
22580 If you supply a &'Reply-To:'& line, it overrides the global &%errors_reply_to%&
22581 option.
22582
22583 The &%quota%& option does not have to be set in order to use this option; they
22584 are independent of one another except when the threshold is specified as a
22585 percentage.
22586
22587
22588 .option use_bsmtp appendfile boolean false
22589 .cindex "envelope sender"
22590 If this option is set true, &(appendfile)& writes messages in &"batch SMTP"&
22591 format, with the envelope sender and recipient(s) included as SMTP commands. If
22592 you want to include a leading HELO command with such messages, you can do
22593 so by setting the &%message_prefix%& option. See section &<<SECTbatchSMTP>>&
22594 for details of batch SMTP.
22595
22596
22597 .option use_crlf appendfile boolean false
22598 .cindex "carriage return"
22599 .cindex "linefeed"
22600 This option causes lines to be terminated with the two-character CRLF sequence
22601 (carriage return, linefeed) instead of just a linefeed character. In the case
22602 of batched SMTP, the byte sequence written to the file is then an exact image
22603 of what would be sent down a real SMTP connection.
22604
22605 &*Note:*& The contents of the &%message_prefix%& and &%message_suffix%& options
22606 (which are used to supply the traditional &"From&~"& and blank line separators
22607 in Berkeley-style mailboxes) are written verbatim, so must contain their own
22608 carriage return characters if these are needed. In cases where these options
22609 have non-empty defaults, the values end with a single linefeed, so they must be
22610 changed to end with &`\r\n`& if &%use_crlf%& is set.
22611
22612
22613 .option use_fcntl_lock appendfile boolean "see below"
22614 This option controls the use of the &[fcntl()]& function to lock a file for
22615 exclusive use when a message is being appended. It is set by default unless
22616 &%use_flock_lock%& is set. Otherwise, it should be turned off only if you know
22617 that all your MUAs use lock file locking. When both &%use_fcntl_lock%& and
22618 &%use_flock_lock%& are unset, &%use_lockfile%& must be set.
22619
22620
22621 .option use_flock_lock appendfile boolean false
22622 This option is provided to support the use of &[flock()]& for file locking, for
22623 the few situations where it is needed. Most modern operating systems support
22624 &[fcntl()]& and &[lockf()]& locking, and these two functions interwork with
22625 each other. Exim uses &[fcntl()]& locking by default.
22626
22627 This option is required only if you are using an operating system where
22628 &[flock()]& is used by programs that access mailboxes (typically MUAs), and
22629 where &[flock()]& does not correctly interwork with &[fcntl()]&. You can use
22630 both &[fcntl()]& and &[flock()]& locking simultaneously if you want.
22631
22632 .cindex "Solaris" "&[flock()]& support"
22633 Not all operating systems provide &[flock()]&. Some versions of Solaris do not
22634 have it (and some, I think, provide a not quite right version built on top of
22635 &[lockf()]&). If the OS does not have &[flock()]&, Exim will be built without
22636 the ability to use it, and any attempt to do so will cause a configuration
22637 error.
22638
22639 &*Warning*&: &[flock()]& locks do not work on NFS files (unless &[flock()]&
22640 is just being mapped onto &[fcntl()]& by the OS).
22641
22642
22643 .option use_lockfile appendfile boolean "see below"
22644 If this option is turned off, Exim does not attempt to create a lock file when
22645 appending to a mailbox file. In this situation, the only locking is by
22646 &[fcntl()]&. You should only turn &%use_lockfile%& off if you are absolutely
22647 sure that every MUA that is ever going to look at your users' mailboxes uses
22648 &[fcntl()]& rather than a lock file, and even then only when you are not
22649 delivering over NFS from more than one host.
22650
22651 .cindex "NFS" "lock file"
22652 In order to append to an NFS file safely from more than one host, it is
22653 necessary to take out a lock &'before'& opening the file, and the lock file
22654 achieves this. Otherwise, even with &[fcntl()]& locking, there is a risk of
22655 file corruption.
22656
22657 The &%use_lockfile%& option is set by default unless &%use_mbx_lock%& is set.
22658 It is not possible to turn both &%use_lockfile%& and &%use_fcntl_lock%& off,
22659 except when &%mbx_format%& is set.
22660
22661
22662 .option use_mbx_lock appendfile boolean "see below"
22663 This option is available only if Exim has been compiled with SUPPORT_MBX
22664 set in &_Local/Makefile_&. Setting the option specifies that special MBX
22665 locking rules be used. It is set by default if &%mbx_format%& is set and none
22666 of the locking options are mentioned in the configuration. The locking rules
22667 are the same as are used by the &'c-client'& library that underlies Pine and
22668 the IMAP4 and POP daemons that come with it (see the discussion below). The
22669 rules allow for shared access to the mailbox. However, this kind of locking
22670 does not work when the mailbox is NFS mounted.
22671
22672 You can set &%use_mbx_lock%& with either (or both) of &%use_fcntl_lock%& and
22673 &%use_flock_lock%& to control what kind of locking is used in implementing the
22674 MBX locking rules. The default is to use &[fcntl()]& if &%use_mbx_lock%& is set
22675 without &%use_fcntl_lock%& or &%use_flock_lock%&.
22676
22677
22678
22679
22680 .section "Operational details for appending" "SECTopappend"
22681 .cindex "appending to a file"
22682 .cindex "file" "appending"
22683 Before appending to a file, the following preparations are made:
22684
22685 .ilist
22686 If the name of the file is &_/dev/null_&, no action is taken, and a success
22687 return is given.
22688
22689 .next
22690 .cindex "directory creation"
22691 If any directories on the file's path are missing, Exim creates them if the
22692 &%create_directory%& option is set. A created directory's mode is given by the
22693 &%directory_mode%& option.
22694
22695 .next
22696 If &%file_format%& is set, the format of an existing file is checked. If this
22697 indicates that a different transport should be used, control is passed to that
22698 transport.
22699
22700 .next
22701 .cindex "file" "locking"
22702 .cindex "locking files"
22703 .cindex "NFS" "lock file"
22704 If &%use_lockfile%& is set, a lock file is built in a way that will work
22705 reliably over NFS, as follows:
22706
22707 .olist
22708 Create a &"hitching post"& file whose name is that of the lock file with the
22709 current time, primary host name, and process id added, by opening for writing
22710 as a new file. If this fails with an access error, delivery is deferred.
22711 .next
22712 Close the hitching post file, and hard link it to the lock file name.
22713 .next
22714 If the call to &[link()]& succeeds, creation of the lock file has succeeded.
22715 Unlink the hitching post name.
22716 .next
22717 Otherwise, use &[stat()]& to get information about the hitching post file, and
22718 then unlink hitching post name. If the number of links is exactly two, creation
22719 of the lock file succeeded but something (for example, an NFS server crash and
22720 restart) caused this fact not to be communicated to the &[link()]& call.
22721 .next
22722 If creation of the lock file failed, wait for &%lock_interval%& and try again,
22723 up to &%lock_retries%& times. However, since any program that writes to a
22724 mailbox should complete its task very quickly, it is reasonable to time out old
22725 lock files that are normally the result of user agent and system crashes. If an
22726 existing lock file is older than &%lockfile_timeout%& Exim attempts to unlink
22727 it before trying again.
22728 .endlist olist
22729
22730 .next
22731 A call is made to &[lstat()]& to discover whether the main file exists, and if
22732 so, what its characteristics are. If &[lstat()]& fails for any reason other
22733 than non-existence, delivery is deferred.
22734
22735 .next
22736 .cindex "symbolic link" "to mailbox"
22737 .cindex "mailbox" "symbolic link"
22738 If the file does exist and is a symbolic link, delivery is deferred, unless the
22739 &%allow_symlink%& option is set, in which case the ownership of the link is
22740 checked, and then &[stat()]& is called to find out about the real file, which
22741 is then subjected to the checks below. The check on the top-level link
22742 ownership prevents one user creating a link for another's mailbox in a sticky
22743 directory, though allowing symbolic links in this case is definitely not a good
22744 idea. If there is a chain of symbolic links, the intermediate ones are not
22745 checked.
22746
22747 .next
22748 If the file already exists but is not a regular file, or if the file's owner
22749 and group (if the group is being checked &-- see &%check_group%& above) are
22750 different from the user and group under which the delivery is running,
22751 delivery is deferred.
22752
22753 .next
22754 If the file's permissions are more generous than specified, they are reduced.
22755 If they are insufficient, delivery is deferred, unless &%mode_fail_narrower%&
22756 is set false, in which case the delivery is tried using the existing
22757 permissions.
22758
22759 .next
22760 The file's inode number is saved, and the file is then opened for appending.
22761 If this fails because the file has vanished, &(appendfile)& behaves as if it
22762 hadn't existed (see below). For any other failures, delivery is deferred.
22763
22764 .next
22765 If the file is opened successfully, check that the inode number hasn't
22766 changed, that it is still a regular file, and that the owner and permissions
22767 have not changed. If anything is wrong, defer delivery and freeze the message.
22768
22769 .next
22770 If the file did not exist originally, defer delivery if the &%file_must_exist%&
22771 option is set. Otherwise, check that the file is being created in a permitted
22772 directory if the &%create_file%& option is set (deferring on failure), and then
22773 open for writing as a new file, with the O_EXCL and O_CREAT options,
22774 except when dealing with a symbolic link (the &%allow_symlink%& option must be
22775 set). In this case, which can happen if the link points to a non-existent file,
22776 the file is opened for writing using O_CREAT but not O_EXCL, because
22777 that prevents link following.
22778
22779 .next
22780 .cindex "loop" "while file testing"
22781 If opening fails because the file exists, obey the tests given above for
22782 existing files. However, to avoid looping in a situation where the file is
22783 being continuously created and destroyed, the exists/not-exists loop is broken
22784 after 10 repetitions, and the message is then frozen.
22785
22786 .next
22787 If opening fails with any other error, defer delivery.
22788
22789 .next
22790 .cindex "file" "locking"
22791 .cindex "locking files"
22792 Once the file is open, unless both &%use_fcntl_lock%& and &%use_flock_lock%&
22793 are false, it is locked using &[fcntl()]& or &[flock()]& or both. If
22794 &%use_mbx_lock%& is false, an exclusive lock is requested in each case.
22795 However, if &%use_mbx_lock%& is true, Exim takes out a shared lock on the open
22796 file, and an exclusive lock on the file whose name is
22797 .code
22798 /tmp/.<device-number>.<inode-number>
22799 .endd
22800 using the device and inode numbers of the open mailbox file, in accordance with
22801 the MBX locking rules. This file is created with a mode that is specified by
22802 the &%lockfile_mode%& option.
22803
22804 If Exim fails to lock the file, there are two possible courses of action,
22805 depending on the value of the locking timeout. This is obtained from
22806 &%lock_fcntl_timeout%& or &%lock_flock_timeout%&, as appropriate.
22807
22808 If the timeout value is zero, the file is closed, Exim waits for
22809 &%lock_interval%&, and then goes back and re-opens the file as above and tries
22810 to lock it again. This happens up to &%lock_retries%& times, after which the
22811 delivery is deferred.
22812
22813 If the timeout has a value greater than zero, blocking calls to &[fcntl()]& or
22814 &[flock()]& are used (with the given timeout), so there has already been some
22815 waiting involved by the time locking fails. Nevertheless, Exim does not give up
22816 immediately. It retries up to
22817 .code
22818 (lock_retries * lock_interval) / <timeout>
22819 .endd
22820 times (rounded up).
22821 .endlist
22822
22823 At the end of delivery, Exim closes the file (which releases the &[fcntl()]&
22824 and/or &[flock()]& locks) and then deletes the lock file if one was created.
22825
22826
22827 .section "Operational details for delivery to a new file" "SECTopdir"
22828 .cindex "delivery" "to single file"
22829 .cindex "&""From""& line"
22830 When the &%directory%& option is set instead of &%file%&, each message is
22831 delivered into a newly-created file or set of files. When &(appendfile)& is
22832 activated directly from a &(redirect)& router, neither &%file%& nor
22833 &%directory%& is normally set, because the path for delivery is supplied by the
22834 router. (See for example, the &(address_file)& transport in the default
22835 configuration.) In this case, delivery is to a new file if either the path name
22836 ends in &`/`&, or the &%maildir_format%& or &%mailstore_format%& option is set.
22837
22838 No locking is required while writing the message to a new file, so the various
22839 locking options of the transport are ignored. The &"From"& line that by default
22840 separates messages in a single file is not normally needed, nor is the escaping
22841 of message lines that start with &"From"&, and there is no need to ensure a
22842 newline at the end of each message. Consequently, the default values for
22843 &%check_string%&, &%message_prefix%&, and &%message_suffix%& are all unset when
22844 any of &%directory%&, &%maildir_format%&, or &%mailstore_format%& is set.
22845
22846 If Exim is required to check a &%quota%& setting, it adds up the sizes of all
22847 the files in the delivery directory by default. However, you can specify a
22848 different directory by setting &%quota_directory%&. Also, for maildir
22849 deliveries (see below) the &_maildirfolder_& convention is honoured.
22850
22851
22852 .cindex "maildir format"
22853 .cindex "mailstore format"
22854 There are three different ways in which delivery to individual files can be
22855 done, controlled by the settings of the &%maildir_format%& and
22856 &%mailstore_format%& options. Note that code to support maildir or mailstore
22857 formats is not included in the binary unless SUPPORT_MAILDIR or
22858 SUPPORT_MAILSTORE, respectively, is set in &_Local/Makefile_&.
22859
22860 .cindex "directory creation"
22861 In all three cases an attempt is made to create the directory and any necessary
22862 sub-directories if they do not exist, provided that the &%create_directory%&
22863 option is set (the default). The location of a created directory can be
22864 constrained by setting &%create_file%&. A created directory's mode is given by
22865 the &%directory_mode%& option. If creation fails, or if the
22866 &%create_directory%& option is not set when creation is required, delivery is
22867 deferred.
22868
22869
22870
22871 .section "Maildir delivery" "SECTmaildirdelivery"
22872 .cindex "maildir format" "description of"
22873 If the &%maildir_format%& option is true, Exim delivers each message by writing
22874 it to a file whose name is &_tmp/<stime>.H<mtime>P<pid>.<host>_& in the
22875 directory that is defined by the &%directory%& option (the &"delivery
22876 directory"&). If the delivery is successful, the file is renamed into the
22877 &_new_& subdirectory.
22878
22879 In the file name, <&'stime'&> is the current time of day in seconds, and
22880 <&'mtime'&> is the microsecond fraction of the time. After a maildir delivery,
22881 Exim checks that the time-of-day clock has moved on by at least one microsecond
22882 before terminating the delivery process. This guarantees uniqueness for the
22883 file name. However, as a precaution, Exim calls &[stat()]& for the file before
22884 opening it. If any response other than ENOENT (does not exist) is given,
22885 Exim waits 2 seconds and tries again, up to &%maildir_retries%& times.
22886
22887 Before Exim carries out a maildir delivery, it ensures that subdirectories
22888 called &_new_&, &_cur_&, and &_tmp_& exist in the delivery directory. If they
22889 do not exist, Exim tries to create them and any superior directories in their
22890 path, subject to the &%create_directory%& and &%create_file%& options. If the
22891 &%maildirfolder_create_regex%& option is set, and the regular expression it
22892 contains matches the delivery directory, Exim also ensures that a file called
22893 &_maildirfolder_& exists in the delivery directory. If a missing directory or
22894 &_maildirfolder_& file cannot be created, delivery is deferred.
22895
22896 These features make it possible to use Exim to create all the necessary files
22897 and directories in a maildir mailbox, including subdirectories for maildir++
22898 folders. Consider this example:
22899 .code
22900 maildir_format = true
22901 directory = /var/mail/$local_part\
22902            ${if eq{$local_part_suffix}{}{}\
22903            {/.${substr_1:$local_part_suffix}}}
22904 maildirfolder_create_regex = /\.[^/]+$
22905 .endd
22906 If &$local_part_suffix$& is empty (there was no suffix for the local part),
22907 delivery is into a toplevel maildir with a name like &_/var/mail/pimbo_& (for
22908 the user called &'pimbo'&). The pattern in &%maildirfolder_create_regex%& does
22909 not match this name, so Exim will not look for or create the file
22910 &_/var/mail/pimbo/maildirfolder_&, though it will create
22911 &_/var/mail/pimbo/{cur,new,tmp}_& if necessary.
22912
22913 However, if &$local_part_suffix$& contains &`-eximusers`& (for example),
22914 delivery is into the maildir++ folder &_/var/mail/pimbo/.eximusers_&, which
22915 does match &%maildirfolder_create_regex%&. In this case, Exim will create
22916 &_/var/mail/pimbo/.eximusers/maildirfolder_& as well as the three maildir
22917 directories &_/var/mail/pimbo/.eximusers/{cur,new,tmp}_&.
22918
22919 &*Warning:*& Take care when setting &%maildirfolder_create_regex%& that it does
22920 not inadvertently match the toplevel maildir directory, because a
22921 &_maildirfolder_& file at top level would completely break quota calculations.
22922
22923 .cindex "quota" "in maildir delivery"
22924 .cindex "maildir++"
22925 If Exim is required to check a &%quota%& setting before a maildir delivery, and
22926 &%quota_directory%& is not set, it looks for a file called &_maildirfolder_& in
22927 the maildir directory (alongside &_new_&, &_cur_&, &_tmp_&). If this exists,
22928 Exim assumes the directory is a maildir++ folder directory, which is one level
22929 down from the user's top level mailbox directory. This causes it to start at
22930 the parent directory instead of the current directory when calculating the
22931 amount of space used.
22932
22933 One problem with delivering into a multi-file mailbox is that it is
22934 computationally expensive to compute the size of the mailbox for quota
22935 checking. Various approaches have been taken to reduce the amount of work
22936 needed. The next two sections describe two of them. A third alternative is to
22937 use some external process for maintaining the size data, and use the expansion
22938 of the &%mailbox_size%& option as a way of importing it into Exim.
22939
22940
22941
22942
22943 .section "Using tags to record message sizes" "SECID135"
22944 If &%maildir_tag%& is set, the string is expanded for each delivery.
22945 When the maildir file is renamed into the &_new_& sub-directory, the
22946 tag is added to its name. However, if adding the tag takes the length of the
22947 name to the point where the test &[stat()]& call fails with ENAMETOOLONG,
22948 the tag is dropped and the maildir file is created with no tag.
22949
22950
22951 .vindex "&$message_size$&"
22952 Tags can be used to encode the size of files in their names; see
22953 &%quota_size_regex%& above for an example. The expansion of &%maildir_tag%&
22954 happens after the message has been written. The value of the &$message_size$&
22955 variable is set to the number of bytes actually written. If the expansion is
22956 forced to fail, the tag is ignored, but a non-forced failure causes delivery to
22957 be deferred. The expanded tag may contain any printing characters except &"/"&.
22958 Non-printing characters in the string are ignored; if the resulting string is
22959 empty, it is ignored. If it starts with an alphanumeric character, a leading
22960 colon is inserted; this default has not proven to be the path that popular
22961 maildir implementations have chosen (but changing it in Exim would break
22962 backwards compatibility).
22963
22964 For one common implementation, you might set:
22965 .code
22966 maildir_tag = ,S=${message_size}
22967 .endd
22968 but you should check the documentation of the other software to be sure.
22969
22970 It is advisable to also set &%quota_size_regex%& when setting &%maildir_tag%&
22971 as this allows Exim to extract the size from your tag, instead of having to
22972 &[stat()]& each message file.
22973
22974
22975 .section "Using a maildirsize file" "SECID136"
22976 .cindex "quota" "in maildir delivery"
22977 .cindex "maildir format" "&_maildirsize_& file"
22978 If &%maildir_use_size_file%& is true, Exim implements the maildir++ rules for
22979 storing quota and message size information in a file called &_maildirsize_&
22980 within the toplevel maildir directory. If this file does not exist, Exim
22981 creates it, setting the quota from the &%quota%& option of the transport. If
22982 the maildir directory itself does not exist, it is created before any attempt
22983 to write a &_maildirsize_& file.
22984
22985 The &_maildirsize_& file is used to hold information about the sizes of
22986 messages in the maildir, thus speeding up quota calculations. The quota value
22987 in the file is just a cache; if the quota is changed in the transport, the new
22988 value overrides the cached value when the next message is delivered. The cache
22989 is maintained for the benefit of other programs that access the maildir and
22990 need to know the quota.
22991
22992 If the &%quota%& option in the transport is unset or zero, the &_maildirsize_&
22993 file is maintained (with a zero quota setting), but no quota is imposed.
22994
22995 A regular expression is available for controlling which directories in the
22996 maildir participate in quota calculations when a &_maildirsizefile_& is in use.
22997 See the description of the &%maildir_quota_directory_regex%& option above for
22998 details.
22999
23000
23001 .section "Mailstore delivery" "SECID137"
23002 .cindex "mailstore format" "description of"
23003 If the &%mailstore_format%& option is true, each message is written as two
23004 files in the given directory. A unique base name is constructed from the
23005 message id and the current delivery process, and the files that are written use
23006 this base name plus the suffixes &_.env_& and &_.msg_&. The &_.env_& file
23007 contains the message's envelope, and the &_.msg_& file contains the message
23008 itself. The base name is placed in the variable &$mailstore_basename$&.
23009
23010 During delivery, the envelope is first written to a file with the suffix
23011 &_.tmp_&. The &_.msg_& file is then written, and when it is complete, the
23012 &_.tmp_& file is renamed as the &_.env_& file. Programs that access messages in
23013 mailstore format should wait for the presence of both a &_.msg_& and a &_.env_&
23014 file before accessing either of them. An alternative approach is to wait for
23015 the absence of a &_.tmp_& file.
23016
23017 The envelope file starts with any text defined by the &%mailstore_prefix%&
23018 option, expanded and terminated by a newline if there isn't one. Then follows
23019 the sender address on one line, then all the recipient addresses, one per line.
23020 There can be more than one recipient only if the &%batch_max%& option is set
23021 greater than one. Finally, &%mailstore_suffix%& is expanded and the result
23022 appended to the file, followed by a newline if it does not end with one.
23023
23024 If expansion of &%mailstore_prefix%& or &%mailstore_suffix%& ends with a forced
23025 failure, it is ignored. Other expansion errors are treated as serious
23026 configuration errors, and delivery is deferred. The variable
23027 &$mailstore_basename$& is available for use during these expansions.
23028
23029
23030 .section "Non-special new file delivery" "SECID138"
23031 If neither &%maildir_format%& nor &%mailstore_format%& is set, a single new
23032 file is created directly in the named directory. For example, when delivering
23033 messages into files in batched SMTP format for later delivery to some host (see
23034 section &<<SECTbatchSMTP>>&), a setting such as
23035 .code
23036 directory = /var/bsmtp/$host
23037 .endd
23038 might be used. A message is written to a file with a temporary name, which is
23039 then renamed when the delivery is complete. The final name is obtained by
23040 expanding the contents of the &%directory_file%& option.
23041 .ecindex IIDapptra1
23042 .ecindex IIDapptra2
23043
23044
23045
23046
23047
23048
23049 . ////////////////////////////////////////////////////////////////////////////
23050 . ////////////////////////////////////////////////////////////////////////////
23051
23052 .chapter "The autoreply transport" "CHID8"
23053 .scindex IIDauttra1 "transports" "&(autoreply)&"
23054 .scindex IIDauttra2 "&(autoreply)& transport"
23055 The &(autoreply)& transport is not a true transport in that it does not cause
23056 the message to be transmitted. Instead, it generates a new mail message as an
23057 automatic reply to the incoming message. &'References:'& and
23058 &'Auto-Submitted:'& header lines are included. These are constructed according
23059 to the rules in RFCs 2822 and 3834, respectively.
23060
23061 If the router that passes the message to this transport does not have the
23062 &%unseen%& option set, the original message (for the current recipient) is not
23063 delivered anywhere. However, when the &%unseen%& option is set on the router
23064 that passes the message to this transport, routing of the address continues, so
23065 another router can set up a normal message delivery.
23066
23067
23068 The &(autoreply)& transport is usually run as the result of mail filtering, a
23069 &"vacation"& message being the standard example. However, it can also be run
23070 directly from a router like any other transport. To reduce the possibility of
23071 message cascades, messages created by the &(autoreply)& transport always have
23072 empty envelope sender addresses, like bounce messages.
23073
23074 The parameters of the message to be sent can be specified in the configuration
23075 by options described below. However, these are used only when the address
23076 passed to the transport does not contain its own reply information. When the
23077 transport is run as a consequence of a
23078 &%mail%&
23079 or &%vacation%& command in a filter file, the parameters of the message are
23080 supplied by the filter, and passed with the address. The transport's options
23081 that define the message are then ignored (so they are not usually set in this
23082 case). The message is specified entirely by the filter or by the transport; it
23083 is never built from a mixture of options. However, the &%file_optional%&,
23084 &%mode%&, and &%return_message%& options apply in all cases.
23085
23086 &(Autoreply)& is implemented as a local transport. When used as a result of a
23087 command in a user's filter file, &(autoreply)& normally runs under the uid and
23088 gid of the user, and with appropriate current and home directories (see chapter
23089 &<<CHAPenvironment>>&).
23090
23091 There is a subtle difference between routing a message to a &(pipe)& transport
23092 that generates some text to be returned to the sender, and routing it to an
23093 &(autoreply)& transport. This difference is noticeable only if more than one
23094 address from the same message is so handled. In the case of a pipe, the
23095 separate outputs from the different addresses are gathered up and returned to
23096 the sender in a single message, whereas if &(autoreply)& is used, a separate
23097 message is generated for each address that is passed to it.
23098
23099 Non-printing characters are not permitted in the header lines generated for the
23100 message that &(autoreply)& creates, with the exception of newlines that are
23101 immediately followed by white space. If any non-printing characters are found,
23102 the transport defers.
23103 Whether characters with the top bit set count as printing characters or not is
23104 controlled by the &%print_topbitchars%& global option.
23105
23106 If any of the generic options for manipulating headers (for example,
23107 &%headers_add%&) are set on an &(autoreply)& transport, they apply to the copy
23108 of the original message that is included in the generated message when
23109 &%return_message%& is set. They do not apply to the generated message itself.
23110
23111 .vindex "&$sender_address$&"
23112 If the &(autoreply)& transport receives return code 2 from Exim when it submits
23113 the message, indicating that there were no recipients, it does not treat this
23114 as an error. This means that autoreplies sent to &$sender_address$& when this
23115 is empty (because the incoming message is a bounce message) do not cause
23116 problems. They are just discarded.
23117
23118
23119
23120 .section "Private options for autoreply" "SECID139"
23121 .cindex "options" "&(autoreply)& transport"
23122
23123 .option bcc autoreply string&!! unset
23124 This specifies the addresses that are to receive &"blind carbon copies"& of the
23125 message when the message is specified by the transport.
23126
23127
23128 .option cc autoreply string&!! unset
23129 This specifies recipients of the message and the contents of the &'Cc:'& header
23130 when the message is specified by the transport.
23131
23132
23133 .option file autoreply string&!! unset
23134 The contents of the file are sent as the body of the message when the message
23135 is specified by the transport. If both &%file%& and &%text%& are set, the text
23136 string comes first.
23137
23138
23139 .option file_expand autoreply boolean false
23140 If this is set, the contents of the file named by the &%file%& option are
23141 subjected to string expansion as they are added to the message.
23142
23143
23144 .option file_optional autoreply boolean false
23145 If this option is true, no error is generated if the file named by the &%file%&
23146 option or passed with the address does not exist or cannot be read.
23147
23148
23149 .option from autoreply string&!! unset
23150 This specifies the contents of the &'From:'& header when the message is
23151 specified by the transport.
23152
23153
23154 .option headers autoreply string&!! unset
23155 This specifies additional RFC 2822 headers that are to be added to the message
23156 when the message is specified by the transport. Several can be given by using
23157 &"\n"& to separate them. There is no check on the format.
23158
23159
23160 .option log autoreply string&!! unset
23161 This option names a file in which a record of every message sent is logged when
23162 the message is specified by the transport.
23163
23164
23165 .option mode autoreply "octal integer" 0600
23166 If either the log file or the &"once"& file has to be created, this mode is
23167 used.
23168
23169
23170 .option never_mail autoreply "address list&!!" unset
23171 If any run of the transport creates a message with a recipient that matches any
23172 item in the list, that recipient is quietly discarded. If all recipients are
23173 discarded, no message is created. This applies both when the recipients are
23174 generated by a filter and when they are specified in the transport.
23175
23176
23177
23178 .option once autoreply string&!! unset
23179 This option names a file or DBM database in which a record of each &'To:'&
23180 recipient is kept when the message is specified by the transport. &*Note*&:
23181 This does not apply to &'Cc:'& or &'Bcc:'& recipients.
23182
23183 If &%once%& is unset, or is set to an empty string, the message is always sent.
23184 By default, if &%once%& is set to a non-empty file name, the message
23185 is not sent if a potential recipient is already listed in the database.
23186 However, if the &%once_repeat%& option specifies a time greater than zero, the
23187 message is sent if that much time has elapsed since a message was last sent to
23188 this recipient. A setting of zero time for &%once_repeat%& (the default)
23189 prevents a message from being sent a second time &-- in this case, zero means
23190 infinity.
23191
23192 If &%once_file_size%& is zero, a DBM database is used to remember recipients,
23193 and it is allowed to grow as large as necessary. If &%once_file_size%& is set
23194 greater than zero, it changes the way Exim implements the &%once%& option.
23195 Instead of using a DBM file to record every recipient it sends to, it uses a
23196 regular file, whose size will never get larger than the given value.
23197
23198 In the file, Exim keeps a linear list of recipient addresses and the times at
23199 which they were sent messages. If the file is full when a new address needs to
23200 be added, the oldest address is dropped. If &%once_repeat%& is not set, this
23201 means that a given recipient may receive multiple messages, but at
23202 unpredictable intervals that depend on the rate of turnover of addresses in the
23203 file. If &%once_repeat%& is set, it specifies a maximum time between repeats.
23204
23205
23206 .option once_file_size autoreply integer 0
23207 See &%once%& above.
23208
23209
23210 .option once_repeat autoreply time&!! 0s
23211 See &%once%& above.
23212 After expansion, the value of this option must be a valid time value.
23213
23214
23215 .option reply_to autoreply string&!! unset
23216 This specifies the contents of the &'Reply-To:'& header when the message is
23217 specified by the transport.
23218
23219
23220 .option return_message autoreply boolean false
23221 If this is set, a copy of the original message is returned with the new
23222 message, subject to the maximum size set in the &%return_size_limit%& global
23223 configuration option.
23224
23225
23226 .option subject autoreply string&!! unset
23227 This specifies the contents of the &'Subject:'& header when the message is
23228 specified by the transport. It is tempting to quote the original subject in
23229 automatic responses. For example:
23230 .code
23231 subject = Re: $h_subject:
23232 .endd
23233 There is a danger in doing this, however. It may allow a third party to
23234 subscribe your users to an opt-in mailing list, provided that the list accepts
23235 bounce messages as subscription confirmations. Well-managed lists require a
23236 non-bounce message to confirm a subscription, so the danger is relatively
23237 small.
23238
23239
23240
23241 .option text autoreply string&!! unset
23242 This specifies a single string to be used as the body of the message when the
23243 message is specified by the transport. If both &%text%& and &%file%& are set,
23244 the text comes first.
23245
23246
23247 .option to autoreply string&!! unset
23248 This specifies recipients of the message and the contents of the &'To:'& header
23249 when the message is specified by the transport.
23250 .ecindex IIDauttra1
23251 .ecindex IIDauttra2
23252
23253
23254
23255
23256 . ////////////////////////////////////////////////////////////////////////////
23257 . ////////////////////////////////////////////////////////////////////////////
23258
23259 .chapter "The lmtp transport" "CHAPLMTP"
23260 .cindex "transports" "&(lmtp)&"
23261 .cindex "&(lmtp)& transport"
23262 .cindex "LMTP" "over a pipe"
23263 .cindex "LMTP" "over a socket"
23264 The &(lmtp)& transport runs the LMTP protocol (RFC 2033) over a pipe to a
23265 specified command
23266 or by interacting with a Unix domain socket.
23267 This transport is something of a cross between the &(pipe)& and &(smtp)&
23268 transports. Exim also has support for using LMTP over TCP/IP; this is
23269 implemented as an option for the &(smtp)& transport. Because LMTP is expected
23270 to be of minority interest, the default build-time configure in &_src/EDITME_&
23271 has it commented out. You need to ensure that
23272 .code
23273 TRANSPORT_LMTP=yes
23274 .endd
23275 .cindex "options" "&(lmtp)& transport"
23276 is present in your &_Local/Makefile_& in order to have the &(lmtp)& transport
23277 included in the Exim binary. The private options of the &(lmtp)& transport are
23278 as follows:
23279
23280 .option batch_id lmtp string&!! unset
23281 See the description of local delivery batching in chapter &<<CHAPbatching>>&.
23282
23283
23284 .option batch_max lmtp integer 1
23285 This limits the number of addresses that can be handled in a single delivery.
23286 Most LMTP servers can handle several addresses at once, so it is normally a
23287 good idea to increase this value. See the description of local delivery
23288 batching in chapter &<<CHAPbatching>>&.
23289
23290
23291 .option command lmtp string&!! unset
23292 This option must be set if &%socket%& is not set. The string is a command which
23293 is run in a separate process. It is split up into a command name and list of
23294 arguments, each of which is separately expanded (so expansion cannot change the
23295 number of arguments). The command is run directly, not via a shell. The message
23296 is passed to the new process using the standard input and output to operate the
23297 LMTP protocol.
23298
23299 .option ignore_quota lmtp boolean false
23300 .cindex "LMTP" "ignoring quota errors"
23301 If this option is set true, the string &`IGNOREQUOTA`& is added to RCPT
23302 commands, provided that the LMTP server has advertised support for IGNOREQUOTA
23303 in its response to the LHLO command.
23304
23305 .option socket lmtp string&!! unset
23306 This option must be set if &%command%& is not set. The result of expansion must
23307 be the name of a Unix domain socket. The transport connects to the socket and
23308 delivers the message to it using the LMTP protocol.
23309
23310
23311 .option timeout lmtp time 5m
23312 The transport is aborted if the created process or Unix domain socket does not
23313 respond to LMTP commands or message input within this timeout. Delivery
23314 is deferred, and will be tried again later. Here is an example of a typical
23315 LMTP transport:
23316 .code
23317 lmtp:
23318   driver = lmtp
23319   command = /some/local/lmtp/delivery/program
23320   batch_max = 20
23321   user = exim
23322 .endd
23323 This delivers up to 20 addresses at a time, in a mixture of domains if
23324 necessary, running as the user &'exim'&.
23325
23326
23327
23328 . ////////////////////////////////////////////////////////////////////////////
23329 . ////////////////////////////////////////////////////////////////////////////
23330
23331 .chapter "The pipe transport" "CHAPpipetransport"
23332 .scindex IIDpiptra1 "transports" "&(pipe)&"
23333 .scindex IIDpiptra2 "&(pipe)& transport"
23334 The &(pipe)& transport is used to deliver messages via a pipe to a command
23335 running in another process. One example is the use of &(pipe)& as a
23336 pseudo-remote transport for passing messages to some other delivery mechanism
23337 (such as UUCP). Another is the use by individual users to automatically process
23338 their incoming messages. The &(pipe)& transport can be used in one of the
23339 following ways:
23340
23341 .ilist
23342 .vindex "&$local_part$&"
23343 A router routes one address to a transport in the normal way, and the
23344 transport is configured as a &(pipe)& transport. In this case, &$local_part$&
23345 contains the local part of the address (as usual), and the command that is run
23346 is specified by the &%command%& option on the transport.
23347 .next
23348 .vindex "&$pipe_addresses$&"
23349 If the &%batch_max%& option is set greater than 1 (the default is 1), the
23350 transport can handle more than one address in a single run. In this case, when
23351 more than one address is routed to the transport, &$local_part$& is not set
23352 (because it is not unique). However, the pseudo-variable &$pipe_addresses$&
23353 (described in section &<<SECThowcommandrun>>& below) contains all the addresses
23354 that are routed to the transport.
23355 .next
23356 .vindex "&$address_pipe$&"
23357 A router redirects an address directly to a pipe command (for example, from an
23358 alias or forward file). In this case, &$address_pipe$& contains the text of the
23359 pipe command, and the &%command%& option on the transport is ignored unless
23360 &%force_command%& is set. If only one address is being transported
23361 (&%batch_max%& is not greater than one, or only one address was redirected to
23362 this pipe command), &$local_part$& contains the local part that was redirected.
23363 .endlist
23364
23365
23366 The &(pipe)& transport is a non-interactive delivery method. Exim can also
23367 deliver messages over pipes using the LMTP interactive protocol. This is
23368 implemented by the &(lmtp)& transport.
23369
23370 In the case when &(pipe)& is run as a consequence of an entry in a local user's
23371 &_.forward_& file, the command runs under the uid and gid of that user. In
23372 other cases, the uid and gid have to be specified explicitly, either on the
23373 transport or on the router that handles the address. Current and &"home"&
23374 directories are also controllable. See chapter &<<CHAPenvironment>>& for
23375 details of the local delivery environment and chapter &<<CHAPbatching>>&
23376 for a discussion of local delivery batching.
23377
23378
23379 .section "Concurrent delivery" "SECID140"
23380 If two messages arrive at almost the same time, and both are routed to a pipe
23381 delivery, the two pipe transports may be run concurrently. You must ensure that
23382 any pipe commands you set up are robust against this happening. If the commands
23383 write to a file, the &%exim_lock%& utility might be of use.
23384 Alternatively the &%max_parallel%& option could be used with a value
23385 of "1" to enforce serialization.
23386
23387
23388
23389
23390 .section "Returned status and data" "SECID141"
23391 .cindex "&(pipe)& transport" "returned data"
23392 If the command exits with a non-zero return code, the delivery is deemed to
23393 have failed, unless either the &%ignore_status%& option is set (in which case
23394 the return code is treated as zero), or the return code is one of those listed
23395 in the &%temp_errors%& option, which are interpreted as meaning &"try again
23396 later"&. In this case, delivery is deferred. Details of a permanent failure are
23397 logged, but are not included in the bounce message, which merely contains
23398 &"local delivery failed"&.
23399
23400 If the command exits on a signal and the &%freeze_signal%& option is set then
23401 the message will be frozen in the queue. If that option is not set, a bounce
23402 will be sent as normal.
23403
23404 If the return code is greater than 128 and the command being run is a shell
23405 script, it normally means that the script was terminated by a signal whose
23406 value is the return code minus 128. The &%freeze_signal%& option does not
23407 apply in this case.
23408
23409 If Exim is unable to run the command (that is, if &[execve()]& fails), the
23410 return code is set to 127. This is the value that a shell returns if it is
23411 asked to run a non-existent command. The wording for the log line suggests that
23412 a non-existent command may be the problem.
23413
23414 The &%return_output%& option can affect the result of a pipe delivery. If it is
23415 set and the command produces any output on its standard output or standard
23416 error streams, the command is considered to have failed, even if it gave a zero
23417 return code or if &%ignore_status%& is set. The output from the command is
23418 included as part of the bounce message. The &%return_fail_output%& option is
23419 similar, except that output is returned only when the command exits with a
23420 failure return code, that is, a value other than zero or a code that matches
23421 &%temp_errors%&.
23422
23423
23424
23425 .section "How the command is run" "SECThowcommandrun"
23426 .cindex "&(pipe)& transport" "path for command"
23427 The command line is (by default) broken down into a command name and arguments
23428 by the &(pipe)& transport itself. The &%allow_commands%& and
23429 &%restrict_to_path%& options can be used to restrict the commands that may be
23430 run.
23431
23432 .cindex "quoting" "in pipe command"
23433 Unquoted arguments are delimited by white space. If an argument appears in
23434 double quotes, backslash is interpreted as an escape character in the usual
23435 way. If an argument appears in single quotes, no escaping is done.
23436
23437 String expansion is applied to the command line except when it comes from a
23438 traditional &_.forward_& file (commands from a filter file are expanded). The
23439 expansion is applied to each argument in turn rather than to the whole line.
23440 For this reason, any string expansion item that contains white space must be
23441 quoted so as to be contained within a single argument. A setting such as
23442 .code
23443 command = /some/path ${if eq{$local_part}{postmaster}{xx}{yy}}
23444 .endd
23445 will not work, because the expansion item gets split between several
23446 arguments. You have to write
23447 .code
23448 command = /some/path "${if eq{$local_part}{postmaster}{xx}{yy}}"
23449 .endd
23450 to ensure that it is all in one argument. The expansion is done in this way,
23451 argument by argument, so that the number of arguments cannot be changed as a
23452 result of expansion, and quotes or backslashes in inserted variables do not
23453 interact with external quoting. However, this leads to problems if you want to
23454 generate multiple arguments (or the command name plus arguments) from a single
23455 expansion. In this situation, the simplest solution is to use a shell. For
23456 example:
23457 .code
23458 command = /bin/sh -c ${lookup{$local_part}lsearch{/some/file}}
23459 .endd
23460
23461 .cindex "transport" "filter"
23462 .cindex "filter" "transport filter"
23463 .vindex "&$pipe_addresses$&"
23464 Special handling takes place when an argument consists of precisely the text
23465 &`$pipe_addresses`&. This is not a general expansion variable; the only
23466 place this string is recognized is when it appears as an argument for a pipe or
23467 transport filter command. It causes each address that is being handled to be
23468 inserted in the argument list at that point &'as a separate argument'&. This
23469 avoids any problems with spaces or shell metacharacters, and is of use when a
23470 &(pipe)& transport is handling groups of addresses in a batch.
23471
23472 If &%force_command%& is enabled on the transport, Special handling takes place
23473 for an argument that consists of precisely the text &`$address_pipe`&.  It
23474 is handled similarly to &$pipe_addresses$& above.  It is expanded and each
23475 argument is inserted in the argument list at that point
23476 &'as a separate argument'&.  The &`$address_pipe`& item does not need to be
23477 the only item in the argument; in fact, if it were then &%force_command%&
23478 should behave as a no-op.  Rather, it should be used to adjust the command
23479 run while preserving the argument vector separation.
23480
23481 After splitting up into arguments and expansion, the resulting command is run
23482 in a subprocess directly from the transport, &'not'& under a shell. The
23483 message that is being delivered is supplied on the standard input, and the
23484 standard output and standard error are both connected to a single pipe that is
23485 read by Exim. The &%max_output%& option controls how much output the command
23486 may produce, and the &%return_output%& and &%return_fail_output%& options
23487 control what is done with it.
23488
23489 Not running the command under a shell (by default) lessens the security risks
23490 in cases when a command from a user's filter file is built out of data that was
23491 taken from an incoming message. If a shell is required, it can of course be
23492 explicitly specified as the command to be run. However, there are circumstances
23493 where existing commands (for example, in &_.forward_& files) expect to be run
23494 under a shell and cannot easily be modified. To allow for these cases, there is
23495 an option called &%use_shell%&, which changes the way the &(pipe)& transport
23496 works. Instead of breaking up the command line as just described, it expands it
23497 as a single string and passes the result to &_/bin/sh_&. The
23498 &%restrict_to_path%& option and the &$pipe_addresses$& facility cannot be used
23499 with &%use_shell%&, and the whole mechanism is inherently less secure.
23500
23501
23502
23503 .section "Environment variables" "SECTpipeenv"
23504 .cindex "&(pipe)& transport" "environment for command"
23505 .cindex "environment" "&(pipe)& transport"
23506 The environment variables listed below are set up when the command is invoked.
23507 This list is a compromise for maximum compatibility with other MTAs. Note that
23508 the &%environment%& option can be used to add additional variables to this
23509 environment. The environment for the &(pipe)& transport is not subject
23510 to the &%add_environment%& and &%keep_environment%& main config options.
23511 .display
23512 &`DOMAIN            `&   the domain of the address
23513 &`HOME              `&   the home directory, if set
23514 &`HOST              `&   the host name when called from a router (see below)
23515 &`LOCAL_PART        `&   see below
23516 &`LOCAL_PART_PREFIX `&   see below
23517 &`LOCAL_PART_SUFFIX `&   see below
23518 &`LOGNAME           `&   see below
23519 &`MESSAGE_ID        `&   Exim's local ID for the message
23520 &`PATH              `&   as specified by the &%path%& option below
23521 &`QUALIFY_DOMAIN    `&   the sender qualification domain
23522 &`RECIPIENT         `&   the complete recipient address
23523 &`SENDER            `&   the sender of the message (empty if a bounce)
23524 &`SHELL             `&   &`/bin/sh`&
23525 &`TZ                `&   the value of the &%timezone%& option, if set
23526 &`USER              `&   see below
23527 .endd
23528 When a &(pipe)& transport is called directly from (for example) an &(accept)&
23529 router, LOCAL_PART is set to the local part of the address. When it is
23530 called as a result of a forward or alias expansion, LOCAL_PART is set to
23531 the local part of the address that was expanded. In both cases, any affixes are
23532 removed from the local part, and made available in LOCAL_PART_PREFIX and
23533 LOCAL_PART_SUFFIX, respectively. LOGNAME and USER are set to the
23534 same value as LOCAL_PART for compatibility with other MTAs.
23535
23536 .cindex "HOST"
23537 HOST is set only when a &(pipe)& transport is called from a router that
23538 associates hosts with an address, typically when using &(pipe)& as a
23539 pseudo-remote transport. HOST is set to the first host name specified by
23540 the router.
23541
23542 .cindex "HOME"
23543 If the transport's generic &%home_directory%& option is set, its value is used
23544 for the HOME environment variable. Otherwise, a home directory may be set
23545 by the router's &%transport_home_directory%& option, which defaults to the
23546 user's home directory if &%check_local_user%& is set.
23547
23548
23549 .section "Private options for pipe" "SECID142"
23550 .cindex "options" "&(pipe)& transport"
23551
23552
23553
23554 .option allow_commands pipe "string list&!!" unset
23555 .cindex "&(pipe)& transport" "permitted commands"
23556 The string is expanded, and is then interpreted as a colon-separated list of
23557 permitted commands. If &%restrict_to_path%& is not set, the only commands
23558 permitted are those in the &%allow_commands%& list. They need not be absolute
23559 paths; the &%path%& option is still used for relative paths. If
23560 &%restrict_to_path%& is set with &%allow_commands%&, the command must either be
23561 in the &%allow_commands%& list, or a name without any slashes that is found on
23562 the path. In other words, if neither &%allow_commands%& nor
23563 &%restrict_to_path%& is set, there is no restriction on the command, but
23564 otherwise only commands that are permitted by one or the other are allowed. For
23565 example, if
23566 .code
23567 allow_commands = /usr/bin/vacation
23568 .endd
23569 and &%restrict_to_path%& is not set, the only permitted command is
23570 &_/usr/bin/vacation_&. The &%allow_commands%& option may not be set if
23571 &%use_shell%& is set.
23572
23573
23574 .option batch_id pipe string&!! unset
23575 See the description of local delivery batching in chapter &<<CHAPbatching>>&.
23576
23577
23578 .option batch_max pipe integer 1
23579 This limits the number of addresses that can be handled in a single delivery.
23580 See the description of local delivery batching in chapter &<<CHAPbatching>>&.
23581
23582
23583 .option check_string pipe string unset
23584 As &(pipe)& writes the message, the start of each line is tested for matching
23585 &%check_string%&, and if it does, the initial matching characters are replaced
23586 by the contents of &%escape_string%&, provided both are set. The value of
23587 &%check_string%& is a literal string, not a regular expression, and the case of
23588 any letters it contains is significant. When &%use_bsmtp%& is set, the contents
23589 of &%check_string%& and &%escape_string%& are forced to values that implement
23590 the SMTP escaping protocol. Any settings made in the configuration file are
23591 ignored.
23592
23593
23594 .option command pipe string&!! unset
23595 This option need not be set when &(pipe)& is being used to deliver to pipes
23596 obtained directly from address redirections. In other cases, the option must be
23597 set, to provide a command to be run. It need not yield an absolute path (see
23598 the &%path%& option below). The command is split up into separate arguments by
23599 Exim, and each argument is separately expanded, as described in section
23600 &<<SECThowcommandrun>>& above.
23601
23602
23603 .option environment pipe string&!! unset
23604 .cindex "&(pipe)& transport" "environment for command"
23605 .cindex "environment" "&(pipe)& transport"
23606 This option is used to add additional variables to the environment in which the
23607 command runs (see section &<<SECTpipeenv>>& for the default list). Its value is
23608 a string which is expanded, and then interpreted as a colon-separated list of
23609 environment settings of the form <&'name'&>=<&'value'&>.
23610
23611
23612 .option escape_string pipe string unset
23613 See &%check_string%& above.
23614
23615
23616 .option freeze_exec_fail pipe boolean false
23617 .cindex "exec failure"
23618 .cindex "failure of exec"
23619 .cindex "&(pipe)& transport" "failure of exec"
23620 Failure to exec the command in a pipe transport is by default treated like
23621 any other failure while running the command. However, if &%freeze_exec_fail%&
23622 is set, failure to exec is treated specially, and causes the message to be
23623 frozen, whatever the setting of &%ignore_status%&.
23624
23625
23626 .option freeze_signal pipe boolean false
23627 .cindex "signal exit"
23628 .cindex "&(pipe)& transport", "signal exit"
23629 Normally if the process run by a command in a pipe transport exits on a signal,
23630 a bounce message is sent. If &%freeze_signal%& is set, the message will be
23631 frozen in Exim's queue instead.
23632
23633
23634 .option force_command pipe boolean false
23635 .cindex "force command"
23636 .cindex "&(pipe)& transport", "force command"
23637 Normally when a router redirects an address directly to a pipe command
23638 the &%command%& option on the transport is ignored.  If &%force_command%&
23639 is set, the &%command%& option will used. This is especially
23640 useful for forcing a wrapper or additional argument to be added to the
23641 command. For example:
23642 .code
23643 command = /usr/bin/remote_exec myhost -- $address_pipe
23644 force_command
23645 .endd
23646
23647 Note that &$address_pipe$& is handled specially in &%command%& when
23648 &%force_command%& is set, expanding out to the original argument vector as
23649 separate items, similarly to a Unix shell &`"$@"`& construct.
23650
23651
23652 .option ignore_status pipe boolean false
23653 If this option is true, the status returned by the subprocess that is set up to
23654 run the command is ignored, and Exim behaves as if zero had been returned.
23655 Otherwise, a non-zero status or termination by signal causes an error return
23656 from the transport unless the status value is one of those listed in
23657 &%temp_errors%&; these cause the delivery to be deferred and tried again later.
23658
23659 &*Note*&: This option does not apply to timeouts, which do not return a status.
23660 See the &%timeout_defer%& option for how timeouts are handled.
23661
23662
23663 .option log_defer_output pipe boolean false
23664 .cindex "&(pipe)& transport" "logging output"
23665 If this option is set, and the status returned by the command is
23666 one of the codes listed in &%temp_errors%& (that is, delivery was deferred),
23667 and any output was produced on stdout or stderr, the first line of it is
23668 written to the main log.
23669
23670
23671 .option log_fail_output pipe boolean false
23672 If this option is set, and the command returns any output on stdout or
23673 stderr, and also ends with a return code that is neither zero nor one of
23674 the return codes listed in &%temp_errors%& (that is, the delivery
23675 failed), the first line of output is written to the main log. This
23676 option and &%log_output%& are mutually exclusive.  Only one of them may
23677 be set.
23678
23679
23680 .option log_output pipe boolean false
23681 If this option is set and the command returns any output on stdout or
23682 stderr, the first line of output is written to the main log, whatever
23683 the return code. This option and &%log_fail_output%& are mutually
23684 exclusive. Only one of them may be set.
23685
23686
23687 .option max_output pipe integer 20K
23688 This specifies the maximum amount of output that the command may produce on its
23689 standard output and standard error file combined. If the limit is exceeded, the
23690 process running the command is killed. This is intended as a safety measure to
23691 catch runaway processes. The limit is applied independently of the settings of
23692 the options that control what is done with such output (for example,
23693 &%return_output%&). Because of buffering effects, the amount of output may
23694 exceed the limit by a small amount before Exim notices.
23695
23696
23697 .option message_prefix pipe string&!! "see below"
23698 The string specified here is expanded and output at the start of every message.
23699 The default is unset if &%use_bsmtp%& is set. Otherwise it is
23700 .code
23701 message_prefix = \
23702   From ${if def:return_path{$return_path}{MAILER-DAEMON}}\
23703   ${tod_bsdinbox}\n
23704 .endd
23705 .cindex "Cyrus"
23706 .cindex "&%tmail%&"
23707 .cindex "&""From""& line"
23708 This is required by the commonly used &_/usr/bin/vacation_& program.
23709 However, it must &'not'& be present if delivery is to the Cyrus IMAP server,
23710 or to the &%tmail%& local delivery agent. The prefix can be suppressed by
23711 setting
23712 .code
23713 message_prefix =
23714 .endd
23715 &*Note:*& If you set &%use_crlf%& true, you must change any occurrences of
23716 &`\n`& to &`\r\n`& in &%message_prefix%&.
23717
23718
23719 .option message_suffix pipe string&!! "see below"
23720 The string specified here is expanded and output at the end of every message.
23721 The default is unset if &%use_bsmtp%& is set. Otherwise it is a single newline.
23722 The suffix can be suppressed by setting
23723 .code
23724 message_suffix =
23725 .endd
23726 &*Note:*& If you set &%use_crlf%& true, you must change any occurrences of
23727 &`\n`& to &`\r\n`& in &%message_suffix%&.
23728
23729
23730 .option path pipe string&!! "/bin:/usr/bin"
23731 This option is expanded and
23732 specifies the string that is set up in the PATH environment
23733 variable of the subprocess.
23734 If the &%command%& option does not yield an absolute path name, the command is
23735 sought in the PATH directories, in the usual way. &*Warning*&: This does not
23736 apply to a command specified as a transport filter.
23737
23738
23739 .option permit_coredump pipe boolean false
23740 Normally Exim inhibits core-dumps during delivery.  If you have a need to get
23741 a core-dump of a pipe command, enable this command.  This enables core-dumps
23742 during delivery and affects both the Exim binary and the pipe command run.
23743 It is recommended that this option remain off unless and until you have a need
23744 for it and that this only be enabled when needed, as the risk of excessive
23745 resource consumption can be quite high.  Note also that Exim is typically
23746 installed as a setuid binary and most operating systems will inhibit coredumps
23747 of these by default, so further OS-specific action may be required.
23748
23749
23750 .option pipe_as_creator pipe boolean false
23751 .cindex "uid (user id)" "local delivery"
23752 If the generic &%user%& option is not set and this option is true, the delivery
23753 process is run under the uid that was in force when Exim was originally called
23754 to accept the message. If the group id is not otherwise set (via the generic
23755 &%group%& option), the gid that was in force when Exim was originally called to
23756 accept the message is used.
23757
23758
23759 .option restrict_to_path pipe boolean false
23760 When this option is set, any command name not listed in &%allow_commands%& must
23761 contain no slashes. The command is searched for only in the directories listed
23762 in the &%path%& option. This option is intended for use in the case when a pipe
23763 command has been generated from a user's &_.forward_& file. This is usually
23764 handled by a &(pipe)& transport called &%address_pipe%&.
23765
23766
23767 .option return_fail_output pipe boolean false
23768 If this option is true, and the command produced any output and ended with a
23769 return code other than zero or one of the codes listed in &%temp_errors%& (that
23770 is, the delivery failed), the output is returned in the bounce message.
23771 However, if the message has a null sender (that is, it is itself a bounce
23772 message), output from the command is discarded. This option and
23773 &%return_output%& are mutually exclusive. Only one of them may be set.
23774
23775
23776
23777 .option return_output pipe boolean false
23778 If this option is true, and the command produced any output, the delivery is
23779 deemed to have failed whatever the return code from the command, and the output
23780 is returned in the bounce message. Otherwise, the output is just discarded.
23781 However, if the message has a null sender (that is, it is a bounce message),
23782 output from the command is always discarded, whatever the setting of this
23783 option. This option and &%return_fail_output%& are mutually exclusive. Only one
23784 of them may be set.
23785
23786
23787
23788 .option temp_errors pipe "string list" "see below"
23789 .cindex "&(pipe)& transport" "temporary failure"
23790 This option contains either a colon-separated list of numbers, or a single
23791 asterisk. If &%ignore_status%& is false
23792 and &%return_output%& is not set,
23793 and the command exits with a non-zero return code, the failure is treated as
23794 temporary and the delivery is deferred if the return code matches one of the
23795 numbers, or if the setting is a single asterisk. Otherwise, non-zero return
23796 codes are treated as permanent errors. The default setting contains the codes
23797 defined by EX_TEMPFAIL and EX_CANTCREAT in &_sysexits.h_&. If Exim is
23798 compiled on a system that does not define these macros, it assumes values of 75
23799 and 73, respectively.
23800
23801
23802 .option timeout pipe time 1h
23803 If the command fails to complete within this time, it is killed. This normally
23804 causes the delivery to fail (but see &%timeout_defer%&). A zero time interval
23805 specifies no timeout. In order to ensure that any subprocesses created by the
23806 command are also killed, Exim makes the initial process a process group leader,
23807 and kills the whole process group on a timeout. However, this can be defeated
23808 if one of the processes starts a new process group.
23809
23810 .option timeout_defer pipe boolean false
23811 A timeout in a &(pipe)& transport, either in the command that the transport
23812 runs, or in a transport filter that is associated with it, is by default
23813 treated as a hard error, and the delivery fails. However, if &%timeout_defer%&
23814 is set true, both kinds of timeout become temporary errors, causing the
23815 delivery to be deferred.
23816
23817 .option umask pipe "octal integer" 022
23818 This specifies the umask setting for the subprocess that runs the command.
23819
23820
23821 .option use_bsmtp pipe boolean false
23822 .cindex "envelope sender"
23823 If this option is set true, the &(pipe)& transport writes messages in &"batch
23824 SMTP"& format, with the envelope sender and recipient(s) included as SMTP
23825 commands. If you want to include a leading HELO command with such messages,
23826 you can do so by setting the &%message_prefix%& option. See section
23827 &<<SECTbatchSMTP>>& for details of batch SMTP.
23828
23829 .option use_classresources pipe boolean false
23830 .cindex "class resources (BSD)"
23831 This option is available only when Exim is running on FreeBSD, NetBSD, or
23832 BSD/OS. If it is set true, the &[setclassresources()]& function is used to set
23833 resource limits when a &(pipe)& transport is run to perform a delivery. The
23834 limits for the uid under which the pipe is to run are obtained from the login
23835 class database.
23836
23837
23838 .option use_crlf pipe boolean false
23839 .cindex "carriage return"
23840 .cindex "linefeed"
23841 This option causes lines to be terminated with the two-character CRLF sequence
23842 (carriage return, linefeed) instead of just a linefeed character. In the case
23843 of batched SMTP, the byte sequence written to the pipe is then an exact image
23844 of what would be sent down a real SMTP connection.
23845
23846 The contents of the &%message_prefix%& and &%message_suffix%& options are
23847 written verbatim, so must contain their own carriage return characters if these
23848 are needed. When &%use_bsmtp%& is not set, the default values for both
23849 &%message_prefix%& and &%message_suffix%& end with a single linefeed, so their
23850 values must be changed to end with &`\r\n`& if &%use_crlf%& is set.
23851
23852
23853 .option use_shell pipe boolean false
23854 .vindex "&$pipe_addresses$&"
23855 If this option is set, it causes the command to be passed to &_/bin/sh_&
23856 instead of being run directly from the transport, as described in section
23857 &<<SECThowcommandrun>>&. This is less secure, but is needed in some situations
23858 where the command is expected to be run under a shell and cannot easily be
23859 modified. The &%allow_commands%& and &%restrict_to_path%& options, and the
23860 &`$pipe_addresses`& facility are incompatible with &%use_shell%&. The
23861 command is expanded as a single string, and handed to &_/bin/sh_& as data for
23862 its &%-c%& option.
23863
23864
23865
23866 .section "Using an external local delivery agent" "SECID143"
23867 .cindex "local delivery" "using an external agent"
23868 .cindex "&'procmail'&"
23869 .cindex "external local delivery"
23870 .cindex "delivery" "&'procmail'&"
23871 .cindex "delivery" "by external agent"
23872 The &(pipe)& transport can be used to pass all messages that require local
23873 delivery to a separate local delivery agent such as &%procmail%&. When doing
23874 this, care must be taken to ensure that the pipe is run under an appropriate
23875 uid and gid. In some configurations one wants this to be a uid that is trusted
23876 by the delivery agent to supply the correct sender of the message. It may be
23877 necessary to recompile or reconfigure the delivery agent so that it trusts an
23878 appropriate user. The following is an example transport and router
23879 configuration for &%procmail%&:
23880 .code
23881 # transport
23882 procmail_pipe:
23883   driver = pipe
23884   command = /usr/local/bin/procmail -d $local_part
23885   return_path_add
23886   delivery_date_add
23887   envelope_to_add
23888   check_string = "From "
23889   escape_string = ">From "
23890   umask = 077
23891   user = $local_part
23892   group = mail
23893
23894 # router
23895 procmail:
23896   driver = accept
23897   check_local_user
23898   transport = procmail_pipe
23899 .endd
23900 In this example, the pipe is run as the local user, but with the group set to
23901 &'mail'&. An alternative is to run the pipe as a specific user such as &'mail'&
23902 or &'exim'&, but in this case you must arrange for &%procmail%& to trust that
23903 user to supply a correct sender address. If you do not specify either a
23904 &%group%& or a &%user%& option, the pipe command is run as the local user. The
23905 home directory is the user's home directory by default.
23906
23907 &*Note*&: The command that the pipe transport runs does &'not'& begin with
23908 .code
23909 IFS=" "
23910 .endd
23911 as shown in some &%procmail%& documentation, because Exim does not by default
23912 use a shell to run pipe commands.
23913
23914 .cindex "Cyrus"
23915 The next example shows a transport and a router for a system where local
23916 deliveries are handled by the Cyrus IMAP server.
23917 .code
23918 # transport
23919 local_delivery_cyrus:
23920   driver = pipe
23921   command = /usr/cyrus/bin/deliver \
23922             -m ${substr_1:$local_part_suffix} -- $local_part
23923   user = cyrus
23924   group = mail
23925   return_output
23926   log_output
23927   message_prefix =
23928   message_suffix =
23929
23930 # router
23931 local_user_cyrus:
23932   driver = accept
23933   check_local_user
23934   local_part_suffix = .*
23935   transport = local_delivery_cyrus
23936 .endd
23937 Note the unsetting of &%message_prefix%& and &%message_suffix%&, and the use of
23938 &%return_output%& to cause any text written by Cyrus to be returned to the
23939 sender.
23940 .ecindex IIDpiptra1
23941 .ecindex IIDpiptra2
23942
23943
23944 . ////////////////////////////////////////////////////////////////////////////
23945 . ////////////////////////////////////////////////////////////////////////////
23946
23947 .chapter "The smtp transport" "CHAPsmtptrans"
23948 .scindex IIDsmttra1 "transports" "&(smtp)&"
23949 .scindex IIDsmttra2 "&(smtp)& transport"
23950 The &(smtp)& transport delivers messages over TCP/IP connections using the SMTP
23951 or LMTP protocol. The list of hosts to try can either be taken from the address
23952 that is being processed (having been set up by the router), or specified
23953 explicitly for the transport. Timeout and retry processing (see chapter
23954 &<<CHAPretry>>&) is applied to each IP address independently.
23955
23956
23957 .section "Multiple messages on a single connection" "SECID144"
23958 The sending of multiple messages over a single TCP/IP connection can arise in
23959 two ways:
23960
23961 .ilist
23962 If a message contains more than &%max_rcpt%& (see below) addresses that are
23963 routed to the same host, more than one copy of the message has to be sent to
23964 that host. In this situation, multiple copies may be sent in a single run of
23965 the &(smtp)& transport over a single TCP/IP connection. (What Exim actually
23966 does when it has too many addresses to send in one message also depends on the
23967 value of the global &%remote_max_parallel%& option. Details are given in
23968 section &<<SECToutSMTPTCP>>&.)
23969 .next
23970 .cindex "hints database" "remembering routing"
23971 When a message has been successfully delivered over a TCP/IP connection, Exim
23972 looks in its hints database to see if there are any other messages awaiting a
23973 connection to the same host. If there are, a new delivery process is started
23974 for one of them, and the current TCP/IP connection is passed on to it. The new
23975 process may in turn send multiple copies and possibly create yet another
23976 process.
23977 .endlist
23978
23979
23980 For each copy sent over the same TCP/IP connection, a sequence counter is
23981 incremented, and if it ever gets to the value of &%connection_max_messages%&,
23982 no further messages are sent over that connection.
23983
23984
23985
23986 .section "Use of the $host and $host_address variables" "SECID145"
23987 .vindex "&$host$&"
23988 .vindex "&$host_address$&"
23989 At the start of a run of the &(smtp)& transport, the values of &$host$& and
23990 &$host_address$& are the name and IP address of the first host on the host list
23991 passed by the router. However, when the transport is about to connect to a
23992 specific host, and while it is connected to that host, &$host$& and
23993 &$host_address$& are set to the values for that host. These are the values
23994 that are in force when the &%helo_data%&, &%hosts_try_auth%&, &%interface%&,
23995 &%serialize_hosts%&, and the various TLS options are expanded.
23996
23997
23998 .section "Use of $tls_cipher and $tls_peerdn" "usecippeer"
23999 .vindex &$tls_bits$&
24000 .vindex &$tls_cipher$&
24001 .vindex &$tls_peerdn$&
24002 .vindex &$tls_sni$&
24003 At the start of a run of the &(smtp)& transport, the values of &$tls_bits$&,
24004 &$tls_cipher$&, &$tls_peerdn$& and &$tls_sni$&
24005 are the values that were set when the message was received.
24006 These are the values that are used for options that are expanded before any
24007 SMTP connections are made. Just before each connection is made, these four
24008 variables are emptied. If TLS is subsequently started, they are set to the
24009 appropriate values for the outgoing connection, and these are the values that
24010 are in force when any authenticators are run and when the
24011 &%authenticated_sender%& option is expanded.
24012
24013 These variables are deprecated in favour of &$tls_in_cipher$& et. al.
24014 and will be removed in a future release.
24015
24016
24017 .section "Private options for smtp" "SECID146"
24018 .cindex "options" "&(smtp)& transport"
24019 The private options of the &(smtp)& transport are as follows:
24020
24021
24022 .option address_retry_include_sender smtp boolean true
24023 .cindex "4&'xx'& responses" "retrying after"
24024 When an address is delayed because of a 4&'xx'& response to a RCPT command, it
24025 is the combination of sender and recipient that is delayed in subsequent queue
24026 runs until the retry time is reached. You can delay the recipient without
24027 reference to the sender (which is what earlier versions of Exim did), by
24028 setting &%address_retry_include_sender%& false. However, this can lead to
24029 problems with servers that regularly issue 4&'xx'& responses to RCPT commands.
24030
24031 .option allow_localhost smtp boolean false
24032 .cindex "local host" "sending to"
24033 .cindex "fallback" "hosts specified on transport"
24034 When a host specified in &%hosts%& or &%fallback_hosts%& (see below) turns out
24035 to be the local host, or is listed in &%hosts_treat_as_local%&, delivery is
24036 deferred by default. However, if &%allow_localhost%& is set, Exim goes on to do
24037 the delivery anyway. This should be used only in special cases when the
24038 configuration ensures that no looping will result (for example, a differently
24039 configured Exim is listening on the port to which the message is sent).
24040
24041
24042 .option authenticated_sender smtp string&!! unset
24043 .cindex "Cyrus"
24044 When Exim has authenticated as a client, or if &%authenticated_sender_force%&
24045 is true, this option sets a value for the AUTH= item on outgoing MAIL commands,
24046 overriding any existing authenticated sender value. If the string expansion is
24047 forced to fail, the option is ignored. Other expansion failures cause delivery
24048 to be deferred. If the result of expansion is an empty string, that is also
24049 ignored.
24050
24051 The expansion happens after the outgoing connection has been made and TLS
24052 started, if required. This means that the &$host$&, &$host_address$&,
24053 &$tls_out_cipher$&, and &$tls_out_peerdn$& variables are set according to the
24054 particular connection.
24055
24056 If the SMTP session is not authenticated, the expansion of
24057 &%authenticated_sender%& still happens (and can cause the delivery to be
24058 deferred if it fails), but no AUTH= item is added to MAIL commands
24059 unless &%authenticated_sender_force%& is true.
24060
24061 This option allows you to use the &(smtp)& transport in LMTP mode to
24062 deliver mail to Cyrus IMAP and provide the proper local part as the
24063 &"authenticated sender"&, via a setting such as:
24064 .code
24065 authenticated_sender = $local_part
24066 .endd
24067 This removes the need for IMAP subfolders to be assigned special ACLs to
24068 allow direct delivery to those subfolders.
24069
24070 Because of expected uses such as that just described for Cyrus (when no
24071 domain is involved), there is no checking on the syntax of the provided
24072 value.
24073
24074
24075 .option authenticated_sender_force smtp boolean false
24076 If this option is set true, the &%authenticated_sender%& option's value
24077 is used for the AUTH= item on outgoing MAIL commands, even if Exim has not
24078 authenticated as a client.
24079
24080
24081 .option command_timeout smtp time 5m
24082 This sets a timeout for receiving a response to an SMTP command that has been
24083 sent out. It is also used when waiting for the initial banner line from the
24084 remote host. Its value must not be zero.
24085
24086
24087 .option connect_timeout smtp time 5m
24088 This sets a timeout for the &[connect()]& function, which sets up a TCP/IP call
24089 to a remote host. A setting of zero allows the system timeout (typically
24090 several minutes) to act. To have any effect, the value of this option must be
24091 less than the system timeout. However, it has been observed that on some
24092 systems there is no system timeout, which is why the default value for this
24093 option is 5 minutes, a value recommended by RFC 1123.
24094
24095
24096 .option connection_max_messages smtp integer 500
24097 .cindex "SMTP" "passed connection"
24098 .cindex "SMTP" "multiple deliveries"
24099 .cindex "multiple SMTP deliveries"
24100 This controls the maximum number of separate message deliveries that are sent
24101 over a single TCP/IP connection. If the value is zero, there is no limit.
24102 For testing purposes, this value can be overridden by the &%-oB%& command line
24103 option.
24104
24105
24106 .option dane_require_tls_ciphers smtp string&!! unset
24107 .cindex "TLS" "requiring specific ciphers for DANE"
24108 .cindex "cipher" "requiring specific"
24109 .cindex DANE "TLS ciphers"
24110 This option may be used to override &%tls_require_ciphers%& for connections
24111 where DANE has been determined to be in effect.
24112 If not set, then &%tls_require_ciphers%& will be used.
24113 Normal SMTP delivery is not able to make strong demands of TLS cipher
24114 configuration, because delivery will fall back to plaintext.  Once DANE has
24115 been determined to be in effect, there is no plaintext fallback and making the
24116 TLS cipherlist configuration stronger will increase security, rather than
24117 counter-intuitively decreasing it.
24118 If the option expands to be empty or is forced to fail, then it will
24119 be treated as unset and &%tls_require_ciphers%& will be used instead.
24120
24121
24122 .option data_timeout smtp time 5m
24123 This sets a timeout for the transmission of each block in the data portion of
24124 the message. As a result, the overall timeout for a message depends on the size
24125 of the message. Its value must not be zero. See also &%final_timeout%&.
24126
24127
24128 .option dkim_canon smtp string&!! unset
24129 .option dkim_domain smtp string list&!! unset
24130 .option dkim_hash smtp string&!! sha256
24131 .option dkim_identity smtp string&!! unset
24132 .option dkim_private_key smtp string&!! unset
24133 .option dkim_selector smtp string&!! unset
24134 .option dkim_strict smtp string&!! unset
24135 .option dkim_sign_headers smtp string&!! "per RFC"
24136 .option dkim_timestamps smtp string&!! unset
24137 DKIM signing options.  For details see section &<<SECDKIMSIGN>>&.
24138
24139
24140 .option delay_after_cutoff smtp boolean true
24141 .cindex "final cutoff" "retries, controlling"
24142 .cindex retry "final cutoff"
24143 This option controls what happens when all remote IP addresses for a given
24144 domain have been inaccessible for so long that they have passed their retry
24145 cutoff times.
24146
24147 In the default state, if the next retry time has not been reached for any of
24148 them, the address is bounced without trying any deliveries. In other words,
24149 Exim delays retrying an IP address after the final cutoff time until a new
24150 retry time is reached, and can therefore bounce an address without ever trying
24151 a delivery, when machines have been down for a long time. Some people are
24152 unhappy at this prospect, so...
24153
24154 If &%delay_after_cutoff%& is set false, Exim behaves differently. If all IP
24155 addresses are past their final cutoff time, Exim tries to deliver to those
24156 IP addresses that have not been tried since the message arrived. If there are
24157 none, of if they all fail, the address is bounced. In other words, it does not
24158 delay when a new message arrives, but immediately tries those expired IP
24159 addresses that haven't been tried since the message arrived. If there is a
24160 continuous stream of messages for the dead hosts, unsetting
24161 &%delay_after_cutoff%& means that there will be many more attempts to deliver
24162 to them.
24163
24164
24165 .option dns_qualify_single smtp boolean true
24166 If the &%hosts%& or &%fallback_hosts%& option is being used,
24167 and the &%gethostbyname%& option is false,
24168 the RES_DEFNAMES resolver option is set. See the &%qualify_single%& option
24169 in chapter &<<CHAPdnslookup>>& for more details.
24170
24171
24172 .option dns_search_parents smtp boolean false
24173 If the &%hosts%& or &%fallback_hosts%& option is being used, and the
24174 &%gethostbyname%& option is false, the RES_DNSRCH resolver option is set.
24175 See the &%search_parents%& option in chapter &<<CHAPdnslookup>>& for more
24176 details.
24177
24178
24179 .option dnssec_request_domains smtp "domain list&!!" unset
24180 .cindex "MX record" "security"
24181 .cindex "DNSSEC" "MX lookup"
24182 .cindex "security" "MX lookup"
24183 .cindex "DNS" "DNSSEC"
24184 DNS lookups for domains matching &%dnssec_request_domains%& will be done with
24185 the dnssec request bit set.
24186 This applies to all of the SRV, MX, AAAA, A lookup sequence.
24187
24188
24189
24190 .option dnssec_require_domains smtp "domain list&!!" unset
24191 .cindex "MX record" "security"
24192 .cindex "DNSSEC" "MX lookup"
24193 .cindex "security" "MX lookup"
24194 .cindex "DNS" "DNSSEC"
24195 DNS lookups for domains matching &%dnssec_require_domains%& will be done with
24196 the dnssec request bit set.  Any returns not having the Authenticated Data bit
24197 (AD bit) set will be ignored and logged as a host-lookup failure.
24198 This applies to all of the SRV, MX, AAAA, A lookup sequence.
24199
24200
24201
24202 .option dscp smtp string&!! unset
24203 .cindex "DCSP" "outbound"
24204 This option causes the DSCP value associated with a socket to be set to one
24205 of a number of fixed strings or to numeric value.
24206 The &%-bI:dscp%& option may be used to ask Exim which names it knows of.
24207 Common values include &`throughput`&, &`mincost`&, and on newer systems
24208 &`ef`&, &`af41`&, etc.  Numeric values may be in the range 0 to 0x3F.
24209
24210 The outbound packets from Exim will be marked with this value in the header
24211 (for IPv4, the TOS field; for IPv6, the TCLASS field); there is no guarantee
24212 that these values will have any effect, not be stripped by networking
24213 equipment, or do much of anything without cooperation with your Network
24214 Engineer and those of all network operators between the source and destination.
24215
24216
24217 .option fallback_hosts smtp "string list" unset
24218 .cindex "fallback" "hosts specified on transport"
24219 String expansion is not applied to this option. The argument must be a
24220 colon-separated list of host names or IP addresses, optionally also including
24221 port numbers, though the separator can be changed, as described in section
24222 &<<SECTlistconstruct>>&. Each individual item in the list is the same as an
24223 item in a &%route_list%& setting for the &(manualroute)& router, as described
24224 in section &<<SECTformatonehostitem>>&.
24225
24226 Fallback hosts can also be specified on routers, which associate them with the
24227 addresses they process. As for the &%hosts%& option without &%hosts_override%&,
24228 &%fallback_hosts%& specified on the transport is used only if the address does
24229 not have its own associated fallback host list. Unlike &%hosts%&, a setting of
24230 &%fallback_hosts%& on an address is not overridden by &%hosts_override%&.
24231 However, &%hosts_randomize%& does apply to fallback host lists.
24232
24233 If Exim is unable to deliver to any of the hosts for a particular address, and
24234 the errors are not permanent rejections, the address is put on a separate
24235 transport queue with its host list replaced by the fallback hosts, unless the
24236 address was routed via MX records and the current host was in the original MX
24237 list. In that situation, the fallback host list is not used.
24238
24239 Once normal deliveries are complete, the fallback queue is delivered by
24240 re-running the same transports with the new host lists. If several failing
24241 addresses have the same fallback hosts (and &%max_rcpt%& permits it), a single
24242 copy of the message is sent.
24243
24244 The resolution of the host names on the fallback list is controlled by the
24245 &%gethostbyname%& option, as for the &%hosts%& option. Fallback hosts apply
24246 both to cases when the host list comes with the address and when it is taken
24247 from &%hosts%&. This option provides a &"use a smart host only if delivery
24248 fails"& facility.
24249
24250
24251 .option final_timeout smtp time 10m
24252 This is the timeout that applies while waiting for the response to the final
24253 line containing just &"."& that terminates a message. Its value must not be
24254 zero.
24255
24256 .option gethostbyname smtp boolean false
24257 If this option is true when the &%hosts%& and/or &%fallback_hosts%& options are
24258 being used, names are looked up using &[gethostbyname()]&
24259 (or &[getipnodebyname()]& when available)
24260 instead of using the DNS. Of course, that function may in fact use the DNS, but
24261 it may also consult other sources of information such as &_/etc/hosts_&.
24262
24263 .option gnutls_compat_mode smtp boolean unset
24264 This option controls whether GnuTLS is used in compatibility mode in an Exim
24265 server. This reduces security slightly, but improves interworking with older
24266 implementations of TLS.
24267
24268 .option helo_data smtp string&!! "see below"
24269 .cindex "HELO" "argument, setting"
24270 .cindex "EHLO" "argument, setting"
24271 .cindex "LHLO argument setting"
24272 The value of this option is expanded after a connection to a another host has
24273 been set up. The result is used as the argument for the EHLO, HELO, or LHLO
24274 command that starts the outgoing SMTP or LMTP session. The default value of the
24275 option is:
24276 .code
24277 $primary_hostname
24278 .endd
24279 During the expansion, the variables &$host$& and &$host_address$& are set to
24280 the identity of the remote host, and the variables &$sending_ip_address$& and
24281 &$sending_port$& are set to the local IP address and port number that are being
24282 used. These variables can be used to generate different values for different
24283 servers or different local IP addresses. For example, if you want the string
24284 that is used for &%helo_data%& to be obtained by a DNS lookup of the outgoing
24285 interface address, you could use this:
24286 .code
24287 helo_data = ${lookup dnsdb{ptr=$sending_ip_address}{$value}\
24288   {$primary_hostname}}
24289 .endd
24290 The use of &%helo_data%& applies both to sending messages and when doing
24291 callouts.
24292
24293 .option hosts smtp "string list&!!" unset
24294 Hosts are associated with an address by a router such as &(dnslookup)&, which
24295 finds the hosts by looking up the address domain in the DNS, or by
24296 &(manualroute)&, which has lists of hosts in its configuration. However,
24297 email addresses can be passed to the &(smtp)& transport by any router, and not
24298 all of them can provide an associated list of hosts.
24299
24300 The &%hosts%& option specifies a list of hosts to be used if the address being
24301 processed does not have any hosts associated with it. The hosts specified by
24302 &%hosts%& are also used, whether or not the address has its own hosts, if
24303 &%hosts_override%& is set.
24304
24305 The string is first expanded, before being interpreted as a colon-separated
24306 list of host names or IP addresses, possibly including port numbers. The
24307 separator may be changed to something other than colon, as described in section
24308 &<<SECTlistconstruct>>&. Each individual item in the list is the same as an
24309 item in a &%route_list%& setting for the &(manualroute)& router, as described
24310 in section &<<SECTformatonehostitem>>&. However, note that the &`/MX`& facility
24311 of the &(manualroute)& router is not available here.
24312
24313 If the expansion fails, delivery is deferred. Unless the failure was caused by
24314 the inability to complete a lookup, the error is logged to the panic log as
24315 well as the main log. Host names are looked up either by searching directly for
24316 address records in the DNS or by calling &[gethostbyname()]& (or
24317 &[getipnodebyname()]& when available), depending on the setting of the
24318 &%gethostbyname%& option. When Exim is compiled with IPv6 support, if a host
24319 that is looked up in the DNS has both IPv4 and IPv6 addresses, both types of
24320 address are used.
24321
24322 During delivery, the hosts are tried in order, subject to their retry status,
24323 unless &%hosts_randomize%& is set.
24324
24325
24326 .option hosts_avoid_esmtp smtp "host list&!!" unset
24327 .cindex "ESMTP, avoiding use of"
24328 .cindex "HELO" "forcing use of"
24329 .cindex "EHLO" "avoiding use of"
24330 .cindex "PIPELINING" "avoiding the use of"
24331 This option is for use with broken hosts that announce ESMTP facilities (for
24332 example, PIPELINING) and then fail to implement them properly. When a host
24333 matches &%hosts_avoid_esmtp%&, Exim sends HELO rather than EHLO at the
24334 start of the SMTP session. This means that it cannot use any of the ESMTP
24335 facilities such as AUTH, PIPELINING, SIZE, and STARTTLS.
24336
24337
24338 .option hosts_avoid_pipelining smtp "host list&!!" unset
24339 .cindex "PIPELINING" "avoiding the use of"
24340 Exim will not use the SMTP PIPELINING extension when delivering to any host
24341 that matches this list, even if the server host advertises PIPELINING support.
24342
24343
24344 .option hosts_avoid_tls smtp "host list&!!" unset
24345 .cindex "TLS" "avoiding for certain hosts"
24346 Exim will not try to start a TLS session when delivering to any host that
24347 matches this list. See chapter &<<CHAPTLS>>& for details of TLS.
24348
24349 .option hosts_verify_avoid_tls smtp "host list&!!" unset
24350 .cindex "TLS" "avoiding for certain hosts"
24351 Exim will not try to start a TLS session for a verify callout,
24352 or when delivering in cutthrough mode,
24353 to any host that matches this list.
24354
24355
24356 .option hosts_max_try smtp integer 5
24357 .cindex "host" "maximum number to try"
24358 .cindex "limit" "number of hosts tried"
24359 .cindex "limit" "number of MX tried"
24360 .cindex "MX record" "maximum tried"
24361 This option limits the number of IP addresses that are tried for any one
24362 delivery in cases where there are temporary delivery errors. Section
24363 &<<SECTvalhosmax>>& describes in detail how the value of this option is used.
24364
24365
24366 .option hosts_max_try_hardlimit smtp integer 50
24367 This is an additional check on the maximum number of IP addresses that Exim
24368 tries for any one delivery. Section &<<SECTvalhosmax>>& describes its use and
24369 why it exists.
24370
24371
24372
24373 .option hosts_nopass_tls smtp "host list&!!" unset
24374 .cindex "TLS" "passing connection"
24375 .cindex "multiple SMTP deliveries"
24376 .cindex "TLS" "multiple message deliveries"
24377 For any host that matches this list, a connection on which a TLS session has
24378 been started will not be passed to a new delivery process for sending another
24379 message on the same connection. See section &<<SECTmulmessam>>& for an
24380 explanation of when this might be needed.
24381
24382 .option hosts_noproxy_tls smtp "host list&!!" *
24383 .cindex "TLS" "passing connection"
24384 .cindex "multiple SMTP deliveries"
24385 .cindex "TLS" "multiple message deliveries"
24386 For any host that matches this list, a TLS session which has
24387 been started will not be passed to a new delivery process for sending another
24388 message on the same session.
24389
24390 The traditional implementation closes down TLS and re-starts it in the new
24391 process, on the same open TCP connection, for each successive message
24392 sent.  If permitted by this option a pipe to to the new process is set up
24393 instead, and the original process maintains the TLS connection and proxies
24394 the SMTP connection from and to the new process and any subsequents.
24395 The new process has no access to TLS information, so cannot include it in
24396 logging.
24397
24398
24399
24400 .option hosts_override smtp boolean false
24401 If this option is set and the &%hosts%& option is also set, any hosts that are
24402 attached to the address are ignored, and instead the hosts specified by the
24403 &%hosts%& option are always used. This option does not apply to
24404 &%fallback_hosts%&.
24405
24406
24407 .option hosts_randomize smtp boolean false
24408 .cindex "randomized host list"
24409 .cindex "host" "list of; randomized"
24410 .cindex "fallback" "randomized hosts"
24411 If this option is set, and either the list of hosts is taken from the
24412 &%hosts%& or the &%fallback_hosts%& option, or the hosts supplied by the router
24413 were not obtained from MX records (this includes fallback hosts from the
24414 router), and were not randomized by the router, the order of trying the hosts
24415 is randomized each time the transport runs. Randomizing the order of a host
24416 list can be used to do crude load sharing.
24417
24418 When &%hosts_randomize%& is true, a host list may be split into groups whose
24419 order is separately randomized. This makes it possible to set up MX-like
24420 behaviour. The boundaries between groups are indicated by an item that is just
24421 &`+`& in the host list. For example:
24422 .code
24423 hosts = host1:host2:host3:+:host4:host5
24424 .endd
24425 The order of the first three hosts and the order of the last two hosts is
24426 randomized for each use, but the first three always end up before the last two.
24427 If &%hosts_randomize%& is not set, a &`+`& item in the list is ignored.
24428
24429 .option hosts_require_auth smtp "host list&!!" unset
24430 .cindex "authentication" "required by client"
24431 This option provides a list of servers for which authentication must succeed
24432 before Exim will try to transfer a message. If authentication fails for
24433 servers which are not in this list, Exim tries to send unauthenticated. If
24434 authentication fails for one of these servers, delivery is deferred. This
24435 temporary error is detectable in the retry rules, so it can be turned into a
24436 hard failure if required. See also &%hosts_try_auth%&, and chapter
24437 &<<CHAPSMTPAUTH>>& for details of authentication.
24438
24439
24440 .option hosts_request_ocsp smtp "host list&!!" *
24441 .cindex "TLS" "requiring for certain servers"
24442 Exim will request a Certificate Status on a
24443 TLS session for any host that matches this list.
24444 &%tls_verify_certificates%& should also be set for the transport.
24445
24446 .option hosts_require_dane smtp "host list&!!" unset
24447 .cindex DANE "transport options"
24448 .cindex DANE "requiring for certain servers"
24449 If built with DANE support, Exim  will require that a DNSSEC-validated
24450 TLSA record is present for any host matching the list,
24451 and that a DANE-verified TLS connection is made.
24452 There will be no fallback to in-clear communication.
24453 See section &<<SECDANE>>&.
24454
24455 .option hosts_require_ocsp smtp "host list&!!" unset
24456 .cindex "TLS" "requiring for certain servers"
24457 Exim will request, and check for a valid Certificate Status being given, on a
24458 TLS session for any host that matches this list.
24459 &%tls_verify_certificates%& should also be set for the transport.
24460
24461 .option hosts_require_tls smtp "host list&!!" unset
24462 .cindex "TLS" "requiring for certain servers"
24463 Exim will insist on using a TLS session when delivering to any host that
24464 matches this list. See chapter &<<CHAPTLS>>& for details of TLS.
24465 &*Note*&: This option affects outgoing mail only. To insist on TLS for
24466 incoming messages, use an appropriate ACL.
24467
24468 .option hosts_try_auth smtp "host list&!!" unset
24469 .cindex "authentication" "optional in client"
24470 This option provides a list of servers to which, provided they announce
24471 authentication support, Exim will attempt to authenticate as a client when it
24472 connects. If authentication fails, Exim will try to transfer the message
24473 unauthenticated. See also &%hosts_require_auth%&, and chapter
24474 &<<CHAPSMTPAUTH>>& for details of authentication.
24475
24476 .option hosts_try_chunking smtp "host list&!!" *
24477 .cindex CHUNKING "enabling, in client"
24478 .cindex BDAT "SMTP command"
24479 .cindex "RFC 3030" "CHUNKING"
24480 This option provides a list of servers to which, provided they announce
24481 CHUNKING support, Exim will attempt to use BDAT commands rather than DATA.
24482 BDAT will not be used in conjunction with a transport filter.
24483
24484 .option hosts_try_dane smtp "host list&!!" unset
24485 .cindex DANE "transport options"
24486 .cindex DANE "attempting for certain servers"
24487 If built with DANE support, Exim  will lookup a
24488 TLSA record for any host matching the list.
24489 If found and verified by DNSSEC,
24490 a DANE-verified TLS connection is made to that host;
24491 there will be no fallback to in-clear communication.
24492 See section &<<SECDANE>>&.
24493
24494 .option hosts_try_fastopen smtp "host list&!!" unset
24495 .cindex "fast open, TCP" "enabling, in client"
24496 .cindex "TCP Fast Open" "enabling, in client"
24497 .cindex "RFC 7413" "TCP Fast Open"
24498 This option provides a list of servers to which, provided
24499 the facility is supported by this system, Exim will attempt to
24500 perform a TCP Fast Open.
24501 No data is sent on the SYN segment but, if the remote server also
24502 supports the facility, it can send its SMTP banner immediately after
24503 the SYN,ACK segment.  This can save up to one round-trip time.
24504
24505 The facility is only active for previously-contacted servers,
24506 as the initiator must present a cookie in the SYN segment.
24507
24508 On (at least some) current Linux distributions the facility must be enabled
24509 in the kernel by the sysadmin before the support is usable.
24510 There is no option for control of the server side; if the system supports
24511 it it is always enabled.  Note that lengthy operations in the connect ACL,
24512 such as DNSBL lookups, will still delay the emission of the SMTP banner.
24513
24514 .option hosts_try_prdr smtp "host list&!!" *
24515 .cindex "PRDR" "enabling, optional in client"
24516 This option provides a list of servers to which, provided they announce
24517 PRDR support, Exim will attempt to negotiate PRDR
24518 for multi-recipient messages.
24519 The option can usually be left as default.
24520
24521 .option interface smtp "string list&!!" unset
24522 .cindex "bind IP address"
24523 .cindex "IP address" "binding"
24524 .vindex "&$host$&"
24525 .vindex "&$host_address$&"
24526 This option specifies which interface to bind to when making an outgoing SMTP
24527 call. The value is an IP address, not an interface name such as
24528 &`eth0`&. Do not confuse this with the interface address that was used when a
24529 message was received, which is in &$received_ip_address$&, formerly known as
24530 &$interface_address$&. The name was changed to minimize confusion with the
24531 outgoing interface address. There is no variable that contains an outgoing
24532 interface address because, unless it is set by this option, its value is
24533 unknown.
24534
24535 During the expansion of the &%interface%& option the variables &$host$& and
24536 &$host_address$& refer to the host to which a connection is about to be made
24537 during the expansion of the string. Forced expansion failure, or an empty
24538 string result causes the option to be ignored. Otherwise, after expansion, the
24539 string must be a list of IP addresses, colon-separated by default, but the
24540 separator can be changed in the usual way. For example:
24541 .code
24542 interface = <; 192.168.123.123 ; 3ffe:ffff:836f::fe86:a061
24543 .endd
24544 The first interface of the correct type (IPv4 or IPv6) is used for the outgoing
24545 connection. If none of them are the correct type, the option is ignored. If
24546 &%interface%& is not set, or is ignored, the system's IP functions choose which
24547 interface to use if the host has more than one.
24548
24549
24550 .option keepalive smtp boolean true
24551 .cindex "keepalive" "on outgoing connection"
24552 This option controls the setting of SO_KEEPALIVE on outgoing TCP/IP socket
24553 connections. When set, it causes the kernel to probe idle connections
24554 periodically, by sending packets with &"old"& sequence numbers. The other end
24555 of the connection should send a acknowledgment if the connection is still okay
24556 or a reset if the connection has been aborted. The reason for doing this is
24557 that it has the beneficial effect of freeing up certain types of connection
24558 that can get stuck when the remote host is disconnected without tidying up the
24559 TCP/IP call properly. The keepalive mechanism takes several hours to detect
24560 unreachable hosts.
24561
24562
24563 .option lmtp_ignore_quota smtp boolean false
24564 .cindex "LMTP" "ignoring quota errors"
24565 If this option is set true when the &%protocol%& option is set to &"lmtp"&, the
24566 string &`IGNOREQUOTA`& is added to RCPT commands, provided that the LMTP server
24567 has advertised support for IGNOREQUOTA in its response to the LHLO command.
24568
24569 .option max_rcpt smtp integer 100
24570 .cindex "RCPT" "maximum number of outgoing"
24571 This option limits the number of RCPT commands that are sent in a single
24572 SMTP message transaction. Each set of addresses is treated independently, and
24573 so can cause parallel connections to the same host if &%remote_max_parallel%&
24574 permits this.
24575
24576
24577 .option multi_domain smtp boolean&!! true
24578 .vindex "&$domain$&"
24579 When this option is set, the &(smtp)& transport can handle a number of
24580 addresses containing a mixture of different domains provided they all resolve
24581 to the same list of hosts. Turning the option off restricts the transport to
24582 handling only one domain at a time. This is useful if you want to use
24583 &$domain$& in an expansion for the transport, because it is set only when there
24584 is a single domain involved in a remote delivery.
24585
24586 It is expanded per-address and can depend on any of
24587 &$address_data$&, &$domain_data$&, &$local_part_data$&,
24588 &$host$&, &$host_address$& and &$host_port$&.
24589
24590 .option port smtp string&!! "see below"
24591 .cindex "port" "sending TCP/IP"
24592 .cindex "TCP/IP" "setting outgoing port"
24593 This option specifies the TCP/IP port on the server to which Exim connects.
24594 &*Note:*& Do not confuse this with the port that was used when a message was
24595 received, which is in &$received_port$&, formerly known as &$interface_port$&.
24596 The name was changed to minimize confusion with the outgoing port. There is no
24597 variable that contains an outgoing port.
24598
24599 If the value of this option begins with a digit it is taken as a port number;
24600 otherwise it is looked up using &[getservbyname()]&. The default value is
24601 normally &"smtp"&,
24602 but if &%protocol%& is set to &"lmtp"& the default is &"lmtp"&
24603 and if &%protocol%& is set to &"smtps"& the default is &"smtps"&.
24604 If the expansion fails, or if a port number cannot be found, delivery
24605 is deferred.
24606
24607 .new
24608 Note that at least one Linux distribution has been seen failing
24609 to put &"smtps"& in its &"/etc/services"& file, resulting is such deferrals.
24610 .wen
24611
24612
24613
24614 .option protocol smtp string smtp
24615 .cindex "LMTP" "over TCP/IP"
24616 .cindex "ssmtp protocol" "outbound"
24617 .cindex "TLS" "SSL-on-connect outbound"
24618 .vindex "&$port$&"
24619 If this option is set to &"lmtp"& instead of &"smtp"&, the default value for
24620 the &%port%& option changes to &"lmtp"&, and the transport operates the LMTP
24621 protocol (RFC 2033) instead of SMTP. This protocol is sometimes used for local
24622 deliveries into closed message stores. Exim also has support for running LMTP
24623 over a pipe to a local process &-- see chapter &<<CHAPLMTP>>&.
24624
24625 If this option is set to &"smtps"&, the default value for the &%port%& option
24626 changes to &"smtps"&, and the transport initiates TLS immediately after
24627 connecting, as an outbound SSL-on-connect, instead of using STARTTLS to upgrade.
24628 .new
24629 The Internet standards bodies used to strongly discourage use of this mode,
24630 but as of RFC 8314 it is perferred over STARTTLS for message submission
24631 (as distinct from MTA-MTA communication).
24632 .wen
24633
24634
24635 .option retry_include_ip_address smtp boolean&!! true
24636 Exim normally includes both the host name and the IP address in the key it
24637 constructs for indexing retry data after a temporary delivery failure. This
24638 means that when one of several IP addresses for a host is failing, it gets
24639 tried periodically (controlled by the retry rules), but use of the other IP
24640 addresses is not affected.
24641
24642 However, in some dialup environments hosts are assigned a different IP address
24643 each time they connect. In this situation the use of the IP address as part of
24644 the retry key leads to undesirable behaviour. Setting this option false causes
24645 Exim to use only the host name.
24646 Since it is expanded it can be made to depend on the host or domain.
24647
24648
24649 .option serialize_hosts smtp "host list&!!" unset
24650 .cindex "serializing connections"
24651 .cindex "host" "serializing connections"
24652 Because Exim operates in a distributed manner, if several messages for the same
24653 host arrive at around the same time, more than one simultaneous connection to
24654 the remote host can occur. This is not usually a problem except when there is a
24655 slow link between the hosts. In that situation it may be helpful to restrict
24656 Exim to one connection at a time. This can be done by setting
24657 &%serialize_hosts%& to match the relevant hosts.
24658
24659 .cindex "hints database" "serializing deliveries to a host"
24660 Exim implements serialization by means of a hints database in which a record is
24661 written whenever a process connects to one of the restricted hosts. The record
24662 is deleted when the connection is completed. Obviously there is scope for
24663 records to get left lying around if there is a system or program crash. To
24664 guard against this, Exim ignores any records that are more than six hours old.
24665
24666 If you set up this kind of serialization, you should also arrange to delete the
24667 relevant hints database whenever your system reboots. The names of the files
24668 start with &_misc_& and they are kept in the &_spool/db_& directory. There
24669 may be one or two files, depending on the type of DBM in use. The same files
24670 are used for ETRN serialization.
24671
24672 See also the &%max_parallel%& generic transport option.
24673
24674
24675 .option size_addition smtp integer 1024
24676 .cindex "SMTP" "SIZE"
24677 .cindex "message" "size issue for transport filter"
24678 .cindex "size" "of message"
24679 .cindex "transport" "filter"
24680 .cindex "filter" "transport filter"
24681 If a remote SMTP server indicates that it supports the SIZE option of the
24682 MAIL command, Exim uses this to pass over the message size at the start of
24683 an SMTP transaction. It adds the value of &%size_addition%& to the value it
24684 sends, to allow for headers and other text that may be added during delivery by
24685 configuration options or in a transport filter. It may be necessary to increase
24686 this if a lot of text is added to messages.
24687
24688 Alternatively, if the value of &%size_addition%& is set negative, it disables
24689 the use of the SIZE option altogether.
24690
24691
24692 .option socks_proxy smtp string&!! unset
24693 .cindex proxy SOCKS
24694 This option enables use of SOCKS proxies for connections made by the
24695 transport.  For details see section &<<SECTproxySOCKS>>&.
24696
24697
24698 .option tls_certificate smtp string&!! unset
24699 .cindex "TLS" "client certificate, location of"
24700 .cindex "certificate" "client, location of"
24701 .vindex "&$host$&"
24702 .vindex "&$host_address$&"
24703 The value of this option must be the absolute path to a file which contains the
24704 client's certificate, for possible use when sending a message over an encrypted
24705 connection. The values of &$host$& and &$host_address$& are set to the name and
24706 address of the server during the expansion. See chapter &<<CHAPTLS>>& for
24707 details of TLS.
24708
24709 &*Note*&: This option must be set if you want Exim to be able to use a TLS
24710 certificate when sending messages as a client. The global option of the same
24711 name specifies the certificate for Exim as a server; it is not automatically
24712 assumed that the same certificate should be used when Exim is operating as a
24713 client.
24714
24715
24716 .option tls_crl smtp string&!! unset
24717 .cindex "TLS" "client certificate revocation list"
24718 .cindex "certificate" "revocation list for client"
24719 This option specifies a certificate revocation list. The expanded value must
24720 be the name of a file that contains a CRL in PEM format.
24721
24722
24723 .option tls_dh_min_bits smtp integer 1024
24724 .cindex "TLS" "Diffie-Hellman minimum acceptable size"
24725 When establishing a TLS session, if a ciphersuite which uses Diffie-Hellman
24726 key agreement is negotiated, the server will provide a large prime number
24727 for use.  This option establishes the minimum acceptable size of that number.
24728 If the parameter offered by the server is too small, then the TLS handshake
24729 will fail.
24730
24731 Only supported when using GnuTLS.
24732
24733
24734 .option tls_privatekey smtp string&!! unset
24735 .cindex "TLS" "client private key, location of"
24736 .vindex "&$host$&"
24737 .vindex "&$host_address$&"
24738 The value of this option must be the absolute path to a file which contains the
24739 client's private key. This is used when sending a message over an encrypted
24740 connection using a client certificate. The values of &$host$& and
24741 &$host_address$& are set to the name and address of the server during the
24742 expansion. If this option is unset, or the expansion is forced to fail, or the
24743 result is an empty string, the private key is assumed to be in the same file as
24744 the certificate. See chapter &<<CHAPTLS>>& for details of TLS.
24745
24746
24747 .option tls_require_ciphers smtp string&!! unset
24748 .cindex "TLS" "requiring specific ciphers"
24749 .cindex "cipher" "requiring specific"
24750 .vindex "&$host$&"
24751 .vindex "&$host_address$&"
24752 The value of this option must be a list of permitted cipher suites, for use
24753 when setting up an outgoing encrypted connection. (There is a global option of
24754 the same name for controlling incoming connections.) The values of &$host$& and
24755 &$host_address$& are set to the name and address of the server during the
24756 expansion. See chapter &<<CHAPTLS>>& for details of TLS; note that this option
24757 is used in different ways by OpenSSL and GnuTLS (see sections
24758 &<<SECTreqciphssl>>& and &<<SECTreqciphgnu>>&). For GnuTLS, the order of the
24759 ciphers is a preference order.
24760
24761
24762
24763 .option tls_sni smtp string&!! unset
24764 .cindex "TLS" "Server Name Indication"
24765 .vindex "&$tls_sni$&"
24766 If this option is set then it sets the $tls_out_sni variable and causes any
24767 TLS session to pass this value as the Server Name Indication extension to
24768 the remote side, which can be used by the remote side to select an appropriate
24769 certificate and private key for the session.
24770
24771 See &<<SECTtlssni>>& for more information.
24772
24773 Note that for OpenSSL, this feature requires a build of OpenSSL that supports
24774 TLS extensions.
24775
24776
24777
24778
24779 .option tls_tempfail_tryclear smtp boolean true
24780 .cindex "4&'xx'& responses" "to STARTTLS"
24781 When the server host is not in &%hosts_require_tls%&, and there is a problem in
24782 setting up a TLS session, this option determines whether or not Exim should try
24783 to deliver the message unencrypted. If it is set false, delivery to the
24784 current host is deferred; if there are other hosts, they are tried. If this
24785 option is set true, Exim attempts to deliver unencrypted after a 4&'xx'&
24786 response to STARTTLS. Also, if STARTTLS is accepted, but the subsequent
24787 TLS negotiation fails, Exim closes the current connection (because it is in an
24788 unknown state), opens a new one to the same host, and then tries the delivery
24789 in clear.
24790
24791
24792 .option tls_try_verify_hosts smtp "host list&!!" *
24793 .cindex "TLS" "server certificate verification"
24794 .cindex "certificate" "verification of server"
24795 This option gives a list of hosts for which, on encrypted connections,
24796 certificate verification will be tried but need not succeed.
24797 The &%tls_verify_certificates%& option must also be set.
24798 Note that unless the host is in this list
24799 TLS connections will be denied to hosts using self-signed certificates
24800 when &%tls_verify_certificates%& is matched.
24801 The &$tls_out_certificate_verified$& variable is set when
24802 certificate verification succeeds.
24803
24804
24805 .option tls_verify_cert_hostnames smtp "host list&!!" *
24806 .cindex "TLS" "server certificate hostname verification"
24807 .cindex "certificate" "verification of server"
24808 This option give a list of hosts for which,
24809 while verifying the server certificate,
24810 checks will be included on the host name
24811 (note that this will generally be the result of a DNS MX lookup)
24812 versus Subject and Subject-Alternate-Name fields.  Wildcard names are permitted
24813 limited to being the initial component of a 3-or-more component FQDN.
24814
24815 There is no equivalent checking on client certificates.
24816
24817
24818 .option tls_verify_certificates smtp string&!! system
24819 .cindex "TLS" "server certificate verification"
24820 .cindex "certificate" "verification of server"
24821 .vindex "&$host$&"
24822 .vindex "&$host_address$&"
24823 The value of this option must be either the
24824 word "system"
24825 or the absolute path to
24826 a file or directory containing permitted certificates for servers,
24827 for use when setting up an encrypted connection.
24828
24829 The "system" value for the option will use a location compiled into the SSL library.
24830 This is not available for GnuTLS versions preceding 3.0.20; a value of "system"
24831 is taken as empty and an explicit location
24832 must be specified.
24833
24834 The use of a directory for the option value is not available for GnuTLS versions
24835 preceding 3.3.6 and a single file must be used.
24836
24837 With OpenSSL the certificates specified
24838 explicitly
24839 either by file or directory
24840 are added to those given by the system default location.
24841
24842 The values of &$host$& and
24843 &$host_address$& are set to the name and address of the server during the
24844 expansion of this option. See chapter &<<CHAPTLS>>& for details of TLS.
24845
24846 For back-compatibility,
24847 if neither tls_verify_hosts nor tls_try_verify_hosts are set
24848 (a single-colon empty list counts as being set)
24849 and certificate verification fails the TLS connection is closed.
24850
24851
24852 .option tls_verify_hosts smtp "host list&!!" unset
24853 .cindex "TLS" "server certificate verification"
24854 .cindex "certificate" "verification of server"
24855 This option gives a list of hosts for which, on encrypted connections,
24856 certificate verification must succeed.
24857 The &%tls_verify_certificates%& option must also be set.
24858 If both this option and &%tls_try_verify_hosts%& are unset
24859 operation is as if this option selected all hosts.
24860
24861 .new
24862 .option utf8_downconvert smtp integer!! unset
24863 .cindex utf8 "address downconversion"
24864 .cindex i18n "utf8 address downconversion"
24865 If built with internationalization support,
24866 this option controls conversion of UTF-8 in message addresses
24867 to a-label form.
24868 For details see section &<<SECTi18nMTA>>&.
24869 .wen
24870
24871
24872
24873
24874 .section "How the limits for the number of hosts to try are used" &&&
24875          "SECTvalhosmax"
24876 .cindex "host" "maximum number to try"
24877 .cindex "limit" "hosts; maximum number tried"
24878 There are two options that are concerned with the number of hosts that are
24879 tried when an SMTP delivery takes place. They are &%hosts_max_try%& and
24880 &%hosts_max_try_hardlimit%&.
24881
24882
24883 The &%hosts_max_try%& option limits the number of hosts that are tried
24884 for a single delivery. However, despite the term &"host"& in its name, the
24885 option actually applies to each IP address independently. In other words, a
24886 multihomed host is treated as several independent hosts, just as it is for
24887 retrying.
24888
24889 Many of the larger ISPs have multiple MX records which often point to
24890 multihomed hosts. As a result, a list of a dozen or more IP addresses may be
24891 created as a result of routing one of these domains.
24892
24893 Trying every single IP address on such a long list does not seem sensible; if
24894 several at the top of the list fail, it is reasonable to assume there is some
24895 problem that is likely to affect all of them. Roughly speaking, the value of
24896 &%hosts_max_try%& is the maximum number that are tried before deferring the
24897 delivery. However, the logic cannot be quite that simple.
24898
24899 Firstly, IP addresses that are skipped because their retry times have not
24900 arrived do not count, and in addition, addresses that are past their retry
24901 limits are also not counted, even when they are tried. This means that when
24902 some IP addresses are past their retry limits, more than the value of
24903 &%hosts_max_retry%& may be tried. The reason for this behaviour is to ensure
24904 that all IP addresses are considered before timing out an email address (but
24905 see below for an exception).
24906
24907 Secondly, when the &%hosts_max_try%& limit is reached, Exim looks down the host
24908 list to see if there is a subsequent host with a different (higher valued) MX.
24909 If there is, that host is considered next, and the current IP address is used
24910 but not counted. This behaviour helps in the case of a domain with a retry rule
24911 that hardly ever delays any hosts, as is now explained:
24912
24913 Consider the case of a long list of hosts with one MX value, and a few with a
24914 higher MX value. If &%hosts_max_try%& is small (the default is 5) only a few
24915 hosts at the top of the list are tried at first. With the default retry rule,
24916 which specifies increasing retry times, the higher MX hosts are eventually
24917 tried when those at the top of the list are skipped because they have not
24918 reached their retry times.
24919
24920 However, it is common practice to put a fixed short retry time on domains for
24921 large ISPs, on the grounds that their servers are rarely down for very long.
24922 Unfortunately, these are exactly the domains that tend to resolve to long lists
24923 of hosts. The short retry time means that the lowest MX hosts are tried every
24924 time. The attempts may be in a different order because of random sorting, but
24925 without the special MX check, the higher MX hosts would never be tried until
24926 all the lower MX hosts had timed out (which might be several days), because
24927 there are always some lower MX hosts that have reached their retry times. With
24928 the special check, Exim considers at least one IP address from each MX value at
24929 every delivery attempt, even if the &%hosts_max_try%& limit has already been
24930 reached.
24931
24932 The above logic means that &%hosts_max_try%& is not a hard limit, and in
24933 particular, Exim normally eventually tries all the IP addresses before timing
24934 out an email address. When &%hosts_max_try%& was implemented, this seemed a
24935 reasonable thing to do. Recently, however, some lunatic DNS configurations have
24936 been set up with hundreds of IP addresses for some domains. It can
24937 take a very long time indeed for an address to time out in these cases.
24938
24939 The &%hosts_max_try_hardlimit%& option was added to help with this problem.
24940 Exim never tries more than this number of IP addresses; if it hits this limit
24941 and they are all timed out, the email address is bounced, even though not all
24942 possible IP addresses have been tried.
24943 .ecindex IIDsmttra1
24944 .ecindex IIDsmttra2
24945
24946
24947
24948
24949
24950 . ////////////////////////////////////////////////////////////////////////////
24951 . ////////////////////////////////////////////////////////////////////////////
24952
24953 .chapter "Address rewriting" "CHAPrewrite"
24954 .scindex IIDaddrew "rewriting" "addresses"
24955 There are some circumstances in which Exim automatically rewrites domains in
24956 addresses. The two most common are when an address is given without a domain
24957 (referred to as an &"unqualified address"&) or when an address contains an
24958 abbreviated domain that is expanded by DNS lookup.
24959
24960 Unqualified envelope addresses are accepted only for locally submitted
24961 messages, or for messages that are received from hosts matching
24962 &%sender_unqualified_hosts%& or &%recipient_unqualified_hosts%&, as
24963 appropriate. Unqualified addresses in header lines are qualified if they are in
24964 locally submitted messages, or messages from hosts that are permitted to send
24965 unqualified envelope addresses. Otherwise, unqualified addresses in header
24966 lines are neither qualified nor rewritten.
24967
24968 One situation in which Exim does &'not'& automatically rewrite a domain is
24969 when it is the name of a CNAME record in the DNS. The older RFCs suggest that
24970 such a domain should be rewritten using the &"canonical"& name, and some MTAs
24971 do this. The new RFCs do not contain this suggestion.
24972
24973
24974 .section "Explicitly configured address rewriting" "SECID147"
24975 This chapter describes the rewriting rules that can be used in the
24976 main rewrite section of the configuration file, and also in the generic
24977 &%headers_rewrite%& option that can be set on any transport.
24978
24979 Some people believe that configured address rewriting is a Mortal Sin.
24980 Others believe that life is not possible without it. Exim provides the
24981 facility; you do not have to use it.
24982
24983 The main rewriting rules that appear in the &"rewrite"& section of the
24984 configuration file are applied to addresses in incoming messages, both envelope
24985 addresses and addresses in header lines. Each rule specifies the types of
24986 address to which it applies.
24987
24988 Whether or not addresses in header lines are rewritten depends on the origin of
24989 the headers and the type of rewriting. Global rewriting, that is, rewriting
24990 rules from the rewrite section of the configuration file, is applied only to
24991 those headers that were received with the message. Header lines that are added
24992 by ACLs or by a system filter or by individual routers or transports (which
24993 are specific to individual recipient addresses) are not rewritten by the global
24994 rules.
24995
24996 Rewriting at transport time, by means of the &%headers_rewrite%& option,
24997 applies all headers except those added by routers and transports. That is, as
24998 well as the headers that were received with the message, it also applies to
24999 headers that were added by an ACL or a system filter.
25000
25001
25002 In general, rewriting addresses from your own system or domain has some
25003 legitimacy. Rewriting other addresses should be done only with great care and
25004 in special circumstances. The author of Exim believes that rewriting should be
25005 used sparingly, and mainly for &"regularizing"& addresses in your own domains.
25006 Although it can sometimes be used as a routing tool, this is very strongly
25007 discouraged.
25008
25009 There are two commonly encountered circumstances where rewriting is used, as
25010 illustrated by these examples:
25011
25012 .ilist
25013 The company whose domain is &'hitch.fict.example'& has a number of hosts that
25014 exchange mail with each other behind a firewall, but there is only a single
25015 gateway to the outer world. The gateway rewrites &'*.hitch.fict.example'& as
25016 &'hitch.fict.example'& when sending mail off-site.
25017 .next
25018 A host rewrites the local parts of its own users so that, for example,
25019 &'fp42@hitch.fict.example'& becomes &'Ford.Prefect@hitch.fict.example'&.
25020 .endlist
25021
25022
25023
25024 .section "When does rewriting happen?" "SECID148"
25025 .cindex "rewriting" "timing of"
25026 .cindex "&ACL;" "rewriting addresses in"
25027 Configured address rewriting can take place at several different stages of a
25028 message's processing.
25029
25030 .vindex "&$sender_address$&"
25031 At the start of an ACL for MAIL, the sender address may have been rewritten
25032 by a special SMTP-time rewrite rule (see section &<<SECTrewriteS>>&), but no
25033 ordinary rewrite rules have yet been applied. If, however, the sender address
25034 is verified in the ACL, it is rewritten before verification, and remains
25035 rewritten thereafter. The subsequent value of &$sender_address$& is the
25036 rewritten address. This also applies if sender verification happens in a
25037 RCPT ACL. Otherwise, when the sender address is not verified, it is
25038 rewritten as soon as a message's header lines have been received.
25039
25040 .vindex "&$domain$&"
25041 .vindex "&$local_part$&"
25042 Similarly, at the start of an ACL for RCPT, the current recipient's address
25043 may have been rewritten by a special SMTP-time rewrite rule, but no ordinary
25044 rewrite rules have yet been applied to it. However, the behaviour is different
25045 from the sender address when a recipient is verified. The address is rewritten
25046 for the verification, but the rewriting is not remembered at this stage. The
25047 value of &$local_part$& and &$domain$& after verification are always the same
25048 as they were before (that is, they contain the unrewritten &-- except for
25049 SMTP-time rewriting &-- address).
25050
25051 As soon as a message's header lines have been received, all the envelope
25052 recipient addresses are permanently rewritten, and rewriting is also applied to
25053 the addresses in the header lines (if configured). This happens before adding
25054 any header lines that were specified in MAIL or RCPT ACLs, and
25055 .cindex "&[local_scan()]& function" "address rewriting; timing of"
25056 before the DATA ACL and &[local_scan()]& functions are run.
25057
25058 When an address is being routed, either for delivery or for verification,
25059 rewriting is applied immediately to child addresses that are generated by
25060 redirection, unless &%no_rewrite%& is set on the router.
25061
25062 .cindex "envelope sender" "rewriting at transport time"
25063 .cindex "rewriting" "at transport time"
25064 .cindex "header lines" "rewriting at transport time"
25065 At transport time, additional rewriting of addresses in header lines can be
25066 specified by setting the generic &%headers_rewrite%& option on a transport.
25067 This option contains rules that are identical in form to those in the rewrite
25068 section of the configuration file. They are applied to the original message
25069 header lines and any that were added by ACLs or a system filter. They are not
25070 applied to header lines that are added by routers or the transport.
25071
25072 The outgoing envelope sender can be rewritten by means of the &%return_path%&
25073 transport option. However, it is not possible to rewrite envelope recipients at
25074 transport time.
25075
25076
25077
25078
25079 .section "Testing the rewriting rules that apply on input" "SECID149"
25080 .cindex "rewriting" "testing"
25081 .cindex "testing" "rewriting"
25082 Exim's input rewriting configuration appears in a part of the run time
25083 configuration file headed by &"begin rewrite"&. It can be tested by the
25084 &%-brw%& command line option. This takes an address (which can be a full RFC
25085 2822 address) as its argument. The output is a list of how the address would be
25086 transformed by the rewriting rules for each of the different places it might
25087 appear in an incoming message, that is, for each different header and for the
25088 envelope sender and recipient fields. For example,
25089 .code
25090 exim -brw ph10@exim.workshop.example
25091 .endd
25092 might produce the output
25093 .code
25094 sender: Philip.Hazel@exim.workshop.example
25095 from: Philip.Hazel@exim.workshop.example
25096 to: ph10@exim.workshop.example
25097 cc: ph10@exim.workshop.example
25098 bcc: ph10@exim.workshop.example
25099 reply-to: Philip.Hazel@exim.workshop.example
25100 env-from: Philip.Hazel@exim.workshop.example
25101 env-to: ph10@exim.workshop.example
25102 .endd
25103 which shows that rewriting has been set up for that address when used in any of
25104 the source fields, but not when it appears as a recipient address. At the
25105 present time, there is no equivalent way of testing rewriting rules that are
25106 set for a particular transport.
25107
25108
25109 .section "Rewriting rules" "SECID150"
25110 .cindex "rewriting" "rules"
25111 The rewrite section of the configuration file consists of lines of rewriting
25112 rules in the form
25113 .display
25114 <&'source pattern'&>  <&'replacement'&>  <&'flags'&>
25115 .endd
25116 Rewriting rules that are specified for the &%headers_rewrite%& generic
25117 transport option are given as a colon-separated list. Each item in the list
25118 takes the same form as a line in the main rewriting configuration (except that
25119 any colons must be doubled, of course).
25120
25121 The formats of source patterns and replacement strings are described below.
25122 Each is terminated by white space, unless enclosed in double quotes, in which
25123 case normal quoting conventions apply inside the quotes. The flags are single
25124 characters which may appear in any order. Spaces and tabs between them are
25125 ignored.
25126
25127 For each address that could potentially be rewritten, the rules are scanned in
25128 order, and replacements for the address from earlier rules can themselves be
25129 replaced by later rules (but see the &"q"& and &"R"& flags).
25130
25131 The order in which addresses are rewritten is undefined, may change between
25132 releases, and must not be relied on, with one exception: when a message is
25133 received, the envelope sender is always rewritten first, before any header
25134 lines are rewritten. For example, the replacement string for a rewrite of an
25135 address in &'To:'& must not assume that the message's address in &'From:'& has
25136 (or has not) already been rewritten. However, a rewrite of &'From:'& may assume
25137 that the envelope sender has already been rewritten.
25138
25139 .vindex "&$domain$&"
25140 .vindex "&$local_part$&"
25141 The variables &$local_part$& and &$domain$& can be used in the replacement
25142 string to refer to the address that is being rewritten. Note that lookup-driven
25143 rewriting can be done by a rule of the form
25144 .code
25145 *@*   ${lookup ...
25146 .endd
25147 where the lookup key uses &$1$& and &$2$& or &$local_part$& and &$domain$& to
25148 refer to the address that is being rewritten.
25149
25150
25151 .section "Rewriting patterns" "SECID151"
25152 .cindex "rewriting" "patterns"
25153 .cindex "address list" "in a rewriting pattern"
25154 The source pattern in a rewriting rule is any item which may appear in an
25155 address list (see section &<<SECTaddresslist>>&). It is in fact processed as a
25156 single-item address list, which means that it is expanded before being tested
25157 against the address. As always, if you use a regular expression as a pattern,
25158 you must take care to escape dollar and backslash characters, or use the &`\N`&
25159 facility to suppress string expansion within the regular expression.
25160
25161 Domains in patterns should be given in lower case. Local parts in patterns are
25162 case-sensitive. If you want to do case-insensitive matching of local parts, you
25163 can use a regular expression that starts with &`^(?i)`&.
25164
25165 .cindex "numerical variables (&$1$& &$2$& etc)" "in rewriting rules"
25166 After matching, the numerical variables &$1$&, &$2$&, etc. may be set,
25167 depending on the type of match which occurred. These can be used in the
25168 replacement string to insert portions of the incoming address. &$0$& always
25169 refers to the complete incoming address. When a regular expression is used, the
25170 numerical variables are set from its capturing subexpressions. For other types
25171 of pattern they are set as follows:
25172
25173 .ilist
25174 If a local part or domain starts with an asterisk, the numerical variables
25175 refer to the character strings matched by asterisks, with &$1$& associated with
25176 the first asterisk, and &$2$& with the second, if present. For example, if the
25177 pattern
25178 .code
25179 *queen@*.fict.example
25180 .endd
25181 is matched against the address &'hearts-queen@wonderland.fict.example'& then
25182 .code
25183 $0 = hearts-queen@wonderland.fict.example
25184 $1 = hearts-
25185 $2 = wonderland
25186 .endd
25187 Note that if the local part does not start with an asterisk, but the domain
25188 does, it is &$1$& that contains the wild part of the domain.
25189
25190 .next
25191 If the domain part of the pattern is a partial lookup, the wild and fixed parts
25192 of the domain are placed in the next available numerical variables. Suppose,
25193 for example, that the address &'foo@bar.baz.example'& is processed by a
25194 rewriting rule of the form
25195 .display
25196 &`*@partial-dbm;/some/dbm/file`&    <&'replacement string'&>
25197 .endd
25198 and the key in the file that matches the domain is &`*.baz.example`&. Then
25199 .code
25200 $1 = foo
25201 $2 = bar
25202 $3 = baz.example
25203 .endd
25204 If the address &'foo@baz.example'& is looked up, this matches the same
25205 wildcard file entry, and in this case &$2$& is set to the empty string, but
25206 &$3$& is still set to &'baz.example'&. If a non-wild key is matched in a
25207 partial lookup, &$2$& is again set to the empty string and &$3$& is set to the
25208 whole domain. For non-partial domain lookups, no numerical variables are set.
25209 .endlist
25210
25211
25212 .section "Rewriting replacements" "SECID152"
25213 .cindex "rewriting" "replacements"
25214 If the replacement string for a rule is a single asterisk, addresses that
25215 match the pattern and the flags are &'not'& rewritten, and no subsequent
25216 rewriting rules are scanned. For example,
25217 .code
25218 hatta@lookingglass.fict.example  *  f
25219 .endd
25220 specifies that &'hatta@lookingglass.fict.example'& is never to be rewritten in
25221 &'From:'& headers.
25222
25223 .vindex "&$domain$&"
25224 .vindex "&$local_part$&"
25225 If the replacement string is not a single asterisk, it is expanded, and must
25226 yield a fully qualified address. Within the expansion, the variables
25227 &$local_part$& and &$domain$& refer to the address that is being rewritten.
25228 Any letters they contain retain their original case &-- they are not lower
25229 cased. The numerical variables are set up according to the type of pattern that
25230 matched the address, as described above. If the expansion is forced to fail by
25231 the presence of &"fail"& in a conditional or lookup item, rewriting by the
25232 current rule is abandoned, but subsequent rules may take effect. Any other
25233 expansion failure causes the entire rewriting operation to be abandoned, and an
25234 entry written to the panic log.
25235
25236
25237
25238 .section "Rewriting flags" "SECID153"
25239 There are three different kinds of flag that may appear on rewriting rules:
25240
25241 .ilist
25242 Flags that specify which headers and envelope addresses to rewrite: E, F, T, b,
25243 c, f, h, r, s, t.
25244 .next
25245 A flag that specifies rewriting at SMTP time: S.
25246 .next
25247 Flags that control the rewriting process: Q, q, R, w.
25248 .endlist
25249
25250 For rules that are part of the &%headers_rewrite%& generic transport option,
25251 E, F, T, and S are not permitted.
25252
25253
25254
25255 .section "Flags specifying which headers and envelope addresses to rewrite" &&&
25256          "SECID154"
25257 .cindex "rewriting" "flags"
25258 If none of the following flag letters, nor the &"S"& flag (see section
25259 &<<SECTrewriteS>>&) are present, a main rewriting rule applies to all headers
25260 and to both the sender and recipient fields of the envelope, whereas a
25261 transport-time rewriting rule just applies to all headers. Otherwise, the
25262 rewriting rule is skipped unless the relevant addresses are being processed.
25263 .display
25264 &`E`&       rewrite all envelope fields
25265 &`F`&       rewrite the envelope From field
25266 &`T`&       rewrite the envelope To field
25267 &`b`&       rewrite the &'Bcc:'& header
25268 &`c`&       rewrite the &'Cc:'& header
25269 &`f`&       rewrite the &'From:'& header
25270 &`h`&       rewrite all headers
25271 &`r`&       rewrite the &'Reply-To:'& header
25272 &`s`&       rewrite the &'Sender:'& header
25273 &`t`&       rewrite the &'To:'& header
25274 .endd
25275 "All headers" means all of the headers listed above that can be selected
25276 individually, plus their &'Resent-'& versions. It does not include
25277 other headers such as &'Subject:'& etc.
25278
25279 You should be particularly careful about rewriting &'Sender:'& headers, and
25280 restrict this to special known cases in your own domains.
25281
25282
25283 .section "The SMTP-time rewriting flag" "SECTrewriteS"
25284 .cindex "SMTP" "rewriting malformed addresses"
25285 .cindex "RCPT" "rewriting argument of"
25286 .cindex "MAIL" "rewriting argument of"
25287 The rewrite flag &"S"& specifies a rewrite of incoming envelope addresses at
25288 SMTP time, as soon as an address is received in a MAIL or RCPT command, and
25289 before any other processing; even before syntax checking. The pattern is
25290 required to be a regular expression, and it is matched against the whole of the
25291 data for the command, including any surrounding angle brackets.
25292
25293 .vindex "&$domain$&"
25294 .vindex "&$local_part$&"
25295 This form of rewrite rule allows for the handling of addresses that are not
25296 compliant with RFCs 2821 and 2822 (for example, &"bang paths"& in batched SMTP
25297 input). Because the input is not required to be a syntactically valid address,
25298 the variables &$local_part$& and &$domain$& are not available during the
25299 expansion of the replacement string. The result of rewriting replaces the
25300 original address in the MAIL or RCPT command.
25301
25302
25303 .section "Flags controlling the rewriting process" "SECID155"
25304 There are four flags which control the way the rewriting process works. These
25305 take effect only when a rule is invoked, that is, when the address is of the
25306 correct type (matches the flags) and matches the pattern:
25307
25308 .ilist
25309 If the &"Q"& flag is set on a rule, the rewritten address is permitted to be an
25310 unqualified local part. It is qualified with &%qualify_recipient%&. In the
25311 absence of &"Q"& the rewritten address must always include a domain.
25312 .next
25313 If the &"q"& flag is set on a rule, no further rewriting rules are considered,
25314 even if no rewriting actually takes place because of a &"fail"& in the
25315 expansion. The &"q"& flag is not effective if the address is of the wrong type
25316 (does not match the flags) or does not match the pattern.
25317 .next
25318 The &"R"& flag causes a successful rewriting rule to be re-applied to the new
25319 address, up to ten times. It can be combined with the &"q"& flag, to stop
25320 rewriting once it fails to match (after at least one successful rewrite).
25321 .next
25322 .cindex "rewriting" "whole addresses"
25323 When an address in a header is rewritten, the rewriting normally applies only
25324 to the working part of the address, with any comments and RFC 2822 &"phrase"&
25325 left unchanged. For example, rewriting might change
25326 .code
25327 From: Ford Prefect <fp42@restaurant.hitch.fict.example>
25328 .endd
25329 into
25330 .code
25331 From: Ford Prefect <prefectf@hitch.fict.example>
25332 .endd
25333 .cindex "RFC 2047"
25334 Sometimes there is a need to replace the whole address item, and this can be
25335 done by adding the flag letter &"w"& to a rule. If this is set on a rule that
25336 causes an address in a header line to be rewritten, the entire address is
25337 replaced, not just the working part. The replacement must be a complete RFC
25338 2822 address, including the angle brackets if necessary. If text outside angle
25339 brackets contains a character whose value is greater than 126 or less than 32
25340 (except for tab), the text is encoded according to RFC 2047. The character set
25341 is taken from &%headers_charset%&, which gets its default at build time.
25342
25343 When the &"w"& flag is set on a rule that causes an envelope address to be
25344 rewritten, all but the working part of the replacement address is discarded.
25345 .endlist
25346
25347
25348 .section "Rewriting examples" "SECID156"
25349 Here is an example of the two common rewriting paradigms:
25350 .code
25351 *@*.hitch.fict.example  $1@hitch.fict.example
25352 *@hitch.fict.example    ${lookup{$1}dbm{/etc/realnames}\
25353                      {$value}fail}@hitch.fict.example bctfrF
25354 .endd
25355 Note the use of &"fail"& in the lookup expansion in the second rule, forcing
25356 the string expansion to fail if the lookup does not succeed. In this context it
25357 has the effect of leaving the original address unchanged, but Exim goes on to
25358 consider subsequent rewriting rules, if any, because the &"q"& flag is not
25359 present in that rule. An alternative to &"fail"& would be to supply &$1$&
25360 explicitly, which would cause the rewritten address to be the same as before,
25361 at the cost of a small bit of processing. Not supplying either of these is an
25362 error, since the rewritten address would then contain no local part.
25363
25364 The first example above replaces the domain with a superior, more general
25365 domain. This may not be desirable for certain local parts. If the rule
25366 .code
25367 root@*.hitch.fict.example  *
25368 .endd
25369 were inserted before the first rule, rewriting would be suppressed for the
25370 local part &'root'& at any domain ending in &'hitch.fict.example'&.
25371
25372 Rewriting can be made conditional on a number of tests, by making use of
25373 &${if$& in the expansion item. For example, to apply a rewriting rule only to
25374 messages that originate outside the local host:
25375 .code
25376 *@*.hitch.fict.example  "${if !eq {$sender_host_address}{}\
25377                          {$1@hitch.fict.example}fail}"
25378 .endd
25379 The replacement string is quoted in this example because it contains white
25380 space.
25381
25382 .cindex "rewriting" "bang paths"
25383 .cindex "bang paths" "rewriting"
25384 Exim does not handle addresses in the form of &"bang paths"&. If it sees such
25385 an address it treats it as an unqualified local part which it qualifies with
25386 the local qualification domain (if the source of the message is local or if the
25387 remote host is permitted to send unqualified addresses). Rewriting can
25388 sometimes be used to handle simple bang paths with a fixed number of
25389 components. For example, the rule
25390 .code
25391 \N^([^!]+)!(.*)@your.domain.example$\N   $2@$1
25392 .endd
25393 rewrites a two-component bang path &'host.name!user'& as the domain address
25394 &'user@host.name'&. However, there is a security implication in using this as
25395 a global rewriting rule for envelope addresses. It can provide a backdoor
25396 method for using your system as a relay, because the incoming addresses appear
25397 to be local. If the bang path addresses are received via SMTP, it is safer to
25398 use the &"S"& flag to rewrite them as they are received, so that relay checking
25399 can be done on the rewritten addresses.
25400 .ecindex IIDaddrew
25401
25402
25403
25404
25405
25406 . ////////////////////////////////////////////////////////////////////////////
25407 . ////////////////////////////////////////////////////////////////////////////
25408
25409 .chapter "Retry configuration" "CHAPretry"
25410 .scindex IIDretconf1 "retry" "configuration, description of"
25411 .scindex IIDregconf2 "configuration file" "retry section"
25412 The &"retry"& section of the runtime configuration file contains a list of
25413 retry rules that control how often Exim tries to deliver messages that cannot
25414 be delivered at the first attempt. If there are no retry rules (the section is
25415 empty or not present), there are no retries. In this situation, temporary
25416 errors are treated as permanent. The default configuration contains a single,
25417 general-purpose retry rule (see section &<<SECID57>>&). The &%-brt%& command
25418 line option can be used to test which retry rule will be used for a given
25419 address, domain and error.
25420
25421 The most common cause of retries is temporary failure to deliver to a remote
25422 host because the host is down, or inaccessible because of a network problem.
25423 Exim's retry processing in this case is applied on a per-host (strictly, per IP
25424 address) basis, not on a per-message basis. Thus, if one message has recently
25425 been delayed, delivery of a new message to the same host is not immediately
25426 tried, but waits for the host's retry time to arrive. If the &%retry_defer%&
25427 log selector is set, the message
25428 .cindex "retry" "time not reached"
25429 &"retry time not reached"& is written to the main log whenever a delivery is
25430 skipped for this reason. Section &<<SECToutSMTPerr>>& contains more details of
25431 the handling of errors during remote deliveries.
25432
25433 Retry processing applies to routing as well as to delivering, except as covered
25434 in the next paragraph. The retry rules do not distinguish between these
25435 actions. It is not possible, for example, to specify different behaviour for
25436 failures to route the domain &'snark.fict.example'& and failures to deliver to
25437 the host &'snark.fict.example'&. I didn't think anyone would ever need this
25438 added complication, so did not implement it. However, although they share the
25439 same retry rule, the actual retry times for routing and transporting a given
25440 domain are maintained independently.
25441
25442 When a delivery is not part of a queue run (typically an immediate delivery on
25443 receipt of a message), the routers are always run, and local deliveries are
25444 always attempted, even if retry times are set for them. This makes for better
25445 behaviour if one particular message is causing problems (for example, causing
25446 quota overflow, or provoking an error in a filter file). If such a delivery
25447 suffers a temporary failure, the retry data is updated as normal, and
25448 subsequent delivery attempts from queue runs occur only when the retry time for
25449 the local address is reached.
25450
25451 .section "Changing retry rules" "SECID157"
25452 If you change the retry rules in your configuration, you should consider
25453 whether or not to delete the retry data that is stored in Exim's spool area in
25454 files with names like &_db/retry_&. Deleting any of Exim's hints files is
25455 always safe; that is why they are called &"hints"&.
25456
25457 The hints retry data contains suggested retry times based on the previous
25458 rules. In the case of a long-running problem with a remote host, it might
25459 record the fact that the host has timed out. If your new rules increase the
25460 timeout time for such a host, you should definitely remove the old retry data
25461 and let Exim recreate it, based on the new rules. Otherwise Exim might bounce
25462 messages that it should now be retaining.
25463
25464
25465
25466 .section "Format of retry rules" "SECID158"
25467 .cindex "retry" "rules"
25468 Each retry rule occupies one line and consists of three or four parts,
25469 separated by white space: a pattern, an error name, an optional list of sender
25470 addresses, and a list of retry parameters. The pattern and sender lists must be
25471 enclosed in double quotes if they contain white space. The rules are searched
25472 in order until one is found where the pattern, error name, and sender list (if
25473 present) match the failing host or address, the error that occurred, and the
25474 message's sender, respectively.
25475
25476
25477 The pattern is any single item that may appear in an address list (see section
25478 &<<SECTaddresslist>>&). It is in fact processed as a one-item address list,
25479 which means that it is expanded before being tested against the address that
25480 has been delayed. A negated address list item is permitted. Address
25481 list processing treats a plain domain name as if it were preceded by &"*@"&,
25482 which makes it possible for many retry rules to start with just a domain. For
25483 example,
25484 .code
25485 lookingglass.fict.example        *  F,24h,30m;
25486 .endd
25487 provides a rule for any address in the &'lookingglass.fict.example'& domain,
25488 whereas
25489 .code
25490 alice@lookingglass.fict.example  *  F,24h,30m;
25491 .endd
25492 applies only to temporary failures involving the local part &%alice%&.
25493 In practice, almost all rules start with a domain name pattern without a local
25494 part.
25495
25496 .cindex "regular expressions" "in retry rules"
25497 &*Warning*&: If you use a regular expression in a retry rule pattern, it
25498 must match a complete address, not just a domain, because that is how regular
25499 expressions work in address lists.
25500 .display
25501 &`^\Nxyz\d+\.abc\.example$\N        *  G,1h,10m,2`&     &%Wrong%&
25502 &`^\N[^@]+@xyz\d+\.abc\.example$\N  *  G,1h,10m,2`&     &%Right%&
25503 .endd
25504
25505
25506 .section "Choosing which retry rule to use for address errors" "SECID159"
25507 When Exim is looking for a retry rule after a routing attempt has failed (for
25508 example, after a DNS timeout), each line in the retry configuration is tested
25509 against the complete address only if &%retry_use_local_part%& is set for the
25510 router. Otherwise, only the domain is used, except when matching against a
25511 regular expression, when the local part of the address is replaced with &"*"&.
25512 A domain on its own can match a domain pattern, or a pattern that starts with
25513 &"*@"&. By default, &%retry_use_local_part%& is true for routers where
25514 &%check_local_user%& is true, and false for other routers.
25515
25516 Similarly, when Exim is looking for a retry rule after a local delivery has
25517 failed (for example, after a mailbox full error), each line in the retry
25518 configuration is tested against the complete address only if
25519 &%retry_use_local_part%& is set for the transport (it defaults true for all
25520 local transports).
25521
25522 .cindex "4&'xx'& responses" "retry rules for"
25523 However, when Exim is looking for a retry rule after a remote delivery attempt
25524 suffers an address error (a 4&'xx'& SMTP response for a recipient address), the
25525 whole address is always used as the key when searching the retry rules. The
25526 rule that is found is used to create a retry time for the combination of the
25527 failing address and the message's sender. It is the combination of sender and
25528 recipient that is delayed in subsequent queue runs until its retry time is
25529 reached. You can delay the recipient without regard to the sender by setting
25530 &%address_retry_include_sender%& false in the &(smtp)& transport but this can
25531 lead to problems with servers that regularly issue 4&'xx'& responses to RCPT
25532 commands.
25533
25534
25535
25536 .section "Choosing which retry rule to use for host and message errors" &&&
25537          "SECID160"
25538 For a temporary error that is not related to an individual address (for
25539 example, a connection timeout), each line in the retry configuration is checked
25540 twice. First, the name of the remote host is used as a domain name (preceded by
25541 &"*@"& when matching a regular expression). If this does not match the line,
25542 the domain from the email address is tried in a similar fashion. For example,
25543 suppose the MX records for &'a.b.c.example'& are
25544 .code
25545 a.b.c.example  MX  5  x.y.z.example
25546                MX  6  p.q.r.example
25547                MX  7  m.n.o.example
25548 .endd
25549 and the retry rules are
25550 .code
25551 p.q.r.example    *      F,24h,30m;
25552 a.b.c.example    *      F,4d,45m;
25553 .endd
25554 and a delivery to the host &'x.y.z.example'& suffers a connection failure. The
25555 first rule matches neither the host nor the domain, so Exim looks at the second
25556 rule. This does not match the host, but it does match the domain, so it is used
25557 to calculate the retry time for the host &'x.y.z.example'&. Meanwhile, Exim
25558 tries to deliver to &'p.q.r.example'&. If this also suffers a host error, the
25559 first retry rule is used, because it matches the host.
25560
25561 In other words, temporary failures to deliver to host &'p.q.r.example'& use the
25562 first rule to determine retry times, but for all the other hosts for the domain
25563 &'a.b.c.example'&, the second rule is used. The second rule is also used if
25564 routing to &'a.b.c.example'& suffers a temporary failure.
25565
25566 &*Note*&: The host name is used when matching the patterns, not its IP address.
25567 However, if a message is routed directly to an IP address without the use of a
25568 host name, for example, if a &(manualroute)& router contains a setting such as:
25569 .code
25570 route_list = *.a.example  192.168.34.23
25571 .endd
25572 then the &"host name"& that is used when searching for a retry rule is the
25573 textual form of the IP address.
25574
25575 .section "Retry rules for specific errors" "SECID161"
25576 .cindex "retry" "specific errors; specifying"
25577 The second field in a retry rule is the name of a particular error, or an
25578 asterisk, which matches any error. The errors that can be tested for are:
25579
25580 .vlist
25581 .vitem &%auth_failed%&
25582 Authentication failed when trying to send to a host in the
25583 &%hosts_require_auth%& list in an &(smtp)& transport.
25584
25585 .vitem &%data_4xx%&
25586 A 4&'xx'& error was received for an outgoing DATA command, either immediately
25587 after the command, or after sending the message's data.
25588
25589 .vitem &%mail_4xx%&
25590 A 4&'xx'& error was received for an outgoing MAIL command.
25591
25592 .vitem &%rcpt_4xx%&
25593 A 4&'xx'& error was received for an outgoing RCPT command.
25594 .endlist
25595
25596 For the three 4&'xx'& errors, either the first or both of the x's can be given
25597 as specific digits, for example: &`mail_45x`& or &`rcpt_436`&. For example, to
25598 recognize 452 errors given to RCPT commands for addresses in a certain domain,
25599 and have retries every ten minutes with a one-hour timeout, you could set up a
25600 retry rule of this form:
25601 .code
25602 the.domain.name  rcpt_452   F,1h,10m
25603 .endd
25604 These errors apply to both outgoing SMTP (the &(smtp)& transport) and outgoing
25605 LMTP (either the &(lmtp)& transport, or the &(smtp)& transport in LMTP mode).
25606
25607 .vlist
25608 .vitem &%lost_connection%&
25609 A server unexpectedly closed the SMTP connection. There may, of course,
25610 legitimate reasons for this (host died, network died), but if it repeats a lot
25611 for the same host, it indicates something odd.
25612
25613 .vitem &%lookup%&
25614 A DNS lookup for a host failed.
25615 Note that a &%dnslookup%& router will need to have matched
25616 its &%fail_defer_domains%& option for this retry type to be usable.
25617 Also note that a &%manualroute%& router will probably need
25618 its &%host_find_failed%& option set to &%defer%&.
25619
25620 .vitem &%refused_MX%&
25621 A connection to a host obtained from an MX record was refused.
25622
25623 .vitem &%refused_A%&
25624 A connection to a host not obtained from an MX record was refused.
25625
25626 .vitem &%refused%&
25627 A connection was refused.
25628
25629 .vitem &%timeout_connect_MX%&
25630 A connection attempt to a host obtained from an MX record timed out.
25631
25632 .vitem &%timeout_connect_A%&
25633 A connection attempt to a host not obtained from an MX record timed out.
25634
25635 .vitem &%timeout_connect%&
25636 A connection attempt timed out.
25637
25638 .vitem &%timeout_MX%&
25639 There was a timeout while connecting or during an SMTP session with a host
25640 obtained from an MX record.
25641
25642 .vitem &%timeout_A%&
25643 There was a timeout while connecting or during an SMTP session with a host not
25644 obtained from an MX record.
25645
25646 .vitem &%timeout%&
25647 There was a timeout while connecting or during an SMTP session.
25648
25649 .vitem &%tls_required%&
25650 The server was required to use TLS (it matched &%hosts_require_tls%& in the
25651 &(smtp)& transport), but either did not offer TLS, or it responded with 4&'xx'&
25652 to STARTTLS, or there was a problem setting up the TLS connection.
25653
25654 .vitem &%quota%&
25655 A mailbox quota was exceeded in a local delivery by the &(appendfile)&
25656 transport.
25657
25658 .vitem &%quota_%&<&'time'&>
25659 .cindex "quota" "error testing in retry rule"
25660 .cindex "retry" "quota error testing"
25661 A mailbox quota was exceeded in a local delivery by the &(appendfile)&
25662 transport, and the mailbox has not been accessed for <&'time'&>. For example,
25663 &'quota_4d'& applies to a quota error when the mailbox has not been accessed
25664 for four days.
25665 .endlist
25666
25667 .cindex "mailbox" "time of last read"
25668 The idea of &%quota_%&<&'time'&> is to make it possible to have shorter
25669 timeouts when the mailbox is full and is not being read by its owner. Ideally,
25670 it should be based on the last time that the user accessed the mailbox.
25671 However, it is not always possible to determine this. Exim uses the following
25672 heuristic rules:
25673
25674 .ilist
25675 If the mailbox is a single file, the time of last access (the &"atime"&) is
25676 used. As no new messages are being delivered (because the mailbox is over
25677 quota), Exim does not access the file, so this is the time of last user access.
25678 .next
25679 .cindex "maildir format" "time of last read"
25680 For a maildir delivery, the time of last modification of the &_new_&
25681 subdirectory is used. As the mailbox is over quota, no new files are created in
25682 the &_new_& subdirectory, because no new messages are being delivered. Any
25683 change to the &_new_& subdirectory is therefore assumed to be the result of an
25684 MUA moving a new message to the &_cur_& directory when it is first read. The
25685 time that is used is therefore the last time that the user read a new message.
25686 .next
25687 For other kinds of multi-file mailbox, the time of last access cannot be
25688 obtained, so a retry rule that uses this type of error field is never matched.
25689 .endlist
25690
25691 The quota errors apply both to system-enforced quotas and to Exim's own quota
25692 mechanism in the &(appendfile)& transport. The &'quota'& error also applies
25693 when a local delivery is deferred because a partition is full (the ENOSPC
25694 error).
25695
25696
25697
25698 .section "Retry rules for specified senders" "SECID162"
25699 .cindex "retry" "rules; sender-specific"
25700 You can specify retry rules that apply only when the failing message has a
25701 specific sender. In particular, this can be used to define retry rules that
25702 apply only to bounce messages. The third item in a retry rule can be of this
25703 form:
25704 .display
25705 &`senders=`&<&'address list'&>
25706 .endd
25707 The retry timings themselves are then the fourth item. For example:
25708 .code
25709 *   rcpt_4xx   senders=:   F,1h,30m
25710 .endd
25711 matches recipient 4&'xx'& errors for bounce messages sent to any address at any
25712 host. If the address list contains white space, it must be enclosed in quotes.
25713 For example:
25714 .code
25715 a.domain  rcpt_452  senders="xb.dom : yc.dom"  G,8h,10m,1.5
25716 .endd
25717 &*Warning*&: This facility can be unhelpful if it is used for host errors
25718 (which do not depend on the recipient). The reason is that the sender is used
25719 only to match the retry rule. Once the rule has been found for a host error,
25720 its contents are used to set a retry time for the host, and this will apply to
25721 all messages, not just those with specific senders.
25722
25723 When testing retry rules using &%-brt%&, you can supply a sender using the
25724 &%-f%& command line option, like this:
25725 .code
25726 exim -f "" -brt user@dom.ain
25727 .endd
25728 If you do not set &%-f%& with &%-brt%&, a retry rule that contains a senders
25729 list is never matched.
25730
25731
25732
25733
25734
25735 .section "Retry parameters" "SECID163"
25736 .cindex "retry" "parameters in rules"
25737 The third (or fourth, if a senders list is present) field in a retry rule is a
25738 sequence of retry parameter sets, separated by semicolons. Each set consists of
25739 .display
25740 <&'letter'&>,<&'cutoff time'&>,<&'arguments'&>
25741 .endd
25742 The letter identifies the algorithm for computing a new retry time; the cutoff
25743 time is the time beyond which this algorithm no longer applies, and the
25744 arguments vary the algorithm's action. The cutoff time is measured from the
25745 time that the first failure for the domain (combined with the local part if
25746 relevant) was detected, not from the time the message was received.
25747
25748 .cindex "retry" "algorithms"
25749 .cindex "retry" "fixed intervals"
25750 .cindex "retry" "increasing intervals"
25751 .cindex "retry" "random intervals"
25752 The available algorithms are:
25753
25754 .ilist
25755 &'F'&: retry at fixed intervals. There is a single time parameter specifying
25756 the interval.
25757 .next
25758 &'G'&: retry at geometrically increasing intervals. The first argument
25759 specifies a starting value for the interval, and the second a multiplier, which
25760 is used to increase the size of the interval at each retry.
25761 .next
25762 &'H'&: retry at randomized intervals. The arguments are as for &'G'&. For each
25763 retry, the previous interval is multiplied by the factor in order to get a
25764 maximum for the next interval. The minimum interval is the first argument of
25765 the parameter, and an actual interval is chosen randomly between them. Such a
25766 rule has been found to be helpful in cluster configurations when all the
25767 members of the cluster restart at once, and may therefore synchronize their
25768 queue processing times.
25769 .endlist
25770
25771 When computing the next retry time, the algorithm definitions are scanned in
25772 order until one whose cutoff time has not yet passed is reached. This is then
25773 used to compute a new retry time that is later than the current time. In the
25774 case of fixed interval retries, this simply means adding the interval to the
25775 current time. For geometrically increasing intervals, retry intervals are
25776 computed from the rule's parameters until one that is greater than the previous
25777 interval is found. The main configuration variable
25778 .cindex "limit" "retry interval"
25779 .cindex "retry" "interval, maximum"
25780 .oindex "&%retry_interval_max%&"
25781 &%retry_interval_max%& limits the maximum interval between retries. It
25782 cannot be set greater than &`24h`&, which is its default value.
25783
25784 A single remote domain may have a number of hosts associated with it, and each
25785 host may have more than one IP address. Retry algorithms are selected on the
25786 basis of the domain name, but are applied to each IP address independently. If,
25787 for example, a host has two IP addresses and one is unusable, Exim will
25788 generate retry times for it and will not try to use it until its next retry
25789 time comes. Thus the good IP address is likely to be tried first most of the
25790 time.
25791
25792 .cindex "hints database" "use for retrying"
25793 Retry times are hints rather than promises. Exim does not make any attempt to
25794 run deliveries exactly at the computed times. Instead, a queue runner process
25795 starts delivery processes for delayed messages periodically, and these attempt
25796 new deliveries only for those addresses that have passed their next retry time.
25797 If a new message arrives for a deferred address, an immediate delivery attempt
25798 occurs only if the address has passed its retry time. In the absence of new
25799 messages, the minimum time between retries is the interval between queue runner
25800 processes. There is not much point in setting retry times of five minutes if
25801 your queue runners happen only once an hour, unless there are a significant
25802 number of incoming messages (which might be the case on a system that is
25803 sending everything to a smart host, for example).
25804
25805 The data in the retry hints database can be inspected by using the
25806 &'exim_dumpdb'& or &'exim_fixdb'& utility programs (see chapter
25807 &<<CHAPutils>>&). The latter utility can also be used to change the data. The
25808 &'exinext'& utility script can be used to find out what the next retry times
25809 are for the hosts associated with a particular mail domain, and also for local
25810 deliveries that have been deferred.
25811
25812
25813 .section "Retry rule examples" "SECID164"
25814 Here are some example retry rules:
25815 .code
25816 alice@wonderland.fict.example quota_5d  F,7d,3h
25817 wonderland.fict.example       quota_5d
25818 wonderland.fict.example       *         F,1h,15m; G,2d,1h,2;
25819 lookingglass.fict.example     *         F,24h,30m;
25820 *                 refused_A   F,2h,20m;
25821 *                 *           F,2h,15m; G,16h,1h,1.5; F,5d,8h
25822 .endd
25823 The first rule sets up special handling for mail to
25824 &'alice@wonderland.fict.example'& when there is an over-quota error and the
25825 mailbox has not been read for at least 5 days. Retries continue every three
25826 hours for 7 days. The second rule handles over-quota errors for all other local
25827 parts at &'wonderland.fict.example'&; the absence of a local part has the same
25828 effect as supplying &"*@"&. As no retry algorithms are supplied, messages that
25829 fail are bounced immediately if the mailbox has not been read for at least 5
25830 days.
25831
25832 The third rule handles all other errors at &'wonderland.fict.example'&; retries
25833 happen every 15 minutes for an hour, then with geometrically increasing
25834 intervals until two days have passed since a delivery first failed. After the
25835 first hour there is a delay of one hour, then two hours, then four hours, and
25836 so on (this is a rather extreme example).
25837
25838 The fourth rule controls retries for the domain &'lookingglass.fict.example'&.
25839 They happen every 30 minutes for 24 hours only. The remaining two rules handle
25840 all other domains, with special action for connection refusal from hosts that
25841 were not obtained from an MX record.
25842
25843 The final rule in a retry configuration should always have asterisks in the
25844 first two fields so as to provide a general catch-all for any addresses that do
25845 not have their own special handling. This example tries every 15 minutes for 2
25846 hours, then with intervals starting at one hour and increasing by a factor of
25847 1.5 up to 16 hours, then every 8 hours up to 5 days.
25848
25849
25850
25851 .section "Timeout of retry data" "SECID165"
25852 .cindex "timeout" "of retry data"
25853 .oindex "&%retry_data_expire%&"
25854 .cindex "hints database" "data expiry"
25855 .cindex "retry" "timeout of data"
25856 Exim timestamps the data that it writes to its retry hints database. When it
25857 consults the data during a delivery it ignores any that is older than the value
25858 set in &%retry_data_expire%& (default 7 days). If, for example, a host hasn't
25859 been tried for 7 days, Exim will try to deliver to it immediately a message
25860 arrives, and if that fails, it will calculate a retry time as if it were
25861 failing for the first time.
25862
25863 This improves the behaviour for messages routed to rarely-used hosts such as MX
25864 backups. If such a host was down at one time, and happens to be down again when
25865 Exim tries a month later, using the old retry data would imply that it had been
25866 down all the time, which is not a justified assumption.
25867
25868 If a host really is permanently dead, this behaviour causes a burst of retries
25869 every now and again, but only if messages routed to it are rare. If there is a
25870 message at least once every 7 days the retry data never expires.
25871
25872
25873
25874
25875 .section "Long-term failures" "SECID166"
25876 .cindex "delivery failure, long-term"
25877 .cindex "retry" "after long-term failure"
25878 Special processing happens when an email address has been failing for so long
25879 that the cutoff time for the last algorithm is reached. For example, using the
25880 default retry rule:
25881 .code
25882 * * F,2h,15m; G,16h,1h,1.5; F,4d,6h
25883 .endd
25884 the cutoff time is four days. Reaching the retry cutoff is independent of how
25885 long any specific message has been failing; it is the length of continuous
25886 failure for the recipient address that counts.
25887
25888 When the cutoff time is reached for a local delivery, or for all the IP
25889 addresses associated with a remote delivery, a subsequent delivery failure
25890 causes Exim to give up on the address, and a bounce message is generated.
25891 In order to cater for new messages that use the failing address, a next retry
25892 time is still computed from the final algorithm, and is used as follows:
25893
25894 For local deliveries, one delivery attempt is always made for any subsequent
25895 messages. If this delivery fails, the address fails immediately. The
25896 post-cutoff retry time is not used.
25897
25898 .cindex "final cutoff" "retries, controlling"
25899 .cindex retry "final cutoff"
25900 If the delivery is remote, there are two possibilities, controlled by the
25901 .oindex "&%delay_after_cutoff%&"
25902 &%delay_after_cutoff%& option of the &(smtp)& transport. The option is true by
25903 default. Until the post-cutoff retry time for one of the IP addresses,
25904 as set by the &%retry_data_expire%& option, is
25905 reached, the failing email address is bounced immediately, without a delivery
25906 attempt taking place. After that time, one new delivery attempt is made to
25907 those IP addresses that are past their retry times, and if that still fails,
25908 the address is bounced and new retry times are computed.
25909
25910 In other words, when all the hosts for a given email address have been failing
25911 for a long time, Exim bounces rather then defers until one of the hosts' retry
25912 times is reached. Then it tries once, and bounces if that attempt fails. This
25913 behaviour ensures that few resources are wasted in repeatedly trying to deliver
25914 to a broken destination, but if the host does recover, Exim will eventually
25915 notice.
25916
25917 If &%delay_after_cutoff%& is set false, Exim behaves differently. If all IP
25918 addresses are past their final cutoff time, Exim tries to deliver to those IP
25919 addresses that have not been tried since the message arrived. If there are
25920 no suitable IP addresses, or if they all fail, the address is bounced. In other
25921 words, it does not delay when a new message arrives, but tries the expired
25922 addresses immediately, unless they have been tried since the message arrived.
25923 If there is a continuous stream of messages for the failing domains, setting
25924 &%delay_after_cutoff%& false means that there will be many more attempts to
25925 deliver to permanently failing IP addresses than when &%delay_after_cutoff%& is
25926 true.
25927
25928 .section "Deliveries that work intermittently" "SECID167"
25929 .cindex "retry" "intermittently working deliveries"
25930 Some additional logic is needed to cope with cases where a host is
25931 intermittently available, or when a message has some attribute that prevents
25932 its delivery when others to the same address get through. In this situation,
25933 because some messages are successfully delivered, the &"retry clock"& for the
25934 host or address keeps getting reset by the successful deliveries, and so
25935 failing messages remain on the queue for ever because the cutoff time is never
25936 reached.
25937
25938 Two exceptional actions are applied to prevent this happening. The first
25939 applies to errors that are related to a message rather than a remote host.
25940 Section &<<SECToutSMTPerr>>& has a discussion of the different kinds of error;
25941 examples of message-related errors are 4&'xx'& responses to MAIL or DATA
25942 commands, and quota failures. For this type of error, if a message's arrival
25943 time is earlier than the &"first failed"& time for the error, the earlier time
25944 is used when scanning the retry rules to decide when to try next and when to
25945 time out the address.
25946
25947 The exceptional second action applies in all cases. If a message has been on
25948 the queue for longer than the cutoff time of any applicable retry rule for a
25949 given address, a delivery is attempted for that address, even if it is not yet
25950 time, and if this delivery fails, the address is timed out. A new retry time is
25951 not computed in this case, so that other messages for the same address are
25952 considered immediately.
25953 .ecindex IIDretconf1
25954 .ecindex IIDregconf2
25955
25956
25957
25958
25959
25960
25961 . ////////////////////////////////////////////////////////////////////////////
25962 . ////////////////////////////////////////////////////////////////////////////
25963
25964 .chapter "SMTP authentication" "CHAPSMTPAUTH"
25965 .scindex IIDauthconf1 "SMTP" "authentication configuration"
25966 .scindex IIDauthconf2 "authentication"
25967 The &"authenticators"& section of Exim's run time configuration is concerned
25968 with SMTP authentication. This facility is an extension to the SMTP protocol,
25969 described in RFC 2554, which allows a client SMTP host to authenticate itself
25970 to a server. This is a common way for a server to recognize clients that are
25971 permitted to use it as a relay. SMTP authentication is not of relevance to the
25972 transfer of mail between servers that have no managerial connection with each
25973 other.
25974
25975 .cindex "AUTH" "description of"
25976 Very briefly, the way SMTP authentication works is as follows:
25977
25978 .ilist
25979 The server advertises a number of authentication &'mechanisms'& in response to
25980 the client's EHLO command.
25981 .next
25982 The client issues an AUTH command, naming a specific mechanism. The command
25983 may, optionally, contain some authentication data.
25984 .next
25985 The server may issue one or more &'challenges'&, to which the client must send
25986 appropriate responses. In simple authentication mechanisms, the challenges are
25987 just prompts for user names and passwords. The server does not have to issue
25988 any challenges &-- in some mechanisms the relevant data may all be transmitted
25989 with the AUTH command.
25990 .next
25991 The server either accepts or denies authentication.
25992 .next
25993 If authentication succeeds, the client may optionally make use of the AUTH
25994 option on the MAIL command to pass an authenticated sender in subsequent
25995 mail transactions. Authentication lasts for the remainder of the SMTP
25996 connection.
25997 .next
25998 If authentication fails, the client may give up, or it may try a different
25999 authentication mechanism, or it may try transferring mail over the
26000 unauthenticated connection.
26001 .endlist
26002
26003 If you are setting up a client, and want to know which authentication
26004 mechanisms the server supports, you can use Telnet to connect to port 25 (the
26005 SMTP port) on the server, and issue an EHLO command. The response to this
26006 includes the list of supported mechanisms. For example:
26007 .display
26008 &`$ `&&*&`telnet server.example 25`&*&
26009 &`Trying 192.168.34.25...`&
26010 &`Connected to server.example.`&
26011 &`Escape character is &#x0027;^]&#x0027;.`&
26012 &`220 server.example ESMTP Exim 4.20 ...`&
26013 &*&`ehlo client.example`&*&
26014 &`250-server.example Hello client.example [10.8.4.5]`&
26015 &`250-SIZE 52428800`&
26016 &`250-PIPELINING`&
26017 &`250-AUTH PLAIN`&
26018 &`250 HELP`&
26019 .endd
26020 The second-last line of this example output shows that the server supports
26021 authentication using the PLAIN mechanism. In Exim, the different authentication
26022 mechanisms are configured by specifying &'authenticator'& drivers. Like the
26023 routers and transports, which authenticators are included in the binary is
26024 controlled by build-time definitions. The following are currently available,
26025 included by setting
26026 .code
26027 AUTH_CRAM_MD5=yes
26028 AUTH_CYRUS_SASL=yes
26029 AUTH_DOVECOT=yes
26030 AUTH_EXTERNAL=yes
26031 AUTH_GSASL=yes
26032 AUTH_HEIMDAL_GSSAPI=yes
26033 AUTH_PLAINTEXT=yes
26034 AUTH_SPA=yes
26035 AUTH_TLS=yes
26036 .endd
26037 in &_Local/Makefile_&, respectively. The first of these supports the CRAM-MD5
26038 authentication mechanism (RFC 2195), and the second provides an interface to
26039 the Cyrus SASL authentication library.
26040 The third is an interface to Dovecot's authentication system, delegating the
26041 work via a socket interface.
26042 .new
26043 The fourth provides for negotiation of authentication done via non-SMTP means,
26044 as defined by RFC 4422 Appendix A.
26045 .wen
26046 The fifth provides an interface to the GNU SASL authentication library, which
26047 provides mechanisms but typically not data sources.
26048 The sixth provides direct access to Heimdal GSSAPI, geared for Kerberos, but
26049 supporting setting a server keytab.
26050 The seventh can be configured to support
26051 the PLAIN authentication mechanism (RFC 2595) or the LOGIN mechanism, which is
26052 not formally documented, but used by several MUAs.
26053 The eighth authenticator
26054 supports Microsoft's &'Secure Password Authentication'& mechanism.
26055 The last is an Exim authenticator but not an SMTP one;
26056 instead it can use information from a TLS negotiation.
26057
26058 The authenticators are configured using the same syntax as other drivers (see
26059 section &<<SECTfordricon>>&). If no authenticators are required, no
26060 authentication section need be present in the configuration file. Each
26061 authenticator can in principle have both server and client functions. When Exim
26062 is receiving SMTP mail, it is acting as a server; when it is sending out
26063 messages over SMTP, it is acting as a client. Authenticator configuration
26064 options are provided for use in both these circumstances.
26065
26066 To make it clear which options apply to which situation, the prefixes
26067 &%server_%& and &%client_%& are used on option names that are specific to
26068 either the server or the client function, respectively. Server and client
26069 functions are disabled if none of their options are set. If an authenticator is
26070 to be used for both server and client functions, a single definition, using
26071 both sets of options, is required. For example:
26072 .code
26073 cram:
26074   driver = cram_md5
26075   public_name = CRAM-MD5
26076   server_secret = ${if eq{$auth1}{ph10}{secret1}fail}
26077   client_name = ph10
26078   client_secret = secret2
26079 .endd
26080 The &%server_%& option is used when Exim is acting as a server, and the
26081 &%client_%& options when it is acting as a client.
26082
26083 Descriptions of the individual authenticators are given in subsequent chapters.
26084 The remainder of this chapter covers the generic options for the
26085 authenticators, followed by general discussion of the way authentication works
26086 in Exim.
26087
26088 &*Beware:*& the meaning of &$auth1$&, &$auth2$&, ... varies on a per-driver and
26089 per-mechanism basis.  Please read carefully to determine which variables hold
26090 account labels such as usercodes and which hold passwords or other
26091 authenticating data.
26092
26093 Note that some mechanisms support two different identifiers for accounts: the
26094 &'authentication id'& and the &'authorization id'&.  The contractions &'authn'&
26095 and &'authz'& are commonly encountered.  The American spelling is standard here.
26096 Conceptually, authentication data such as passwords are tied to the identifier
26097 used to authenticate; servers may have rules to permit one user to act as a
26098 second user, so that after login the session is treated as though that second
26099 user had logged in.  That second user is the &'authorization id'&.  A robust
26100 configuration might confirm that the &'authz'& field is empty or matches the
26101 &'authn'& field.  Often this is just ignored.  The &'authn'& can be considered
26102 as verified data, the &'authz'& as an unverified request which the server might
26103 choose to honour.
26104
26105 A &'realm'& is a text string, typically a domain name, presented by a server
26106 to a client to help it select an account and credentials to use.  In some
26107 mechanisms, the client and server provably agree on the realm, but clients
26108 typically can not treat the realm as secure data to be blindly trusted.
26109
26110
26111
26112 .section "Generic options for authenticators" "SECID168"
26113 .cindex "authentication" "generic options"
26114 .cindex "options" "generic; for authenticators"
26115
26116 .option client_condition authenticators string&!! unset
26117 When Exim is authenticating as a client, it skips any authenticator whose
26118 &%client_condition%& expansion yields &"0"&, &"no"&, or &"false"&. This can be
26119 used, for example, to skip plain text authenticators when the connection is not
26120 encrypted by a setting such as:
26121 .code
26122 client_condition = ${if !eq{$tls_out_cipher}{}}
26123 .endd
26124
26125
26126 .option client_set_id authenticators string&!! unset
26127 When client authentication succeeds, this condition is expanded; the
26128 result is used in the log lines for outbound messages.
26129 Typically it will be the user name used for authentication.
26130
26131
26132 .option driver authenticators string unset
26133 This option must always be set. It specifies which of the available
26134 authenticators is to be used.
26135
26136
26137 .option public_name authenticators string unset
26138 This option specifies the name of the authentication mechanism that the driver
26139 implements, and by which it is known to the outside world. These names should
26140 contain only upper case letters, digits, underscores, and hyphens (RFC 2222),
26141 but Exim in fact matches them caselessly. If &%public_name%& is not set, it
26142 defaults to the driver's instance name.
26143
26144
26145 .option server_advertise_condition authenticators string&!! unset
26146 When a server is about to advertise an authentication mechanism, the condition
26147 is expanded. If it yields the empty string, &"0"&, &"no"&, or &"false"&, the
26148 mechanism is not advertised.
26149 If the expansion fails, the mechanism is not advertised. If the failure was not
26150 forced, and was not caused by a lookup defer, the incident is logged.
26151 See section &<<SECTauthexiser>>& below for further discussion.
26152
26153
26154 .option server_condition authenticators string&!! unset
26155 This option must be set for a &%plaintext%& server authenticator, where it
26156 is used directly to control authentication. See section &<<SECTplainserver>>&
26157 for details.
26158
26159 For the &(gsasl)& authenticator, this option is required for various
26160 mechanisms; see chapter &<<CHAPgsasl>>& for details.
26161
26162 For the other authenticators, &%server_condition%& can be used as an additional
26163 authentication or authorization mechanism that is applied after the other
26164 authenticator conditions succeed. If it is set, it is expanded when the
26165 authenticator would otherwise return a success code. If the expansion is forced
26166 to fail, authentication fails. Any other expansion failure causes a temporary
26167 error code to be returned. If the result of a successful expansion is an empty
26168 string, &"0"&, &"no"&, or &"false"&, authentication fails. If the result of the
26169 expansion is &"1"&, &"yes"&, or &"true"&, authentication succeeds. For any
26170 other result, a temporary error code is returned, with the expanded string as
26171 the error text.
26172
26173
26174 .option server_debug_print authenticators string&!! unset
26175 If this option is set and authentication debugging is enabled (see the &%-d%&
26176 command line option), the string is expanded and included in the debugging
26177 output when the authenticator is run as a server. This can help with checking
26178 out the values of variables.
26179 If expansion of the string fails, the error message is written to the debugging
26180 output, and Exim carries on processing.
26181
26182
26183 .option server_set_id authenticators string&!! unset
26184 .vindex "&$authenticated_id$&"
26185 .vindex "&$authenticated_fail_id$&"
26186 When an Exim server successfully authenticates a client, this string is
26187 expanded using data from the authentication, and preserved for any incoming
26188 messages in the variable &$authenticated_id$&. It is also included in the log
26189 lines for incoming messages. For example, a user/password authenticator
26190 configuration might preserve the user name that was used to authenticate, and
26191 refer to it subsequently during delivery of the message.
26192 On a failing authentication the expansion result is instead saved in
26193 the &$authenticated_fail_id$& variable.
26194 If expansion fails, the option is ignored.
26195
26196
26197 .option server_mail_auth_condition authenticators string&!! unset
26198 This option allows a server to discard authenticated sender addresses supplied
26199 as part of MAIL commands in SMTP connections that are authenticated by the
26200 driver on which &%server_mail_auth_condition%& is set. The option is not used
26201 as part of the authentication process; instead its (unexpanded) value is
26202 remembered for later use.
26203 How it is used is described in the following section.
26204
26205
26206
26207
26208
26209 .section "The AUTH parameter on MAIL commands" "SECTauthparamail"
26210 .cindex "authentication" "sender; authenticated"
26211 .cindex "AUTH" "on MAIL command"
26212 When a client supplied an AUTH= item on a MAIL command, Exim applies
26213 the following checks before accepting it as the authenticated sender of the
26214 message:
26215
26216 .ilist
26217 If the connection is not using extended SMTP (that is, HELO was used rather
26218 than EHLO), the use of AUTH= is a syntax error.
26219 .next
26220 If the value of the AUTH= parameter is &"<>"&, it is ignored.
26221 .next
26222 .vindex "&$authenticated_sender$&"
26223 If &%acl_smtp_mailauth%& is defined, the ACL it specifies is run. While it is
26224 running, the value of &$authenticated_sender$& is set to the value obtained
26225 from the AUTH= parameter. If the ACL does not yield &"accept"&, the value of
26226 &$authenticated_sender$& is deleted. The &%acl_smtp_mailauth%& ACL may not
26227 return &"drop"& or &"discard"&. If it defers, a temporary error code (451) is
26228 given for the MAIL command.
26229 .next
26230 If &%acl_smtp_mailauth%& is not defined, the value of the AUTH= parameter
26231 is accepted and placed in &$authenticated_sender$& only if the client has
26232 authenticated.
26233 .next
26234 If the AUTH= value was accepted by either of the two previous rules, and
26235 the client has authenticated, and the authenticator has a setting for the
26236 &%server_mail_auth_condition%&, the condition is checked at this point. The
26237 valued that was saved from the authenticator is expanded. If the expansion
26238 fails, or yields an empty string, &"0"&, &"no"&, or &"false"&, the value of
26239 &$authenticated_sender$& is deleted. If the expansion yields any other value,
26240 the value of &$authenticated_sender$& is retained and passed on with the
26241 message.
26242 .endlist
26243
26244
26245 When &$authenticated_sender$& is set for a message, it is passed on to other
26246 hosts to which Exim authenticates as a client. Do not confuse this value with
26247 &$authenticated_id$&, which is a string obtained from the authentication
26248 process, and which is not usually a complete email address.
26249
26250 .vindex "&$sender_address$&"
26251 Whenever an AUTH= value is ignored, the incident is logged. The ACL for
26252 MAIL, if defined, is run after AUTH= is accepted or ignored. It can
26253 therefore make use of &$authenticated_sender$&. The converse is not true: the
26254 value of &$sender_address$& is not yet set up when the &%acl_smtp_mailauth%&
26255 ACL is run.
26256
26257
26258
26259 .section "Authentication on an Exim server" "SECTauthexiser"
26260 .cindex "authentication" "on an Exim server"
26261 When Exim receives an EHLO command, it advertises the public names of those
26262 authenticators that are configured as servers, subject to the following
26263 conditions:
26264
26265 .ilist
26266 The client host must match &%auth_advertise_hosts%& (default *).
26267 .next
26268 It the &%server_advertise_condition%& option is set, its expansion must not
26269 yield the empty string, &"0"&, &"no"&, or &"false"&.
26270 .endlist
26271
26272 The order in which the authenticators are defined controls the order in which
26273 the mechanisms are advertised.
26274
26275 Some mail clients (for example, some versions of Netscape) require the user to
26276 provide a name and password for authentication whenever AUTH is advertised,
26277 even though authentication may not in fact be needed (for example, Exim may be
26278 set up to allow unconditional relaying from the client by an IP address check).
26279 You can make such clients more friendly by not advertising AUTH to them.
26280 For example, if clients on the 10.9.8.0/24 network are permitted (by the ACL
26281 that runs for RCPT) to relay without authentication, you should set
26282 .code
26283 auth_advertise_hosts = ! 10.9.8.0/24
26284 .endd
26285 so that no authentication mechanisms are advertised to them.
26286
26287 The &%server_advertise_condition%& controls the advertisement of individual
26288 authentication mechanisms. For example, it can be used to restrict the
26289 advertisement of a particular mechanism to encrypted connections, by a setting
26290 such as:
26291 .code
26292 server_advertise_condition = ${if eq{$tls_in_cipher}{}{no}{yes}}
26293 .endd
26294 .vindex "&$tls_in_cipher$&"
26295 If the session is encrypted, &$tls_in_cipher$& is not empty, and so the expansion
26296 yields &"yes"&, which allows the advertisement to happen.
26297
26298 When an Exim server receives an AUTH command from a client, it rejects it
26299 immediately if AUTH was not advertised in response to an earlier EHLO
26300 command. This is the case if
26301
26302 .ilist
26303 The client host does not match &%auth_advertise_hosts%&; or
26304 .next
26305 No authenticators are configured with server options; or
26306 .next
26307 Expansion of &%server_advertise_condition%& blocked the advertising of all the
26308 server authenticators.
26309 .endlist
26310
26311
26312 Otherwise, Exim runs the ACL specified by &%acl_smtp_auth%& in order
26313 to decide whether to accept the command. If &%acl_smtp_auth%& is not set,
26314 AUTH is accepted from any client host.
26315
26316 If AUTH is not rejected by the ACL, Exim searches its configuration for a
26317 server authentication mechanism that was advertised in response to EHLO and
26318 that matches the one named in the AUTH command. If it finds one, it runs
26319 the appropriate authentication protocol, and authentication either succeeds or
26320 fails. If there is no matching advertised mechanism, the AUTH command is
26321 rejected with a 504 error.
26322
26323 .vindex "&$received_protocol$&"
26324 .vindex "&$sender_host_authenticated$&"
26325 When a message is received from an authenticated host, the value of
26326 &$received_protocol$& is set to &"esmtpa"& or &"esmtpsa"& instead of &"esmtp"&
26327 or &"esmtps"&, and &$sender_host_authenticated$& contains the name (not the
26328 public name) of the authenticator driver that successfully authenticated the
26329 client from which the message was received. This variable is empty if there was
26330 no successful authentication.
26331
26332 .cindex authentication "expansion item"
26333 Successful authentication sets up information used by the
26334 &$authresults$& expansion item.
26335
26336
26337
26338
26339 .section "Testing server authentication" "SECID169"
26340 .cindex "authentication" "testing a server"
26341 .cindex "AUTH" "testing a server"
26342 .cindex "base64 encoding" "creating authentication test data"
26343 Exim's &%-bh%& option can be useful for testing server authentication
26344 configurations. The data for the AUTH command has to be sent using base64
26345 encoding. A quick way to produce such data for testing is the following Perl
26346 script:
26347 .code
26348 use MIME::Base64;
26349 printf ("%s", encode_base64(eval "\"$ARGV[0]\""));
26350 .endd
26351 .cindex "binary zero" "in authentication data"
26352 This interprets its argument as a Perl string, and then encodes it. The
26353 interpretation as a Perl string allows binary zeros, which are required for
26354 some kinds of authentication, to be included in the data. For example, a
26355 command line to run this script on such data might be
26356 .code
26357 encode '\0user\0password'
26358 .endd
26359 Note the use of single quotes to prevent the shell interpreting the
26360 backslashes, so that they can be interpreted by Perl to specify characters
26361 whose code value is zero.
26362
26363 &*Warning 1*&: If either of the user or password strings starts with an octal
26364 digit, you must use three zeros instead of one after the leading backslash. If
26365 you do not, the octal digit that starts your string will be incorrectly
26366 interpreted as part of the code for the first character.
26367
26368 &*Warning 2*&: If there are characters in the strings that Perl interprets
26369 specially, you must use a Perl escape to prevent them being misinterpreted. For
26370 example, a command such as
26371 .code
26372 encode '\0user@domain.com\0pas$$word'
26373 .endd
26374 gives an incorrect answer because of the unescaped &"@"& and &"$"& characters.
26375
26376 If you have the &%mimencode%& command installed, another way to do produce
26377 base64-encoded strings is to run the command
26378 .code
26379 echo -e -n `\0user\0password' | mimencode
26380 .endd
26381 The &%-e%& option of &%echo%& enables the interpretation of backslash escapes
26382 in the argument, and the &%-n%& option specifies no newline at the end of its
26383 output. However, not all versions of &%echo%& recognize these options, so you
26384 should check your version before relying on this suggestion.
26385
26386
26387
26388 .section "Authentication by an Exim client" "SECID170"
26389 .cindex "authentication" "on an Exim client"
26390 The &(smtp)& transport has two options called &%hosts_require_auth%& and
26391 &%hosts_try_auth%&. When the &(smtp)& transport connects to a server that
26392 announces support for authentication, and the host matches an entry in either
26393 of these options, Exim (as a client) tries to authenticate as follows:
26394
26395 .ilist
26396 For each authenticator that is configured as a client, in the order in which
26397 they are defined in the configuration, it searches the authentication
26398 mechanisms announced by the server for one whose name matches the public name
26399 of the authenticator.
26400 .next
26401 .vindex "&$host$&"
26402 .vindex "&$host_address$&"
26403 When it finds one that matches, it runs the authenticator's client code. The
26404 variables &$host$& and &$host_address$& are available for any string expansions
26405 that the client might do. They are set to the server's name and IP address. If
26406 any expansion is forced to fail, the authentication attempt is abandoned, and
26407 Exim moves on to the next authenticator. Otherwise an expansion failure causes
26408 delivery to be deferred.
26409 .next
26410 If the result of the authentication attempt is a temporary error or a timeout,
26411 Exim abandons trying to send the message to the host for the moment. It will
26412 try again later. If there are any backup hosts available, they are tried in the
26413 usual way.
26414 .next
26415 If the response to authentication is a permanent error (5&'xx'& code), Exim
26416 carries on searching the list of authenticators and tries another one if
26417 possible. If all authentication attempts give permanent errors, or if there are
26418 no attempts because no mechanisms match (or option expansions force failure),
26419 what happens depends on whether the host matches &%hosts_require_auth%& or
26420 &%hosts_try_auth%&. In the first case, a temporary error is generated, and
26421 delivery is deferred. The error can be detected in the retry rules, and thereby
26422 turned into a permanent error if you wish. In the second case, Exim tries to
26423 deliver the message unauthenticated.
26424 .endlist
26425
26426 Note that the hostlist test for whether to do authentication can be
26427 confused if name-IP lookups change between the time the peer is decided
26428 upon and the time that the transport runs.  For example, with a manualroute
26429 router given a host name, and with DNS "round-robin" used by that name: if
26430 the local resolver cache times out between the router and the transport
26431 running, the transport may get an IP for the name for its authentication
26432 check which does not match the connection peer IP.
26433 No authentication will then be done, despite the names being identical.
26434
26435 For such cases use a separate transport which always authenticates.
26436
26437 .cindex "AUTH" "on MAIL command"
26438 When Exim has authenticated itself to a remote server, it adds the AUTH
26439 parameter to the MAIL commands it sends, if it has an authenticated sender for
26440 the message. If the message came from a remote host, the authenticated sender
26441 is the one that was receiving on an incoming MAIL command, provided that the
26442 incoming connection was authenticated and the &%server_mail_auth%& condition
26443 allowed the authenticated sender to be retained. If a local process calls Exim
26444 to send a message, the sender address that is built from the login name and
26445 &%qualify_domain%& is treated as authenticated. However, if the
26446 &%authenticated_sender%& option is set on the &(smtp)& transport, it overrides
26447 the authenticated sender that was received with the message.
26448 .ecindex IIDauthconf1
26449 .ecindex IIDauthconf2
26450
26451
26452
26453
26454
26455
26456 . ////////////////////////////////////////////////////////////////////////////
26457 . ////////////////////////////////////////////////////////////////////////////
26458
26459 .chapter "The plaintext authenticator" "CHAPplaintext"
26460 .scindex IIDplaiauth1 "&(plaintext)& authenticator"
26461 .scindex IIDplaiauth2 "authenticators" "&(plaintext)&"
26462 The &(plaintext)& authenticator can be configured to support the PLAIN and
26463 LOGIN authentication mechanisms, both of which transfer authentication data as
26464 plain (unencrypted) text (though base64 encoded). The use of plain text is a
26465 security risk; you are strongly advised to insist on the use of SMTP encryption
26466 (see chapter &<<CHAPTLS>>&) if you use the PLAIN or LOGIN mechanisms. If you do
26467 use unencrypted plain text, you should not use the same passwords for SMTP
26468 connections as you do for login accounts.
26469
26470 .section "Plaintext options" "SECID171"
26471 .cindex "options" "&(plaintext)& authenticator (server)"
26472 When configured as a server, &(plaintext)& uses the following options:
26473
26474 .option server_condition authenticators string&!! unset
26475 This is actually a global authentication option, but it must be set in order to
26476 configure the &(plaintext)& driver as a server. Its use is described below.
26477
26478 .option server_prompts plaintext string&!! unset
26479 The contents of this option, after expansion, must be a colon-separated list of
26480 prompt strings. If expansion fails, a temporary authentication rejection is
26481 given.
26482
26483 .section "Using plaintext in a server" "SECTplainserver"
26484 .cindex "AUTH" "in &(plaintext)& authenticator"
26485 .cindex "binary zero" "in &(plaintext)& authenticator"
26486 .cindex "numerical variables (&$1$& &$2$& etc)" &&&
26487         "in &(plaintext)& authenticator"
26488 .vindex "&$auth1$&, &$auth2$&, etc"
26489 .cindex "base64 encoding" "in &(plaintext)& authenticator"
26490
26491 When running as a server, &(plaintext)& performs the authentication test by
26492 expanding a string. The data sent by the client with the AUTH command, or in
26493 response to subsequent prompts, is base64 encoded, and so may contain any byte
26494 values when decoded. If any data is supplied with the command, it is treated as
26495 a list of strings, separated by NULs (binary zeros), the first three of which
26496 are placed in the expansion variables &$auth1$&, &$auth2$&, and &$auth3$&
26497 (neither LOGIN nor PLAIN uses more than three strings).
26498
26499 For compatibility with previous releases of Exim, the values are also placed in
26500 the expansion variables &$1$&, &$2$&, and &$3$&. However, the use of these
26501 variables for this purpose is now deprecated, as it can lead to confusion in
26502 string expansions that also use them for other things.
26503
26504 If there are more strings in &%server_prompts%& than the number of strings
26505 supplied with the AUTH command, the remaining prompts are used to obtain more
26506 data. Each response from the client may be a list of NUL-separated strings.
26507
26508 .vindex "&$authenticated_id$&"
26509 Once a sufficient number of data strings have been received,
26510 &%server_condition%& is expanded. If the expansion is forced to fail,
26511 authentication fails. Any other expansion failure causes a temporary error code
26512 to be returned. If the result of a successful expansion is an empty string,
26513 &"0"&, &"no"&, or &"false"&, authentication fails. If the result of the
26514 expansion is &"1"&, &"yes"&, or &"true"&, authentication succeeds and the
26515 generic &%server_set_id%& option is expanded and saved in &$authenticated_id$&.
26516 For any other result, a temporary error code is returned, with the expanded
26517 string as the error text.
26518
26519 &*Warning*&: If you use a lookup in the expansion to find the user's
26520 password, be sure to make the authentication fail if the user is unknown.
26521 There are good and bad examples at the end of the next section.
26522
26523
26524
26525 .section "The PLAIN authentication mechanism" "SECID172"
26526 .cindex "PLAIN authentication mechanism"
26527 .cindex "authentication" "PLAIN mechanism"
26528 .cindex "binary zero" "in &(plaintext)& authenticator"
26529 The PLAIN authentication mechanism (RFC 2595) specifies that three strings be
26530 sent as one item of data (that is, one combined string containing two NUL
26531 separators). The data is sent either as part of the AUTH command, or
26532 subsequently in response to an empty prompt from the server.
26533
26534 The second and third strings are a user name and a corresponding password.
26535 Using a single fixed user name and password as an example, this could be
26536 configured as follows:
26537 .code
26538 fixed_plain:
26539   driver = plaintext
26540   public_name = PLAIN
26541   server_prompts = :
26542   server_condition = \
26543     ${if and {{eq{$auth2}{username}}{eq{$auth3}{mysecret}}}}
26544   server_set_id = $auth2
26545 .endd
26546 Note that the default result strings from &%if%& (&"true"& or an empty string)
26547 are exactly what we want here, so they need not be specified. Obviously, if the
26548 password contains expansion-significant characters such as dollar, backslash,
26549 or closing brace, they have to be escaped.
26550
26551 The &%server_prompts%& setting specifies a single, empty prompt (empty items at
26552 the end of a string list are ignored). If all the data comes as part of the
26553 AUTH command, as is commonly the case, the prompt is not used. This
26554 authenticator is advertised in the response to EHLO as
26555 .code
26556 250-AUTH PLAIN
26557 .endd
26558 and a client host can authenticate itself by sending the command
26559 .code
26560 AUTH PLAIN AHVzZXJuYW1lAG15c2VjcmV0
26561 .endd
26562 As this contains three strings (more than the number of prompts), no further
26563 data is required from the client. Alternatively, the client may just send
26564 .code
26565 AUTH PLAIN
26566 .endd
26567 to initiate authentication, in which case the server replies with an empty
26568 prompt. The client must respond with the combined data string.
26569
26570 The data string is base64 encoded, as required by the RFC. This example,
26571 when decoded, is <&'NUL'&>&`username`&<&'NUL'&>&`mysecret`&, where <&'NUL'&>
26572 represents a zero byte. This is split up into three strings, the first of which
26573 is empty. The &%server_condition%& option in the authenticator checks that the
26574 second two are &`username`& and &`mysecret`& respectively.
26575
26576 Having just one fixed user name and password, as in this example, is not very
26577 realistic, though for a small organization with only a handful of
26578 authenticating clients it could make sense.
26579
26580 A more sophisticated instance of this authenticator could use the user name in
26581 &$auth2$& to look up a password in a file or database, and maybe do an encrypted
26582 comparison (see &%crypteq%& in chapter &<<CHAPexpand>>&). Here is a example of
26583 this approach, where the passwords are looked up in a DBM file. &*Warning*&:
26584 This is an incorrect example:
26585 .code
26586 server_condition = \
26587   ${if eq{$auth3}{${lookup{$auth2}dbm{/etc/authpwd}}}}
26588 .endd
26589 The expansion uses the user name (&$auth2$&) as the key to look up a password,
26590 which it then compares to the supplied password (&$auth3$&). Why is this example
26591 incorrect? It works fine for existing users, but consider what happens if a
26592 non-existent user name is given. The lookup fails, but as no success/failure
26593 strings are given for the lookup, it yields an empty string. Thus, to defeat
26594 the authentication, all a client has to do is to supply a non-existent user
26595 name and an empty password. The correct way of writing this test is:
26596 .code
26597 server_condition = ${lookup{$auth2}dbm{/etc/authpwd}\
26598   {${if eq{$value}{$auth3}}} {false}}
26599 .endd
26600 In this case, if the lookup succeeds, the result is checked; if the lookup
26601 fails, &"false"& is returned and authentication fails. If &%crypteq%& is being
26602 used instead of &%eq%&, the first example is in fact safe, because &%crypteq%&
26603 always fails if its second argument is empty. However, the second way of
26604 writing the test makes the logic clearer.
26605
26606
26607 .section "The LOGIN authentication mechanism" "SECID173"
26608 .cindex "LOGIN authentication mechanism"
26609 .cindex "authentication" "LOGIN mechanism"
26610 The LOGIN authentication mechanism is not documented in any RFC, but is in use
26611 in a number of programs. No data is sent with the AUTH command. Instead, a
26612 user name and password are supplied separately, in response to prompts. The
26613 plaintext authenticator can be configured to support this as in this example:
26614 .code
26615 fixed_login:
26616   driver = plaintext
26617   public_name = LOGIN
26618   server_prompts = User Name : Password
26619   server_condition = \
26620     ${if and {{eq{$auth1}{username}}{eq{$auth2}{mysecret}}}}
26621   server_set_id = $auth1
26622 .endd
26623 Because of the way plaintext operates, this authenticator accepts data supplied
26624 with the AUTH command (in contravention of the specification of LOGIN), but
26625 if the client does not supply it (as is the case for LOGIN clients), the prompt
26626 strings are used to obtain two data items.
26627
26628 Some clients are very particular about the precise text of the prompts. For
26629 example, Outlook Express is reported to recognize only &"Username:"& and
26630 &"Password:"&. Here is an example of a LOGIN authenticator that uses those
26631 strings. It uses the &%ldapauth%& expansion condition to check the user
26632 name and password by binding to an LDAP server:
26633 .code
26634 login:
26635   driver = plaintext
26636   public_name = LOGIN
26637   server_prompts = Username:: : Password::
26638   server_condition = ${if and{{ \
26639     !eq{}{$auth1} }{ \
26640     ldapauth{\
26641       user="uid=${quote_ldap_dn:$auth1},ou=people,o=example.org" \
26642       pass=${quote:$auth2} \
26643       ldap://ldap.example.org/} }} }
26644   server_set_id = uid=$auth1,ou=people,o=example.org
26645 .endd
26646 We have to check that the username is not empty before using it, because LDAP
26647 does not permit empty DN components. We must also use the &%quote_ldap_dn%&
26648 operator to correctly quote the DN for authentication. However, the basic
26649 &%quote%& operator, rather than any of the LDAP quoting operators, is the
26650 correct one to use for the password, because quoting is needed only to make
26651 the password conform to the Exim syntax. At the LDAP level, the password is an
26652 uninterpreted string.
26653
26654
26655 .section "Support for different kinds of authentication" "SECID174"
26656 A number of string expansion features are provided for the purpose of
26657 interfacing to different ways of user authentication. These include checking
26658 traditionally encrypted passwords from &_/etc/passwd_& (or equivalent), PAM,
26659 Radius, &%ldapauth%&, &'pwcheck'&, and &'saslauthd'&. For details see section
26660 &<<SECTexpcond>>&.
26661
26662
26663
26664
26665 .section "Using plaintext in a client" "SECID175"
26666 .cindex "options" "&(plaintext)& authenticator (client)"
26667 The &(plaintext)& authenticator has two client options:
26668
26669 .option client_ignore_invalid_base64 plaintext boolean false
26670 If the client receives a server prompt that is not a valid base64 string,
26671 authentication is abandoned by default. However, if this option is set true,
26672 the error in the challenge is ignored and the client sends the response as
26673 usual.
26674
26675 .option client_send plaintext string&!! unset
26676 The string is a colon-separated list of authentication data strings. Each
26677 string is independently expanded before being sent to the server. The first
26678 string is sent with the AUTH command; any more strings are sent in response
26679 to prompts from the server. Before each string is expanded, the value of the
26680 most recent prompt is placed in the next &$auth$&<&'n'&> variable, starting
26681 with &$auth1$& for the first prompt. Up to three prompts are stored in this
26682 way. Thus, the prompt that is received in response to sending the first string
26683 (with the AUTH command) can be used in the expansion of the second string, and
26684 so on. If an invalid base64 string is received when
26685 &%client_ignore_invalid_base64%& is set, an empty string is put in the
26686 &$auth$&<&'n'&> variable.
26687
26688 &*Note*&: You cannot use expansion to create multiple strings, because
26689 splitting takes priority and happens first.
26690
26691 Because the PLAIN authentication mechanism requires NUL (binary zero) bytes in
26692 the data, further processing is applied to each string before it is sent. If
26693 there are any single circumflex characters in the string, they are converted to
26694 NULs. Should an actual circumflex be required as data, it must be doubled in
26695 the string.
26696
26697 This is an example of a client configuration that implements the PLAIN
26698 authentication mechanism with a fixed user name and password:
26699 .code
26700 fixed_plain:
26701   driver = plaintext
26702   public_name = PLAIN
26703   client_send = ^username^mysecret
26704 .endd
26705 The lack of colons means that the entire text is sent with the AUTH
26706 command, with the circumflex characters converted to NULs. A similar example
26707 that uses the LOGIN mechanism is:
26708 .code
26709 fixed_login:
26710   driver = plaintext
26711   public_name = LOGIN
26712   client_send = : username : mysecret
26713 .endd
26714 The initial colon means that the first string is empty, so no data is sent with
26715 the AUTH command itself. The remaining strings are sent in response to
26716 prompts.
26717 .ecindex IIDplaiauth1
26718 .ecindex IIDplaiauth2
26719
26720
26721
26722
26723 . ////////////////////////////////////////////////////////////////////////////
26724 . ////////////////////////////////////////////////////////////////////////////
26725
26726 .chapter "The cram_md5 authenticator" "CHID9"
26727 .scindex IIDcramauth1 "&(cram_md5)& authenticator"
26728 .scindex IIDcramauth2 "authenticators" "&(cram_md5)&"
26729 .cindex "CRAM-MD5 authentication mechanism"
26730 .cindex "authentication" "CRAM-MD5 mechanism"
26731 The CRAM-MD5 authentication mechanism is described in RFC 2195. The server
26732 sends a challenge string to the client, and the response consists of a user
26733 name and the CRAM-MD5 digest of the challenge string combined with a secret
26734 string (password) which is known to both server and client. Thus, the secret
26735 is not sent over the network as plain text, which makes this authenticator more
26736 secure than &(plaintext)&. However, the downside is that the secret has to be
26737 available in plain text at either end.
26738
26739
26740 .section "Using cram_md5 as a server" "SECID176"
26741 .cindex "options" "&(cram_md5)& authenticator (server)"
26742 This authenticator has one server option, which must be set to configure the
26743 authenticator as a server:
26744
26745 .option server_secret cram_md5 string&!! unset
26746 .cindex "numerical variables (&$1$& &$2$& etc)" "in &(cram_md5)& authenticator"
26747 When the server receives the client's response, the user name is placed in
26748 the expansion variable &$auth1$&, and &%server_secret%& is expanded to
26749 obtain the password for that user. The server then computes the CRAM-MD5 digest
26750 that the client should have sent, and checks that it received the correct
26751 string. If the expansion of &%server_secret%& is forced to fail, authentication
26752 fails. If the expansion fails for some other reason, a temporary error code is
26753 returned to the client.
26754
26755 For compatibility with previous releases of Exim, the user name is also placed
26756 in &$1$&. However, the use of this variables for this purpose is now
26757 deprecated, as it can lead to confusion in string expansions that also use
26758 numeric variables for other things.
26759
26760 For example, the following authenticator checks that the user name given by the
26761 client is &"ph10"&, and if so, uses &"secret"& as the password. For any other
26762 user name, authentication fails.
26763 .code
26764 fixed_cram:
26765   driver = cram_md5
26766   public_name = CRAM-MD5
26767   server_secret = ${if eq{$auth1}{ph10}{secret}fail}
26768   server_set_id = $auth1
26769 .endd
26770 .vindex "&$authenticated_id$&"
26771 If authentication succeeds, the setting of &%server_set_id%& preserves the user
26772 name in &$authenticated_id$&. A more typical configuration might look up the
26773 secret string in a file, using the user name as the key. For example:
26774 .code
26775 lookup_cram:
26776   driver = cram_md5
26777   public_name = CRAM-MD5
26778   server_secret = ${lookup{$auth1}lsearch{/etc/authpwd}\
26779                   {$value}fail}
26780   server_set_id = $auth1
26781 .endd
26782 Note that this expansion explicitly forces failure if the lookup fails
26783 because &$auth1$& contains an unknown user name.
26784
26785 As another example, if you wish to re-use a Cyrus SASL sasldb2 file without
26786 using the relevant libraries, you need to know the realm to specify in the
26787 lookup and then ask for the &"userPassword"& attribute for that user in that
26788 realm, with:
26789 .code
26790 cyrusless_crammd5:
26791   driver = cram_md5
26792   public_name = CRAM-MD5
26793   server_secret = ${lookup{$auth1:mail.example.org:userPassword}\
26794                   dbmjz{/etc/sasldb2}{$value}fail}
26795   server_set_id = $auth1
26796 .endd
26797
26798 .section "Using cram_md5 as a client" "SECID177"
26799 .cindex "options" "&(cram_md5)& authenticator (client)"
26800 When used as a client, the &(cram_md5)& authenticator has two options:
26801
26802
26803
26804 .option client_name cram_md5 string&!! "the primary host name"
26805 This string is expanded, and the result used as the user name data when
26806 computing the response to the server's challenge.
26807
26808
26809 .option client_secret cram_md5 string&!! unset
26810 This option must be set for the authenticator to work as a client. Its value is
26811 expanded and the result used as the secret string when computing the response.
26812
26813
26814 .vindex "&$host$&"
26815 .vindex "&$host_address$&"
26816 Different user names and secrets can be used for different servers by referring
26817 to &$host$& or &$host_address$& in the options. Forced failure of either
26818 expansion string is treated as an indication that this authenticator is not
26819 prepared to handle this case. Exim moves on to the next configured client
26820 authenticator. Any other expansion failure causes Exim to give up trying to
26821 send the message to the current server.
26822
26823 A simple example configuration of a &(cram_md5)& authenticator, using fixed
26824 strings, is:
26825 .code
26826 fixed_cram:
26827   driver = cram_md5
26828   public_name = CRAM-MD5
26829   client_name = ph10
26830   client_secret = secret
26831 .endd
26832 .ecindex IIDcramauth1
26833 .ecindex IIDcramauth2
26834
26835
26836
26837 . ////////////////////////////////////////////////////////////////////////////
26838 . ////////////////////////////////////////////////////////////////////////////
26839
26840 .chapter "The cyrus_sasl authenticator" "CHID10"
26841 .scindex IIDcyrauth1 "&(cyrus_sasl)& authenticator"
26842 .scindex IIDcyrauth2 "authenticators" "&(cyrus_sasl)&"
26843 .cindex "Cyrus" "SASL library"
26844 .cindex "Kerberos"
26845 The code for this authenticator was provided by Matthew Byng-Maddick while
26846 at A L Digital Ltd.
26847
26848 The &(cyrus_sasl)& authenticator provides server support for the Cyrus SASL
26849 library implementation of the RFC 2222 (&"Simple Authentication and Security
26850 Layer"&). This library supports a number of authentication mechanisms,
26851 including PLAIN and LOGIN, but also several others that Exim does not support
26852 directly. In particular, there is support for Kerberos authentication.
26853
26854 The &(cyrus_sasl)& authenticator provides a gatewaying mechanism directly to
26855 the Cyrus interface, so if your Cyrus library can do, for example, CRAM-MD5,
26856 then so can the &(cyrus_sasl)& authenticator. By default it uses the public
26857 name of the driver to determine which mechanism to support.
26858
26859 Where access to some kind of secret file is required, for example in GSSAPI
26860 or CRAM-MD5, it is worth noting that the authenticator runs as the Exim
26861 user, and that the Cyrus SASL library has no way of escalating privileges
26862 by default. You may also find you need to set environment variables,
26863 depending on the driver you are using.
26864
26865 The application name provided by Exim is &"exim"&, so various SASL options may
26866 be set in &_exim.conf_& in your SASL directory. If you are using GSSAPI for
26867 Kerberos, note that because of limitations in the GSSAPI interface,
26868 changing the server keytab might need to be communicated down to the Kerberos
26869 layer independently. The mechanism for doing so is dependent upon the Kerberos
26870 implementation.
26871
26872 For example, for older releases of Heimdal, the environment variable KRB5_KTNAME
26873 may be set to point to an alternative keytab file. Exim will pass this
26874 variable through from its own inherited environment when started as root or the
26875 Exim user. The keytab file needs to be readable by the Exim user.
26876 With newer releases of Heimdal, a setuid Exim may cause Heimdal to discard the
26877 environment variable.  In practice, for those releases, the Cyrus authenticator
26878 is not a suitable interface for GSSAPI (Kerberos) support.  Instead, consider
26879 the &(heimdal_gssapi)& authenticator, described in chapter &<<CHAPheimdalgss>>&
26880
26881
26882 .section "Using cyrus_sasl as a server" "SECID178"
26883 The &(cyrus_sasl)& authenticator has four private options. It puts the username
26884 (on a successful authentication) into &$auth1$&. For compatibility with
26885 previous releases of Exim, the username is also placed in &$1$&. However, the
26886 use of this variable for this purpose is now deprecated, as it can lead to
26887 confusion in string expansions that also use numeric variables for other
26888 things.
26889
26890
26891 .option server_hostname cyrus_sasl string&!! "see below"
26892 This option selects the hostname that is used when communicating with the
26893 library. The default value is &`$primary_hostname`&. It is up to the underlying
26894 SASL plug-in what it does with this data.
26895
26896
26897 .option server_mech cyrus_sasl string "see below"
26898 This option selects the authentication mechanism this driver should use. The
26899 default is the value of the generic &%public_name%& option. This option allows
26900 you to use a different underlying mechanism from the advertised name. For
26901 example:
26902 .code
26903 sasl:
26904   driver = cyrus_sasl
26905   public_name = X-ANYTHING
26906   server_mech = CRAM-MD5
26907   server_set_id = $auth1
26908 .endd
26909
26910 .option server_realm cyrus_sasl string&!! unset
26911 This specifies the SASL realm that the server claims to be in.
26912
26913
26914 .option server_service cyrus_sasl string &`smtp`&
26915 This is the SASL service that the server claims to implement.
26916
26917
26918 For straightforward cases, you do not need to set any of the authenticator's
26919 private options. All you need to do is to specify an appropriate mechanism as
26920 the public name. Thus, if you have a SASL library that supports CRAM-MD5 and
26921 PLAIN, you could have two authenticators as follows:
26922 .code
26923 sasl_cram_md5:
26924   driver = cyrus_sasl
26925   public_name = CRAM-MD5
26926   server_set_id = $auth1
26927
26928 sasl_plain:
26929   driver = cyrus_sasl
26930   public_name = PLAIN
26931   server_set_id = $auth2
26932 .endd
26933 Cyrus SASL does implement the LOGIN authentication method, even though it is
26934 not a standard method. It is disabled by default in the source distribution,
26935 but it is present in many binary distributions.
26936 .ecindex IIDcyrauth1
26937 .ecindex IIDcyrauth2
26938
26939
26940
26941
26942 . ////////////////////////////////////////////////////////////////////////////
26943 . ////////////////////////////////////////////////////////////////////////////
26944 .chapter "The dovecot authenticator" "CHAPdovecot"
26945 .scindex IIDdcotauth1 "&(dovecot)& authenticator"
26946 .scindex IIDdcotauth2 "authenticators" "&(dovecot)&"
26947 This authenticator is an interface to the authentication facility of the
26948 Dovecot POP/IMAP server, which can support a number of authentication methods.
26949 Note that Dovecot must be configured to use auth-client not auth-userdb.
26950 If you are using Dovecot to authenticate POP/IMAP clients, it might be helpful
26951 to use the same mechanisms for SMTP authentication. This is a server
26952 authenticator only. There is only one option:
26953
26954 .option server_socket dovecot string unset
26955
26956 This option must specify the UNIX socket that is the interface to Dovecot
26957 authentication. The &%public_name%& option must specify an authentication
26958 mechanism that Dovecot is configured to support. You can have several
26959 authenticators for different mechanisms. For example:
26960 .code
26961 dovecot_plain:
26962   driver = dovecot
26963   public_name = PLAIN
26964   server_socket = /var/run/dovecot/auth-client
26965   server_set_id = $auth1
26966
26967 dovecot_ntlm:
26968   driver = dovecot
26969   public_name = NTLM
26970   server_socket = /var/run/dovecot/auth-client
26971   server_set_id = $auth1
26972 .endd
26973 If the SMTP connection is encrypted, or if &$sender_host_address$& is equal to
26974 &$received_ip_address$& (that is, the connection is local), the &"secured"&
26975 option is passed in the Dovecot authentication command. If, for a TLS
26976 connection, a client certificate has been verified, the &"valid-client-cert"&
26977 option is passed. When authentication succeeds, the identity of the user
26978 who authenticated is placed in &$auth1$&.
26979 .ecindex IIDdcotauth1
26980 .ecindex IIDdcotauth2
26981
26982
26983 . ////////////////////////////////////////////////////////////////////////////
26984 . ////////////////////////////////////////////////////////////////////////////
26985 .chapter "The gsasl authenticator" "CHAPgsasl"
26986 .scindex IIDgsaslauth1 "&(gsasl)& authenticator"
26987 .scindex IIDgsaslauth2 "authenticators" "&(gsasl)&"
26988 .cindex "authentication" "GNU SASL"
26989 .cindex "authentication" "SASL"
26990 .cindex "authentication" "EXTERNAL"
26991 .cindex "authentication" "ANONYMOUS"
26992 .cindex "authentication" "PLAIN"
26993 .cindex "authentication" "LOGIN"
26994 .cindex "authentication" "DIGEST-MD5"
26995 .cindex "authentication" "CRAM-MD5"
26996 .cindex "authentication" "SCRAM-SHA-1"
26997 The &(gsasl)& authenticator provides server integration for the GNU SASL
26998 library and the mechanisms it provides.  This is new as of the 4.80 release
26999 and there are a few areas where the library does not let Exim smoothly
27000 scale to handle future authentication mechanisms, so no guarantee can be
27001 made that any particular new authentication mechanism will be supported
27002 without code changes in Exim.
27003
27004
27005 .option server_channelbinding gsasl boolean false
27006 Do not set this true without consulting a cryptographic engineer.
27007
27008 Some authentication mechanisms are able to use external context at both ends
27009 of the session to bind the authentication to that context, and fail the
27010 authentication process if that context differs.  Specifically, some TLS
27011 ciphersuites can provide identifying information about the cryptographic
27012 context.
27013
27014 This should have meant that certificate identity and verification becomes a
27015 non-issue, as a man-in-the-middle attack will cause the correct client and
27016 server to see different identifiers and authentication will fail.
27017
27018 This is currently only supported when using the GnuTLS library.  This is
27019 only usable by mechanisms which support "channel binding"; at time of
27020 writing, that's the SCRAM family.
27021
27022 This defaults off to ensure smooth upgrade across Exim releases, in case
27023 this option causes some clients to start failing.  Some future release
27024 of Exim might have switched the default to be true.
27025
27026 However, Channel Binding in TLS has proven to be broken in current versions.
27027 Do not plan to rely upon this feature for security, ever, without consulting
27028 with a subject matter expert (a cryptographic engineer).
27029
27030
27031 .option server_hostname gsasl string&!! "see below"
27032 This option selects the hostname that is used when communicating with the
27033 library. The default value is &`$primary_hostname`&.
27034 Some mechanisms will use this data.
27035
27036
27037 .option server_mech gsasl string "see below"
27038 This option selects the authentication mechanism this driver should use. The
27039 default is the value of the generic &%public_name%& option. This option allows
27040 you to use a different underlying mechanism from the advertised name. For
27041 example:
27042 .code
27043 sasl:
27044   driver = gsasl
27045   public_name = X-ANYTHING
27046   server_mech = CRAM-MD5
27047   server_set_id = $auth1
27048 .endd
27049
27050
27051 .option server_password gsasl string&!! unset
27052 Various mechanisms need access to the cleartext password on the server, so
27053 that proof-of-possession can be demonstrated on the wire, without sending
27054 the password itself.
27055
27056 The data available for lookup varies per mechanism.
27057 In all cases, &$auth1$& is set to the &'authentication id'&.
27058 The &$auth2$& variable will always be the &'authorization id'& (&'authz'&)
27059 if available, else the empty string.
27060 The &$auth3$& variable will always be the &'realm'& if available,
27061 else the empty string.
27062
27063 A forced failure will cause authentication to defer.
27064
27065 If using this option, it may make sense to set the &%server_condition%&
27066 option to be simply "true".
27067
27068
27069 .option server_realm gsasl string&!! unset
27070 This specifies the SASL realm that the server claims to be in.
27071 Some mechanisms will use this data.
27072
27073
27074 .option server_scram_iter gsasl string&!! unset
27075 This option provides data for the SCRAM family of mechanisms.
27076 &$auth1$& is not available at evaluation time.
27077 (This may change, as we receive feedback on use)
27078
27079
27080 .option server_scram_salt gsasl string&!! unset
27081 This option provides data for the SCRAM family of mechanisms.
27082 &$auth1$& is not available at evaluation time.
27083 (This may change, as we receive feedback on use)
27084
27085
27086 .option server_service gsasl string &`smtp`&
27087 This is the SASL service that the server claims to implement.
27088 Some mechanisms will use this data.
27089
27090
27091 .section "&(gsasl)& auth variables" "SECTgsaslauthvar"
27092 .vindex "&$auth1$&, &$auth2$&, etc"
27093 These may be set when evaluating specific options, as detailed above.
27094 They will also be set when evaluating &%server_condition%&.
27095
27096 Unless otherwise stated below, the &(gsasl)& integration will use the following
27097 meanings for these variables:
27098
27099 .ilist
27100 .vindex "&$auth1$&"
27101 &$auth1$&: the &'authentication id'&
27102 .next
27103 .vindex "&$auth2$&"
27104 &$auth2$&: the &'authorization id'&
27105 .next
27106 .vindex "&$auth3$&"
27107 &$auth3$&: the &'realm'&
27108 .endlist
27109
27110 On a per-mechanism basis:
27111
27112 .ilist
27113 .cindex "authentication" "EXTERNAL"
27114 EXTERNAL: only &$auth1$& is set, to the possibly empty &'authorization id'&;
27115 the &%server_condition%& option must be present.
27116 .next
27117 .cindex "authentication" "ANONYMOUS"
27118 ANONYMOUS: only &$auth1$& is set, to the possibly empty &'anonymous token'&;
27119 the &%server_condition%& option must be present.
27120 .next
27121 .cindex "authentication" "GSSAPI"
27122 GSSAPI: &$auth1$& will be set to the &'GSSAPI Display Name'&;
27123 &$auth2$& will be set to the &'authorization id'&,
27124 the &%server_condition%& option must be present.
27125 .endlist
27126
27127 An &'anonymous token'& is something passed along as an unauthenticated
27128 identifier; this is analogous to FTP anonymous authentication passing an
27129 email address, or software-identifier@, as the "password".
27130
27131
27132 An example showing the password having the realm specified in the callback
27133 and demonstrating a Cyrus SASL to GSASL migration approach is:
27134 .code
27135 gsasl_cyrusless_crammd5:
27136   driver = gsasl
27137   public_name = CRAM-MD5
27138   server_realm = imap.example.org
27139   server_password = ${lookup{$auth1:$auth3:userPassword}\
27140                     dbmjz{/etc/sasldb2}{$value}fail}
27141   server_set_id = ${quote:$auth1}
27142   server_condition = yes
27143 .endd
27144
27145
27146 . ////////////////////////////////////////////////////////////////////////////
27147 . ////////////////////////////////////////////////////////////////////////////
27148
27149 .chapter "The heimdal_gssapi authenticator" "CHAPheimdalgss"
27150 .scindex IIDheimdalgssauth1 "&(heimdal_gssapi)& authenticator"
27151 .scindex IIDheimdalgssauth2 "authenticators" "&(heimdal_gssapi)&"
27152 .cindex "authentication" "GSSAPI"
27153 .cindex "authentication" "Kerberos"
27154 The &(heimdal_gssapi)& authenticator provides server integration for the
27155 Heimdal GSSAPI/Kerberos library, permitting Exim to set a keytab pathname
27156 reliably.
27157
27158 .option server_hostname heimdal_gssapi string&!! "see below"
27159 This option selects the hostname that is used, with &%server_service%&,
27160 for constructing the GSS server name, as a &'GSS_C_NT_HOSTBASED_SERVICE'&
27161 identifier.  The default value is &`$primary_hostname`&.
27162
27163 .option server_keytab heimdal_gssapi string&!! unset
27164 If set, then Heimdal will not use the system default keytab (typically
27165 &_/etc/krb5.keytab_&) but instead the pathname given in this option.
27166 The value should be a pathname, with no &"file:"& prefix.
27167
27168 .option server_service heimdal_gssapi string&!! "smtp"
27169 This option specifies the service identifier used, in conjunction with
27170 &%server_hostname%&, for building the identifier for finding credentials
27171 from the keytab.
27172
27173
27174 .section "&(heimdal_gssapi)& auth variables" "SECTheimdalgssauthvar"
27175 Beware that these variables will typically include a realm, thus will appear
27176 to be roughly like an email address already.  The &'authzid'& in &$auth2$& is
27177 not verified, so a malicious client can set it to anything.
27178
27179 The &$auth1$& field should be safely trustable as a value from the Key
27180 Distribution Center.  Note that these are not quite email addresses.
27181 Each identifier is for a role, and so the left-hand-side may include a
27182 role suffix.  For instance, &"joe/admin@EXAMPLE.ORG"&.
27183
27184 .vindex "&$auth1$&, &$auth2$&, etc"
27185 .ilist
27186 .vindex "&$auth1$&"
27187 &$auth1$&: the &'authentication id'&, set to the GSS Display Name.
27188 .next
27189 .vindex "&$auth2$&"
27190 &$auth2$&: the &'authorization id'&, sent within SASL encapsulation after
27191 authentication.  If that was empty, this will also be set to the
27192 GSS Display Name.
27193 .endlist
27194
27195
27196 . ////////////////////////////////////////////////////////////////////////////
27197 . ////////////////////////////////////////////////////////////////////////////
27198
27199 .chapter "The spa authenticator" "CHAPspa"
27200 .scindex IIDspaauth1 "&(spa)& authenticator"
27201 .scindex IIDspaauth2 "authenticators" "&(spa)&"
27202 .cindex "authentication" "Microsoft Secure Password"
27203 .cindex "authentication" "NTLM"
27204 .cindex "Microsoft Secure Password Authentication"
27205 .cindex "NTLM authentication"
27206 The &(spa)& authenticator provides client support for Microsoft's &'Secure
27207 Password Authentication'& mechanism,
27208 which is also sometimes known as NTLM (NT LanMan). The code for client side of
27209 this authenticator was contributed by Marc Prud'hommeaux, and much of it is
27210 taken from the Samba project (&url(https://www.samba.org/)). The code for the
27211 server side was subsequently contributed by Tom Kistner. The mechanism works as
27212 follows:
27213
27214 .ilist
27215 After the AUTH command has been accepted, the client sends an SPA
27216 authentication request based on the user name and optional domain.
27217 .next
27218 The server sends back a challenge.
27219 .next
27220 The client builds a challenge response which makes use of the user's password
27221 and sends it to the server, which then accepts or rejects it.
27222 .endlist
27223
27224 Encryption is used to protect the password in transit.
27225
27226
27227
27228 .section "Using spa as a server" "SECID179"
27229 .cindex "options" "&(spa)& authenticator (server)"
27230 The &(spa)& authenticator has just one server option:
27231
27232 .option server_password spa string&!! unset
27233 .cindex "numerical variables (&$1$& &$2$& etc)" "in &(spa)& authenticator"
27234 This option is expanded, and the result must be the cleartext password for the
27235 authenticating user, whose name is at this point in &$auth1$&. For
27236 compatibility with previous releases of Exim, the user name is also placed in
27237 &$1$&. However, the use of this variable for this purpose is now deprecated, as
27238 it can lead to confusion in string expansions that also use numeric variables
27239 for other things. For example:
27240 .code
27241 spa:
27242   driver = spa
27243   public_name = NTLM
27244   server_password = \
27245     ${lookup{$auth1}lsearch{/etc/exim/spa_clearpass}{$value}fail}
27246 .endd
27247 If the expansion is forced to fail, authentication fails. Any other expansion
27248 failure causes a temporary error code to be returned.
27249
27250
27251
27252
27253
27254 .section "Using spa as a client" "SECID180"
27255 .cindex "options" "&(spa)& authenticator (client)"
27256 The &(spa)& authenticator has the following client options:
27257
27258
27259
27260 .option client_domain spa string&!! unset
27261 This option specifies an optional domain for the authentication.
27262
27263
27264 .option client_password spa string&!! unset
27265 This option specifies the user's password, and must be set.
27266
27267
27268 .option client_username spa string&!! unset
27269 This option specifies the user name, and must be set. Here is an example of a
27270 configuration of this authenticator for use with the mail servers at
27271 &'msn.com'&:
27272 .code
27273 msn:
27274   driver = spa
27275   public_name = MSN
27276   client_username = msn/msn_username
27277   client_password = msn_plaintext_password
27278   client_domain = DOMAIN_OR_UNSET
27279 .endd
27280 .ecindex IIDspaauth1
27281 .ecindex IIDspaauth2
27282
27283
27284
27285
27286
27287 . ////////////////////////////////////////////////////////////////////////////
27288 . ////////////////////////////////////////////////////////////////////////////
27289
27290 .chapter "The external authenticator" "CHAPexternauth"
27291 .scindex IIDexternauth1 "&(external)& authenticator"
27292 .scindex IIDexternauth2 "authenticators" "&(external)&"
27293 .cindex "authentication" "Client Certificate"
27294 .cindex "authentication" "X509"
27295 .cindex "Certificate-based authentication"
27296 The &(external)& authenticator provides support for
27297 authentication based on non-SMTP information.
27298 The specification is in RFC 4422 Appendix A
27299 (&url(https://tools.ietf.org/html/rfc4422)).
27300 It is only a transport and negotiation mechanism;
27301 the process of authentication is entirely controlled
27302 by the server configuration.
27303
27304 The client presents an identity in-clear.
27305 It is probably wise for a server to only advertise,
27306 and for clients to only attempt,
27307 this authentication method on a secure (eg. under TLS) connection.
27308
27309 One possible use, compatible with the
27310 K-9 Mail Andoid client (&url(https://k9mail.github.io/)),
27311 is for using X509 client certificates.
27312
27313 It thus overlaps in function with the TLS authenticator
27314 (see &<<CHAPtlsauth>>&)
27315 but is a full SMTP SASL authenticator
27316 rather than being implicit for TLS-connection carried
27317 client certificates only.
27318
27319 The examples and discussion in this chapter assume that 
27320 client-certificate authentication is being done.
27321
27322 The client must present a certificate,
27323 for which it must have been requested via the
27324 &%tls_verify_hosts%& or &%tls_try_verify_hosts%& main options
27325 (see &<<CHAPTLS>>&).
27326 For authentication to be effective the certificate should be
27327 verifiable against a trust-anchor certificate known to the server.
27328
27329 .section "External options" "SECTexternsoptions"
27330 .cindex "options" "&(external)& authenticator (server)"
27331 The &(external)& authenticator has two server options:
27332
27333 .option server_param2 external string&!! unset
27334 .option server_param3 external string&!! unset
27335 .cindex "variables (&$auth1$& &$auth2$& etc)" "in &(external)& authenticator"
27336 These options are expanded before the &%server_condition%& option
27337 and the result are placed in &$auth2$& and &$auth3$& resectively.
27338 If the expansion is forced to fail, authentication fails. Any other expansion
27339 failure causes a temporary error code to be returned.
27340
27341 They can be used to clarify the coding of a complex &%server_condition%&.
27342
27343 .section "Using external in a server" "SECTexternserver"
27344 .cindex "AUTH" "in &(external)& authenticator"
27345 .cindex "numerical variables (&$1$& &$2$& etc)" &&&
27346         "in &(external)& authenticator"
27347 .vindex "&$auth1$&, &$auth2$&, etc"
27348 .cindex "base64 encoding" "in &(external)& authenticator"
27349
27350 When running as a server, &(external)& performs the authentication test by
27351 expanding a string. The data sent by the client with the AUTH command, or in
27352 response to subsequent prompts, is base64 encoded, and so may contain any byte
27353 values when decoded. The decoded value is treated as
27354 an identity for authentication and
27355 placed in the expansion variable &$auth1$&.
27356
27357 For compatibility with previous releases of Exim, the value is also placed in
27358 the expansion variable &$1$&. However, the use of this
27359 variable for this purpose is now deprecated, as it can lead to confusion in
27360 string expansions that also use them for other things.
27361
27362 .vindex "&$authenticated_id$&"
27363 Once an identity has been received,
27364 &%server_condition%& is expanded. If the expansion is forced to fail,
27365 authentication fails. Any other expansion failure causes a temporary error code
27366 to be returned. If the result of a successful expansion is an empty string,
27367 &"0"&, &"no"&, or &"false"&, authentication fails. If the result of the
27368 expansion is &"1"&, &"yes"&, or &"true"&, authentication succeeds and the
27369 generic &%server_set_id%& option is expanded and saved in &$authenticated_id$&.
27370 For any other result, a temporary error code is returned, with the expanded
27371 string as the error text.
27372
27373 Example:
27374 .code
27375 ext_ccert_san_mail:
27376   driver =            external
27377   public_name =       EXTERNAL
27378
27379   server_advertise_condition = $tls_in_certificate_verified
27380   server_param2 =     ${certextract {subj_altname,mail,>:} \
27381                                     {$tls_in_peercert}}
27382   server_condition =  ${if forany {$auth2} \
27383                             {eq {$item}{$auth1}}}
27384   server_set_id =     $auth1
27385 .endd
27386 This accepts a client certificate that is verifiable against any
27387 of your configured trust-anchors
27388 (which usually means the full set of public CAs)
27389 and which has a mail-SAN matching the claimed identity sent by the client.
27390
27391 Note that, up to TLS1.2, the client cert is on the wire in-clear, including the SAN,
27392 The account name is therefore guessable by an opponent.
27393 TLS 1.3 protects both server and client certificates, and is not vulnerable
27394 in this way.
27395 Likewise, a traditional plaintext SMTP AUTH done inside TLS is not.
27396
27397
27398 .section "Using external in a client" "SECTexternclient"
27399 .cindex "options" "&(external)& authenticator (client)"
27400 The &(external)& authenticator has one client option:
27401
27402 .option client_send external string&!! unset
27403 This option is expanded and sent with the AUTH command as the
27404 identity being asserted.
27405
27406 Example:
27407 .code
27408 ext_ccert:
27409   driver =      external
27410   public_name = EXTERNAL
27411
27412   client_condition = ${if !eq{$tls_out_cipher}{}}
27413   client_send = myaccount@smarthost.example.net
27414 .endd
27415
27416
27417 .ecindex IIDexternauth1
27418 .ecindex IIDexternauth2
27419
27420
27421
27422
27423
27424 . ////////////////////////////////////////////////////////////////////////////
27425 . ////////////////////////////////////////////////////////////////////////////
27426
27427 .chapter "The tls authenticator" "CHAPtlsauth"
27428 .scindex IIDtlsauth1 "&(tls)& authenticator"
27429 .scindex IIDtlsauth2 "authenticators" "&(tls)&"
27430 .cindex "authentication" "Client Certificate"
27431 .cindex "authentication" "X509"
27432 .cindex "Certificate-based authentication"
27433 The &(tls)& authenticator provides server support for
27434 authentication based on client certificates.
27435
27436 It is not an SMTP authentication mechanism and is not
27437 advertised by the server as part of the SMTP EHLO response.
27438 It is an Exim authenticator in the sense that it affects
27439 the protocol element of the log line, can be tested for
27440 by the &%authenticated%& ACL condition, and can set
27441 the &$authenticated_id$& variable.
27442
27443 The client must present a verifiable certificate,
27444 for which it must have been requested via the
27445 &%tls_verify_hosts%& or &%tls_try_verify_hosts%& main options
27446 (see &<<CHAPTLS>>&).
27447
27448 If an authenticator of this type is configured it is
27449 run before any SMTP-level communication is done,
27450 and can authenticate the connection.
27451 If it does, SMTP authentication is not offered.
27452
27453 A maximum of one authenticator of this type may be present.
27454
27455
27456 .cindex "options" "&(tls)& authenticator (server)"
27457 The &(tls)& authenticator has three server options:
27458
27459 .option server_param1 tls string&!! unset
27460 .cindex "variables (&$auth1$& &$auth2$& etc)" "in &(tls)& authenticator"
27461 This option is expanded after the TLS negotiation and
27462 the result is placed in &$auth1$&.
27463 If the expansion is forced to fail, authentication fails. Any other expansion
27464 failure causes a temporary error code to be returned.
27465
27466 .option server_param2 tls string&!! unset
27467 .option server_param3 tls string&!! unset
27468 As above, for &$auth2$& and &$auth3$&.
27469
27470 &%server_param1%& may also be spelled &%server_param%&.
27471
27472
27473 Example:
27474 .code
27475 tls:
27476   driver = tls
27477   server_param1 =     ${certextract {subj_altname,mail,>:} \
27478                                     {$tls_in_peercert}}
27479   server_condition =  ${if and { {eq{$tls_in_certificate_verified}{1}} \
27480                                  {forany {$auth1} \
27481                             {!= {0} \
27482                                 {${lookup ldap{ldap:///\
27483                          mailname=${quote_ldap_dn:${lc:$item}},\
27484                          ou=users,LDAP_DC?mailid} {$value}{0} \
27485                        }    }  } }}}
27486   server_set_id =     ${if = {1}{${listcount:$auth1}} {$auth1}{}}
27487 .endd
27488 This accepts a client certificate that is verifiable against any
27489 of your configured trust-anchors
27490 (which usually means the full set of public CAs)
27491 and which has a SAN with a good account name.
27492
27493 Note that, up to TLS1.2, the client cert is on the wire in-clear, including the SAN,
27494 The account name is therefore guessable by an opponent.
27495 TLS 1.3 protects both server and client certificates, and is not vulnerable
27496 in this way.
27497 Likewise, a traditional plaintext SMTP AUTH done inside TLS is not.
27498
27499 . An alternative might use
27500 . .code
27501 .   server_param1 = ${sha256:$tls_in_peercert}
27502 . .endd
27503 . to require one of a set of specific certs that define a given account
27504 . (the verification is still required, but mostly irrelevant).
27505 . This would help for per-device use.
27506 .
27507 . However, for the future we really need support for checking a
27508 . user cert in LDAP - which probably wants a base-64 DER.
27509
27510 .ecindex IIDtlsauth1
27511 .ecindex IIDtlsauth2
27512
27513
27514 Note that because authentication is traditionally an SMTP operation,
27515 the &%authenticated%& ACL condition cannot be used in
27516 a connect- or helo-ACL.
27517
27518
27519
27520 . ////////////////////////////////////////////////////////////////////////////
27521 . ////////////////////////////////////////////////////////////////////////////
27522
27523 .chapter "Encrypted SMTP connections using TLS/SSL" "CHAPTLS" &&&
27524          "Encrypted SMTP connections"
27525 .scindex IIDencsmtp1 "encryption" "on SMTP connection"
27526 .scindex IIDencsmtp2 "SMTP" "encryption"
27527 .cindex "TLS" "on SMTP connection"
27528 .cindex "OpenSSL"
27529 .cindex "GnuTLS"
27530 Support for TLS (Transport Layer Security), formerly known as SSL (Secure
27531 Sockets Layer), is implemented by making use of the OpenSSL library or the
27532 GnuTLS library (Exim requires GnuTLS release 1.0 or later). There is no
27533 cryptographic code in the Exim distribution itself for implementing TLS. In
27534 order to use this feature you must install OpenSSL or GnuTLS, and then build a
27535 version of Exim that includes TLS support (see section &<<SECTinctlsssl>>&).
27536 You also need to understand the basic concepts of encryption at a managerial
27537 level, and in particular, the way that public keys, private keys, and
27538 certificates are used.
27539
27540 RFC 3207 defines how SMTP connections can make use of encryption. Once a
27541 connection is established, the client issues a STARTTLS command. If the
27542 server accepts this, the client and the server negotiate an encryption
27543 mechanism. If the negotiation succeeds, the data that subsequently passes
27544 between them is encrypted.
27545
27546 Exim's ACLs can detect whether the current SMTP session is encrypted or not,
27547 and if so, what cipher suite is in use, whether the client supplied a
27548 certificate, and whether or not that certificate was verified. This makes it
27549 possible for an Exim server to deny or accept certain commands based on the
27550 encryption state.
27551
27552 &*Warning*&: Certain types of firewall and certain anti-virus products can
27553 disrupt TLS connections. You need to turn off SMTP scanning for these products
27554 in order to get TLS to work.
27555
27556
27557
27558 .section "Support for the &""submissions""& (aka &""ssmtp""& and &""smtps""&) protocol" &&&
27559          "SECID284"
27560 .cindex "submissions protocol"
27561 .cindex "ssmtp protocol"
27562 .cindex "smtps protocol"
27563 .cindex "SMTP" "submissions protocol"
27564 .cindex "SMTP" "ssmtp protocol"
27565 .cindex "SMTP" "smtps protocol"
27566 The history of port numbers for TLS in SMTP is a little messy and has been
27567 contentious.  As of RFC 8314, the common practice of using the historically
27568 allocated port 465 for "email submission but with TLS immediately upon connect
27569 instead of using STARTTLS" is officially blessed by the IETF, and recommended
27570 by them in preference to STARTTLS.
27571
27572 The name originally assigned to the port was &"ssmtp"& or &"smtps"&, but as
27573 clarity emerged over the dual roles of SMTP, for MX delivery and Email
27574 Submission, nomenclature has shifted.  The modern name is now &"submissions"&.
27575
27576 This approach was, for a while, officially abandoned when encrypted SMTP was
27577 standardized, but many clients kept using it, even as the TCP port number was
27578 reassigned for other use.
27579 Thus you may encounter guidance claiming that you shouldn't enable use of
27580 this port.
27581 In practice, a number of mail-clients have only ever supported submissions,
27582 not submission with STARTTLS upgrade.
27583 Ideally, offer both submission (587) and submissions (465) service.
27584
27585 Exim supports TLS-on-connect by means of the &%tls_on_connect_ports%&
27586 global option. Its value must be a list of port numbers;
27587 the most common use is expected to be:
27588 .code
27589 tls_on_connect_ports = 465
27590 .endd
27591 The port numbers specified by this option apply to all SMTP connections, both
27592 via the daemon and via &'inetd'&. You still need to specify all the ports that
27593 the daemon uses (by setting &%daemon_smtp_ports%& or &%local_interfaces%& or
27594 the &%-oX%& command line option) because &%tls_on_connect_ports%& does not add
27595 an extra port &-- rather, it specifies different behaviour on a port that is
27596 defined elsewhere.
27597
27598 There is also a &%-tls-on-connect%& command line option. This overrides
27599 &%tls_on_connect_ports%&; it forces the TLS-only behaviour for all ports.
27600
27601
27602
27603
27604
27605
27606 .section "OpenSSL vs GnuTLS" "SECTopenvsgnu"
27607 .cindex "TLS" "OpenSSL &'vs'& GnuTLS"
27608 The first TLS support in Exim was implemented using OpenSSL. Support for GnuTLS
27609 followed later, when the first versions of GnuTLS were released. To build Exim
27610 to use GnuTLS, you need to set
27611 .code
27612 USE_GNUTLS=yes
27613 .endd
27614 in Local/Makefile, in addition to
27615 .code
27616 SUPPORT_TLS=yes
27617 .endd
27618 You must also set TLS_LIBS and TLS_INCLUDE appropriately, so that the
27619 include files and libraries for GnuTLS can be found.
27620
27621 There are some differences in usage when using GnuTLS instead of OpenSSL:
27622
27623 .ilist
27624 The &%tls_verify_certificates%& option
27625 cannot be the path of a directory
27626 for GnuTLS versions before 3.3.6
27627 (for later versions, or OpenSSL, it can be either).
27628 .next
27629 The default value for &%tls_dhparam%& differs for historical reasons.
27630 .next
27631 .vindex "&$tls_in_peerdn$&"
27632 .vindex "&$tls_out_peerdn$&"
27633 Distinguished Name (DN) strings reported by the OpenSSL library use a slash for
27634 separating fields; GnuTLS uses commas, in accordance with RFC 2253. This
27635 affects the value of the &$tls_in_peerdn$& and &$tls_out_peerdn$& variables.
27636 .next
27637 OpenSSL identifies cipher suites using hyphens as separators, for example:
27638 DES-CBC3-SHA. GnuTLS historically used underscores, for example:
27639 RSA_ARCFOUR_SHA. What is more, OpenSSL complains if underscores are present
27640 in a cipher list. To make life simpler, Exim changes underscores to hyphens
27641 for OpenSSL and passes the string unchanged to GnuTLS (expecting the library
27642 to handle its own older variants) when processing lists of cipher suites in the
27643 &%tls_require_ciphers%& options (the global option and the &(smtp)& transport
27644 option).
27645 .next
27646 The &%tls_require_ciphers%& options operate differently, as described in the
27647 sections &<<SECTreqciphssl>>& and &<<SECTreqciphgnu>>&.
27648 .next
27649 The &%tls_dh_min_bits%& SMTP transport option is only honoured by GnuTLS.
27650 When using OpenSSL, this option is ignored.
27651 (If an API is found to let OpenSSL be configured in this way,
27652 let the Exim Maintainers know and we'll likely use it).
27653 .next
27654 With GnuTLS, if an explicit list is used for the &%tls_privatekey%& main option
27655 main option, it must be ordered to match the &%tls_certificate%& list.
27656 .next
27657 Some other recently added features may only be available in one or the other.
27658 This should be documented with the feature.  If the documentation does not
27659 explicitly state that the feature is infeasible in the other TLS
27660 implementation, then patches are welcome.
27661 .endlist
27662
27663
27664 .section "GnuTLS parameter computation" "SECTgnutlsparam"
27665 This section only applies if &%tls_dhparam%& is set to &`historic`& or to
27666 an explicit path; if the latter, then the text about generation still applies,
27667 but not the chosen filename.
27668 By default, as of Exim 4.80 a hard-coded D-H prime is used.
27669 See the documentation of &%tls_dhparam%& for more information.
27670
27671 GnuTLS uses D-H parameters that may take a substantial amount of time
27672 to compute. It is unreasonable to re-compute them for every TLS session.
27673 Therefore, Exim keeps this data in a file in its spool directory, called
27674 &_gnutls-params-NNNN_& for some value of NNNN, corresponding to the number
27675 of bits requested.
27676 The file is owned by the Exim user and is readable only by
27677 its owner. Every Exim process that start up GnuTLS reads the D-H
27678 parameters from this file. If the file does not exist, the first Exim process
27679 that needs it computes the data and writes it to a temporary file which is
27680 renamed once it is complete. It does not matter if several Exim processes do
27681 this simultaneously (apart from wasting a few resources). Once a file is in
27682 place, new Exim processes immediately start using it.
27683
27684 For maximum security, the parameters that are stored in this file should be
27685 recalculated periodically, the frequency depending on your paranoia level.
27686 If you are avoiding using the fixed D-H primes published in RFCs, then you
27687 are concerned about some advanced attacks and will wish to do this; if you do
27688 not regenerate then you might as well stick to the standard primes.
27689
27690 Arranging this is easy in principle; just delete the file when you want new
27691 values to be computed. However, there may be a problem. The calculation of new
27692 parameters needs random numbers, and these are obtained from &_/dev/random_&.
27693 If the system is not very active, &_/dev/random_& may delay returning data
27694 until enough randomness (entropy) is available. This may cause Exim to hang for
27695 a substantial amount of time, causing timeouts on incoming connections.
27696
27697 The solution is to generate the parameters externally to Exim. They are stored
27698 in &_gnutls-params-N_& in PEM format, which means that they can be
27699 generated externally using the &(certtool)& command that is part of GnuTLS.
27700
27701 To replace the parameters with new ones, instead of deleting the file
27702 and letting Exim re-create it, you can generate new parameters using
27703 &(certtool)& and, when this has been done, replace Exim's cache file by
27704 renaming. The relevant commands are something like this:
27705 .code
27706 # ls
27707 [ look for file; assume gnutls-params-2236 is the most recent ]
27708 # rm -f new-params
27709 # touch new-params
27710 # chown exim:exim new-params
27711 # chmod 0600 new-params
27712 # certtool --generate-dh-params --bits 2236 >>new-params
27713 # openssl dhparam -noout -text -in new-params | head
27714 [ check the first line, make sure it's not more than 2236;
27715   if it is, then go back to the start ("rm") and repeat
27716   until the size generated is at most the size requested ]
27717 # chmod 0400 new-params
27718 # mv new-params gnutls-params-2236
27719 .endd
27720 If Exim never has to generate the parameters itself, the possibility of
27721 stalling is removed.
27722
27723 The filename changed in Exim 4.80, to gain the -bits suffix.  The value which
27724 Exim will choose depends upon the version of GnuTLS in use.  For older GnuTLS,
27725 the value remains hard-coded in Exim as 1024.  As of GnuTLS 2.12.x, there is
27726 a way for Exim to ask for the "normal" number of bits for D-H public-key usage,
27727 and Exim does so.  This attempt to remove Exim from TLS policy decisions
27728 failed, as GnuTLS 2.12 returns a value higher than the current hard-coded limit
27729 of the NSS library.  Thus Exim gains the &%tls_dh_max_bits%& global option,
27730 which applies to all D-H usage, client or server.  If the value returned by
27731 GnuTLS is greater than &%tls_dh_max_bits%& then the value will be clamped down
27732 to &%tls_dh_max_bits%&.  The default value has been set at the current NSS
27733 limit, which is still much higher than Exim historically used.
27734
27735 The filename and bits used will change as the GnuTLS maintainers change the
27736 value for their parameter &`GNUTLS_SEC_PARAM_NORMAL`&, as clamped by
27737 &%tls_dh_max_bits%&.  At the time of writing (mid 2012), GnuTLS 2.12 recommends
27738 2432 bits, while NSS is limited to 2236 bits.
27739
27740 In fact, the requested value will be *lower* than &%tls_dh_max_bits%&, to
27741 increase the chance of the generated prime actually being within acceptable
27742 bounds, as GnuTLS has been observed to overshoot.  Note the check step in the
27743 procedure above.  There is no sane procedure available to Exim to double-check
27744 the size of the generated prime, so it might still be too large.
27745
27746
27747 .section "Requiring specific ciphers in OpenSSL" "SECTreqciphssl"
27748 .cindex "TLS" "requiring specific ciphers (OpenSSL)"
27749 .oindex "&%tls_require_ciphers%&" "OpenSSL"
27750 There is a function in the OpenSSL library that can be passed a list of cipher
27751 suites before the cipher negotiation takes place. This specifies which ciphers
27752 .new
27753 are acceptable for TLS versions prior to 1.3.
27754 .wen
27755 The list is colon separated and may contain names like
27756 DES-CBC3-SHA. Exim passes the expanded value of &%tls_require_ciphers%&
27757 directly to this function call.
27758 Many systems will install the OpenSSL manual-pages, so you may have
27759 &'ciphers(1)'& available to you.
27760 The following quotation from the OpenSSL
27761 documentation specifies what forms of item are allowed in the cipher string:
27762
27763 .ilist
27764 It can consist of a single cipher suite such as RC4-SHA.
27765 .next
27766 It can represent a list of cipher suites containing a certain algorithm,
27767 or cipher suites of a certain type. For example SHA1 represents all
27768 ciphers suites using the digest algorithm SHA1 and SSLv3 represents all
27769 SSL v3 algorithms.
27770 .next
27771 Lists of cipher suites can be combined in a single cipher string using
27772 the + character. This is used as a logical and operation. For example
27773 SHA1+DES represents all cipher suites containing the SHA1 and the DES
27774 algorithms.
27775 .endlist
27776
27777 Each cipher string can be optionally preceded by one of the characters &`!`&,
27778 &`-`& or &`+`&.
27779 .ilist
27780 If &`!`& is used, the ciphers are permanently deleted from the list. The
27781 ciphers deleted can never reappear in the list even if they are explicitly
27782 stated.
27783 .next
27784 If &`-`& is used, the ciphers are deleted from the list, but some or all
27785 of the ciphers can be added again by later options.
27786 .next
27787 If &`+`& is used, the ciphers are moved to the end of the list. This
27788 option does not add any new ciphers; it just moves matching existing ones.
27789 .endlist
27790
27791 If none of these characters is present, the string is interpreted as
27792 a list of ciphers to be appended to the current preference list. If the list
27793 includes any ciphers already present they will be ignored: that is, they will
27794 not be moved to the end of the list.
27795 .endlist
27796
27797 The OpenSSL &'ciphers(1)'& command may be used to test the results of a given
27798 string:
27799 .code
27800 # note single-quotes to get ! past any shell history expansion
27801 $ openssl ciphers 'HIGH:!MD5:!SHA1'
27802 .endd
27803
27804 This example will let the library defaults be permitted on the MX port, where
27805 there's probably no identity verification anyway, but ups the ante on the
27806 submission ports where the administrator might have some influence on the
27807 choice of clients used:
27808 .code
27809 # OpenSSL variant; see man ciphers(1)
27810 tls_require_ciphers = ${if =={$received_port}{25}\
27811                            {DEFAULT}\
27812                            {HIGH:!MD5:!SHA1}}
27813 .endd
27814
27815 This example will prefer ECDSA-authenticated ciphers over RSA ones:
27816 .code
27817 tls_require_ciphers = ECDSA:RSA:!COMPLEMENTOFDEFAULT
27818 .endd
27819
27820 .new
27821 For TLS version 1.3 the control available is less fine-grained
27822 and Exim does not provide access to it at present.
27823 The value of the &%tls_require_ciphers%& option is ignored when
27824 TLS version 1.3 is negotiated.
27825
27826 As of writing the library default cipher suite list for TLSv1.3 is
27827 .code
27828 TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256
27829 .endd
27830 .wen
27831
27832
27833 .section "Requiring specific ciphers or other parameters in GnuTLS" &&&
27834          "SECTreqciphgnu"
27835 .cindex "GnuTLS" "specifying parameters for"
27836 .cindex "TLS" "specifying ciphers (GnuTLS)"
27837 .cindex "TLS" "specifying key exchange methods (GnuTLS)"
27838 .cindex "TLS" "specifying MAC algorithms (GnuTLS)"
27839 .cindex "TLS" "specifying protocols (GnuTLS)"
27840 .cindex "TLS" "specifying priority string (GnuTLS)"
27841 .oindex "&%tls_require_ciphers%&" "GnuTLS"
27842 The GnuTLS library allows the caller to provide a "priority string", documented
27843 as part of the &[gnutls_priority_init]& function.  This is very similar to the
27844 ciphersuite specification in OpenSSL.
27845
27846 The &%tls_require_ciphers%& option is treated as the GnuTLS priority string
27847 and controls both protocols and ciphers.
27848
27849 The &%tls_require_ciphers%& option is available both as an global option,
27850 controlling how Exim behaves as a server, and also as an option of the
27851 &(smtp)& transport, controlling how Exim behaves as a client.  In both cases
27852 the value is string expanded.  The resulting string is not an Exim list and
27853 the string is given to the GnuTLS library, so that Exim does not need to be
27854 aware of future feature enhancements of GnuTLS.
27855
27856 Documentation of the strings accepted may be found in the GnuTLS manual, under
27857 "Priority strings".  This is online as
27858 &url(https://www.gnutls.org/manual/html_node/Priority-Strings.html),
27859 but beware that this relates to GnuTLS 3, which may be newer than the version
27860 installed on your system.  If you are using GnuTLS 3,
27861 then the example code
27862 &url(https://www.gnutls.org/manual/gnutls.html#Listing-the-ciphersuites-in-a-priority-string)
27863 on that site can be used to test a given string.
27864
27865 For example:
27866 .code
27867 # Disable older versions of protocols
27868 tls_require_ciphers = NORMAL:%LATEST_RECORD_VERSION:-VERS-SSL3.0
27869 .endd
27870
27871 Prior to Exim 4.80, an older API of GnuTLS was used, and Exim supported three
27872 additional options, "&%gnutls_require_kx%&", "&%gnutls_require_mac%&" and
27873 "&%gnutls_require_protocols%&".  &%tls_require_ciphers%& was an Exim list.
27874
27875 This example will let the library defaults be permitted on the MX port, where
27876 there's probably no identity verification anyway, and lowers security further
27877 by increasing compatibility; but this ups the ante on the submission ports
27878 where the administrator might have some influence on the choice of clients
27879 used:
27880 .code
27881 # GnuTLS variant
27882 tls_require_ciphers = ${if =={$received_port}{25}\
27883                            {NORMAL:%COMPAT}\
27884                            {SECURE128}}
27885 .endd
27886
27887
27888 .section "Configuring an Exim server to use TLS" "SECID182"
27889 .cindex "TLS" "configuring an Exim server"
27890 When Exim has been built with TLS support, it advertises the availability of
27891 the STARTTLS command to client hosts that match &%tls_advertise_hosts%&,
27892 but not to any others. The default value of this option is *, which means
27893 that STARTTLS is always advertised.  Set it to blank to never advertise;
27894 this is reasonable for systems that want to use TLS only as a client.
27895
27896 If STARTTLS is to be used you
27897 need to set some other options in order to make TLS available.
27898
27899 If a client issues a STARTTLS command and there is some configuration
27900 problem in the server, the command is rejected with a 454 error. If the client
27901 persists in trying to issue SMTP commands, all except QUIT are rejected
27902 with the error
27903 .code
27904 554 Security failure
27905 .endd
27906 If a STARTTLS command is issued within an existing TLS session, it is
27907 rejected with a 554 error code.
27908
27909 To enable TLS operations on a server, the &%tls_advertise_hosts%& option
27910 must be set to match some hosts. The default is * which matches all hosts.
27911
27912 If this is all you do, TLS encryption will be enabled but not authentication -
27913 meaning that the peer has no assurance it is actually you he is talking to.
27914 You gain protection from a passive sniffer listening on the wire but not
27915 from someone able to intercept the communication.
27916
27917 Further protection requires some further configuration at the server end.
27918
27919 To make TLS work you need to set, in the server,
27920 .code
27921 tls_certificate = /some/file/name
27922 tls_privatekey = /some/file/name
27923 .endd
27924 These options are, in fact, expanded strings, so you can make them depend on
27925 the identity of the client that is connected if you wish. The first file
27926 contains the server's X509 certificate, and the second contains the private key
27927 that goes with it. These files need to be
27928 PEM format and readable by the Exim user, and must
27929 always be given as full path names.
27930 The key must not be password-protected.
27931 They can be the same file if both the
27932 certificate and the key are contained within it. If &%tls_privatekey%& is not
27933 set, or if its expansion is forced to fail or results in an empty string, this
27934 is assumed to be the case. The certificate file may also contain intermediate
27935 certificates that need to be sent to the client to enable it to authenticate
27936 the server's certificate.
27937
27938 For dual-stack (eg. RSA and ECDSA) configurations, these options can be
27939 colon-separated lists of file paths.  Ciphers using given authentication
27940 algorithms require the presence of a suitable certificate to supply the
27941 public-key.  The server selects among the certificates to present to the
27942 client depending on the selected cipher, hence the priority ordering for
27943 ciphers will affect which certificate is used.
27944
27945 If you do not understand about certificates and keys, please try to find a
27946 source of this background information, which is not Exim-specific. (There are a
27947 few comments below in section &<<SECTcerandall>>&.)
27948
27949 &*Note*&: These options do not apply when Exim is operating as a client &--
27950 they apply only in the case of a server. If you need to use a certificate in an
27951 Exim client, you must set the options of the same names in an &(smtp)&
27952 transport.
27953
27954 With just these options, an Exim server will be able to use TLS. It does not
27955 require the client to have a certificate (but see below for how to insist on
27956 this). There is one other option that may be needed in other situations. If
27957 .code
27958 tls_dhparam = /some/file/name
27959 .endd
27960 is set, the SSL library is initialized for the use of Diffie-Hellman ciphers
27961 with the parameters contained in the file.
27962 Set this to &`none`& to disable use of DH entirely, by making no prime
27963 available:
27964 .code
27965 tls_dhparam = none
27966 .endd
27967 This may also be set to a string identifying a standard prime to be used for
27968 DH; if it is set to &`default`& or, for OpenSSL, is unset, then the prime
27969 used is &`ike23`&.  There are a few standard primes available, see the
27970 documentation for &%tls_dhparam%& for the complete list.
27971
27972 See the command
27973 .code
27974 openssl dhparam
27975 .endd
27976 for a way of generating file data.
27977
27978 The strings supplied for these three options are expanded every time a client
27979 host connects. It is therefore possible to use different certificates and keys
27980 for different hosts, if you so wish, by making use of the client's IP address
27981 in &$sender_host_address$& to control the expansion. If a string expansion is
27982 forced to fail, Exim behaves as if the option is not set.
27983
27984 .cindex "cipher" "logging"
27985 .cindex "log" "TLS cipher"
27986 .vindex "&$tls_in_cipher$&"
27987 The variable &$tls_in_cipher$& is set to the cipher suite that was negotiated for
27988 an incoming TLS connection. It is included in the &'Received:'& header of an
27989 incoming message (by default &-- you can, of course, change this), and it is
27990 also included in the log line that records a message's arrival, keyed by
27991 &"X="&, unless the &%tls_cipher%& log selector is turned off. The &%encrypted%&
27992 condition can be used to test for specific cipher suites in ACLs.
27993
27994 Once TLS has been established, the ACLs that run for subsequent SMTP commands
27995 can check the name of the cipher suite and vary their actions accordingly. The
27996 cipher suite names vary, depending on which TLS library is being used. For
27997 example, OpenSSL uses the name DES-CBC3-SHA for the cipher suite which in other
27998 contexts is known as TLS_RSA_WITH_3DES_EDE_CBC_SHA. Check the OpenSSL or GnuTLS
27999 documentation for more details.
28000
28001 For outgoing SMTP deliveries, &$tls_out_cipher$& is used and logged
28002 (again depending on the &%tls_cipher%& log selector).
28003
28004
28005 .section "Requesting and verifying client certificates" "SECID183"
28006 .cindex "certificate" "verification of client"
28007 .cindex "TLS" "client certificate verification"
28008 If you want an Exim server to request a certificate when negotiating a TLS
28009 session with a client, you must set either &%tls_verify_hosts%& or
28010 &%tls_try_verify_hosts%&. You can, of course, set either of them to * to
28011 apply to all TLS connections. For any host that matches one of these options,
28012 Exim requests a certificate as part of the setup of the TLS session. The
28013 contents of the certificate are verified by comparing it with a list of
28014 expected trust-anchors or certificates.
28015 These may be the system default set (depending on library version),
28016 an explicit file or,
28017 depending on library version, a directory, identified by
28018 &%tls_verify_certificates%&.
28019
28020 A file can contain multiple certificates, concatenated end to end. If a
28021 directory is used
28022 (OpenSSL only),
28023 each certificate must be in a separate file, with a name (or a symbolic link)
28024 of the form <&'hash'&>.0, where <&'hash'&> is a hash value constructed from the
28025 certificate. You can compute the relevant hash by running the command
28026 .code
28027 openssl x509 -hash -noout -in /cert/file
28028 .endd
28029 where &_/cert/file_& contains a single certificate.
28030
28031 There is no checking of names of the client against the certificate
28032 Subject Name or Subject Alternate Names.
28033
28034 The difference between &%tls_verify_hosts%& and &%tls_try_verify_hosts%& is
28035 what happens if the client does not supply a certificate, or if the certificate
28036 does not match any of the certificates in the collection named by
28037 &%tls_verify_certificates%&. If the client matches &%tls_verify_hosts%&, the
28038 attempt to set up a TLS session is aborted, and the incoming connection is
28039 dropped. If the client matches &%tls_try_verify_hosts%&, the (encrypted) SMTP
28040 session continues. ACLs that run for subsequent SMTP commands can detect the
28041 fact that no certificate was verified, and vary their actions accordingly. For
28042 example, you can insist on a certificate before accepting a message for
28043 relaying, but not when the message is destined for local delivery.
28044
28045 .vindex "&$tls_in_peerdn$&"
28046 When a client supplies a certificate (whether it verifies or not), the value of
28047 the Distinguished Name of the certificate is made available in the variable
28048 &$tls_in_peerdn$& during subsequent processing of the message.
28049
28050 .cindex "log" "distinguished name"
28051 Because it is often a long text string, it is not included in the log line or
28052 &'Received:'& header by default. You can arrange for it to be logged, keyed by
28053 &"DN="&, by setting the &%tls_peerdn%& log selector, and you can use
28054 &%received_header_text%& to change the &'Received:'& header. When no
28055 certificate is supplied, &$tls_in_peerdn$& is empty.
28056
28057
28058 .section "Revoked certificates" "SECID184"
28059 .cindex "TLS" "revoked certificates"
28060 .cindex "revocation list"
28061 .cindex "certificate" "revocation list"
28062 .cindex "OCSP" "stapling"
28063 Certificate issuing authorities issue Certificate Revocation Lists (CRLs) when
28064 certificates are revoked. If you have such a list, you can pass it to an Exim
28065 server using the global option called &%tls_crl%& and to an Exim client using
28066 an identically named option for the &(smtp)& transport. In each case, the value
28067 of the option is expanded and must then be the name of a file that contains a
28068 CRL in PEM format.
28069 The downside is that clients have to periodically re-download a potentially huge
28070 file from every certificate authority they know of.
28071
28072 The way with most moving parts at query time is Online Certificate
28073 Status Protocol (OCSP), where the client verifies the certificate
28074 against an OCSP server run by the CA.  This lets the CA track all
28075 usage of the certs.  It requires running software with access to the
28076 private key of the CA, to sign the responses to the OCSP queries.  OCSP
28077 is based on HTTP and can be proxied accordingly.
28078
28079 The only widespread OCSP server implementation (known to this writer)
28080 comes as part of OpenSSL and aborts on an invalid request, such as
28081 connecting to the port and then disconnecting.  This requires
28082 re-entering the passphrase each time some random client does this.
28083
28084 The third way is OCSP Stapling; in this, the server using a certificate
28085 issued by the CA periodically requests an OCSP proof of validity from
28086 the OCSP server, then serves it up inline as part of the TLS
28087 negotiation.   This approach adds no extra round trips, does not let the
28088 CA track users, scales well with number of certs issued by the CA and is
28089 resilient to temporary OCSP server failures, as long as the server
28090 starts retrying to fetch an OCSP proof some time before its current
28091 proof expires.  The downside is that it requires server support.
28092
28093 Unless Exim is built with the support disabled,
28094 or with GnuTLS earlier than version 3.3.16 / 3.4.8
28095 support for OCSP stapling is included.
28096
28097 There is a global option called &%tls_ocsp_file%&.
28098 The file specified therein is expected to be in DER format, and contain
28099 an OCSP proof.  Exim will serve it as part of the TLS handshake.  This
28100 option will be re-expanded for SNI, if the &%tls_certificate%& option
28101 contains &`tls_in_sni`&, as per other TLS options.
28102
28103 Exim does not at this time implement any support for fetching a new OCSP
28104 proof.  The burden is on the administrator to handle this, outside of
28105 Exim.  The file specified should be replaced atomically, so that the
28106 contents are always valid.  Exim will expand the &%tls_ocsp_file%& option
28107 on each connection, so a new file will be handled transparently on the
28108 next connection.
28109
28110 When built with OpenSSL Exim will check for a valid next update timestamp
28111 in the OCSP proof; if not present, or if the proof has expired, it will be
28112 ignored.
28113
28114 For the client to be able to verify the stapled OCSP the server must
28115 also supply, in its stapled information, any intermediate
28116 certificates for the chain leading to the OCSP proof from the signer
28117 of the server certificate.  There may be zero or one such. These
28118 intermediate certificates should be added to the server OCSP stapling
28119 file named by &%tls_ocsp_file%&.
28120
28121 Note that the proof only covers the terminal server certificate,
28122 not any of the chain from CA to it.
28123
28124 There is no current way to staple a proof for a client certificate.
28125
28126 .code
28127   A helper script "ocsp_fetch.pl" for fetching a proof from a CA
28128   OCSP server is supplied.  The server URL may be included in the
28129   server certificate, if the CA is helpful.
28130
28131   One failure mode seen was the OCSP Signer cert expiring before the end
28132   of validity of the OCSP proof. The checking done by Exim/OpenSSL
28133   noted this as invalid overall, but the re-fetch script did not.
28134 .endd
28135
28136
28137
28138
28139 .section "Configuring an Exim client to use TLS" "SECID185"
28140 .cindex "cipher" "logging"
28141 .cindex "log" "TLS cipher"
28142 .cindex "log" "distinguished name"
28143 .cindex "TLS" "configuring an Exim client"
28144 The &%tls_cipher%& and &%tls_peerdn%& log selectors apply to outgoing SMTP
28145 deliveries as well as to incoming, the latter one causing logging of the
28146 server certificate's DN. The remaining client configuration for TLS is all
28147 within the &(smtp)& transport.
28148
28149 It is not necessary to set any options to have TLS work in the &(smtp)&
28150 transport. If Exim is built with TLS support, and TLS is advertised by a
28151 server, the &(smtp)& transport always tries to start a TLS session. However,
28152 this can be prevented by setting &%hosts_avoid_tls%& (an option of the
28153 transport) to a list of server hosts for which TLS should not be used.
28154
28155 If you do not want Exim to attempt to send messages unencrypted when an attempt
28156 to set up an encrypted connection fails in any way, you can set
28157 &%hosts_require_tls%& to a list of hosts for which encryption is mandatory. For
28158 those hosts, delivery is always deferred if an encrypted connection cannot be
28159 set up. If there are any other hosts for the address, they are tried in the
28160 usual way.
28161
28162 When the server host is not in &%hosts_require_tls%&, Exim may try to deliver
28163 the message unencrypted. It always does this if the response to STARTTLS is
28164 a 5&'xx'& code. For a temporary error code, or for a failure to negotiate a TLS
28165 session after a success response code, what happens is controlled by the
28166 &%tls_tempfail_tryclear%& option of the &(smtp)& transport. If it is false,
28167 delivery to this host is deferred, and other hosts (if available) are tried. If
28168 it is true, Exim attempts to deliver unencrypted after a 4&'xx'& response to
28169 STARTTLS, and if STARTTLS is accepted, but the subsequent TLS
28170 negotiation fails, Exim closes the current connection (because it is in an
28171 unknown state), opens a new one to the same host, and then tries the delivery
28172 unencrypted.
28173
28174 The &%tls_certificate%& and &%tls_privatekey%& options of the &(smtp)&
28175 transport provide the client with a certificate, which is passed to the server
28176 if it requests it. If the server is Exim, it will request a certificate only if
28177 &%tls_verify_hosts%& or &%tls_try_verify_hosts%& matches the client.
28178
28179 If the &%tls_verify_certificates%& option is set on the &(smtp)& transport, it
28180 specifies a collection of expected server certificates.
28181 These may be
28182 the system default set (depending on library version),
28183 a file,
28184 or (depending on library version) a directory.
28185 The client verifies the server's certificate
28186 against this collection, taking into account any revoked certificates that are
28187 in the list defined by &%tls_crl%&.
28188 Failure to verify fails the TLS connection unless either of the
28189 &%tls_verify_hosts%& or &%tls_try_verify_hosts%& options are set.
28190
28191 The &%tls_verify_hosts%& and &%tls_try_verify_hosts%& options restrict
28192 certificate verification to the listed servers.  Verification either must
28193 or need not succeed respectively.
28194
28195 The &%tls_verify_cert_hostnames%& option lists hosts for which additional
28196 checks are made: that the host name (the one in the DNS A record)
28197 is valid for the certificate.
28198 The option defaults to always checking.
28199
28200 The &(smtp)& transport has two OCSP-related options:
28201 &%hosts_require_ocsp%&; a host-list for which a Certificate Status
28202 is requested and required for the connection to proceed.  The default
28203 value is empty.
28204 &%hosts_request_ocsp%&; a host-list for which (additionally)
28205 a Certificate Status is requested (but not necessarily verified).  The default
28206 value is "*" meaning that requests are made unless configured
28207 otherwise.
28208
28209 The host(s) should also be in &%hosts_require_tls%&, and
28210 &%tls_verify_certificates%& configured for the transport,
28211 for OCSP to be relevant.
28212
28213 If
28214 &%tls_require_ciphers%& is set on the &(smtp)& transport, it must contain a
28215 list of permitted cipher suites. If either of these checks fails, delivery to
28216 the current host is abandoned, and the &(smtp)& transport tries to deliver to
28217 alternative hosts, if any.
28218
28219  &*Note*&:
28220 These options must be set in the &(smtp)& transport for Exim to use TLS when it
28221 is operating as a client. Exim does not assume that a server certificate (set
28222 by the global options of the same name) should also be used when operating as a
28223 client.
28224
28225 .vindex "&$host$&"
28226 .vindex "&$host_address$&"
28227 All the TLS options in the &(smtp)& transport are expanded before use, with
28228 &$host$& and &$host_address$& containing the name and address of the server to
28229 which the client is connected. Forced failure of an expansion causes Exim to
28230 behave as if the relevant option were unset.
28231
28232 .vindex &$tls_out_bits$&
28233 .vindex &$tls_out_cipher$&
28234 .vindex &$tls_out_peerdn$&
28235 .vindex &$tls_out_sni$&
28236 Before an SMTP connection is established, the
28237 &$tls_out_bits$&, &$tls_out_cipher$&, &$tls_out_peerdn$& and &$tls_out_sni$&
28238 variables are emptied. (Until the first connection, they contain the values
28239 that were set when the message was received.) If STARTTLS is subsequently
28240 successfully obeyed, these variables are set to the relevant values for the
28241 outgoing connection.
28242
28243
28244
28245 .section "Use of TLS Server Name Indication" "SECTtlssni"
28246 .cindex "TLS" "Server Name Indication"
28247 .vindex "&$tls_in_sni$&"
28248 .oindex "&%tls_in_sni%&"
28249 With TLS1.0 or above, there is an extension mechanism by which extra
28250 information can be included at various points in the protocol.  One of these
28251 extensions, documented in RFC 6066 (and before that RFC 4366) is
28252 &"Server Name Indication"&, commonly &"SNI"&.  This extension is sent by the
28253 client in the initial handshake, so that the server can examine the servername
28254 within and possibly choose to use different certificates and keys (and more)
28255 for this session.
28256
28257 This is analogous to HTTP's &"Host:"& header, and is the main mechanism by
28258 which HTTPS-enabled web-sites can be virtual-hosted, many sites to one IP
28259 address.
28260
28261 With SMTP to MX, there are the same problems here as in choosing the identity
28262 against which to validate a certificate: you can't rely on insecure DNS to
28263 provide the identity which you then cryptographically verify.  So this will
28264 be of limited use in that environment.
28265
28266 With SMTP to Submission, there is a well-defined hostname which clients are
28267 connecting to and can validate certificates against.  Thus clients &*can*&
28268 choose to include this information in the TLS negotiation.  If this becomes
28269 wide-spread, then hosters can choose to present different certificates to
28270 different clients.  Or even negotiate different cipher suites.
28271
28272 The &%tls_sni%& option on an SMTP transport is an expanded string; the result,
28273 if not empty, will be sent on a TLS session as part of the handshake.  There's
28274 nothing more to it.  Choosing a sensible value not derived insecurely is the
28275 only point of caution.  The &$tls_out_sni$& variable will be set to this string
28276 for the lifetime of the client connection (including during authentication).
28277
28278 Except during SMTP client sessions, if &$tls_in_sni$& is set then it is a string
28279 received from a client.
28280 It can be logged with the &%log_selector%& item &`+tls_sni`&.
28281
28282 If the string &`tls_in_sni`& appears in the main section's &%tls_certificate%&
28283 option (prior to expansion) then the following options will be re-expanded
28284 during TLS session handshake, to permit alternative values to be chosen:
28285
28286 .ilist
28287 &%tls_certificate%&
28288 .next
28289 &%tls_crl%&
28290 .next
28291 &%tls_privatekey%&
28292 .next
28293 &%tls_verify_certificates%&
28294 .next
28295 &%tls_ocsp_file%&
28296 .endlist
28297
28298 Great care should be taken to deal with matters of case, various injection
28299 attacks in the string (&`../`& or SQL), and ensuring that a valid filename
28300 can always be referenced; it is important to remember that &$tls_in_sni$& is
28301 arbitrary unverified data provided prior to authentication.
28302 Further, the initial certificate is loaded before SNI is arrived, so
28303 an expansion for &%tls_certificate%& must have a default which is used
28304 when &$tls_in_sni$& is empty.
28305
28306 The Exim developers are proceeding cautiously and so far no other TLS options
28307 are re-expanded.
28308
28309 When Exim is built against OpenSSL, OpenSSL must have been built with support
28310 for TLS Extensions.  This holds true for OpenSSL 1.0.0+ and 0.9.8+ with
28311 enable-tlsext in EXTRACONFIGURE.  If you invoke &(openssl s_client -h)& and
28312 see &`-servername`& in the output, then OpenSSL has support.
28313
28314 When Exim is built against GnuTLS, SNI support is available as of GnuTLS
28315 0.5.10.  (Its presence predates the current API which Exim uses, so if Exim
28316 built, then you have SNI support).
28317
28318
28319
28320 .section "Multiple messages on the same encrypted TCP/IP connection" &&&
28321          "SECTmulmessam"
28322 .cindex "multiple SMTP deliveries with TLS"
28323 .cindex "TLS" "multiple message deliveries"
28324 Exim sends multiple messages down the same TCP/IP connection by starting up
28325 an entirely new delivery process for each message, passing the socket from
28326 one process to the next. This implementation does not fit well with the use
28327 of TLS, because there is quite a lot of state information associated with a TLS
28328 connection, not just a socket identification. Passing all the state information
28329 to a new process is not feasible. Consequently, for sending using TLS Exim
28330 starts an additional proxy process for handling the encryption, piping the
28331 unencrypted data stream from and to the delivery processes.
28332
28333 An older mode of operation can be enabled on a per-host basis by the
28334 &%hosts_noproxy_tls%& option on the &(smtp)& transport.  If the host matches
28335 this list the proxy process described above is not used; instead Exim
28336 shuts down an existing TLS session being run by the delivery process
28337 before passing the socket to a new process. The new process may then
28338 try to start a new TLS session, and if successful, may try to re-authenticate
28339 if AUTH is in use, before sending the next message.
28340
28341 The RFC is not clear as to whether or not an SMTP session continues in clear
28342 after TLS has been shut down, or whether TLS may be restarted again later, as
28343 just described. However, if the server is Exim, this shutdown and
28344 reinitialization works. It is not known which (if any) other servers operate
28345 successfully if the client closes a TLS session and continues with unencrypted
28346 SMTP, but there are certainly some that do not work. For such servers, Exim
28347 should not pass the socket to another process, because the failure of the
28348 subsequent attempt to use it would cause Exim to record a temporary host error,
28349 and delay other deliveries to that host.
28350
28351 To test for this case, Exim sends an EHLO command to the server after
28352 closing down the TLS session. If this fails in any way, the connection is
28353 closed instead of being passed to a new delivery process, but no retry
28354 information is recorded.
28355
28356 There is also a manual override; you can set &%hosts_nopass_tls%& on the
28357 &(smtp)& transport to match those hosts for which Exim should not pass
28358 connections to new processes if TLS has been used.
28359
28360
28361
28362
28363 .section "Certificates and all that" "SECTcerandall"
28364 .cindex "certificate" "references to discussion"
28365 In order to understand fully how TLS works, you need to know about
28366 certificates, certificate signing, and certificate authorities.
28367 This is a large topic and an introductory guide is unsuitable for the Exim
28368 reference manual, so instead we provide pointers to existing documentation.
28369
28370 The Apache web-server was for a long time the canonical guide, so their
28371 documentation is a good place to start; their SSL module's Introduction
28372 document is currently at
28373 .display
28374 &url(https://httpd.apache.org/docs/current/ssl/ssl_intro.html)
28375 .endd
28376 and their FAQ is at
28377 .display
28378 &url(https://httpd.apache.org/docs/current/ssl/ssl_faq.html)
28379 .endd
28380
28381 Eric Rescorla's book, &'SSL and TLS'&, published by Addison-Wesley (ISBN
28382 0-201-61598-3) in 2001, contains both introductory and more in-depth
28383 descriptions.
28384 More recently Ivan Ristić's book &'Bulletproof SSL and TLS'&,
28385 published by Feisty Duck (ISBN 978-1907117046) in 2013 is good.
28386 Ivan is the author of the popular TLS testing tools at
28387 &url(https://www.ssllabs.com/).
28388
28389
28390 .section "Certificate chains" "SECID186"
28391 The file named by &%tls_certificate%& may contain more than one
28392 certificate. This is useful in the case where the certificate that is being
28393 sent is validated by an intermediate certificate which the other end does
28394 not have. Multiple certificates must be in the correct order in the file.
28395 First the host's certificate itself, then the first intermediate
28396 certificate to validate the issuer of the host certificate, then the next
28397 intermediate certificate to validate the issuer of the first intermediate
28398 certificate, and so on, until finally (optionally) the root certificate.
28399 The root certificate must already be trusted by the recipient for
28400 validation to succeed, of course, but if it's not preinstalled, sending the
28401 root certificate along with the rest makes it available for the user to
28402 install if the receiving end is a client MUA that can interact with a user.
28403
28404 Note that certificates using MD5 are unlikely to work on today's Internet;
28405 even if your libraries allow loading them for use in Exim when acting as a
28406 server, increasingly clients will not accept such certificates.  The error
28407 diagnostics in such a case can be frustratingly vague.
28408
28409
28410
28411 .section "Self-signed certificates" "SECID187"
28412 .cindex "certificate" "self-signed"
28413 You can create a self-signed certificate using the &'req'& command provided
28414 with OpenSSL, like this:
28415 . ==== Do not shorten the duration here without reading and considering
28416 . ==== the text below.  Please leave it at 9999 days.
28417 .code
28418 openssl req -x509 -newkey rsa:1024 -keyout file1 -out file2 \
28419             -days 9999 -nodes
28420 .endd
28421 &_file1_& and &_file2_& can be the same file; the key and the certificate are
28422 delimited and so can be identified independently. The &%-days%& option
28423 specifies a period for which the certificate is valid. The &%-nodes%& option is
28424 important: if you do not set it, the key is encrypted with a passphrase
28425 that you are prompted for, and any use that is made of the key causes more
28426 prompting for the passphrase. This is not helpful if you are going to use
28427 this certificate and key in an MTA, where prompting is not possible.
28428
28429 . ==== I expect to still be working 26 years from now.  The less technical
28430 . ==== debt I create, in terms of storing up trouble for my later years, the
28431 . ==== happier I will be then.  We really have reached the point where we
28432 . ==== should start, at the very least, provoking thought and making folks
28433 . ==== pause before proceeding, instead of leaving all the fixes until two
28434 . ==== years before 2^31 seconds after the 1970 Unix epoch.
28435 . ==== -pdp, 2012
28436 NB: we are now past the point where 9999 days takes us past the 32-bit Unix
28437 epoch.  If your system uses unsigned time_t (most do) and is 32-bit, then
28438 the above command might produce a date in the past.  Think carefully about
28439 the lifetime of the systems you're deploying, and either reduce the duration
28440 of the certificate or reconsider your platform deployment.  (At time of
28441 writing, reducing the duration is the most likely choice, but the inexorable
28442 progression of time takes us steadily towards an era where this will not
28443 be a sensible resolution).
28444
28445 A self-signed certificate made in this way is sufficient for testing, and
28446 may be adequate for all your requirements if you are mainly interested in
28447 encrypting transfers, and not in secure identification.
28448
28449 However, many clients require that the certificate presented by the server be a
28450 user (also called &"leaf"& or &"site"&) certificate, and not a self-signed
28451 certificate. In this situation, the self-signed certificate described above
28452 must be installed on the client host as a trusted root &'certification
28453 authority'& (CA), and the certificate used by Exim must be a user certificate
28454 signed with that self-signed certificate.
28455
28456 For information on creating self-signed CA certificates and using them to sign
28457 user certificates, see the &'General implementation overview'& chapter of the
28458 Open-source PKI book, available online at
28459 &url(https://sourceforge.net/projects/ospkibook/).
28460 .ecindex IIDencsmtp1
28461 .ecindex IIDencsmtp2
28462
28463
28464
28465 .section DANE "SECDANE"
28466 .cindex DANE
28467 DNS-based Authentication of Named Entities, as applied to SMTP over TLS, provides assurance to a client that
28468 it is actually talking to the server it wants to rather than some attacker operating a Man In The Middle (MITM)
28469 operation.  The latter can terminate the TLS connection you make, and make another one to the server (so both
28470 you and the server still think you have an encrypted connection) and, if one of the "well known" set of
28471 Certificate Authorities has been suborned - something which *has* been seen already (2014), a verifiable
28472 certificate (if you're using normal root CAs, eg. the Mozilla set, as your trust anchors).
28473
28474 What DANE does is replace the CAs with the DNS as the trust anchor.  The assurance is limited to a) the possibility
28475 that the DNS has been suborned, b) mistakes made by the admins of the target server.   The attack surface presented
28476 by (a) is thought to be smaller than that of the set of root CAs.
28477
28478 It also allows the server to declare (implicitly) that connections to it should use TLS.  An MITM could simply
28479 fail to pass on a server's STARTTLS.
28480
28481 DANE scales better than having to maintain (and side-channel communicate) copies of server certificates
28482 for every possible target server.  It also scales (slightly) better than having to maintain on an SMTP
28483 client a copy of the standard CAs bundle.  It also means not having to pay a CA for certificates.
28484
28485 DANE requires a server operator to do three things: 1) run DNSSEC.  This provides assurance to clients
28486 that DNS lookups they do for the server have not been tampered with.  The domain MX record applying
28487 to this server, its A record, its TLSA record and any associated CNAME records must all be covered by
28488 DNSSEC.
28489 2) add TLSA DNS records.  These say what the server certificate for a TLS connection should be.
28490 3) offer a server certificate, or certificate chain, in TLS connections which is is anchored by one of the TLSA records.
28491
28492 There are no changes to Exim specific to server-side operation of DANE.
28493 Support for client-side operation of DANE can be included at compile time by defining SUPPORT_DANE=yes
28494 in &_Local/Makefile_&.
28495 If it has been included, the macro "_HAVE_DANE" will be defined.
28496
28497 The TLSA record for the server may have "certificate usage" of DANE-TA(2) or DANE-EE(3).
28498 These are the "Trust Anchor" and "End Entity" variants.
28499 The latter specifies the End Entity directly, i.e. the certificate involved is that of the server
28500 (and if only DANE-EE is used then it should be the sole one transmitted during the TLS handshake);
28501 this is appropriate for a single system, using a self-signed certificate.
28502 DANE-TA usage is effectively declaring a specific CA to be used; this might be a private CA or a public,
28503 well-known one.
28504 A private CA at simplest is just a self-signed certificate (with certain
28505 attributes) which is used to sign server certificates, but running one securely
28506 does require careful arrangement.
28507 With DANE-TA, as implemented in Exim and commonly in other MTAs,
28508 the server TLS handshake must transmit the entire certificate chain from CA to server-certificate.
28509 DANE-TA is commonly used for several services and/or servers, each having a TLSA query-domain CNAME record,
28510 all of which point to a single TLSA record.
28511 DANE-TA and DANE-EE can both be used together.
28512
28513 .new
28514 Our recommendation is to use DANE with a certificate from a public CA,
28515 because this enables a variety of strategies for remote clients to verify
28516 your certificate.
28517 You can then publish information both via DANE and another technology,
28518 "MTA-STS", described below.
28519
28520 When you use DANE-TA to publish trust anchor information, you ask entities
28521 outside your administrative control to trust the Certificate Authority for
28522 connections to you.
28523 If using a private CA then you should expect others to still apply the
28524 technical criteria they'd use for a public CA to your certificates.
28525 In particular, you should probably try to follow current best practices for CA
28526 operation around hash algorithms and key sizes.
28527 Do not expect other organizations to lower their security expectations just
28528 because a particular profile might be reasonable for your own internal use.
28529
28530 When this text was last updated, this in practice means to avoid use of SHA-1
28531 and MD5; if using RSA to use key sizes of at least 2048 bits (and no larger
28532 than 4096, for interoperability); to use keyUsage fields correctly; to use
28533 random serial numbers.
28534 The list of requirements is subject to change as best practices evolve.
28535 If you're not already using a private CA, or it doesn't meet these
28536 requirements, then we encourage you to avoid all these issues and use a public
28537 CA such as &url(https://letsencrypt.org/,Let's Encrypt) instead.
28538 .wen
28539
28540 The TLSA record should have a Selector field of SPKI(1) and a Matching Type field of SHA2-512(2).
28541
28542 At the time of writing, &url(https://www.huque.com/bin/gen_tlsa)
28543 is useful for quickly generating TLSA records; and commands like
28544
28545 .code
28546   openssl x509 -in -pubkey -noout <certificate.pem \
28547   | openssl rsa -outform der -pubin 2>/dev/null \
28548   | openssl sha512 \
28549   | awk '{print $2}'
28550 .endd
28551
28552 are workable for 4th-field hashes.
28553
28554 For use with the DANE-TA model, server certificates must have a correct name (SubjectName or SubjectAltName).
28555
28556 .new
28557 The Certificate issued by the CA published in the DANE-TA model should be
28558 issued using a strong hash algorithm.
28559 Exim, and importantly various other MTAs sending to you, will not
28560 re-enable hash algorithms which have been disabled by default in TLS
28561 libraries.
28562 This means no MD5 and no SHA-1.  SHA2-256 is the minimum for reliable
28563 interoperability (and probably the maximum too, in 2018).
28564 .wen
28565
28566 The use of OCSP-stapling should be considered, allowing for fast revocation of certificates (which would otherwise
28567 be limited by the DNS TTL on the TLSA records).  However, this is likely to only be usable with DANE-TA.  NOTE: the
28568 default of requesting OCSP for all hosts is modified iff DANE is in use, to:
28569
28570 .code
28571   hosts_request_ocsp = ${if or { {= {0}{$tls_out_tlsa_usage}} \
28572                                  {= {4}{$tls_out_tlsa_usage}} } \
28573                          {*}{}}
28574 .endd
28575
28576 The (new) variable &$tls_out_tlsa_usage$& is a bitfield with numbered bits set for TLSA record usage codes.
28577 The zero above means DANE was not in use, the four means that only DANE-TA usage TLSA records were
28578 found. If the definition of &%hosts_request_ocsp%& includes the
28579 string "tls_out_tlsa_usage", they are re-expanded in time to
28580 control the OCSP request.
28581
28582 This modification of hosts_request_ocsp is only done if it has the default value of "*".  Admins who change it, and
28583 those who use &%hosts_require_ocsp%&, should consider the interaction with DANE in their OCSP settings.
28584
28585
28586 For client-side DANE there are three new smtp transport options, &%hosts_try_dane%&, &%hosts_require_dane%&
28587 and &%dane_require_tls_ciphers%&.
28588 The require variant will result in failure if the target host is not DNSSEC-secured.
28589
28590 DANE will only be usable if the target host has DNSSEC-secured MX, A and TLSA records.
28591
28592 A TLSA lookup will be done if either of the above options match and the host-lookup succeeded using dnssec.
28593 If a TLSA lookup is done and succeeds, a DANE-verified TLS connection
28594 will be required for the host.  If it does not, the host will not
28595 be used; there is no fallback to non-DANE or non-TLS.
28596
28597 If DANE is requested and usable, then the TLS cipher list configuration
28598 prefers to use the option &%dane_require_tls_ciphers%& and falls
28599 back to &%tls_require_ciphers%& only if that is unset.
28600 This lets you configure "decent crypto" for DANE and "better than nothing
28601 crypto" as the default.  Note though that while GnuTLS lets the string control
28602 which versions of TLS/SSL will be negotiated, OpenSSL does not and you're
28603 limited to ciphersuite constraints.
28604
28605 If DANE is requested and useable (see above) the following transport options are ignored:
28606 .code
28607   hosts_require_tls
28608   tls_verify_hosts
28609   tls_try_verify_hosts
28610   tls_verify_certificates
28611   tls_crl
28612   tls_verify_cert_hostnames
28613 .endd
28614
28615 If DANE is not usable, whether requested or not, and CA-anchored
28616 verification evaluation is wanted, the above variables should be set appropriately.
28617
28618 Currently the &%dnssec_request_domains%& must be active and &%dnssec_require_domains%& is ignored.
28619
28620 If verification was successful using DANE then the "CV" item in the delivery log line will show as "CV=dane".
28621
28622 There is a new variable &$tls_out_dane$& which will have "yes" if
28623 verification succeeded using DANE and "no" otherwise (only useful
28624 in combination with events; see &<<CHAPevents>>&),
28625 and a new variable &$tls_out_tlsa_usage$& (detailed above).
28626
28627 .cindex DANE reporting
28628 An event (see &<<CHAPevents>>&) of type "dane:fail" will be raised on failures
28629 to achieve DANE-verified connection, if one was either requested and offered, or
28630 required.  This is intended to support TLS-reporting as defined in
28631 &url(https://tools.ietf.org/html/draft-ietf-uta-smtp-tlsrpt-17).
28632 The &$event_data$& will be one of the Result Types defined in
28633 Section 4.3 of that document.
28634
28635 Under GnuTLS, DANE is only supported from version 3.0.0 onwards.
28636
28637 DANE is specified in published RFCs and decouples certificate authority trust
28638 selection from a "race to the bottom" of "you must trust everything for mail
28639 to get through".  There is an alternative technology called MTA-STS, which
28640 instead publishes MX trust anchor information on an HTTPS website.  At the
28641 time this text was last updated, MTA-STS was still a draft, not yet an RFC.
28642 Exim has no support for MTA-STS as a client, but Exim mail server operators
28643 can choose to publish information describing their TLS configuration using
28644 MTA-STS to let those clients who do use that protocol derive trust
28645 information.
28646
28647 The MTA-STS design requires a certificate from a public Certificate Authority
28648 which is recognized by clients sending to you.
28649 That selection of which CAs are trusted by others is outside your control.
28650
28651 The most interoperable course of action is probably to use
28652 &url(https://letsencrypt.org/,Let's Encrypt), with automated certificate
28653 renewal; to publish the anchor information in DNSSEC-secured DNS via TLSA
28654 records for DANE clients (such as Exim and Postfix) and to publish anchor
28655 information for MTA-STS as well.  This is what is done for the &'exim.org'&
28656 domain itself (with caveats around occasionally broken MTA-STS because of
28657 incompatible specification changes prior to reaching RFC status).
28658
28659
28660
28661 . ////////////////////////////////////////////////////////////////////////////
28662 . ////////////////////////////////////////////////////////////////////////////
28663
28664 .chapter "Access control lists" "CHAPACL"
28665 .scindex IIDacl "&ACL;" "description"
28666 .cindex "control of incoming mail"
28667 .cindex "message" "controlling incoming"
28668 .cindex "policy control" "access control lists"
28669 Access Control Lists (ACLs) are defined in a separate section of the run time
28670 configuration file, headed by &"begin acl"&. Each ACL definition starts with a
28671 name, terminated by a colon. Here is a complete ACL section that contains just
28672 one very small ACL:
28673 .code
28674 begin acl
28675 small_acl:
28676   accept   hosts = one.host.only
28677 .endd
28678 You can have as many lists as you like in the ACL section, and the order in
28679 which they appear does not matter. The lists are self-terminating.
28680
28681 The majority of ACLs are used to control Exim's behaviour when it receives
28682 certain SMTP commands. This applies both to incoming TCP/IP connections, and
28683 when a local process submits a message using SMTP by specifying the &%-bs%&
28684 option. The most common use is for controlling which recipients are accepted
28685 in incoming messages. In addition, you can define an ACL that is used to check
28686 local non-SMTP messages. The default configuration file contains an example of
28687 a realistic ACL for checking RCPT commands. This is discussed in chapter
28688 &<<CHAPdefconfil>>&.
28689
28690
28691 .section "Testing ACLs" "SECID188"
28692 The &%-bh%& command line option provides a way of testing your ACL
28693 configuration locally by running a fake SMTP session with which you interact.
28694
28695
28696 .section "Specifying when ACLs are used" "SECID189"
28697 .cindex "&ACL;" "options for specifying"
28698 In order to cause an ACL to be used, you have to name it in one of the relevant
28699 options in the main part of the configuration. These options are:
28700 .cindex "AUTH" "ACL for"
28701 .cindex "DATA" "ACLs for"
28702 .cindex "ETRN" "ACL for"
28703 .cindex "EXPN" "ACL for"
28704 .cindex "HELO" "ACL for"
28705 .cindex "EHLO" "ACL for"
28706 .cindex "DKIM" "ACL for"
28707 .cindex "MAIL" "ACL for"
28708 .cindex "QUIT, ACL for"
28709 .cindex "RCPT" "ACL for"
28710 .cindex "STARTTLS, ACL for"
28711 .cindex "VRFY" "ACL for"
28712 .cindex "SMTP" "connection, ACL for"
28713 .cindex "non-SMTP messages" "ACLs for"
28714 .cindex "MIME content scanning" "ACL for"
28715 .cindex "PRDR" "ACL for"
28716
28717 .table2 140pt
28718 .irow &%acl_not_smtp%&         "ACL for non-SMTP messages"
28719 .irow &%acl_not_smtp_mime%&    "ACL for non-SMTP MIME parts"
28720 .irow &%acl_not_smtp_start%&   "ACL at start of non-SMTP message"
28721 .irow &%acl_smtp_auth%&        "ACL for AUTH"
28722 .irow &%acl_smtp_connect%&     "ACL for start of SMTP connection"
28723 .irow &%acl_smtp_data%&        "ACL after DATA is complete"
28724 .irow &%acl_smtp_data_prdr%&   "ACL for each recipient, after DATA is complete"
28725 .irow &%acl_smtp_dkim%&        "ACL for each DKIM signer"
28726 .irow &%acl_smtp_etrn%&        "ACL for ETRN"
28727 .irow &%acl_smtp_expn%&        "ACL for EXPN"
28728 .irow &%acl_smtp_helo%&        "ACL for HELO or EHLO"
28729 .irow &%acl_smtp_mail%&        "ACL for MAIL"
28730 .irow &%acl_smtp_mailauth%&    "ACL for the AUTH parameter of MAIL"
28731 .irow &%acl_smtp_mime%&        "ACL for content-scanning MIME parts"
28732 .irow &%acl_smtp_notquit%&     "ACL for non-QUIT terminations"
28733 .irow &%acl_smtp_predata%&     "ACL at start of DATA command"
28734 .irow &%acl_smtp_quit%&        "ACL for QUIT"
28735 .irow &%acl_smtp_rcpt%&        "ACL for RCPT"
28736 .irow &%acl_smtp_starttls%&    "ACL for STARTTLS"
28737 .irow &%acl_smtp_vrfy%&        "ACL for VRFY"
28738 .endtable
28739
28740 For example, if you set
28741 .code
28742 acl_smtp_rcpt = small_acl
28743 .endd
28744 the little ACL defined above is used whenever Exim receives a RCPT command
28745 in an SMTP dialogue. The majority of policy tests on incoming messages can be
28746 done when RCPT commands arrive. A rejection of RCPT should cause the
28747 sending MTA to give up on the recipient address contained in the RCPT
28748 command, whereas rejection at other times may cause the client MTA to keep on
28749 trying to deliver the message. It is therefore recommended that you do as much
28750 testing as possible at RCPT time.
28751
28752
28753 .section "The non-SMTP ACLs" "SECID190"
28754 .cindex "non-SMTP messages" "ACLs for"
28755 The non-SMTP ACLs apply to all non-interactive incoming messages, that is, they
28756 apply to batched SMTP as well as to non-SMTP messages. (Batched SMTP is not
28757 really SMTP.) Many of the ACL conditions (for example, host tests, and tests on
28758 the state of the SMTP connection such as encryption and authentication) are not
28759 relevant and are forbidden in these ACLs. However, the sender and recipients
28760 are known, so the &%senders%& and &%sender_domains%& conditions and the
28761 &$sender_address$& and &$recipients$& variables can be used. Variables such as
28762 &$authenticated_sender$& are also available. You can specify added header lines
28763 in any of these ACLs.
28764
28765 The &%acl_not_smtp_start%& ACL is run right at the start of receiving a
28766 non-SMTP message, before any of the message has been read. (This is the
28767 analogue of the &%acl_smtp_predata%& ACL for SMTP input.) In the case of
28768 batched SMTP input, it runs after the DATA command has been reached. The
28769 result of this ACL is ignored; it cannot be used to reject a message. If you
28770 really need to, you could set a value in an ACL variable here and reject based
28771 on that in the &%acl_not_smtp%& ACL. However, this ACL can be used to set
28772 controls, and in particular, it can be used to set
28773 .code
28774 control = suppress_local_fixups
28775 .endd
28776 This cannot be used in the other non-SMTP ACLs because by the time they are
28777 run, it is too late.
28778
28779 The &%acl_not_smtp_mime%& ACL is available only when Exim is compiled with the
28780 content-scanning extension. For details, see chapter &<<CHAPexiscan>>&.
28781
28782 The &%acl_not_smtp%& ACL is run just before the &[local_scan()]& function. Any
28783 kind of rejection is treated as permanent, because there is no way of sending a
28784 temporary error for these kinds of message.
28785
28786
28787 .section "The SMTP connect ACL" "SECID191"
28788 .cindex "SMTP" "connection, ACL for"
28789 .oindex &%smtp_banner%&
28790 The ACL test specified by &%acl_smtp_connect%& happens at the start of an SMTP
28791 session, after the test specified by &%host_reject_connection%& (which is now
28792 an anomaly) and any TCP Wrappers testing (if configured). If the connection is
28793 accepted by an &%accept%& verb that has a &%message%& modifier, the contents of
28794 the message override the banner message that is otherwise specified by the
28795 &%smtp_banner%& option.
28796
28797
28798 .section "The EHLO/HELO ACL" "SECID192"
28799 .cindex "EHLO" "ACL for"
28800 .cindex "HELO" "ACL for"
28801 The ACL test specified by &%acl_smtp_helo%& happens when the client issues an
28802 EHLO or HELO command, after the tests specified by &%helo_accept_junk_hosts%&,
28803 &%helo_allow_chars%&, &%helo_verify_hosts%&, and &%helo_try_verify_hosts%&.
28804 Note that a client may issue more than one EHLO or HELO command in an SMTP
28805 session, and indeed is required to issue a new EHLO or HELO after successfully
28806 setting up encryption following a STARTTLS command.
28807
28808 Note also that a deny neither forces the client to go away nor means that
28809 mail will be refused on the connection.  Consider checking for
28810 &$sender_helo_name$& being defined in a MAIL or RCPT ACL to do that.
28811
28812 If the command is accepted by an &%accept%& verb that has a &%message%&
28813 modifier, the message may not contain more than one line (it will be truncated
28814 at the first newline and a panic logged if it does). Such a message cannot
28815 affect the EHLO options that are listed on the second and subsequent lines of
28816 an EHLO response.
28817
28818
28819 .section "The DATA ACLs" "SECID193"
28820 .cindex "DATA" "ACLs for"
28821 Two ACLs are associated with the DATA command, because it is two-stage
28822 command, with two responses being sent to the client.
28823 When the DATA command is received, the ACL defined by &%acl_smtp_predata%&
28824 is obeyed. This gives you control after all the RCPT commands, but before
28825 the message itself is received. It offers the opportunity to give a negative
28826 response to the DATA command before the data is transmitted. Header lines
28827 added by MAIL or RCPT ACLs are not visible at this time, but any that
28828 are defined here are visible when the &%acl_smtp_data%& ACL is run.
28829
28830 You cannot test the contents of the message, for example, to verify addresses
28831 in the headers, at RCPT time or when the DATA command is received. Such
28832 tests have to appear in the ACL that is run after the message itself has been
28833 received, before the final response to the DATA command is sent. This is
28834 the ACL specified by &%acl_smtp_data%&, which is the second ACL that is
28835 associated with the DATA command.
28836
28837 .cindex CHUNKING "BDAT command"
28838 .cindex BDAT "SMTP command"
28839 .cindex "RFC 3030" CHUNKING
28840 If CHUNKING was advertised and a BDAT command sequence is received,
28841 the &%acl_smtp_predata%& ACL is not run.
28842 . XXX why not?  It should be possible, for the first BDAT.
28843 The &%acl_smtp_data%& is run after the last BDAT command and all of
28844 the data specified is received.
28845
28846 For both of these ACLs, it is not possible to reject individual recipients. An
28847 error response rejects the entire message. Unfortunately, it is known that some
28848 MTAs do not treat hard (5&'xx'&) responses to the DATA command (either
28849 before or after the data) correctly &-- they keep the message on their queues
28850 and try again later, but that is their problem, though it does waste some of
28851 your resources.
28852
28853 The &%acl_smtp_data%& ACL is run after
28854 the &%acl_smtp_data_prdr%&,
28855 the &%acl_smtp_dkim%&
28856 and the &%acl_smtp_mime%& ACLs.
28857
28858 .section "The SMTP DKIM ACL" "SECTDKIMACL"
28859 The &%acl_smtp_dkim%& ACL is available only when Exim is compiled with DKIM support
28860 enabled (which is the default).
28861
28862 The ACL test specified by &%acl_smtp_dkim%& happens after a message has been
28863 received, and is executed for each DKIM signature found in a message.  If not
28864 otherwise specified, the default action is to accept.
28865
28866 This ACL is evaluated before &%acl_smtp_mime%& and &%acl_smtp_data%&.
28867
28868 For details on the operation of DKIM, see section &<<SECDKIM>>&.
28869
28870
28871 .section "The SMTP MIME ACL" "SECID194"
28872 The &%acl_smtp_mime%& option is available only when Exim is compiled with the
28873 content-scanning extension. For details, see chapter &<<CHAPexiscan>>&.
28874
28875 This ACL is evaluated after &%acl_smtp_dkim%& but before &%acl_smtp_data%&.
28876
28877
28878 .section "The SMTP PRDR ACL" "SECTPRDRACL"
28879 .cindex "PRDR" "ACL for"
28880 .oindex "&%prdr_enable%&"
28881 The &%acl_smtp_data_prdr%& ACL is available only when Exim is compiled
28882 with PRDR support enabled (which is the default).
28883 It becomes active only when the PRDR feature is negotiated between
28884 client and server for a message, and more than one recipient
28885 has been accepted.
28886
28887 The ACL test specified by &%acl_smtp_data_prdr%& happens after a message
28888 has been received, and is executed once for each recipient of the message
28889 with &$local_part$& and &$domain$& valid.
28890 The test may accept, defer or deny for individual recipients.
28891 The &%acl_smtp_data%& will still be called after this ACL and
28892 can reject the message overall, even if this ACL has accepted it
28893 for some or all recipients.
28894
28895 PRDR may be used to support per-user content filtering.  Without it
28896 one must defer any recipient after the first that has a different
28897 content-filter configuration.  With PRDR, the RCPT-time check
28898 .cindex "PRDR" "variable for"
28899 for this can be disabled when the variable &$prdr_requested$&
28900 is &"yes"&.
28901 Any required difference in behaviour of the main DATA-time
28902 ACL should however depend on the PRDR-time ACL having run, as Exim
28903 will avoid doing so in some situations (e.g.  single-recipient mails).
28904
28905 See also the &%prdr_enable%& global option
28906 and the &%hosts_try_prdr%& smtp transport option.
28907
28908 This ACL is evaluated after &%acl_smtp_dkim%& but before &%acl_smtp_data%&.
28909 If the ACL is not defined, processing completes as if
28910 the feature was not requested by the client.
28911
28912 .section "The QUIT ACL" "SECTQUITACL"
28913 .cindex "QUIT, ACL for"
28914 The ACL for the SMTP QUIT command is anomalous, in that the outcome of the ACL
28915 does not affect the response code to QUIT, which is always 221. Thus, the ACL
28916 does not in fact control any access.
28917 For this reason, it may only accept
28918 or warn as its final result.
28919
28920 This ACL can be used for tasks such as custom logging at the end of an SMTP
28921 session. For example, you can use ACL variables in other ACLs to count
28922 messages, recipients, etc., and log the totals at QUIT time using one or
28923 more &%logwrite%& modifiers on a &%warn%& verb.
28924
28925 &*Warning*&: Only the &$acl_c$&&'x'& variables can be used for this, because
28926 the &$acl_m$&&'x'& variables are reset at the end of each incoming message.
28927
28928 You do not need to have a final &%accept%&, but if you do, you can use a
28929 &%message%& modifier to specify custom text that is sent as part of the 221
28930 response to QUIT.
28931
28932 This ACL is run only for a &"normal"& QUIT. For certain kinds of disastrous
28933 failure (for example, failure to open a log file, or when Exim is bombing out
28934 because it has detected an unrecoverable error), all SMTP commands from the
28935 client are given temporary error responses until QUIT is received or the
28936 connection is closed. In these special cases, the QUIT ACL does not run.
28937
28938
28939 .section "The not-QUIT ACL" "SECTNOTQUITACL"
28940 .vindex &$acl_smtp_notquit$&
28941 The not-QUIT ACL, specified by &%acl_smtp_notquit%&, is run in most cases when
28942 an SMTP session ends without sending QUIT. However, when Exim itself is in bad
28943 trouble, such as being unable to write to its log files, this ACL is not run,
28944 because it might try to do things (such as write to log files) that make the
28945 situation even worse.
28946
28947 Like the QUIT ACL, this ACL is provided to make it possible to do customized
28948 logging or to gather statistics, and its outcome is ignored. The &%delay%&
28949 modifier is forbidden in this ACL, and the only permitted verbs are &%accept%&
28950 and &%warn%&.
28951
28952 .vindex &$smtp_notquit_reason$&
28953 When the not-QUIT ACL is running, the variable &$smtp_notquit_reason$& is set
28954 to a string that indicates the reason for the termination of the SMTP
28955 connection. The possible values are:
28956 .table2
28957 .irow &`acl-drop`&                 "Another ACL issued a &%drop%& command"
28958 .irow &`bad-commands`&             "Too many unknown or non-mail commands"
28959 .irow &`command-timeout`&          "Timeout while reading SMTP commands"
28960 .irow &`connection-lost`&          "The SMTP connection has been lost"
28961 .irow &`data-timeout`&             "Timeout while reading message data"
28962 .irow &`local-scan-error`&         "The &[local_scan()]& function crashed"
28963 .irow &`local-scan-timeout`&       "The &[local_scan()]& function timed out"
28964 .irow &`signal-exit`&              "SIGTERM or SIGINT"
28965 .irow &`synchronization-error`&    "SMTP synchronization error"
28966 .irow &`tls-failed`&               "TLS failed to start"
28967 .endtable
28968 In most cases when an SMTP connection is closed without having received QUIT,
28969 Exim sends an SMTP response message before actually closing the connection.
28970 With the exception of the &`acl-drop`& case, the default message can be
28971 overridden by the &%message%& modifier in the not-QUIT ACL. In the case of a
28972 &%drop%& verb in another ACL, it is the message from the other ACL that is
28973 used.
28974
28975
28976 .section "Finding an ACL to use" "SECID195"
28977 .cindex "&ACL;" "finding which to use"
28978 The value of an &%acl_smtp_%&&'xxx'& option is expanded before use, so
28979 you can use different ACLs in different circumstances. For example,
28980 .code
28981 acl_smtp_rcpt = ${if ={25}{$interface_port} \
28982                      {acl_check_rcpt} {acl_check_rcpt_submit} }
28983 .endd
28984 In the default configuration file there are some example settings for
28985 providing an RFC 4409 message &"submission"& service on port 587 and
28986 an RFC 8314 &"submissions"& service on port 465. You can use a string
28987 expansion like this to choose an ACL for MUAs on these ports which is
28988 more appropriate for this purpose than the default ACL on port 25.
28989
28990 The expanded string does not have to be the name of an ACL in the
28991 configuration file; there are other possibilities. Having expanded the
28992 string, Exim searches for an ACL as follows:
28993
28994 .ilist
28995 If the string begins with a slash, Exim uses it as a file name, and reads its
28996 contents as an ACL. The lines are processed in the same way as lines in the
28997 Exim configuration file. In particular, continuation lines are supported, blank
28998 lines are ignored, as are lines whose first non-whitespace character is &"#"&.
28999 If the file does not exist or cannot be read, an error occurs (typically
29000 causing a temporary failure of whatever caused the ACL to be run). For example:
29001 .code
29002 acl_smtp_data = /etc/acls/\
29003   ${lookup{$sender_host_address}lsearch\
29004   {/etc/acllist}{$value}{default}}
29005 .endd
29006 This looks up an ACL file to use on the basis of the host's IP address, falling
29007 back to a default if the lookup fails. If an ACL is successfully read from a
29008 file, it is retained in memory for the duration of the Exim process, so that it
29009 can be re-used without having to re-read the file.
29010 .next
29011 If the string does not start with a slash, and does not contain any spaces,
29012 Exim searches the ACL section of the configuration for an ACL whose name
29013 matches the string.
29014 .next
29015 If no named ACL is found, or if the string contains spaces, Exim parses
29016 the string as an inline ACL. This can save typing in cases where you just
29017 want to have something like
29018 .code
29019 acl_smtp_vrfy = accept
29020 .endd
29021 in order to allow free use of the VRFY command. Such a string may contain
29022 newlines; it is processed in the same way as an ACL that is read from a file.
29023 .endlist
29024
29025
29026
29027
29028 .section "ACL return codes" "SECID196"
29029 .cindex "&ACL;" "return codes"
29030 Except for the QUIT ACL, which does not affect the SMTP return code (see
29031 section &<<SECTQUITACL>>& above), the result of running an ACL is either
29032 &"accept"& or &"deny"&, or, if some test cannot be completed (for example, if a
29033 database is down), &"defer"&. These results cause 2&'xx'&, 5&'xx'&, and 4&'xx'&
29034 return codes, respectively, to be used in the SMTP dialogue. A fourth return,
29035 &"error"&, occurs when there is an error such as invalid syntax in the ACL.
29036 This also causes a 4&'xx'& return code.
29037
29038 For the non-SMTP ACL, &"defer"& and &"error"& are treated in the same way as
29039 &"deny"&, because there is no mechanism for passing temporary errors to the
29040 submitters of non-SMTP messages.
29041
29042
29043 ACLs that are relevant to message reception may also return &"discard"&. This
29044 has the effect of &"accept"&, but causes either the entire message or an
29045 individual recipient address to be discarded. In other words, it is a
29046 blackholing facility. Use it with care.
29047
29048 If the ACL for MAIL returns &"discard"&, all recipients are discarded, and no
29049 ACL is run for subsequent RCPT commands. The effect of &"discard"& in a
29050 RCPT ACL is to discard just the one recipient address. If there are no
29051 recipients left when the message's data is received, the DATA ACL is not
29052 run. A &"discard"& return from the DATA or the non-SMTP ACL discards all the
29053 remaining recipients. The &"discard"& return is not permitted for the
29054 &%acl_smtp_predata%& ACL.
29055
29056 If the ACL for VRFY returns &"accept"&, a recipient verify (without callout)
29057 is done on the address and the result determines the SMTP response.
29058
29059
29060 .cindex "&[local_scan()]& function" "when all recipients discarded"
29061 The &[local_scan()]& function is always run, even if there are no remaining
29062 recipients; it may create new recipients.
29063
29064
29065
29066 .section "Unset ACL options" "SECID197"
29067 .cindex "&ACL;" "unset options"
29068 The default actions when any of the &%acl_%&&'xxx'& options are unset are not
29069 all the same. &*Note*&: These defaults apply only when the relevant ACL is
29070 not defined at all. For any defined ACL, the default action when control
29071 reaches the end of the ACL statements is &"deny"&.
29072
29073 For &%acl_smtp_quit%& and &%acl_not_smtp_start%& there is no default because
29074 these two are ACLs that are used only for their side effects. They cannot be
29075 used to accept or reject anything.
29076
29077 For &%acl_not_smtp%&, &%acl_smtp_auth%&, &%acl_smtp_connect%&,
29078 &%acl_smtp_data%&, &%acl_smtp_helo%&, &%acl_smtp_mail%&, &%acl_smtp_mailauth%&,
29079 &%acl_smtp_mime%&, &%acl_smtp_predata%&, and &%acl_smtp_starttls%&, the action
29080 when the ACL is not defined is &"accept"&.
29081
29082 For the others (&%acl_smtp_etrn%&, &%acl_smtp_expn%&, &%acl_smtp_rcpt%&, and
29083 &%acl_smtp_vrfy%&), the action when the ACL is not defined is &"deny"&.
29084 This means that &%acl_smtp_rcpt%& must be defined in order to receive any
29085 messages over an SMTP connection. For an example, see the ACL in the default
29086 configuration file.
29087
29088
29089
29090
29091 .section "Data for message ACLs" "SECID198"
29092 .cindex "&ACL;" "data for message ACL"
29093 .vindex &$domain$&
29094 .vindex &$local_part$&
29095 .vindex &$sender_address$&
29096 .vindex &$sender_host_address$&
29097 .vindex &$smtp_command$&
29098 When a MAIL or RCPT ACL, or either of the DATA ACLs, is running, the variables
29099 that contain information about the host and the message's sender (for example,
29100 &$sender_host_address$& and &$sender_address$&) are set, and can be used in ACL
29101 statements. In the case of RCPT (but not MAIL or DATA), &$domain$& and
29102 &$local_part$& are set from the argument address. The entire SMTP command
29103 is available in &$smtp_command$&.
29104
29105 When an ACL for the AUTH parameter of MAIL is running, the variables that
29106 contain information about the host are set, but &$sender_address$& is not yet
29107 set. Section &<<SECTauthparamail>>& contains a discussion of this parameter and
29108 how it is used.
29109
29110 .vindex "&$message_size$&"
29111 The &$message_size$& variable is set to the value of the SIZE parameter on
29112 the MAIL command at MAIL, RCPT and pre-data time, or to -1 if
29113 that parameter is not given. The value is updated to the true message size by
29114 the time the final DATA ACL is run (after the message data has been
29115 received).
29116
29117 .vindex "&$rcpt_count$&"
29118 .vindex "&$recipients_count$&"
29119 The &$rcpt_count$& variable increases by one for each RCPT command received.
29120 The &$recipients_count$& variable increases by one each time a RCPT command is
29121 accepted, so while an ACL for RCPT is being processed, it contains the number
29122 of previously accepted recipients. At DATA time (for both the DATA ACLs),
29123 &$rcpt_count$& contains the total number of RCPT commands, and
29124 &$recipients_count$& contains the total number of accepted recipients.
29125
29126
29127
29128
29129
29130 .section "Data for non-message ACLs" "SECTdatfornon"
29131 .cindex "&ACL;" "data for non-message ACL"
29132 .vindex &$smtp_command_argument$&
29133 .vindex &$smtp_command$&
29134 When an ACL is being run for AUTH, EHLO, ETRN, EXPN, HELO, STARTTLS, or VRFY,
29135 the remainder of the SMTP command line is placed in &$smtp_command_argument$&,
29136 and the entire SMTP command is available in &$smtp_command$&.
29137 These variables can be tested using a &%condition%& condition. For example,
29138 here is an ACL for use with AUTH, which insists that either the session is
29139 encrypted, or the CRAM-MD5 authentication method is used. In other words, it
29140 does not permit authentication methods that use cleartext passwords on
29141 unencrypted connections.
29142 .code
29143 acl_check_auth:
29144   accept encrypted = *
29145   accept condition = ${if eq{${uc:$smtp_command_argument}}\
29146                      {CRAM-MD5}}
29147   deny   message   = TLS encryption or CRAM-MD5 required
29148 .endd
29149 (Another way of applying this restriction is to arrange for the authenticators
29150 that use cleartext passwords not to be advertised when the connection is not
29151 encrypted. You can use the generic &%server_advertise_condition%& authenticator
29152 option to do this.)
29153
29154
29155
29156 .section "Format of an ACL" "SECID199"
29157 .cindex "&ACL;" "format of"
29158 .cindex "&ACL;" "verbs, definition of"
29159 An individual ACL consists of a number of statements. Each statement starts
29160 with a verb, optionally followed by a number of conditions and &"modifiers"&.
29161 Modifiers can change the way the verb operates, define error and log messages,
29162 set variables, insert delays, and vary the processing of accepted messages.
29163
29164 If all the conditions are met, the verb is obeyed. The same condition may be
29165 used (with different arguments) more than once in the same statement. This
29166 provides a means of specifying an &"and"& conjunction between conditions. For
29167 example:
29168 .code
29169 deny  dnslists = list1.example
29170       dnslists = list2.example
29171 .endd
29172 If there are no conditions, the verb is always obeyed. Exim stops evaluating
29173 the conditions and modifiers when it reaches a condition that fails. What
29174 happens then depends on the verb (and in one case, on a special modifier). Not
29175 all the conditions make sense at every testing point. For example, you cannot
29176 test a sender address in the ACL that is run for a VRFY command.
29177
29178
29179 .section "ACL verbs" "SECID200"
29180 The ACL verbs are as follows:
29181
29182 .ilist
29183 .cindex "&%accept%& ACL verb"
29184 &%accept%&: If all the conditions are met, the ACL returns &"accept"&. If any
29185 of the conditions are not met, what happens depends on whether &%endpass%&
29186 appears among the conditions (for syntax see below). If the failing condition
29187 is before &%endpass%&, control is passed to the next ACL statement; if it is
29188 after &%endpass%&, the ACL returns &"deny"&. Consider this statement, used to
29189 check a RCPT command:
29190 .code
29191 accept domains = +local_domains
29192        endpass
29193        verify = recipient
29194 .endd
29195 If the recipient domain does not match the &%domains%& condition, control
29196 passes to the next statement. If it does match, the recipient is verified, and
29197 the command is accepted if verification succeeds. However, if verification
29198 fails, the ACL yields &"deny"&, because the failing condition is after
29199 &%endpass%&.
29200
29201 The &%endpass%& feature has turned out to be confusing to many people, so its
29202 use is not recommended nowadays. It is always possible to rewrite an ACL so
29203 that &%endpass%& is not needed, and it is no longer used in the default
29204 configuration.
29205
29206 .cindex "&%message%& ACL modifier" "with &%accept%&"
29207 If a &%message%& modifier appears on an &%accept%& statement, its action
29208 depends on whether or not &%endpass%& is present. In the absence of &%endpass%&
29209 (when an &%accept%& verb either accepts or passes control to the next
29210 statement), &%message%& can be used to vary the message that is sent when an
29211 SMTP command is accepted. For example, in a RCPT ACL you could have:
29212 .display
29213 &`accept  `&<&'some conditions'&>
29214 &`        message = OK, I will allow you through today`&
29215 .endd
29216 You can specify an SMTP response code, optionally followed by an &"extended
29217 response code"& at the start of the message, but the first digit must be the
29218 same as would be sent by default, which is 2 for an &%accept%& verb.
29219
29220 If &%endpass%& is present in an &%accept%& statement, &%message%& specifies
29221 an error message that is used when access is denied. This behaviour is retained
29222 for backward compatibility, but current &"best practice"& is to avoid the use
29223 of &%endpass%&.
29224
29225
29226 .next
29227 .cindex "&%defer%& ACL verb"
29228 &%defer%&: If all the conditions are true, the ACL returns &"defer"& which, in
29229 an SMTP session, causes a 4&'xx'& response to be given. For a non-SMTP ACL,
29230 &%defer%& is the same as &%deny%&, because there is no way of sending a
29231 temporary error. For a RCPT command, &%defer%& is much the same as using a
29232 &(redirect)& router and &`:defer:`& while verifying, but the &%defer%& verb can
29233 be used in any ACL, and even for a recipient it might be a simpler approach.
29234
29235
29236 .next
29237 .cindex "&%deny%& ACL verb"
29238 &%deny%&: If all the conditions are met, the ACL returns &"deny"&. If any of
29239 the conditions are not met, control is passed to the next ACL statement. For
29240 example,
29241 .code
29242 deny dnslists = blackholes.mail-abuse.org
29243 .endd
29244 rejects commands from hosts that are on a DNS black list.
29245
29246
29247 .next
29248 .cindex "&%discard%& ACL verb"
29249 &%discard%&: This verb behaves like &%accept%&, except that it returns
29250 &"discard"& from the ACL instead of &"accept"&. It is permitted only on ACLs
29251 that are concerned with receiving messages. When all the conditions are true,
29252 the sending entity receives a &"success"& response. However, &%discard%& causes
29253 recipients to be discarded. If it is used in an ACL for RCPT, just the one
29254 recipient is discarded; if used for MAIL, DATA or in the non-SMTP ACL, all the
29255 message's recipients are discarded. Recipients that are discarded before DATA
29256 do not appear in the log line when the &%received_recipients%& log selector is set.
29257
29258 If the &%log_message%& modifier is set when &%discard%& operates,
29259 its contents are added to the line that is automatically written to the log.
29260 The &%message%& modifier operates exactly as it does for &%accept%&.
29261
29262
29263 .next
29264 .cindex "&%drop%& ACL verb"
29265 &%drop%&: This verb behaves like &%deny%&, except that an SMTP connection is
29266 forcibly closed after the 5&'xx'& error message has been sent. For example:
29267 .code
29268 drop   message   = I don't take more than 20 RCPTs
29269        condition = ${if > {$rcpt_count}{20}}
29270 .endd
29271 There is no difference between &%deny%& and &%drop%& for the connect-time ACL.
29272 The connection is always dropped after sending a 550 response.
29273
29274 .next
29275 .cindex "&%require%& ACL verb"
29276 &%require%&: If all the conditions are met, control is passed to the next ACL
29277 statement. If any of the conditions are not met, the ACL returns &"deny"&. For
29278 example, when checking a RCPT command,
29279 .code
29280 require message = Sender did not verify
29281         verify  = sender
29282 .endd
29283 passes control to subsequent statements only if the message's sender can be
29284 verified. Otherwise, it rejects the command. Note the positioning of the
29285 &%message%& modifier, before the &%verify%& condition. The reason for this is
29286 discussed in section &<<SECTcondmodproc>>&.
29287
29288 .next
29289 .cindex "&%warn%& ACL verb"
29290 &%warn%&: If all the conditions are true, a line specified by the
29291 &%log_message%& modifier is written to Exim's main log. Control always passes
29292 to the next ACL statement. If any condition is false, the log line is not
29293 written. If an identical log line is requested several times in the same
29294 message, only one copy is actually written to the log. If you want to force
29295 duplicates to be written, use the &%logwrite%& modifier instead.
29296
29297 If &%log_message%& is not present, a &%warn%& verb just checks its conditions
29298 and obeys any &"immediate"& modifiers (such as &%control%&, &%set%&,
29299 &%logwrite%&, &%add_header%&, and &%remove_header%&) that appear before the
29300 first failing condition. There is more about adding header lines in section
29301 &<<SECTaddheadacl>>&.
29302
29303 If any condition on a &%warn%& statement cannot be completed (that is, there is
29304 some sort of defer), the log line specified by &%log_message%& is not written.
29305 This does not include the case of a forced failure from a lookup, which
29306 is considered to be a successful completion. After a defer, no further
29307 conditions or modifiers in the &%warn%& statement are processed. The incident
29308 is logged, and the ACL continues to be processed, from the next statement
29309 onwards.
29310
29311
29312 .vindex "&$acl_verify_message$&"
29313 When one of the &%warn%& conditions is an address verification that fails, the
29314 text of the verification failure message is in &$acl_verify_message$&. If you
29315 want this logged, you must set it up explicitly. For example:
29316 .code
29317 warn   !verify = sender
29318        log_message = sender verify failed: $acl_verify_message
29319 .endd
29320 .endlist
29321
29322 At the end of each ACL there is an implicit unconditional &%deny%&.
29323
29324 As you can see from the examples above, the conditions and modifiers are
29325 written one to a line, with the first one on the same line as the verb, and
29326 subsequent ones on following lines. If you have a very long condition, you can
29327 continue it onto several physical lines by the usual backslash continuation
29328 mechanism. It is conventional to align the conditions vertically.
29329
29330
29331
29332 .section "ACL variables" "SECTaclvariables"
29333 .cindex "&ACL;" "variables"
29334 There are some special variables that can be set during ACL processing. They
29335 can be used to pass information between different ACLs, different invocations
29336 of the same ACL in the same SMTP connection, and between ACLs and the routers,
29337 transports, and filters that are used to deliver a message. The names of these
29338 variables must begin with &$acl_c$& or &$acl_m$&, followed either by a digit or
29339 an underscore, but the remainder of the name can be any sequence of
29340 alphanumeric characters and underscores that you choose. There is no limit on
29341 the number of ACL variables. The two sets act as follows:
29342 .ilist
29343 The values of those variables whose names begin with &$acl_c$& persist
29344 throughout an SMTP connection. They are never reset. Thus, a value that is set
29345 while receiving one message is still available when receiving the next message
29346 on the same SMTP connection.
29347 .next
29348 The values of those variables whose names begin with &$acl_m$& persist only
29349 while a message is being received. They are reset afterwards. They are also
29350 reset by MAIL, RSET, EHLO, HELO, and after starting up a TLS session.
29351 .endlist
29352
29353 When a message is accepted, the current values of all the ACL variables are
29354 preserved with the message and are subsequently made available at delivery
29355 time. The ACL variables are set by a modifier called &%set%&. For example:
29356 .code
29357 accept hosts = whatever
29358        set acl_m4 = some value
29359 accept authenticated = *
29360        set acl_c_auth = yes
29361 .endd
29362 &*Note*&: A leading dollar sign is not used when naming a variable that is to
29363 be set. If you want to set a variable without taking any action, you can use a
29364 &%warn%& verb without any other modifiers or conditions.
29365
29366 .oindex &%strict_acl_vars%&
29367 What happens if a syntactically valid but undefined ACL variable is
29368 referenced depends on the setting of the &%strict_acl_vars%& option. If it is
29369 false (the default), an empty string is substituted; if it is true, an
29370 error is generated.
29371
29372 Versions of Exim before 4.64 have a limited set of numbered variables, but
29373 their names are compatible, so there is no problem with upgrading.
29374
29375
29376 .section "Condition and modifier processing" "SECTcondmodproc"
29377 .cindex "&ACL;" "conditions; processing"
29378 .cindex "&ACL;" "modifiers; processing"
29379 An exclamation mark preceding a condition negates its result. For example:
29380 .code
29381 deny   domains = *.dom.example
29382       !verify  = recipient
29383 .endd
29384 causes the ACL to return &"deny"& if the recipient domain ends in
29385 &'dom.example'& and the recipient address cannot be verified. Sometimes
29386 negation can be used on the right-hand side of a condition. For example, these
29387 two statements are equivalent:
29388 .code
29389 deny  hosts = !192.168.3.4
29390 deny !hosts =  192.168.3.4
29391 .endd
29392 However, for many conditions (&%verify%& being a good example), only left-hand
29393 side negation of the whole condition is possible.
29394
29395 The arguments of conditions and modifiers are expanded. A forced failure
29396 of an expansion causes a condition to be ignored, that is, it behaves as if the
29397 condition is true. Consider these two statements:
29398 .code
29399 accept  senders = ${lookup{$host_name}lsearch\
29400                   {/some/file}{$value}fail}
29401 accept  senders = ${lookup{$host_name}lsearch\
29402                   {/some/file}{$value}{}}
29403 .endd
29404 Each attempts to look up a list of acceptable senders. If the lookup succeeds,
29405 the returned list is searched, but if the lookup fails the behaviour is
29406 different in the two cases. The &%fail%& in the first statement causes the
29407 condition to be ignored, leaving no further conditions. The &%accept%& verb
29408 therefore succeeds. The second statement, however, generates an empty list when
29409 the lookup fails. No sender can match an empty list, so the condition fails,
29410 and therefore the &%accept%& also fails.
29411
29412 ACL modifiers appear mixed in with conditions in ACL statements. Some of them
29413 specify actions that are taken as the conditions for a statement are checked;
29414 others specify text for messages that are used when access is denied or a
29415 warning is generated. The &%control%& modifier affects the way an incoming
29416 message is handled.
29417
29418 The positioning of the modifiers in an ACL statement is important, because the
29419 processing of a verb ceases as soon as its outcome is known. Only those
29420 modifiers that have already been encountered will take effect. For example,
29421 consider this use of the &%message%& modifier:
29422 .code
29423 require message = Can't verify sender
29424         verify  = sender
29425         message = Can't verify recipient
29426         verify  = recipient
29427         message = This message cannot be used
29428 .endd
29429 If sender verification fails, Exim knows that the result of the statement is
29430 &"deny"&, so it goes no further. The first &%message%& modifier has been seen,
29431 so its text is used as the error message. If sender verification succeeds, but
29432 recipient verification fails, the second message is used. If recipient
29433 verification succeeds, the third message becomes &"current"&, but is never used
29434 because there are no more conditions to cause failure.
29435
29436 For the &%deny%& verb, on the other hand, it is always the last &%message%&
29437 modifier that is used, because all the conditions must be true for rejection to
29438 happen. Specifying more than one &%message%& modifier does not make sense, and
29439 the message can even be specified after all the conditions. For example:
29440 .code
29441 deny   hosts = ...
29442       !senders = *@my.domain.example
29443        message = Invalid sender from client host
29444 .endd
29445 The &"deny"& result does not happen until the end of the statement is reached,
29446 by which time Exim has set up the message.
29447
29448
29449
29450 .section "ACL modifiers" "SECTACLmodi"
29451 .cindex "&ACL;" "modifiers; list of"
29452 The ACL modifiers are as follows:
29453
29454 .vlist
29455 .vitem &*add_header*&&~=&~<&'text'&>
29456 This modifier specifies one or more header lines that are to be added to an
29457 incoming message, assuming, of course, that the message is ultimately
29458 accepted. For details, see section &<<SECTaddheadacl>>&.
29459
29460 .vitem &*continue*&&~=&~<&'text'&>
29461 .cindex "&%continue%& ACL modifier"
29462 .cindex "database" "updating in ACL"
29463 This modifier does nothing of itself, and processing of the ACL always
29464 continues with the next condition or modifier. The value of &%continue%& is in
29465 the side effects of expanding its argument. Typically this could be used to
29466 update a database. It is really just a syntactic tidiness, to avoid having to
29467 write rather ugly lines like this:
29468 .display
29469 &`condition = ${if eq{0}{`&<&'some expansion'&>&`}{true}{true}}`&
29470 .endd
29471 Instead, all you need is
29472 .display
29473 &`continue = `&<&'some expansion'&>
29474 .endd
29475
29476 .vitem &*control*&&~=&~<&'text'&>
29477 .cindex "&%control%& ACL modifier"
29478 This modifier affects the subsequent processing of the SMTP connection or of an
29479 incoming message that is accepted. The effect of the first type of control
29480 lasts for the duration of the connection, whereas the effect of the second type
29481 lasts only until the current message has been received. The message-specific
29482 controls always apply to the whole message, not to individual recipients,
29483 even if the &%control%& modifier appears in a RCPT ACL.
29484
29485 As there are now quite a few controls that can be applied, they are described
29486 separately in section &<<SECTcontrols>>&. The &%control%& modifier can be used
29487 in several different ways. For example:
29488
29489 . ==== As this is a nested list, any displays it contains must be indented
29490 . ==== as otherwise they are too far to the left. That comment applies only
29491 . ==== when xmlto and fop are used; formatting with sdop gets it right either
29492 . ==== way.
29493
29494 .ilist
29495 It can be at the end of an &%accept%& statement:
29496 .code
29497     accept  ...some conditions
29498             control = queue_only
29499 .endd
29500 In this case, the control is applied when this statement yields &"accept"&, in
29501 other words, when the conditions are all true.
29502
29503 .next
29504 It can be in the middle of an &%accept%& statement:
29505 .code
29506     accept  ...some conditions...
29507             control = queue_only
29508             ...some more conditions...
29509 .endd
29510 If the first set of conditions are true, the control is applied, even if the
29511 statement does not accept because one of the second set of conditions is false.
29512 In this case, some subsequent statement must yield &"accept"& for the control
29513 to be relevant.
29514
29515 .next
29516 It can be used with &%warn%& to apply the control, leaving the
29517 decision about accepting or denying to a subsequent verb. For
29518 example:
29519 .code
29520     warn    ...some conditions...
29521             control = freeze
29522     accept  ...
29523 .endd
29524 This example of &%warn%& does not contain &%message%&, &%log_message%&, or
29525 &%logwrite%&, so it does not add anything to the message and does not write a
29526 log entry.
29527
29528 .next
29529 If you want to apply a control unconditionally, you can use it with a
29530 &%require%& verb. For example:
29531 .code
29532     require  control = no_multiline_responses
29533 .endd
29534 .endlist
29535
29536 .vitem &*delay*&&~=&~<&'time'&>
29537 .cindex "&%delay%& ACL modifier"
29538 .oindex "&%-bh%&"
29539 This modifier may appear in any ACL except notquit. It causes Exim to wait for
29540 the time interval before proceeding. However, when testing Exim using the
29541 &%-bh%& option, the delay is not actually imposed (an appropriate message is
29542 output instead). The time is given in the usual Exim notation, and the delay
29543 happens as soon as the modifier is processed. In an SMTP session, pending
29544 output is flushed before the delay is imposed.
29545
29546 Like &%control%&, &%delay%& can be used with &%accept%& or &%deny%&, for
29547 example:
29548 .code
29549 deny    ...some conditions...
29550         delay = 30s
29551 .endd
29552 The delay happens if all the conditions are true, before the statement returns
29553 &"deny"&. Compare this with:
29554 .code
29555 deny    delay = 30s
29556         ...some conditions...
29557 .endd
29558 which waits for 30s before processing the conditions. The &%delay%& modifier
29559 can also be used with &%warn%& and together with &%control%&:
29560 .code
29561 warn    ...some conditions...
29562         delay = 2m
29563         control = freeze
29564 accept  ...
29565 .endd
29566
29567 If &%delay%& is encountered when the SMTP PIPELINING extension is in use,
29568 responses to several commands are no longer buffered and sent in one packet (as
29569 they would normally be) because all output is flushed before imposing the
29570 delay. This optimization is disabled so that a number of small delays do not
29571 appear to the client as one large aggregated delay that might provoke an
29572 unwanted timeout. You can, however, disable output flushing for &%delay%& by
29573 using a &%control%& modifier to set &%no_delay_flush%&.
29574
29575
29576 .vitem &*endpass*&
29577 .cindex "&%endpass%& ACL modifier"
29578 This modifier, which has no argument, is recognized only in &%accept%& and
29579 &%discard%& statements. It marks the boundary between the conditions whose
29580 failure causes control to pass to the next statement, and the conditions whose
29581 failure causes the ACL to return &"deny"&. This concept has proved to be
29582 confusing to some people, so the use of &%endpass%& is no longer recommended as
29583 &"best practice"&. See the description of &%accept%& above for more details.
29584
29585
29586 .vitem &*log_message*&&~=&~<&'text'&>
29587 .cindex "&%log_message%& ACL modifier"
29588 This modifier sets up a message that is used as part of the log message if the
29589 ACL denies access or a &%warn%& statement's conditions are true. For example:
29590 .code
29591 require log_message = wrong cipher suite $tls_in_cipher
29592         encrypted   = DES-CBC3-SHA
29593 .endd
29594 &%log_message%& is also used when recipients are discarded by &%discard%&. For
29595 example:
29596 .display
29597 &`discard `&<&'some conditions'&>
29598 &`        log_message = Discarded $local_part@$domain because...`&
29599 .endd
29600 When access is denied, &%log_message%& adds to any underlying error message
29601 that may exist because of a condition failure. For example, while verifying a
29602 recipient address, a &':fail:'& redirection might have already set up a
29603 message.
29604
29605 The message may be defined before the conditions to which it applies, because
29606 the string expansion does not happen until Exim decides that access is to be
29607 denied. This means that any variables that are set by the condition are
29608 available for inclusion in the message. For example, the &$dnslist_$&<&'xxx'&>
29609 variables are set after a DNS black list lookup succeeds. If the expansion of
29610 &%log_message%& fails, or if the result is an empty string, the modifier is
29611 ignored.
29612
29613 .vindex "&$acl_verify_message$&"
29614 If you want to use a &%warn%& statement to log the result of an address
29615 verification, you can use &$acl_verify_message$& to include the verification
29616 error message.
29617
29618 If &%log_message%& is used with a &%warn%& statement, &"Warning:"& is added to
29619 the start of the logged message. If the same warning log message is requested
29620 more than once while receiving  a single email message, only one copy is
29621 actually logged. If you want to log multiple copies, use &%logwrite%& instead
29622 of &%log_message%&. In the absence of &%log_message%& and &%logwrite%&, nothing
29623 is logged for a successful &%warn%& statement.
29624
29625 If &%log_message%& is not present and there is no underlying error message (for
29626 example, from the failure of address verification), but &%message%& is present,
29627 the &%message%& text is used for logging rejections. However, if any text for
29628 logging contains newlines, only the first line is logged. In the absence of
29629 both &%log_message%& and &%message%&, a default built-in message is used for
29630 logging rejections.
29631
29632
29633 .vitem "&*log_reject_target*&&~=&~<&'log name list'&>"
29634 .cindex "&%log_reject_target%& ACL modifier"
29635 .cindex "logging in ACL" "specifying which log"
29636 This modifier makes it possible to specify which logs are used for messages
29637 about ACL rejections. Its argument is a colon-separated list of words that can
29638 be &"main"&, &"reject"&, or &"panic"&. The default is &`main:reject`&. The list
29639 may be empty, in which case a rejection is not logged at all. For example, this
29640 ACL fragment writes no logging information when access is denied:
29641 .display
29642 &`deny `&<&'some conditions'&>
29643 &`     log_reject_target =`&
29644 .endd
29645 This modifier can be used in SMTP and non-SMTP ACLs. It applies to both
29646 permanent and temporary rejections. Its effect lasts for the rest of the
29647 current ACL.
29648
29649
29650 .vitem &*logwrite*&&~=&~<&'text'&>
29651 .cindex "&%logwrite%& ACL modifier"
29652 .cindex "logging in ACL" "immediate"
29653 This modifier writes a message to a log file as soon as it is encountered when
29654 processing an ACL. (Compare &%log_message%&, which, except in the case of
29655 &%warn%& and &%discard%&, is used only if the ACL statement denies
29656 access.) The &%logwrite%& modifier can be used to log special incidents in
29657 ACLs. For example:
29658 .display
29659 &`accept `&<&'some special conditions'&>
29660 &`       control  = freeze`&
29661 &`       logwrite = froze message because ...`&
29662 .endd
29663 By default, the message is written to the main log. However, it may begin
29664 with a colon, followed by a comma-separated list of log names, and then
29665 another colon, to specify exactly which logs are to be written. For
29666 example:
29667 .code
29668 logwrite = :main,reject: text for main and reject logs
29669 logwrite = :panic: text for panic log only
29670 .endd
29671
29672
29673 .vitem &*message*&&~=&~<&'text'&>
29674 .cindex "&%message%& ACL modifier"
29675 This modifier sets up a text string that is expanded and used as a response
29676 message when an ACL statement terminates the ACL with an &"accept"&, &"deny"&,
29677 or &"defer"& response. (In the case of the &%accept%& and &%discard%& verbs,
29678 there is some complication if &%endpass%& is involved; see the description of
29679 &%accept%& for details.)
29680
29681 The expansion of the message happens at the time Exim decides that the ACL is
29682 to end, not at the time it processes &%message%&. If the expansion fails, or
29683 generates an empty string, the modifier is ignored. Here is an example where
29684 &%message%& must be specified first, because the ACL ends with a rejection if
29685 the &%hosts%& condition fails:
29686 .code
29687 require  message = Host not recognized
29688          hosts = 10.0.0.0/8
29689 .endd
29690 (Once a condition has failed, no further conditions or modifiers are
29691 processed.)
29692
29693 .cindex "SMTP" "error codes"
29694 .oindex "&%smtp_banner%&
29695 For ACLs that are triggered by SMTP commands, the message is returned as part
29696 of the SMTP response. The use of &%message%& with &%accept%& (or &%discard%&)
29697 is meaningful only for SMTP, as no message is returned when a non-SMTP message
29698 is accepted. In the case of the connect ACL, accepting with a message modifier
29699 overrides the value of &%smtp_banner%&. For the EHLO/HELO ACL, a customized
29700 accept message may not contain more than one line (otherwise it will be
29701 truncated at the first newline and a panic logged), and it cannot affect the
29702 EHLO options.
29703
29704 When SMTP is involved, the message may begin with an overriding response code,
29705 consisting of three digits optionally followed by an &"extended response code"&
29706 of the form &'n.n.n'&, each code being followed by a space. For example:
29707 .code
29708 deny  message = 599 1.2.3 Host not welcome
29709       hosts = 192.168.34.0/24
29710 .endd
29711 The first digit of the supplied response code must be the same as would be sent
29712 by default. A panic occurs if it is not. Exim uses a 550 code when it denies
29713 access, but for the predata ACL, note that the default success code is 354, not
29714 2&'xx'&.
29715
29716 Notwithstanding the previous paragraph, for the QUIT ACL, unlike the others,
29717 the message modifier cannot override the 221 response code.
29718
29719 The text in a &%message%& modifier is literal; any quotes are taken as
29720 literals, but because the string is expanded, backslash escapes are processed
29721 anyway. If the message contains newlines, this gives rise to a multi-line SMTP
29722 response.
29723
29724 .vindex "&$acl_verify_message$&"
29725 For ACLs that are called by an &%acl =%& ACL condition, the message is
29726 stored in &$acl_verify_message$&, from which the calling ACL may use it.
29727
29728 If &%message%& is used on a statement that verifies an address, the message
29729 specified overrides any message that is generated by the verification process.
29730 However, the original message is available in the variable
29731 &$acl_verify_message$&, so you can incorporate it into your message if you
29732 wish. In particular, if you want the text from &%:fail:%& items in &(redirect)&
29733 routers to be passed back as part of the SMTP response, you should either not
29734 use a &%message%& modifier, or make use of &$acl_verify_message$&.
29735
29736 For compatibility with previous releases of Exim, a &%message%& modifier that
29737 is used with a &%warn%& verb behaves in a similar way to the &%add_header%&
29738 modifier, but this usage is now deprecated. However, &%message%& acts only when
29739 all the conditions are true, wherever it appears in an ACL command, whereas
29740 &%add_header%& acts as soon as it is encountered. If &%message%& is used with
29741 &%warn%& in an ACL that is not concerned with receiving a message, it has no
29742 effect.
29743
29744
29745 .vitem &*queue*&&~=&~<&'text'&>
29746 .cindex "&%queue%& ACL modifier"
29747 .cindex "named queues" "selecting in ACL"
29748 This modifier specifies the use of a named queue for spool files
29749 for the message.
29750 It can only be used before the message is received (i.e. not in
29751 the DATA ACL).
29752 This could be used, for example, for known high-volume burst sources
29753 of traffic, or for quarantine of messages.
29754 Separate queue-runner processes will be needed for named queues.
29755 If the text after expansion is empty, the default queue is used.
29756
29757
29758 .vitem &*remove_header*&&~=&~<&'text'&>
29759 This modifier specifies one or more header names in a colon-separated list
29760  that are to be removed from an incoming message, assuming, of course, that
29761 the message is ultimately accepted. For details, see section &<<SECTremoveheadacl>>&.
29762
29763
29764 .vitem &*set*&&~<&'acl_name'&>&~=&~<&'value'&>
29765 .cindex "&%set%& ACL modifier"
29766 This modifier puts a value into one of the ACL variables (see section
29767 &<<SECTaclvariables>>&).
29768
29769
29770 .vitem &*udpsend*&&~=&~<&'parameters'&>
29771 .cindex "UDP communications"
29772 This modifier sends a UDP packet, for purposes such as statistics
29773 collection or behaviour monitoring. The parameters are expanded, and
29774 the result of the expansion must be a colon-separated list consisting
29775 of a destination server, port number, and the packet contents. The
29776 server can be specified as a host name or IPv4 or IPv6 address. The
29777 separator can be changed with the usual angle bracket syntax. For
29778 example, you might want to collect information on which hosts connect
29779 when:
29780 .code
29781 udpsend = <; 2001:dB8::dead:beef ; 1234 ;\
29782              $tod_zulu $sender_host_address
29783 .endd
29784 .endlist
29785
29786
29787
29788
29789 .section "Use of the control modifier" "SECTcontrols"
29790 .cindex "&%control%& ACL modifier"
29791 The &%control%& modifier supports the following settings:
29792
29793 .vlist
29794 .vitem &*control&~=&~allow_auth_unadvertised*&
29795 This modifier allows a client host to use the SMTP AUTH command even when it
29796 has not been advertised in response to EHLO. Furthermore, because there are
29797 apparently some really broken clients that do this, Exim will accept AUTH after
29798 HELO (rather than EHLO) when this control is set. It should be used only if you
29799 really need it, and you should limit its use to those broken clients that do
29800 not work without it. For example:
29801 .code
29802 warn hosts   = 192.168.34.25
29803      control = allow_auth_unadvertised
29804 .endd
29805 Normally, when an Exim server receives an AUTH command, it checks the name of
29806 the authentication mechanism that is given in the command to ensure that it
29807 matches an advertised mechanism. When this control is set, the check that a
29808 mechanism has been advertised is bypassed. Any configured mechanism can be used
29809 by the client. This control is permitted only in the connection and HELO ACLs.
29810
29811
29812 .vitem &*control&~=&~caseful_local_part*& &&&
29813        &*control&~=&~caselower_local_part*&
29814 .cindex "&ACL;" "case of local part in"
29815 .cindex "case of local parts"
29816 .vindex "&$local_part$&"
29817 These two controls are permitted only in the ACL specified by &%acl_smtp_rcpt%&
29818 (that is, during RCPT processing). By default, the contents of &$local_part$&
29819 are lower cased before ACL processing. If &"caseful_local_part"& is specified,
29820 any uppercase letters in the original local part are restored in &$local_part$&
29821 for the rest of the ACL, or until a control that sets &"caselower_local_part"&
29822 is encountered.
29823
29824 These controls affect only the current recipient. Moreover, they apply only to
29825 local part handling that takes place directly in the ACL (for example, as a key
29826 in lookups). If a test to verify the recipient is obeyed, the case-related
29827 handling of the local part during the verification is controlled by the router
29828 configuration (see the &%caseful_local_part%& generic router option).
29829
29830 This facility could be used, for example, to add a spam score to local parts
29831 containing upper case letters. For example, using &$acl_m4$& to accumulate the
29832 spam score:
29833 .code
29834 warn  control = caseful_local_part
29835       set acl_m4 = ${eval:\
29836                      $acl_m4 + \
29837                      ${if match{$local_part}{[A-Z]}{1}{0}}\
29838                     }
29839       control = caselower_local_part
29840 .endd
29841 Notice that we put back the lower cased version afterwards, assuming that
29842 is what is wanted for subsequent tests.
29843
29844
29845 .vitem &*control&~=&~cutthrough_delivery/*&<&'options'&>
29846 .cindex "&ACL;" "cutthrough routing"
29847 .cindex "cutthrough" "requesting"
29848 This option requests delivery be attempted while the item is being received.
29849
29850 The option is usable in the RCPT ACL.
29851 If enabled for a message received via smtp and routed to an smtp transport,
29852 and only one transport, interface, destination host and port combination
29853 is used for all recipients of the message,
29854 then the delivery connection is made while the receiving connection is open
29855 and data is copied from one to the other.
29856
29857 An attempt to set this option for any recipient but the first
29858 for a mail will be quietly ignored.
29859 If a recipient-verify callout
29860 (with use_sender)
29861 connection is subsequently
29862 requested in the same ACL it is held open and used for
29863 any subsequent recipients and the data,
29864 otherwise one is made after the initial RCPT ACL completes.
29865
29866 Note that routers are used in verify mode,
29867 and cannot depend on content of received headers.
29868 Note also that headers cannot be
29869 modified by any of the post-data ACLs (DATA, MIME and DKIM).
29870 Headers may be modified by routers (subject to the above) and transports.
29871 The &'Received-By:'& header is generated as soon as the body reception starts,
29872 rather than the traditional time after the full message is received;
29873 this will affect the timestamp.
29874
29875 All the usual ACLs are called; if one results in the message being
29876 rejected, all effort spent in delivery (including the costs on
29877 the ultimate destination) will be wasted.
29878 Note that in the case of data-time ACLs this includes the entire
29879 message body.
29880
29881 Cutthrough delivery is not supported via transport-filters or when DKIM signing
29882 of outgoing messages is done, because it sends data to the ultimate destination
29883 before the entire message has been received from the source.
29884 It is not supported for messages received with the SMTP PRDR
29885 or CHUNKING
29886 options in use.
29887
29888 Should the ultimate destination system positively accept or reject the mail,
29889 a corresponding indication is given to the source system and nothing is queued.
29890 If the item is successfully delivered in cutthrough mode
29891 the delivery log lines are tagged with ">>" rather than "=>" and appear
29892 before the acceptance "<=" line.
29893
29894 If there is a temporary error the item is queued for later delivery in the
29895 usual fashion.
29896 This behaviour can be adjusted by appending the option &*defer=*&<&'value'&>
29897 to the control; the default value is &"spool"& and the alternate value
29898 &"pass"& copies an SMTP defer response from the target back to the initiator
29899 and does not queue the message.
29900 Note that this is independent of any recipient verify conditions in the ACL.
29901
29902 Delivery in this mode avoids the generation of a bounce mail to a
29903 (possibly faked)
29904 sender when the destination system is doing content-scan based rejection.
29905
29906
29907 .vitem &*control&~=&~debug/*&<&'options'&>
29908 .cindex "&ACL;" "enabling debug logging"
29909 .cindex "debugging" "enabling from an ACL"
29910 This control turns on debug logging, almost as though Exim had been invoked
29911 with &`-d`&, with the output going to a new logfile in the usual logs directory,
29912 by default called &'debuglog'&.
29913 The filename can be adjusted with the &'tag'& option, which
29914 may access any variables already defined.  The logging may be adjusted with
29915 the &'opts'& option, which takes the same values as the &`-d`& command-line
29916 option.
29917 Logging started this way may be stopped, and the file removed,
29918 with the &'kill'& option.
29919 Some examples (which depend on variables that don't exist in all
29920 contexts):
29921 .code
29922       control = debug
29923       control = debug/tag=.$sender_host_address
29924       control = debug/opts=+expand+acl
29925       control = debug/tag=.$message_exim_id/opts=+expand
29926       control = debug/kill
29927 .endd
29928
29929
29930 .vitem &*control&~=&~dkim_disable_verify*&
29931 .cindex "disable DKIM verify"
29932 .cindex "DKIM" "disable verify"
29933 This control turns off DKIM verification processing entirely.  For details on
29934 the operation and configuration of DKIM, see section &<<SECDKIM>>&.
29935
29936
29937 .vitem &*control&~=&~dscp/*&<&'value'&>
29938 .cindex "&ACL;" "setting DSCP value"
29939 .cindex "DSCP" "inbound"
29940 This option causes the DSCP value associated with the socket for the inbound
29941 connection to be adjusted to a given value, given as one of a number of fixed
29942 strings or to numeric value.
29943 The &%-bI:dscp%& option may be used to ask Exim which names it knows of.
29944 Common values include &`throughput`&, &`mincost`&, and on newer systems
29945 &`ef`&, &`af41`&, etc.  Numeric values may be in the range 0 to 0x3F.
29946
29947 The outbound packets from Exim will be marked with this value in the header
29948 (for IPv4, the TOS field; for IPv6, the TCLASS field); there is no guarantee
29949 that these values will have any effect, not be stripped by networking
29950 equipment, or do much of anything without cooperation with your Network
29951 Engineer and those of all network operators between the source and destination.
29952
29953
29954 .vitem &*control&~=&~enforce_sync*& &&&
29955        &*control&~=&~no_enforce_sync*&
29956 .cindex "SMTP" "synchronization checking"
29957 .cindex "synchronization checking in SMTP"
29958 These controls make it possible to be selective about when SMTP synchronization
29959 is enforced. The global option &%smtp_enforce_sync%& specifies the initial
29960 state of the switch (it is true by default). See the description of this option
29961 in chapter &<<CHAPmainconfig>>& for details of SMTP synchronization checking.
29962
29963 The effect of these two controls lasts for the remainder of the SMTP
29964 connection. They can appear in any ACL except the one for the non-SMTP
29965 messages. The most straightforward place to put them is in the ACL defined by
29966 &%acl_smtp_connect%&, which is run at the start of an incoming SMTP connection,
29967 before the first synchronization check. The expected use is to turn off the
29968 synchronization checks for badly-behaved hosts that you nevertheless need to
29969 work with.
29970
29971
29972 .vitem &*control&~=&~fakedefer/*&<&'message'&>
29973 .cindex "fake defer"
29974 .cindex "defer, fake"
29975 This control works in exactly the same way as &%fakereject%& (described below)
29976 except that it causes an SMTP 450 response after the message data instead of a
29977 550 response. You must take care when using &%fakedefer%& because it causes the
29978 messages to be duplicated when the sender retries. Therefore, you should not
29979 use &%fakedefer%& if the message is to be delivered normally.
29980
29981 .vitem &*control&~=&~fakereject/*&<&'message'&>
29982 .cindex "fake rejection"
29983 .cindex "rejection, fake"
29984 This control is permitted only for the MAIL, RCPT, and DATA ACLs, in other
29985 words, only when an SMTP message is being received. If Exim accepts the
29986 message, instead the final 250 response, a 550 rejection message is sent.
29987 However, Exim proceeds to deliver the message as normal. The control applies
29988 only to the current message, not to any subsequent ones that may be received in
29989 the same SMTP connection.
29990
29991 The text for the 550 response is taken from the &%control%& modifier. If no
29992 message is supplied, the following is used:
29993 .code
29994 550-Your message has been rejected but is being
29995 550-kept for evaluation.
29996 550-If it was a legitimate message, it may still be
29997 550 delivered to the target recipient(s).
29998 .endd
29999 This facility should be used with extreme caution.
30000
30001 .vitem &*control&~=&~freeze*&
30002 .cindex "frozen messages" "forcing in ACL"
30003 This control is permitted only for the MAIL, RCPT, DATA, and non-SMTP ACLs, in
30004 other words, only when a message is being received. If the message is accepted,
30005 it is placed on Exim's queue and frozen. The control applies only to the
30006 current message, not to any subsequent ones that may be received in the same
30007 SMTP connection.
30008
30009 This modifier can optionally be followed by &`/no_tell`&. If the global option
30010 &%freeze_tell%& is set, it is ignored for the current message (that is, nobody
30011 is told about the freezing), provided all the &*control=freeze*& modifiers that
30012 are obeyed for the current message have the &`/no_tell`& option.
30013
30014 .vitem &*control&~=&~no_delay_flush*&
30015 .cindex "SMTP" "output flushing, disabling for delay"
30016 Exim normally flushes SMTP output before implementing a delay in an ACL, to
30017 avoid unexpected timeouts in clients when the SMTP PIPELINING extension is in
30018 use. This control, as long as it is encountered before the &%delay%& modifier,
30019 disables such output flushing.
30020
30021 .vitem &*control&~=&~no_callout_flush*&
30022 .cindex "SMTP" "output flushing, disabling for callout"
30023 Exim normally flushes SMTP output before performing a callout in an ACL, to
30024 avoid unexpected timeouts in clients when the SMTP PIPELINING extension is in
30025 use. This control, as long as it is encountered before the &%verify%& condition
30026 that causes the callout, disables such output flushing.
30027
30028 .vitem &*control&~=&~no_mbox_unspool*&
30029 This control is available when Exim is compiled with the content scanning
30030 extension. Content scanning may require a copy of the current message, or parts
30031 of it, to be written in &"mbox format"& to a spool file, for passing to a virus
30032 or spam scanner. Normally, such copies are deleted when they are no longer
30033 needed. If this control is set, the copies are not deleted. The control applies
30034 only to the current message, not to any subsequent ones that may be received in
30035 the same SMTP connection. It is provided for debugging purposes and is unlikely
30036 to be useful in production.
30037
30038 .vitem &*control&~=&~no_multiline_responses*&
30039 .cindex "multiline responses, suppressing"
30040 This control is permitted for any ACL except the one for non-SMTP messages.
30041 It seems that there are broken clients in use that cannot handle multiline
30042 SMTP responses, despite the fact that RFC 821 defined them over 20 years ago.
30043
30044 If this control is set, multiline SMTP responses from ACL rejections are
30045 suppressed. One way of doing this would have been to put out these responses as
30046 one long line. However, RFC 2821 specifies a maximum of 512 bytes per response
30047 (&"use multiline responses for more"& it says &-- ha!), and some of the
30048 responses might get close to that. So this facility, which is after all only a
30049 sop to broken clients, is implemented by doing two very easy things:
30050
30051 .ilist
30052 Extra information that is normally output as part of a rejection caused by
30053 sender verification failure is omitted. Only the final line (typically &"sender
30054 verification failed"&) is sent.
30055 .next
30056 If a &%message%& modifier supplies a multiline response, only the first
30057 line is output.
30058 .endlist
30059
30060 The setting of the switch can, of course, be made conditional on the
30061 calling host. Its effect lasts until the end of the SMTP connection.
30062
30063 .vitem &*control&~=&~no_pipelining*&
30064 .cindex "PIPELINING" "suppressing advertising"
30065 This control turns off the advertising of the PIPELINING extension to SMTP in
30066 the current session. To be useful, it must be obeyed before Exim sends its
30067 response to an EHLO command. Therefore, it should normally appear in an ACL
30068 controlled by &%acl_smtp_connect%& or &%acl_smtp_helo%&. See also
30069 &%pipelining_advertise_hosts%&.
30070
30071 .vitem &*control&~=&~queue_only*&
30072 .oindex "&%queue_only%&"
30073 .cindex "queueing incoming messages"
30074 This control is permitted only for the MAIL, RCPT, DATA, and non-SMTP ACLs, in
30075 other words, only when a message is being received. If the message is accepted,
30076 it is placed on Exim's queue and left there for delivery by a subsequent queue
30077 runner. No immediate delivery process is started. In other words, it has the
30078 effect as the &%queue_only%& global option. However, the control applies only
30079 to the current message, not to any subsequent ones that may be received in the
30080 same SMTP connection.
30081
30082 .vitem &*control&~=&~submission/*&<&'options'&>
30083 .cindex "message" "submission"
30084 .cindex "submission mode"
30085 This control is permitted only for the MAIL, RCPT, and start of data ACLs (the
30086 latter is the one defined by &%acl_smtp_predata%&). Setting it tells Exim that
30087 the current message is a submission from a local MUA. In this case, Exim
30088 operates in &"submission mode"&, and applies certain fixups to the message if
30089 necessary. For example, it adds a &'Date:'& header line if one is not present.
30090 This control is not permitted in the &%acl_smtp_data%& ACL, because that is too
30091 late (the message has already been created).
30092
30093 Chapter &<<CHAPmsgproc>>& describes the processing that Exim applies to
30094 messages. Section &<<SECTsubmodnon>>& covers the processing that happens in
30095 submission mode; the available options for this control are described there.
30096 The control applies only to the current message, not to any subsequent ones
30097 that may be received in the same SMTP connection.
30098
30099 .vitem &*control&~=&~suppress_local_fixups*&
30100 .cindex "submission fixups, suppressing"
30101 This control applies to locally submitted (non TCP/IP) messages, and is the
30102 complement of &`control = submission`&. It disables the fixups that are
30103 normally applied to locally-submitted messages. Specifically:
30104
30105 .ilist
30106 Any &'Sender:'& header line is left alone (in this respect, it is a
30107 dynamic version of &%local_sender_retain%&).
30108 .next
30109 No &'Message-ID:'&, &'From:'&, or &'Date:'& header lines are added.
30110 .next
30111 There is no check that &'From:'& corresponds to the actual sender.
30112 .endlist ilist
30113
30114 This control may be useful when a remotely-originated message is accepted,
30115 passed to some scanning program, and then re-submitted for delivery. It can be
30116 used only in the &%acl_smtp_mail%&, &%acl_smtp_rcpt%&, &%acl_smtp_predata%&,
30117 and &%acl_not_smtp_start%& ACLs, because it has to be set before the message's
30118 data is read.
30119
30120 &*Note:*& This control applies only to the current message, not to any others
30121 that are being submitted at the same time using &%-bs%& or &%-bS%&.
30122
30123 .vitem &*control&~=&~utf8_downconvert*&
30124 This control enables conversion of UTF-8 in message addresses
30125 to a-label form.
30126 For details see section &<<SECTi18nMTA>>&.
30127 .endlist vlist
30128
30129
30130 .section "Summary of message fixup control" "SECTsummesfix"
30131 All four possibilities for message fixups can be specified:
30132
30133 .ilist
30134 Locally submitted, fixups applied: the default.
30135 .next
30136 Locally submitted, no fixups applied: use
30137 &`control = suppress_local_fixups`&.
30138 .next
30139 Remotely submitted, no fixups applied: the default.
30140 .next
30141 Remotely submitted, fixups applied: use &`control = submission`&.
30142 .endlist
30143
30144
30145
30146 .section "Adding header lines in ACLs" "SECTaddheadacl"
30147 .cindex "header lines" "adding in an ACL"
30148 .cindex "header lines" "position of added lines"
30149 .cindex "&%add_header%& ACL modifier"
30150 The &%add_header%& modifier can be used to add one or more extra header lines
30151 to an incoming message, as in this example:
30152 .code
30153 warn dnslists = sbl.spamhaus.org : \
30154                 dialup.mail-abuse.org
30155      add_header = X-blacklisted-at: $dnslist_domain
30156 .endd
30157 The &%add_header%& modifier is permitted in the MAIL, RCPT, PREDATA, DATA,
30158 MIME, DKIM, and non-SMTP ACLs (in other words, those that are concerned with
30159 receiving a message). The message must ultimately be accepted for
30160 &%add_header%& to have any significant effect. You can use &%add_header%& with
30161 any ACL verb, including &%deny%& (though this is potentially useful only in a
30162 RCPT ACL).
30163
30164 Headers will not be added to the message if the modifier is used in
30165 DATA, MIME or DKIM ACLs for a message delivered by cutthrough routing.
30166
30167 Leading and trailing newlines are removed from
30168 the data for the &%add_header%& modifier; if it then
30169 contains one or more newlines that
30170 are not followed by a space or a tab, it is assumed to contain multiple header
30171 lines. Each one is checked for valid syntax; &`X-ACL-Warn:`& is added to the
30172 front of any line that is not a valid header line.
30173
30174 Added header lines are accumulated during the MAIL, RCPT, and predata ACLs.
30175 They are added to the message before processing the DATA and MIME ACLs.
30176 However, if an identical header line is requested more than once, only one copy
30177 is actually added to the message. Further header lines may be accumulated
30178 during the DATA and MIME ACLs, after which they are added to the message, again
30179 with duplicates suppressed. Thus, it is possible to add two identical header
30180 lines to an SMTP message, but only if one is added before DATA and one after.
30181 In the case of non-SMTP messages, new headers are accumulated during the
30182 non-SMTP ACLs, and are added to the message after all the ACLs have run. If a
30183 message is rejected after DATA or by the non-SMTP ACL, all added header lines
30184 are included in the entry that is written to the reject log.
30185
30186 .cindex "header lines" "added; visibility of"
30187 Header lines are not visible in string expansions
30188 of message headers
30189 until they are added to the
30190 message. It follows that header lines defined in the MAIL, RCPT, and predata
30191 ACLs are not visible until the DATA ACL and MIME ACLs are run. Similarly,
30192 header lines that are added by the DATA or MIME ACLs are not visible in those
30193 ACLs. Because of this restriction, you cannot use header lines as a way of
30194 passing data between (for example) the MAIL and RCPT ACLs. If you want to do
30195 this, you can use ACL variables, as described in section
30196 &<<SECTaclvariables>>&.
30197
30198 The list of headers yet to be added is given by the &%$headers_added%& variable.
30199
30200 The &%add_header%& modifier acts immediately as it is encountered during the
30201 processing of an ACL. Notice the difference between these two cases:
30202 .display
30203 &`accept add_header = ADDED: some text`&
30204 &`       `&<&'some condition'&>
30205
30206 &`accept `&<&'some condition'&>
30207 &`       add_header = ADDED: some text`&
30208 .endd
30209 In the first case, the header line is always added, whether or not the
30210 condition is true. In the second case, the header line is added only if the
30211 condition is true. Multiple occurrences of &%add_header%& may occur in the same
30212 ACL statement. All those that are encountered before a condition fails are
30213 honoured.
30214
30215 .cindex "&%warn%& ACL verb"
30216 For compatibility with previous versions of Exim, a &%message%& modifier for a
30217 &%warn%& verb acts in the same way as &%add_header%&, except that it takes
30218 effect only if all the conditions are true, even if it appears before some of
30219 them. Furthermore, only the last occurrence of &%message%& is honoured. This
30220 usage of &%message%& is now deprecated. If both &%add_header%& and &%message%&
30221 are present on a &%warn%& verb, both are processed according to their
30222 specifications.
30223
30224 By default, new header lines are added to a message at the end of the existing
30225 header lines. However, you can specify that any particular header line should
30226 be added right at the start (before all the &'Received:'& lines), immediately
30227 after the first block of &'Received:'& lines, or immediately before any line
30228 that is not a &'Received:'& or &'Resent-something:'& header.
30229
30230 This is done by specifying &":at_start:"&, &":after_received:"&, or
30231 &":at_start_rfc:"& (or, for completeness, &":at_end:"&) before the text of the
30232 header line, respectively. (Header text cannot start with a colon, as there has
30233 to be a header name first.) For example:
30234 .code
30235 warn add_header = \
30236        :after_received:X-My-Header: something or other...
30237 .endd
30238 If more than one header line is supplied in a single &%add_header%& modifier,
30239 each one is treated independently and can therefore be placed differently. If
30240 you add more than one line at the start, or after the Received: block, they end
30241 up in reverse order.
30242
30243 &*Warning*&: This facility currently applies only to header lines that are
30244 added in an ACL. It does NOT work for header lines that are added in a
30245 system filter or in a router or transport.
30246
30247
30248
30249 .section "Removing header lines in ACLs" "SECTremoveheadacl"
30250 .cindex "header lines" "removing in an ACL"
30251 .cindex "header lines" "position of removed lines"
30252 .cindex "&%remove_header%& ACL modifier"
30253 The &%remove_header%& modifier can be used to remove one or more header lines
30254 from an incoming message, as in this example:
30255 .code
30256 warn   message        = Remove internal headers
30257        remove_header  = x-route-mail1 : x-route-mail2
30258 .endd
30259 The &%remove_header%& modifier is permitted in the MAIL, RCPT, PREDATA, DATA,
30260 MIME, DKIM, and non-SMTP ACLs (in other words, those that are concerned with
30261 receiving a message). The message must ultimately be accepted for
30262 &%remove_header%& to have any significant effect. You can use &%remove_header%&
30263 with any ACL verb, including &%deny%&, though this is really not useful for
30264 any verb that doesn't result in a delivered message.
30265
30266 Headers will not be removed from the message if the modifier is used in
30267 DATA, MIME or DKIM ACLs for a message delivered by cutthrough routing.
30268
30269 More than one header can be removed at the same time by using a colon separated
30270 list of header names. The header matching is case insensitive. Wildcards are
30271 not permitted, nor is list expansion performed, so you cannot use hostlists to
30272 create a list of headers, however both connection and message variable expansion
30273 are performed (&%$acl_c_*%& and &%$acl_m_*%&), illustrated in this example:
30274 .code
30275 warn   hosts           = +internal_hosts
30276        set acl_c_ihdrs = x-route-mail1 : x-route-mail2
30277 warn   message         = Remove internal headers
30278        remove_header   = $acl_c_ihdrs
30279 .endd
30280 Header names for removal are accumulated during the MAIL, RCPT, and predata ACLs.
30281 Matching header lines are removed from the message before processing the DATA and MIME ACLs.
30282 If multiple header lines match, all are removed.
30283 There is no harm in attempting to remove the same header twice nor in removing
30284 a non-existent header. Further header lines to be removed may be accumulated
30285 during the DATA and MIME ACLs, after which they are removed from the message,
30286 if present. In the case of non-SMTP messages, headers to be removed are
30287 accumulated during the non-SMTP ACLs, and are removed from the message after
30288 all the ACLs have run. If a message is rejected after DATA or by the non-SMTP
30289 ACL, there really is no effect because there is no logging of what headers
30290 would have been removed.
30291
30292 .cindex "header lines" "removed; visibility of"
30293 Header lines are not visible in string expansions until the DATA phase when it
30294 is received. Any header lines removed in the MAIL, RCPT, and predata ACLs are
30295 not visible in the DATA ACL and MIME ACLs. Similarly, header lines that are
30296 removed by the DATA or MIME ACLs are still visible in those ACLs. Because of
30297 this restriction, you cannot use header lines as a way of controlling data
30298 passed between (for example) the MAIL and RCPT ACLs. If you want to do this,
30299 you should instead use ACL variables, as described in section
30300 &<<SECTaclvariables>>&.
30301
30302 The &%remove_header%& modifier acts immediately as it is encountered during the
30303 processing of an ACL. Notice the difference between these two cases:
30304 .display
30305 &`accept remove_header = X-Internal`&
30306 &`       `&<&'some condition'&>
30307
30308 &`accept `&<&'some condition'&>
30309 &`       remove_header = X-Internal`&
30310 .endd
30311 In the first case, the header line is always removed, whether or not the
30312 condition is true. In the second case, the header line is removed only if the
30313 condition is true. Multiple occurrences of &%remove_header%& may occur in the
30314 same ACL statement. All those that are encountered before a condition fails
30315 are honoured.
30316
30317 &*Warning*&: This facility currently applies only to header lines that are
30318 present during ACL processing. It does NOT remove header lines that are added
30319 in a system filter or in a router or transport.
30320
30321
30322
30323
30324 .section "ACL conditions" "SECTaclconditions"
30325 .cindex "&ACL;" "conditions; list of"
30326 Some of the conditions listed in this section are available only when Exim is
30327 compiled with the content-scanning extension. They are included here briefly
30328 for completeness. More detailed descriptions can be found in the discussion on
30329 content scanning in chapter &<<CHAPexiscan>>&.
30330
30331 Not all conditions are relevant in all circumstances. For example, testing
30332 senders and recipients does not make sense in an ACL that is being run as the
30333 result of the arrival of an ETRN command, and checks on message headers can be
30334 done only in the ACLs specified by &%acl_smtp_data%& and &%acl_not_smtp%&. You
30335 can use the same condition (with different parameters) more than once in the
30336 same ACL statement. This provides a way of specifying an &"and"& conjunction.
30337 The conditions are as follows:
30338
30339
30340 .vlist
30341 .vitem &*acl&~=&~*&<&'name&~of&~acl&~or&~ACL&~string&~or&~file&~name&~'&>
30342 .cindex "&ACL;" "nested"
30343 .cindex "&ACL;" "indirect"
30344 .cindex "&ACL;" "arguments"
30345 .cindex "&%acl%& ACL condition"
30346 The possible values of the argument are the same as for the
30347 &%acl_smtp_%&&'xxx'& options. The named or inline ACL is run. If it returns
30348 &"accept"& the condition is true; if it returns &"deny"& the condition is
30349 false. If it returns &"defer"&, the current ACL returns &"defer"& unless the
30350 condition is on a &%warn%& verb. In that case, a &"defer"& return makes the
30351 condition false. This means that further processing of the &%warn%& verb
30352 ceases, but processing of the ACL continues.
30353
30354 If the argument is a named ACL, up to nine space-separated optional values
30355 can be appended; they appear within the called ACL in $acl_arg1 to $acl_arg9,
30356 and $acl_narg is set to the count of values.
30357 Previous values of these variables are restored after the call returns.
30358 The name and values are expanded separately.
30359 Note that spaces in complex expansions which are used as arguments
30360 will act as argument separators.
30361
30362 If the nested &%acl%& returns &"drop"& and the outer condition denies access,
30363 the connection is dropped. If it returns &"discard"&, the verb must be
30364 &%accept%& or &%discard%&, and the action is taken immediately &-- no further
30365 conditions are tested.
30366
30367 ACLs may be nested up to 20 deep; the limit exists purely to catch runaway
30368 loops. This condition allows you to use different ACLs in different
30369 circumstances. For example, different ACLs can be used to handle RCPT commands
30370 for different local users or different local domains.
30371
30372 .vitem &*authenticated&~=&~*&<&'string&~list'&>
30373 .cindex "&%authenticated%& ACL condition"
30374 .cindex "authentication" "ACL checking"
30375 .cindex "&ACL;" "testing for authentication"
30376 If the SMTP connection is not authenticated, the condition is false. Otherwise,
30377 the name of the authenticator is tested against the list. To test for
30378 authentication by any authenticator, you can set
30379 .code
30380 authenticated = *
30381 .endd
30382
30383 .vitem &*condition&~=&~*&<&'string'&>
30384 .cindex "&%condition%& ACL condition"
30385 .cindex "customizing" "ACL condition"
30386 .cindex "&ACL;" "customized test"
30387 .cindex "&ACL;" "testing, customized"
30388 This feature allows you to make up custom conditions. If the result of
30389 expanding the string is an empty string, the number zero, or one of the strings
30390 &"no"& or &"false"&, the condition is false. If the result is any non-zero
30391 number, or one of the strings &"yes"& or &"true"&, the condition is true. For
30392 any other value, some error is assumed to have occurred, and the ACL returns
30393 &"defer"&. However, if the expansion is forced to fail, the condition is
30394 ignored. The effect is to treat it as true, whether it is positive or
30395 negative.
30396
30397 .vitem &*decode&~=&~*&<&'location'&>
30398 .cindex "&%decode%& ACL condition"
30399 This condition is available only when Exim is compiled with the
30400 content-scanning extension, and it is allowed only in the ACL defined by
30401 &%acl_smtp_mime%&. It causes the current MIME part to be decoded into a file.
30402 If all goes well, the condition is true. It is false only if there are
30403 problems such as a syntax error or a memory shortage. For more details, see
30404 chapter &<<CHAPexiscan>>&.
30405
30406 .vitem &*dnslists&~=&~*&<&'list&~of&~domain&~names&~and&~other&~data'&>
30407 .cindex "&%dnslists%& ACL condition"
30408 .cindex "DNS list" "in ACL"
30409 .cindex "black list (DNS)"
30410 .cindex "&ACL;" "testing a DNS list"
30411 This condition checks for entries in DNS black lists. These are also known as
30412 &"RBL lists"&, after the original Realtime Blackhole List, but note that the
30413 use of the lists at &'mail-abuse.org'& now carries a charge. There are too many
30414 different variants of this condition to describe briefly here. See sections
30415 &<<SECTmorednslists>>&&--&<<SECTmorednslistslast>>& for details.
30416
30417 .vitem &*domains&~=&~*&<&'domain&~list'&>
30418 .cindex "&%domains%& ACL condition"
30419 .cindex "domain" "ACL checking"
30420 .cindex "&ACL;" "testing a recipient domain"
30421 .vindex "&$domain_data$&"
30422 This condition is relevant only after a RCPT command. It checks that the domain
30423 of the recipient address is in the domain list. If percent-hack processing is
30424 enabled, it is done before this test is done. If the check succeeds with a
30425 lookup, the result of the lookup is placed in &$domain_data$& until the next
30426 &%domains%& test.
30427
30428 &*Note carefully*& (because many people seem to fall foul of this): you cannot
30429 use &%domains%& in a DATA ACL.
30430
30431
30432 .vitem &*encrypted&~=&~*&<&'string&~list'&>
30433 .cindex "&%encrypted%& ACL condition"
30434 .cindex "encryption" "checking in an ACL"
30435 .cindex "&ACL;" "testing for encryption"
30436 If the SMTP connection is not encrypted, the condition is false. Otherwise, the
30437 name of the cipher suite in use is tested against the list. To test for
30438 encryption without testing for any specific cipher suite(s), set
30439 .code
30440 encrypted = *
30441 .endd
30442
30443
30444 .vitem &*hosts&~=&~*&<&'host&~list'&>
30445 .cindex "&%hosts%& ACL condition"
30446 .cindex "host" "ACL checking"
30447 .cindex "&ACL;" "testing the client host"
30448 This condition tests that the calling host matches the host list. If you have
30449 name lookups or wildcarded host names and IP addresses in the same host list,
30450 you should normally put the IP addresses first. For example, you could have:
30451 .code
30452 accept hosts = 10.9.8.7 : dbm;/etc/friendly/hosts
30453 .endd
30454 The lookup in this example uses the host name for its key. This is implied by
30455 the lookup type &"dbm"&. (For a host address lookup you would use &"net-dbm"&
30456 and it wouldn't matter which way round you had these two items.)
30457
30458 The reason for the problem with host names lies in the left-to-right way that
30459 Exim processes lists. It can test IP addresses without doing any DNS lookups,
30460 but when it reaches an item that requires a host name, it fails if it cannot
30461 find a host name to compare with the pattern. If the above list is given in the
30462 opposite order, the &%accept%& statement fails for a host whose name cannot be
30463 found, even if its IP address is 10.9.8.7.
30464
30465 If you really do want to do the name check first, and still recognize the IP
30466 address even if the name lookup fails, you can rewrite the ACL like this:
30467 .code
30468 accept hosts = dbm;/etc/friendly/hosts
30469 accept hosts = 10.9.8.7
30470 .endd
30471 The default action on failing to find the host name is to assume that the host
30472 is not in the list, so the first &%accept%& statement fails. The second
30473 statement can then check the IP address.
30474
30475 .vindex "&$host_data$&"
30476 If a &%hosts%& condition is satisfied by means of a lookup, the result
30477 of the lookup is made available in the &$host_data$& variable. This
30478 allows you, for example, to set up a statement like this:
30479 .code
30480 deny  hosts = net-lsearch;/some/file
30481 message = $host_data
30482 .endd
30483 which gives a custom error message for each denied host.
30484
30485 .vitem &*local_parts&~=&~*&<&'local&~part&~list'&>
30486 .cindex "&%local_parts%& ACL condition"
30487 .cindex "local part" "ACL checking"
30488 .cindex "&ACL;" "testing a local part"
30489 .vindex "&$local_part_data$&"
30490 This condition is relevant only after a RCPT command. It checks that the local
30491 part of the recipient address is in the list. If percent-hack processing is
30492 enabled, it is done before this test. If the check succeeds with a lookup, the
30493 result of the lookup is placed in &$local_part_data$&, which remains set until
30494 the next &%local_parts%& test.
30495
30496 .vitem &*malware&~=&~*&<&'option'&>
30497 .cindex "&%malware%& ACL condition"
30498 .cindex "&ACL;" "virus scanning"
30499 .cindex "&ACL;" "scanning for viruses"
30500 This condition is available only when Exim is compiled with the
30501 content-scanning extension. It causes the incoming message to be scanned for
30502 viruses. For details, see chapter &<<CHAPexiscan>>&.
30503
30504 .vitem &*mime_regex&~=&~*&<&'list&~of&~regular&~expressions'&>
30505 .cindex "&%mime_regex%& ACL condition"
30506 .cindex "&ACL;" "testing by regex matching"
30507 This condition is available only when Exim is compiled with the
30508 content-scanning extension, and it is allowed only in the ACL defined by
30509 &%acl_smtp_mime%&. It causes the current MIME part to be scanned for a match
30510 with any of the regular expressions. For details, see chapter
30511 &<<CHAPexiscan>>&.
30512
30513 .vitem &*ratelimit&~=&~*&<&'parameters'&>
30514 .cindex "rate limiting"
30515 This condition can be used to limit the rate at which a user or host submits
30516 messages. Details are given in section &<<SECTratelimiting>>&.
30517
30518 .vitem &*recipients&~=&~*&<&'address&~list'&>
30519 .cindex "&%recipients%& ACL condition"
30520 .cindex "recipient" "ACL checking"
30521 .cindex "&ACL;" "testing a recipient"
30522 This condition is relevant only after a RCPT command. It checks the entire
30523 recipient address against a list of recipients.
30524
30525 .vitem &*regex&~=&~*&<&'list&~of&~regular&~expressions'&>
30526 .cindex "&%regex%& ACL condition"
30527 .cindex "&ACL;" "testing by regex matching"
30528 This condition is available only when Exim is compiled with the
30529 content-scanning extension, and is available only in the DATA, MIME, and
30530 non-SMTP ACLs. It causes the incoming message to be scanned for a match with
30531 any of the regular expressions. For details, see chapter &<<CHAPexiscan>>&.
30532
30533 .vitem &*sender_domains&~=&~*&<&'domain&~list'&>
30534 .cindex "&%sender_domains%& ACL condition"
30535 .cindex "sender" "ACL checking"
30536 .cindex "&ACL;" "testing a sender domain"
30537 .vindex "&$domain$&"
30538 .vindex "&$sender_address_domain$&"
30539 This condition tests the domain of the sender of the message against the given
30540 domain list. &*Note*&: The domain of the sender address is in
30541 &$sender_address_domain$&. It is &'not'& put in &$domain$& during the testing
30542 of this condition. This is an exception to the general rule for testing domain
30543 lists. It is done this way so that, if this condition is used in an ACL for a
30544 RCPT command, the recipient's domain (which is in &$domain$&) can be used to
30545 influence the sender checking.
30546
30547 &*Warning*&: It is a bad idea to use this condition on its own as a control on
30548 relaying, because sender addresses are easily, and commonly, forged.
30549
30550 .vitem &*senders&~=&~*&<&'address&~list'&>
30551 .cindex "&%senders%& ACL condition"
30552 .cindex "sender" "ACL checking"
30553 .cindex "&ACL;" "testing a sender"
30554 This condition tests the sender of the message against the given list. To test
30555 for a bounce message, which has an empty sender, set
30556 .code
30557 senders = :
30558 .endd
30559 &*Warning*&: It is a bad idea to use this condition on its own as a control on
30560 relaying, because sender addresses are easily, and commonly, forged.
30561
30562 .vitem &*spam&~=&~*&<&'username'&>
30563 .cindex "&%spam%& ACL condition"
30564 .cindex "&ACL;" "scanning for spam"
30565 This condition is available only when Exim is compiled with the
30566 content-scanning extension. It causes the incoming message to be scanned by
30567 SpamAssassin. For details, see chapter &<<CHAPexiscan>>&.
30568
30569 .vitem &*verify&~=&~certificate*&
30570 .cindex "&%verify%& ACL condition"
30571 .cindex "TLS" "client certificate verification"
30572 .cindex "certificate" "verification of client"
30573 .cindex "&ACL;" "certificate verification"
30574 .cindex "&ACL;" "testing a TLS certificate"
30575 This condition is true in an SMTP session if the session is encrypted, and a
30576 certificate was received from the client, and the certificate was verified. The
30577 server requests a certificate only if the client matches &%tls_verify_hosts%&
30578 or &%tls_try_verify_hosts%& (see chapter &<<CHAPTLS>>&).
30579
30580 .vitem &*verify&~=&~csa*&
30581 .cindex "CSA verification"
30582 This condition checks whether the sending host (the client) is authorized to
30583 send email. Details of how this works are given in section
30584 &<<SECTverifyCSA>>&.
30585
30586 .vitem &*verify&~=&~header_names_ascii*&
30587 .cindex "&%verify%& ACL condition"
30588 .cindex "&ACL;" "verifying header names only ASCII"
30589 .cindex "header lines" "verifying header names only ASCII"
30590 .cindex "verifying" "header names only ASCII"
30591 This condition is relevant only in an ACL that is run after a message has been
30592 received, that is, in an ACL specified by &%acl_smtp_data%& or
30593 &%acl_not_smtp%&.  It checks all header names (not the content) to make sure
30594 there are no non-ASCII characters, also excluding control characters.  The
30595 allowable characters are decimal ASCII values 33 through 126.
30596
30597 Exim itself will handle headers with non-ASCII characters, but it can cause
30598 problems for downstream applications, so this option will allow their
30599 detection and rejection in the DATA ACL's.
30600
30601 .vitem &*verify&~=&~header_sender/*&<&'options'&>
30602 .cindex "&%verify%& ACL condition"
30603 .cindex "&ACL;" "verifying sender in the header"
30604 .cindex "header lines" "verifying the sender in"
30605 .cindex "sender" "verifying in header"
30606 .cindex "verifying" "sender in header"
30607 This condition is relevant only in an ACL that is run after a message has been
30608 received, that is, in an ACL specified by &%acl_smtp_data%& or
30609 &%acl_not_smtp%&. It checks that there is a verifiable address in at least one
30610 of the &'Sender:'&, &'Reply-To:'&, or &'From:'& header lines. Such an address
30611 is loosely thought of as a &"sender"& address (hence the name of the test).
30612 However, an address that appears in one of these headers need not be an address
30613 that accepts bounce messages; only sender addresses in envelopes are required
30614 to accept bounces. Therefore, if you use the callout option on this check, you
30615 might want to arrange for a non-empty address in the MAIL command.
30616
30617 Details of address verification and the options are given later, starting at
30618 section &<<SECTaddressverification>>& (callouts are described in section
30619 &<<SECTcallver>>&). You can combine this condition with the &%senders%&
30620 condition to restrict it to bounce messages only:
30621 .code
30622 deny    senders = :
30623         message = A valid sender header is required for bounces
30624        !verify  = header_sender
30625 .endd
30626
30627 .vitem &*verify&~=&~header_syntax*&
30628 .cindex "&%verify%& ACL condition"
30629 .cindex "&ACL;" "verifying header syntax"
30630 .cindex "header lines" "verifying syntax"
30631 .cindex "verifying" "header syntax"
30632 This condition is relevant only in an ACL that is run after a message has been
30633 received, that is, in an ACL specified by &%acl_smtp_data%& or
30634 &%acl_not_smtp%&. It checks the syntax of all header lines that can contain
30635 lists of addresses (&'Sender:'&, &'From:'&, &'Reply-To:'&, &'To:'&, &'Cc:'&,
30636 and &'Bcc:'&), returning true if there are no problems.
30637 Unqualified addresses (local parts without domains) are
30638 permitted only in locally generated messages and from hosts that match
30639 &%sender_unqualified_hosts%& or &%recipient_unqualified_hosts%&, as
30640 appropriate.
30641
30642 Note that this condition is a syntax check only. However, a common spamming
30643 ploy used to be to send syntactically invalid headers such as
30644 .code
30645 To: @
30646 .endd
30647 and this condition can be used to reject such messages, though they are not as
30648 common as they used to be.
30649
30650 .vitem &*verify&~=&~helo*&
30651 .cindex "&%verify%& ACL condition"
30652 .cindex "&ACL;" "verifying HELO/EHLO"
30653 .cindex "HELO" "verifying"
30654 .cindex "EHLO" "verifying"
30655 .cindex "verifying" "EHLO"
30656 .cindex "verifying" "HELO"
30657 This condition is true if a HELO or EHLO command has been received from the
30658 client host, and its contents have been verified. If there has been no previous
30659 attempt to verify the HELO/EHLO contents, it is carried out when this
30660 condition is encountered. See the description of the &%helo_verify_hosts%& and
30661 &%helo_try_verify_hosts%& options for details of how to request verification
30662 independently of this condition.
30663
30664 For SMTP input that does not come over TCP/IP (the &%-bs%& command line
30665 option), this condition is always true.
30666
30667
30668 .vitem &*verify&~=&~not_blind*&
30669 .cindex "verifying" "not blind"
30670 .cindex "bcc recipients, verifying none"
30671 This condition checks that there are no blind (bcc) recipients in the message.
30672 Every envelope recipient must appear either in a &'To:'& header line or in a
30673 &'Cc:'& header line for this condition to be true. Local parts are checked
30674 case-sensitively; domains are checked case-insensitively. If &'Resent-To:'& or
30675 &'Resent-Cc:'& header lines exist, they are also checked. This condition can be
30676 used only in a DATA or non-SMTP ACL.
30677
30678 There are, of course, many legitimate messages that make use of blind (bcc)
30679 recipients. This check should not be used on its own for blocking messages.
30680
30681
30682 .vitem &*verify&~=&~recipient/*&<&'options'&>
30683 .cindex "&%verify%& ACL condition"
30684 .cindex "&ACL;" "verifying recipient"
30685 .cindex "recipient" "verifying"
30686 .cindex "verifying" "recipient"
30687 .vindex "&$address_data$&"
30688 This condition is relevant only after a RCPT command. It verifies the current
30689 recipient. Details of address verification are given later, starting at section
30690 &<<SECTaddressverification>>&. After a recipient has been verified, the value
30691 of &$address_data$& is the last value that was set while routing the address.
30692 This applies even if the verification fails. When an address that is being
30693 verified is redirected to a single address, verification continues with the new
30694 address, and in that case, the subsequent value of &$address_data$& is the
30695 value for the child address.
30696
30697 .vitem &*verify&~=&~reverse_host_lookup/*&<&'options'&>
30698 .cindex "&%verify%& ACL condition"
30699 .cindex "&ACL;" "verifying host reverse lookup"
30700 .cindex "host" "verifying reverse lookup"
30701 This condition ensures that a verified host name has been looked up from the IP
30702 address of the client host. (This may have happened already if the host name
30703 was needed for checking a host list, or if the host matched &%host_lookup%&.)
30704 Verification ensures that the host name obtained from a reverse DNS lookup, or
30705 one of its aliases, does, when it is itself looked up in the DNS, yield the
30706 original IP address.
30707
30708 There is one possible option, &`defer_ok`&.  If this is present and a
30709 DNS operation returns a temporary error, the verify condition succeeds.
30710
30711 If this condition is used for a locally generated message (that is, when there
30712 is no client host involved), it always succeeds.
30713
30714 .vitem &*verify&~=&~sender/*&<&'options'&>
30715 .cindex "&%verify%& ACL condition"
30716 .cindex "&ACL;" "verifying sender"
30717 .cindex "sender" "verifying"
30718 .cindex "verifying" "sender"
30719 This condition is relevant only after a MAIL or RCPT command, or after a
30720 message has been received (the &%acl_smtp_data%& or &%acl_not_smtp%& ACLs). If
30721 the message's sender is empty (that is, this is a bounce message), the
30722 condition is true. Otherwise, the sender address is verified.
30723
30724 .vindex "&$address_data$&"
30725 .vindex "&$sender_address_data$&"
30726 If there is data in the &$address_data$& variable at the end of routing, its
30727 value is placed in &$sender_address_data$& at the end of verification. This
30728 value can be used in subsequent conditions and modifiers in the same ACL
30729 statement. It does not persist after the end of the current statement. If you
30730 want to preserve the value for longer, you can save it in an ACL variable.
30731
30732 Details of verification are given later, starting at section
30733 &<<SECTaddressverification>>&. Exim caches the result of sender verification,
30734 to avoid doing it more than once per message.
30735
30736 .vitem &*verify&~=&~sender=*&<&'address'&>&*/*&<&'options'&>
30737 .cindex "&%verify%& ACL condition"
30738 This is a variation of the previous option, in which a modified address is
30739 verified as a sender.
30740
30741 Note that '/' is legal in local-parts; if the address may have such
30742 (eg. is generated from the received message)
30743 they must be protected from the options parsing by doubling:
30744 .code
30745 verify = sender=${sg{${address:$h_sender:}}{/}{//}}
30746 .endd
30747 .endlist
30748
30749
30750
30751 .section "Using DNS lists" "SECTmorednslists"
30752 .cindex "DNS list" "in ACL"
30753 .cindex "black list (DNS)"
30754 .cindex "&ACL;" "testing a DNS list"
30755 In its simplest form, the &%dnslists%& condition tests whether the calling host
30756 is on at least one of a number of DNS lists by looking up the inverted IP
30757 address in one or more DNS domains. (Note that DNS list domains are not mail
30758 domains, so the &`+`& syntax for named lists doesn't work - it is used for
30759 special options instead.) For example, if the calling host's IP
30760 address is 192.168.62.43, and the ACL statement is
30761 .code
30762 deny dnslists = blackholes.mail-abuse.org : \
30763                 dialups.mail-abuse.org
30764 .endd
30765 the following records are looked up:
30766 .code
30767 43.62.168.192.blackholes.mail-abuse.org
30768 43.62.168.192.dialups.mail-abuse.org
30769 .endd
30770 As soon as Exim finds an existing DNS record, processing of the list stops.
30771 Thus, multiple entries on the list provide an &"or"& conjunction. If you want
30772 to test that a host is on more than one list (an &"and"& conjunction), you can
30773 use two separate conditions:
30774 .code
30775 deny dnslists = blackholes.mail-abuse.org
30776      dnslists = dialups.mail-abuse.org
30777 .endd
30778 If a DNS lookup times out or otherwise fails to give a decisive answer, Exim
30779 behaves as if the host does not match the list item, that is, as if the DNS
30780 record does not exist. If there are further items in the DNS list, they are
30781 processed.
30782
30783 This is usually the required action when &%dnslists%& is used with &%deny%&
30784 (which is the most common usage), because it prevents a DNS failure from
30785 blocking mail. However, you can change this behaviour by putting one of the
30786 following special items in the list:
30787 .display
30788 &`+include_unknown `&   behave as if the item is on the list
30789 &`+exclude_unknown `&   behave as if the item is not on the list (default)
30790 &`+defer_unknown   `&   give a temporary error
30791 .endd
30792 .cindex "&`+include_unknown`&"
30793 .cindex "&`+exclude_unknown`&"
30794 .cindex "&`+defer_unknown`&"
30795 Each of these applies to any subsequent items on the list. For example:
30796 .code
30797 deny dnslists = +defer_unknown : foo.bar.example
30798 .endd
30799 Testing the list of domains stops as soon as a match is found. If you want to
30800 warn for one list and block for another, you can use two different statements:
30801 .code
30802 deny  dnslists = blackholes.mail-abuse.org
30803 warn  message  = X-Warn: sending host is on dialups list
30804       dnslists = dialups.mail-abuse.org
30805 .endd
30806 .cindex caching "of dns lookup"
30807 .cindex DNS TTL
30808 DNS list lookups are cached by Exim for the duration of the SMTP session
30809 (but limited by the DNS return TTL value),
30810 so a lookup based on the IP address is done at most once for any incoming
30811 connection (assuming long-enough TTL).
30812 Exim does not share information between multiple incoming
30813 connections (but your local name server cache should be active).
30814
30815 There are a number of DNS lists to choose from, some commercial, some free,
30816 or free for small deployments.  An overview can be found at
30817 &url(https://en.wikipedia.org/wiki/Comparison_of_DNS_blacklists).
30818
30819
30820
30821 .section "Specifying the IP address for a DNS list lookup" "SECID201"
30822 .cindex "DNS list" "keyed by explicit IP address"
30823 By default, the IP address that is used in a DNS list lookup is the IP address
30824 of the calling host. However, you can specify another IP address by listing it
30825 after the domain name, introduced by a slash. For example:
30826 .code
30827 deny dnslists = black.list.tld/192.168.1.2
30828 .endd
30829 This feature is not very helpful with explicit IP addresses; it is intended for
30830 use with IP addresses that are looked up, for example, the IP addresses of the
30831 MX hosts or nameservers of an email sender address. For an example, see section
30832 &<<SECTmulkeyfor>>& below.
30833
30834
30835
30836
30837 .section "DNS lists keyed on domain names" "SECID202"
30838 .cindex "DNS list" "keyed by domain name"
30839 There are some lists that are keyed on domain names rather than inverted IP
30840 addresses.  No reversing of components is used
30841 with these lists. You can change the name that is looked up in a DNS list by
30842 listing it after the domain name, introduced by a slash. For example,
30843 .code
30844 deny  message  = Sender's domain is listed at $dnslist_domain
30845       dnslists = dsn.rfc-ignorant.org/$sender_address_domain
30846 .endd
30847 This particular example is useful only in ACLs that are obeyed after the
30848 RCPT or DATA commands, when a sender address is available. If (for
30849 example) the message's sender is &'user@tld.example'& the name that is looked
30850 up by this example is
30851 .code
30852 tld.example.dsn.rfc-ignorant.org
30853 .endd
30854 A single &%dnslists%& condition can contain entries for both names and IP
30855 addresses. For example:
30856 .code
30857 deny dnslists = sbl.spamhaus.org : \
30858                 dsn.rfc-ignorant.org/$sender_address_domain
30859 .endd
30860 The first item checks the sending host's IP address; the second checks a domain
30861 name. The whole condition is true if either of the DNS lookups succeeds.
30862
30863
30864
30865
30866 .section "Multiple explicit keys for a DNS list" "SECTmulkeyfor"
30867 .cindex "DNS list" "multiple keys for"
30868 The syntax described above for looking up explicitly-defined values (either
30869 names or IP addresses) in a DNS blacklist is a simplification. After the domain
30870 name for the DNS list, what follows the slash can in fact be a list of items.
30871 As with all lists in Exim, the default separator is a colon. However, because
30872 this is a sublist within the list of DNS blacklist domains, it is necessary
30873 either to double the separators like this:
30874 .code
30875 dnslists = black.list.tld/name.1::name.2
30876 .endd
30877 or to change the separator character, like this:
30878 .code
30879 dnslists = black.list.tld/<;name.1;name.2
30880 .endd
30881 If an item in the list is an IP address, it is inverted before the DNS
30882 blacklist domain is appended. If it is not an IP address, no inversion
30883 occurs. Consider this condition:
30884 .code
30885 dnslists = black.list.tld/<;192.168.1.2;a.domain
30886 .endd
30887 The DNS lookups that occur are:
30888 .code
30889 2.1.168.192.black.list.tld
30890 a.domain.black.list.tld
30891 .endd
30892 Once a DNS record has been found (that matches a specific IP return
30893 address, if specified &-- see section &<<SECTaddmatcon>>&), no further lookups
30894 are done. If there is a temporary DNS error, the rest of the sublist of domains
30895 or IP addresses is tried. A temporary error for the whole dnslists item occurs
30896 only if no other DNS lookup in this sublist succeeds. In other words, a
30897 successful lookup for any of the items in the sublist overrides a temporary
30898 error for a previous item.
30899
30900 The ability to supply a list of items after the slash is in some sense just a
30901 syntactic convenience. These two examples have the same effect:
30902 .code
30903 dnslists = black.list.tld/a.domain : black.list.tld/b.domain
30904 dnslists = black.list.tld/a.domain::b.domain
30905 .endd
30906 However, when the data for the list is obtained from a lookup, the second form
30907 is usually much more convenient. Consider this example:
30908 .code
30909 deny message  = The mail servers for the domain \
30910                 $sender_address_domain \
30911                 are listed at $dnslist_domain ($dnslist_value); \
30912                 see $dnslist_text.
30913      dnslists = sbl.spamhaus.org/<|${lookup dnsdb {>|a=<|\
30914                                    ${lookup dnsdb {>|mxh=\
30915                                    $sender_address_domain} }} }
30916 .endd
30917 Note the use of &`>|`& in the dnsdb lookup to specify the separator for
30918 multiple DNS records. The inner dnsdb lookup produces a list of MX hosts
30919 and the outer dnsdb lookup finds the IP addresses for these hosts. The result
30920 of expanding the condition might be something like this:
30921 .code
30922 dnslists = sbl.spamhaus.org/<|192.168.2.3|192.168.5.6|...
30923 .endd
30924 Thus, this example checks whether or not the IP addresses of the sender
30925 domain's mail servers are on the Spamhaus black list.
30926
30927 The key that was used for a successful DNS list lookup is put into the variable
30928 &$dnslist_matched$& (see section &<<SECID204>>&).
30929
30930
30931
30932
30933 .section "Data returned by DNS lists" "SECID203"
30934 .cindex "DNS list" "data returned from"
30935 DNS lists are constructed using address records in the DNS. The original RBL
30936 just used the address 127.0.0.1 on the right hand side of each record, but the
30937 RBL+ list and some other lists use a number of values with different meanings.
30938 The values used on the RBL+ list are:
30939 .display
30940 127.1.0.1  RBL
30941 127.1.0.2  DUL
30942 127.1.0.3  DUL and RBL
30943 127.1.0.4  RSS
30944 127.1.0.5  RSS and RBL
30945 127.1.0.6  RSS and DUL
30946 127.1.0.7  RSS and DUL and RBL
30947 .endd
30948 Section &<<SECTaddmatcon>>& below describes how you can distinguish between
30949 different values. Some DNS lists may return more than one address record;
30950 see section &<<SECThanmuldnsrec>>& for details of how they are checked.
30951
30952
30953 .section "Variables set from DNS lists" "SECID204"
30954 .cindex "expansion" "variables, set from DNS list"
30955 .cindex "DNS list" "variables set from"
30956 .vindex "&$dnslist_domain$&"
30957 .vindex "&$dnslist_matched$&"
30958 .vindex "&$dnslist_text$&"
30959 .vindex "&$dnslist_value$&"
30960 When an entry is found in a DNS list, the variable &$dnslist_domain$& contains
30961 the name of the overall domain that matched (for example,
30962 &`spamhaus.example`&), &$dnslist_matched$& contains the key within that domain
30963 (for example, &`192.168.5.3`&), and &$dnslist_value$& contains the data from
30964 the DNS record. When the key is an IP address, it is not reversed in
30965 &$dnslist_matched$& (though it is, of course, in the actual lookup). In simple
30966 cases, for example:
30967 .code
30968 deny dnslists = spamhaus.example
30969 .endd
30970 the key is also available in another variable (in this case,
30971 &$sender_host_address$&). In more complicated cases, however, this is not true.
30972 For example, using a data lookup (as described in section &<<SECTmulkeyfor>>&)
30973 might generate a dnslists lookup like this:
30974 .code
30975 deny dnslists = spamhaus.example/<|192.168.1.2|192.168.6.7|...
30976 .endd
30977 If this condition succeeds, the value in &$dnslist_matched$& might be
30978 &`192.168.6.7`& (for example).
30979
30980 If more than one address record is returned by the DNS lookup, all the IP
30981 addresses are included in &$dnslist_value$&, separated by commas and spaces.
30982 The variable &$dnslist_text$& contains the contents of any associated TXT
30983 record. For lists such as RBL+ the TXT record for a merged entry is often not
30984 very meaningful. See section &<<SECTmordetinf>>& for a way of obtaining more
30985 information.
30986
30987 You can use the DNS list variables in &%message%& or &%log_message%& modifiers
30988 &-- although these appear before the condition in the ACL, they are not
30989 expanded until after it has failed. For example:
30990 .code
30991 deny    hosts = !+local_networks
30992         message = $sender_host_address is listed \
30993                   at $dnslist_domain
30994         dnslists = rbl-plus.mail-abuse.example
30995 .endd
30996
30997
30998
30999 .section "Additional matching conditions for DNS lists" "SECTaddmatcon"
31000 .cindex "DNS list" "matching specific returned data"
31001 You can add an equals sign and an IP address after a &%dnslists%& domain name
31002 in order to restrict its action to DNS records with a matching right hand side.
31003 For example,
31004 .code
31005 deny dnslists = rblplus.mail-abuse.org=127.0.0.2
31006 .endd
31007 rejects only those hosts that yield 127.0.0.2. Without this additional data,
31008 any address record is considered to be a match. For the moment, we assume
31009 that the DNS lookup returns just one record. Section &<<SECThanmuldnsrec>>&
31010 describes how multiple records are handled.
31011
31012 More than one IP address may be given for checking, using a comma as a
31013 separator. These are alternatives &-- if any one of them matches, the
31014 &%dnslists%& condition is true. For example:
31015 .code
31016 deny  dnslists = a.b.c=127.0.0.2,127.0.0.3
31017 .endd
31018 If you want to specify a constraining address list and also specify names or IP
31019 addresses to be looked up, the constraining address list must be specified
31020 first. For example:
31021 .code
31022 deny dnslists = dsn.rfc-ignorant.org\
31023                 =127.0.0.2/$sender_address_domain
31024 .endd
31025
31026 If the character &`&&`& is used instead of &`=`&, the comparison for each
31027 listed IP address is done by a bitwise &"and"& instead of by an equality test.
31028 In other words, the listed addresses are used as bit masks. The comparison is
31029 true if all the bits in the mask are present in the address that is being
31030 tested. For example:
31031 .code
31032 dnslists = a.b.c&0.0.0.3
31033 .endd
31034 matches if the address is &'x.x.x.'&3, &'x.x.x.'&7, &'x.x.x.'&11, etc. If you
31035 want to test whether one bit or another bit is present (as opposed to both
31036 being present), you must use multiple values. For example:
31037 .code
31038 dnslists = a.b.c&0.0.0.1,0.0.0.2
31039 .endd
31040 matches if the final component of the address is an odd number or two times
31041 an odd number.
31042
31043
31044
31045 .section "Negated DNS matching conditions" "SECID205"
31046 You can supply a negative list of IP addresses as part of a &%dnslists%&
31047 condition. Whereas
31048 .code
31049 deny  dnslists = a.b.c=127.0.0.2,127.0.0.3
31050 .endd
31051 means &"deny if the host is in the black list at the domain &'a.b.c'& and the
31052 IP address yielded by the list is either 127.0.0.2 or 127.0.0.3"&,
31053 .code
31054 deny  dnslists = a.b.c!=127.0.0.2,127.0.0.3
31055 .endd
31056 means &"deny if the host is in the black list at the domain &'a.b.c'& and the
31057 IP address yielded by the list is not 127.0.0.2 and not 127.0.0.3"&. In other
31058 words, the result of the test is inverted if an exclamation mark appears before
31059 the &`=`& (or the &`&&`&) sign.
31060
31061 &*Note*&: This kind of negation is not the same as negation in a domain,
31062 host, or address list (which is why the syntax is different).
31063
31064 If you are using just one list, the negation syntax does not gain you much. The
31065 previous example is precisely equivalent to
31066 .code
31067 deny  dnslists = a.b.c
31068      !dnslists = a.b.c=127.0.0.2,127.0.0.3
31069 .endd
31070 However, if you are using multiple lists, the negation syntax is clearer.
31071 Consider this example:
31072 .code
31073 deny  dnslists = sbl.spamhaus.org : \
31074                  list.dsbl.org : \
31075                  dnsbl.njabl.org!=127.0.0.3 : \
31076                  relays.ordb.org
31077 .endd
31078 Using only positive lists, this would have to be:
31079 .code
31080 deny  dnslists = sbl.spamhaus.org : \
31081                  list.dsbl.org
31082 deny  dnslists = dnsbl.njabl.org
31083      !dnslists = dnsbl.njabl.org=127.0.0.3
31084 deny  dnslists = relays.ordb.org
31085 .endd
31086 which is less clear, and harder to maintain.
31087
31088
31089
31090
31091 .section "Handling multiple DNS records from a DNS list" "SECThanmuldnsrec"
31092 A DNS lookup for a &%dnslists%& condition may return more than one DNS record,
31093 thereby providing more than one IP address. When an item in a &%dnslists%& list
31094 is followed by &`=`& or &`&&`& and a list of IP addresses, in order to restrict
31095 the match to specific results from the DNS lookup, there are two ways in which
31096 the checking can be handled. For example, consider the condition:
31097 .code
31098 dnslists = a.b.c=127.0.0.1
31099 .endd
31100 What happens if the DNS lookup for the incoming IP address yields both
31101 127.0.0.1 and 127.0.0.2 by means of two separate DNS records? Is the
31102 condition true because at least one given value was found, or is it false
31103 because at least one of the found values was not listed? And how does this
31104 affect negated conditions? Both possibilities are provided for with the help of
31105 additional separators &`==`& and &`=&&`&.
31106
31107 .ilist
31108 If &`=`& or &`&&`& is used, the condition is true if any one of the looked up
31109 IP addresses matches one of the listed addresses. For the example above, the
31110 condition is true because 127.0.0.1 matches.
31111 .next
31112 If &`==`& or &`=&&`& is used, the condition is true only if every one of the
31113 looked up IP addresses matches one of the listed addresses. If the condition is
31114 changed to:
31115 .code
31116 dnslists = a.b.c==127.0.0.1
31117 .endd
31118 and the DNS lookup yields both 127.0.0.1 and 127.0.0.2, the condition is
31119 false because 127.0.0.2 is not listed. You would need to have:
31120 .code
31121 dnslists = a.b.c==127.0.0.1,127.0.0.2
31122 .endd
31123 for the condition to be true.
31124 .endlist
31125
31126 When &`!`& is used to negate IP address matching, it inverts the result, giving
31127 the precise opposite of the behaviour above. Thus:
31128 .ilist
31129 If &`!=`& or &`!&&`& is used, the condition is true if none of the looked up IP
31130 addresses matches one of the listed addresses. Consider:
31131 .code
31132 dnslists = a.b.c!&0.0.0.1
31133 .endd
31134 If the DNS lookup yields both 127.0.0.1 and 127.0.0.2, the condition is
31135 false because 127.0.0.1 matches.
31136 .next
31137 If &`!==`& or &`!=&&`& is used, the condition is true if there is at least one
31138 looked up IP address that does not match. Consider:
31139 .code
31140 dnslists = a.b.c!=&0.0.0.1
31141 .endd
31142 If the DNS lookup yields both 127.0.0.1 and 127.0.0.2, the condition is
31143 true, because 127.0.0.2 does not match. You would need to have:
31144 .code
31145 dnslists = a.b.c!=&0.0.0.1,0.0.0.2
31146 .endd
31147 for the condition to be false.
31148 .endlist
31149 When the DNS lookup yields only a single IP address, there is no difference
31150 between &`=`& and &`==`& and between &`&&`& and &`=&&`&.
31151
31152
31153
31154
31155 .section "Detailed information from merged DNS lists" "SECTmordetinf"
31156 .cindex "DNS list" "information from merged"
31157 When the facility for restricting the matching IP values in a DNS list is used,
31158 the text from the TXT record that is set in &$dnslist_text$& may not reflect
31159 the true reason for rejection. This happens when lists are merged and the IP
31160 address in the A record is used to distinguish them; unfortunately there is
31161 only one TXT record. One way round this is not to use merged lists, but that
31162 can be inefficient because it requires multiple DNS lookups where one would do
31163 in the vast majority of cases when the host of interest is not on any of the
31164 lists.
31165
31166 A less inefficient way of solving this problem is available. If
31167 two domain names, comma-separated, are given, the second is used first to
31168 do an initial check, making use of any IP value restrictions that are set.
31169 If there is a match, the first domain is used, without any IP value
31170 restrictions, to get the TXT record. As a byproduct of this, there is also
31171 a check that the IP being tested is indeed on the first list. The first
31172 domain is the one that is put in &$dnslist_domain$&. For example:
31173 .code
31174 deny message  = \
31175          rejected because $sender_host_address is blacklisted \
31176          at $dnslist_domain\n$dnslist_text
31177        dnslists = \
31178          sbl.spamhaus.org,sbl-xbl.spamhaus.org=127.0.0.2 : \
31179          dul.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.10
31180 .endd
31181 For the first blacklist item, this starts by doing a lookup in
31182 &'sbl-xbl.spamhaus.org'& and testing for a 127.0.0.2 return. If there is a
31183 match, it then looks in &'sbl.spamhaus.org'&, without checking the return
31184 value, and as long as something is found, it looks for the corresponding TXT
31185 record. If there is no match in &'sbl-xbl.spamhaus.org'&, nothing more is done.
31186 The second blacklist item is processed similarly.
31187
31188 If you are interested in more than one merged list, the same list must be
31189 given several times, but because the results of the DNS lookups are cached,
31190 the DNS calls themselves are not repeated. For example:
31191 .code
31192 deny dnslists = \
31193          http.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.2 : \
31194          socks.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.3 : \
31195          misc.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.4 : \
31196          dul.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.10
31197 .endd
31198 In this case there is one lookup in &'dnsbl.sorbs.net'&, and if none of the IP
31199 values matches (or if no record is found), this is the only lookup that is
31200 done. Only if there is a match is one of the more specific lists consulted.
31201
31202
31203
31204 .section "DNS lists and IPv6" "SECTmorednslistslast"
31205 .cindex "IPv6" "DNS black lists"
31206 .cindex "DNS list" "IPv6 usage"
31207 If Exim is asked to do a dnslist lookup for an IPv6 address, it inverts it
31208 nibble by nibble. For example, if the calling host's IP address is
31209 3ffe:ffff:836f:0a00:000a:0800:200a:c031, Exim might look up
31210 .code
31211 1.3.0.c.a.0.0.2.0.0.8.0.a.0.0.0.0.0.a.0.f.6.3.8.
31212   f.f.f.f.e.f.f.3.blackholes.mail-abuse.org
31213 .endd
31214 (split over two lines here to fit on the page). Unfortunately, some of the DNS
31215 lists contain wildcard records, intended for IPv4, that interact badly with
31216 IPv6. For example, the DNS entry
31217 .code
31218 *.3.some.list.example.    A    127.0.0.1
31219 .endd
31220 is probably intended to put the entire 3.0.0.0/8 IPv4 network on the list.
31221 Unfortunately, it also matches the entire 3::/4 IPv6 network.
31222
31223 You can exclude IPv6 addresses from DNS lookups by making use of a suitable
31224 &%condition%& condition, as in this example:
31225 .code
31226 deny   condition = ${if isip4{$sender_host_address}}
31227        dnslists  = some.list.example
31228 .endd
31229
31230 If an explicit key is being used for a DNS lookup and it may be an IPv6
31231 address you should specify alternate list separators for both the outer
31232 (DNS list name) list and inner (lookup keys) list:
31233 .code
31234        dnslists = <; dnsbl.example.com/<|$acl_m_addrslist
31235 .endd
31236
31237 .section "Rate limiting incoming messages" "SECTratelimiting"
31238 .cindex "rate limiting" "client sending"
31239 .cindex "limiting client sending rates"
31240 .oindex "&%smtp_ratelimit_*%&"
31241 The &%ratelimit%& ACL condition can be used to measure and control the rate at
31242 which clients can send email. This is more powerful than the
31243 &%smtp_ratelimit_*%& options, because those options control the rate of
31244 commands in a single SMTP session only, whereas the &%ratelimit%& condition
31245 works across all connections (concurrent and sequential) from the same client
31246 host. The syntax of the &%ratelimit%& condition is:
31247 .display
31248 &`ratelimit =`& <&'m'&> &`/`& <&'p'&> &`/`& <&'options'&> &`/`& <&'key'&>
31249 .endd
31250 If the average client sending rate is less than &'m'& messages per time
31251 period &'p'& then the condition is false; otherwise it is true.
31252
31253 As a side-effect, the &%ratelimit%& condition sets the expansion variable
31254 &$sender_rate$& to the client's computed rate, &$sender_rate_limit$& to the
31255 configured value of &'m'&, and &$sender_rate_period$& to the configured value
31256 of &'p'&.
31257
31258 The parameter &'p'& is the smoothing time constant, in the form of an Exim
31259 time interval, for example, &`8h`& for eight hours. A larger time constant
31260 means that it takes Exim longer to forget a client's past behaviour. The
31261 parameter &'m'& is the maximum number of messages that a client is permitted to
31262 send in each time interval. It also specifies the number of messages permitted
31263 in a fast burst. By increasing both &'m'& and &'p'& but keeping &'m/p'&
31264 constant, you can allow a client to send more messages in a burst without
31265 changing its long-term sending rate limit. Conversely, if &'m'& and &'p'& are
31266 both small, messages must be sent at an even rate.
31267
31268 There is a script in &_util/ratelimit.pl_& which extracts sending rates from
31269 log files, to assist with choosing appropriate settings for &'m'& and &'p'&
31270 when deploying the &%ratelimit%& ACL condition. The script prints usage
31271 instructions when it is run with no arguments.
31272
31273 The key is used to look up the data for calculating the client's average
31274 sending rate. This data is stored in Exim's spool directory, alongside the
31275 retry and other hints databases. The default key is &$sender_host_address$&,
31276 which means Exim computes the sending rate of each client host IP address.
31277 By changing the key you can change how Exim identifies clients for the purpose
31278 of ratelimiting. For example, to limit the sending rate of each authenticated
31279 user, independent of the computer they are sending from, set the key to
31280 &$authenticated_id$&. You must ensure that the lookup key is meaningful; for
31281 example, &$authenticated_id$& is only meaningful if the client has
31282 authenticated (which you can check with the &%authenticated%& ACL condition).
31283
31284 The lookup key does not have to identify clients: If you want to limit the
31285 rate at which a recipient receives messages, you can use the key
31286 &`$local_part@$domain`& with the &%per_rcpt%& option (see below) in a RCPT
31287 ACL.
31288
31289 Each &%ratelimit%& condition can have up to four options. A &%per_*%& option
31290 specifies what Exim measures the rate of, for example messages or recipients
31291 or bytes. You can adjust the measurement using the &%unique=%& and/or
31292 &%count=%& options. You can also control when Exim updates the recorded rate
31293 using a &%strict%&, &%leaky%&, or &%readonly%& option. The options are
31294 separated by a slash, like the other parameters. They may appear in any order.
31295
31296 Internally, Exim appends the smoothing constant &'p'& onto the lookup key with
31297 any options that alter the meaning of the stored data. The limit &'m'& is not
31298 stored, so you can alter the configured maximum rate and Exim will still
31299 remember clients' past behaviour. If you change the &%per_*%& mode or add or
31300 remove the &%unique=%& option, the lookup key changes so Exim will forget past
31301 behaviour. The lookup key is not affected by changes to the update mode and
31302 the &%count=%& option.
31303
31304
31305 .section "Ratelimit options for what is being measured" "ratoptmea"
31306 .cindex "rate limiting" "per_* options"
31307 The &%per_conn%& option limits the client's connection rate. It is not
31308 normally used in the &%acl_not_smtp%&, &%acl_not_smtp_mime%&, or
31309 &%acl_not_smtp_start%& ACLs.
31310
31311 The &%per_mail%& option limits the client's rate of sending messages. This is
31312 the default if none of the &%per_*%& options is specified. It can be used in
31313 &%acl_smtp_mail%&, &%acl_smtp_rcpt%&, &%acl_smtp_predata%&, &%acl_smtp_mime%&,
31314 &%acl_smtp_data%&, or &%acl_not_smtp%&.
31315
31316 The &%per_byte%& option limits the sender's email bandwidth. It can be used in
31317 the same ACLs as the &%per_mail%& option, though it is best to use this option
31318 in the &%acl_smtp_mime%&, &%acl_smtp_data%& or &%acl_not_smtp%& ACLs; if it is
31319 used in an earlier ACL, Exim relies on the SIZE parameter given by the client
31320 in its MAIL command, which may be inaccurate or completely missing. You can
31321 follow the limit &'m'& in the configuration with K, M, or G to specify limits
31322 in kilobytes, megabytes, or gigabytes, respectively.
31323
31324 The &%per_rcpt%& option causes Exim to limit the rate at which recipients are
31325 accepted. It can be used in the &%acl_smtp_rcpt%&, &%acl_smtp_predata%&,
31326 &%acl_smtp_mime%&, &%acl_smtp_data%&, or &%acl_smtp_rcpt%& ACLs. In
31327 &%acl_smtp_rcpt%& the rate is updated one recipient at a time; in the other
31328 ACLs the rate is updated with the total (accepted) recipient count in one go. Note that
31329 in either case the rate limiting engine will see a message with many
31330 recipients as a large high-speed burst.
31331
31332 The &%per_addr%& option is like the &%per_rcpt%& option, except it counts the
31333 number of different recipients that the client has sent messages to in the
31334 last time period. That is, if the client repeatedly sends messages to the same
31335 recipient, its measured rate is not increased. This option can only be used in
31336 &%acl_smtp_rcpt%&.
31337
31338 The &%per_cmd%& option causes Exim to recompute the rate every time the
31339 condition is processed. This can be used to limit the rate of any SMTP
31340 command. If it is used in multiple ACLs it can limit the aggregate rate of
31341 multiple different commands.
31342
31343 The &%count=%& option can be used to alter how much Exim adds to the client's
31344 measured rate. For example, the &%per_byte%& option is equivalent to
31345 &`per_mail/count=$message_size`&. If there is no &%count=%& option, Exim
31346 increases the measured rate by one (except for the &%per_rcpt%& option in ACLs
31347 other than &%acl_smtp_rcpt%&). The count does not have to be an integer.
31348
31349 The &%unique=%& option is described in section &<<ratoptuniq>>& below.
31350
31351
31352 .section "Ratelimit update modes" "ratoptupd"
31353 .cindex "rate limiting" "reading data without updating"
31354 You can specify one of three options with the &%ratelimit%& condition to
31355 control when its database is updated. This section describes the &%readonly%&
31356 mode, and the next section describes the &%strict%& and &%leaky%& modes.
31357
31358 If the &%ratelimit%& condition is used in &%readonly%& mode, Exim looks up a
31359 previously-computed rate to check against the limit.
31360
31361 For example, you can test the client's sending rate and deny it access (when
31362 it is too fast) in the connect ACL. If the client passes this check then it
31363 can go on to send a message, in which case its recorded rate will be updated
31364 in the MAIL ACL. Subsequent connections from the same client will check this
31365 new rate.
31366 .code
31367 acl_check_connect:
31368  deny ratelimit = 100 / 5m / readonly
31369     log_message = RATE CHECK: $sender_rate/$sender_rate_period \
31370                   (max $sender_rate_limit)
31371 # ...
31372 acl_check_mail:
31373  warn ratelimit = 100 / 5m / strict
31374     log_message = RATE UPDATE: $sender_rate/$sender_rate_period \
31375                   (max $sender_rate_limit)
31376 .endd
31377
31378 If Exim encounters multiple &%ratelimit%& conditions with the same key when
31379 processing a message then it may increase the client's measured rate more than
31380 it should. For example, this will happen if you check the &%per_rcpt%& option
31381 in both &%acl_smtp_rcpt%& and &%acl_smtp_data%&. However it's OK to check the
31382 same &%ratelimit%& condition multiple times in the same ACL. You can avoid any
31383 multiple update problems by using the &%readonly%& option on later ratelimit
31384 checks.
31385
31386 The &%per_*%& options described above do not make sense in some ACLs. If you
31387 use a &%per_*%& option in an ACL where it is not normally permitted then the
31388 update mode defaults to &%readonly%& and you cannot specify the &%strict%& or
31389 &%leaky%& modes. In other ACLs the default update mode is &%leaky%& (see the
31390 next section) so you must specify the &%readonly%& option explicitly.
31391
31392
31393 .section "Ratelimit options for handling fast clients" "ratoptfast"
31394 .cindex "rate limiting" "strict and leaky modes"
31395 If a client's average rate is greater than the maximum, the rate limiting
31396 engine can react in two possible ways, depending on the presence of the
31397 &%strict%& or &%leaky%& update modes. This is independent of the other
31398 counter-measures (such as rejecting the message) that may be specified by the
31399 rest of the ACL.
31400
31401 The &%leaky%& (default) option means that the client's recorded rate is not
31402 updated if it is above the limit. The effect of this is that Exim measures the
31403 client's average rate of successfully sent email,
31404 .new
31405 up to the given limit.
31406 This is appropriate if the countermeasure when the condition is true
31407 consists of refusing the message, and
31408 is generally the better choice if you have clients that retry automatically.
31409 If the action when true is anything more complex then this option is
31410 likely not what is wanted.
31411 .wen
31412
31413 The &%strict%& option means that the client's recorded rate is always
31414 updated. The effect of this is that Exim measures the client's average rate
31415 of attempts to send email, which can be much higher than the maximum it is
31416 actually allowed. If the client is over the limit it may be subjected to
31417 counter-measures by the ACL. It must slow down and allow sufficient time to
31418 pass that its computed rate falls below the maximum before it can send email
31419 again. The time (the number of smoothing periods) it must wait and not
31420 attempt to send mail can be calculated with this formula:
31421 .code
31422         ln(peakrate/maxrate)
31423 .endd
31424
31425
31426 .section "Limiting the rate of different events" "ratoptuniq"
31427 .cindex "rate limiting" "counting unique events"
31428 The &%ratelimit%& &%unique=%& option controls a mechanism for counting the
31429 rate of different events. For example, the &%per_addr%& option uses this
31430 mechanism to count the number of different recipients that the client has
31431 sent messages to in the last time period; it is equivalent to
31432 &`per_rcpt/unique=$local_part@$domain`&. You could use this feature to
31433 measure the rate that a client uses different sender addresses with the
31434 options &`per_mail/unique=$sender_address`&.
31435
31436 For each &%ratelimit%& key Exim stores the set of &%unique=%& values that it
31437 has seen for that key. The whole set is thrown away when it is older than the
31438 rate smoothing period &'p'&, so each different event is counted at most once
31439 per period. In the &%leaky%& update mode, an event that causes the client to
31440 go over the limit is not added to the set, in the same way that the client's
31441 recorded rate is not updated in the same situation.
31442
31443 When you combine the &%unique=%& and &%readonly%& options, the specific
31444 &%unique=%& value is ignored, and Exim just retrieves the client's stored
31445 rate.
31446
31447 The &%unique=%& mechanism needs more space in the ratelimit database than the
31448 other &%ratelimit%& options in order to store the event set. The number of
31449 unique values is potentially as large as the rate limit, so the extra space
31450 required increases with larger limits.
31451
31452 The uniqueification is not perfect: there is a small probability that Exim
31453 will think a new event has happened before. If the sender's rate is less than
31454 the limit, Exim should be more than 99.9% correct. However in &%strict%& mode
31455 the measured rate can go above the limit, in which case Exim may under-count
31456 events by a significant margin. Fortunately, if the rate is high enough (2.7
31457 times the limit) that the false positive rate goes above 9%, then Exim will
31458 throw away the over-full event set before the measured rate falls below the
31459 limit. Therefore the only harm should be that exceptionally high sending rates
31460 are logged incorrectly; any countermeasures you configure will be as effective
31461 as intended.
31462
31463
31464 .section "Using rate limiting" "useratlim"
31465 Exim's other ACL facilities are used to define what counter-measures are taken
31466 when the rate limit is exceeded. This might be anything from logging a warning
31467 (for example, while measuring existing sending rates in order to define
31468 policy), through time delays to slow down fast senders, up to rejecting the
31469 message. For example:
31470 .code
31471 # Log all senders' rates
31472 warn ratelimit = 0 / 1h / strict
31473      log_message = Sender rate $sender_rate / $sender_rate_period
31474
31475 # Slow down fast senders; note the need to truncate $sender_rate
31476 # at the decimal point.
31477 warn ratelimit = 100 / 1h / per_rcpt / strict
31478      delay     = ${eval: ${sg{$sender_rate}{[.].*}{}} - \
31479                    $sender_rate_limit }s
31480
31481 # Keep authenticated users under control
31482 deny authenticated = *
31483      ratelimit = 100 / 1d / strict / $authenticated_id
31484
31485 # System-wide rate limit
31486 defer message = Sorry, too busy. Try again later.
31487      ratelimit = 10 / 1s / $primary_hostname
31488
31489 # Restrict incoming rate from each host, with a default
31490 # set using a macro and special cases looked up in a table.
31491 defer message = Sender rate exceeds $sender_rate_limit \
31492                messages per $sender_rate_period
31493      ratelimit = ${lookup {$sender_host_address} \
31494                    cdb {DB/ratelimits.cdb} \
31495                    {$value} {RATELIMIT} }
31496 .endd
31497 &*Warning*&: If you have a busy server with a lot of &%ratelimit%& tests,
31498 especially with the &%per_rcpt%& option, you may suffer from a performance
31499 bottleneck caused by locking on the ratelimit hints database. Apart from
31500 making your ACLs less complicated, you can reduce the problem by using a
31501 RAM disk for Exim's hints directory (usually &_/var/spool/exim/db/_&). However
31502 this means that Exim will lose its hints data after a reboot (including retry
31503 hints, the callout cache, and ratelimit data).
31504
31505
31506
31507 .section "Address verification" "SECTaddressverification"
31508 .cindex "verifying address" "options for"
31509 .cindex "policy control" "address verification"
31510 Several of the &%verify%& conditions described in section
31511 &<<SECTaclconditions>>& cause addresses to be verified. Section
31512 &<<SECTsenaddver>>& discusses the reporting of sender verification failures.
31513 The verification conditions can be followed by options that modify the
31514 verification process. The options are separated from the keyword and from each
31515 other by slashes, and some of them contain parameters. For example:
31516 .code
31517 verify = sender/callout
31518 verify = recipient/defer_ok/callout=10s,defer_ok
31519 .endd
31520 The first stage of address verification, which always happens, is to run the
31521 address through the routers, in &"verify mode"&. Routers can detect the
31522 difference between verification and routing for delivery, and their actions can
31523 be varied by a number of generic options such as &%verify%& and &%verify_only%&
31524 (see chapter &<<CHAProutergeneric>>&). If routing fails, verification fails.
31525 The available options are as follows:
31526
31527 .ilist
31528 If the &%callout%& option is specified, successful routing to one or more
31529 remote hosts is followed by a &"callout"& to those hosts as an additional
31530 check. Callouts and their sub-options are discussed in the next section.
31531 .next
31532 If there is a defer error while doing verification routing, the ACL
31533 normally returns &"defer"&. However, if you include &%defer_ok%& in the
31534 options, the condition is forced to be true instead. Note that this is a main
31535 verification option as well as a suboption for callouts.
31536 .next
31537 The &%no_details%& option is covered in section &<<SECTsenaddver>>&, which
31538 discusses the reporting of sender address verification failures.
31539 .next
31540 The &%success_on_redirect%& option causes verification always to succeed
31541 immediately after a successful redirection. By default, if a redirection
31542 generates just one address, that address is also verified. See further
31543 discussion in section &<<SECTredirwhilveri>>&.
31544 .endlist
31545
31546 .cindex "verifying address" "differentiating failures"
31547 .vindex "&$recipient_verify_failure$&"
31548 .vindex "&$sender_verify_failure$&"
31549 .vindex "&$acl_verify_message$&"
31550 After an address verification failure, &$acl_verify_message$& contains the
31551 error message that is associated with the failure. It can be preserved by
31552 coding like this:
31553 .code
31554 warn  !verify = sender
31555        set acl_m0 = $acl_verify_message
31556 .endd
31557 If you are writing your own custom rejection message or log message when
31558 denying access, you can use this variable to include information about the
31559 verification failure.
31560
31561 In addition, &$sender_verify_failure$& or &$recipient_verify_failure$& (as
31562 appropriate) contains one of the following words:
31563
31564 .ilist
31565 &%qualify%&: The address was unqualified (no domain), and the message
31566 was neither local nor came from an exempted host.
31567 .next
31568 &%route%&: Routing failed.
31569 .next
31570 &%mail%&: Routing succeeded, and a callout was attempted; rejection
31571 occurred at or before the MAIL command (that is, on initial
31572 connection, HELO, or MAIL).
31573 .next
31574 &%recipient%&: The RCPT command in a callout was rejected.
31575 .next
31576 &%postmaster%&: The postmaster check in a callout was rejected.
31577 .endlist
31578
31579 The main use of these variables is expected to be to distinguish between
31580 rejections of MAIL and rejections of RCPT in callouts.
31581
31582 .new
31583 The above variables may also be set after a &*successful*&
31584 address verification to:
31585
31586 .ilist
31587 &%random%&: A random local-part callout succeeded
31588 .endlist
31589 .wen
31590
31591
31592
31593
31594 .section "Callout verification" "SECTcallver"
31595 .cindex "verifying address" "by callout"
31596 .cindex "callout" "verification"
31597 .cindex "SMTP" "callout verification"
31598 For non-local addresses, routing verifies the domain, but is unable to do any
31599 checking of the local part. There are situations where some means of verifying
31600 the local part is desirable. One way this can be done is to make an SMTP
31601 &'callback'& to a delivery host for the sender address or a &'callforward'& to
31602 a subsequent host for a recipient address, to see if the host accepts the
31603 address. We use the term &'callout'& to cover both cases. Note that for a
31604 sender address, the callback is not to the client host that is trying to
31605 deliver the message, but to one of the hosts that accepts incoming mail for the
31606 sender's domain.
31607
31608 Exim does not do callouts by default. If you want them to happen, you must
31609 request them by setting appropriate options on the &%verify%& condition, as
31610 described below. This facility should be used with care, because it can add a
31611 lot of resource usage to the cost of verifying an address. However, Exim does
31612 cache the results of callouts, which helps to reduce the cost. Details of
31613 caching are in section &<<SECTcallvercache>>&.
31614
31615 Recipient callouts are usually used only between hosts that are controlled by
31616 the same administration. For example, a corporate gateway host could use
31617 callouts to check for valid recipients on an internal mailserver. A successful
31618 callout does not guarantee that a real delivery to the address would succeed;
31619 on the other hand, a failing callout does guarantee that a delivery would fail.
31620
31621 If the &%callout%& option is present on a condition that verifies an address, a
31622 second stage of verification occurs if the address is successfully routed to
31623 one or more remote hosts. The usual case is routing by a &(dnslookup)& or a
31624 &(manualroute)& router, where the router specifies the hosts. However, if a
31625 router that does not set up hosts routes to an &(smtp)& transport with a
31626 &%hosts%& setting, the transport's hosts are used. If an &(smtp)& transport has
31627 &%hosts_override%& set, its hosts are always used, whether or not the router
31628 supplies a host list.
31629 Callouts are only supported on &(smtp)& transports.
31630
31631 The port that is used is taken from the transport, if it is specified and is a
31632 remote transport. (For routers that do verification only, no transport need be
31633 specified.) Otherwise, the default SMTP port is used. If a remote transport
31634 specifies an outgoing interface, this is used; otherwise the interface is not
31635 specified. Likewise, the text that is used for the HELO command is taken from
31636 the transport's &%helo_data%& option; if there is no transport, the value of
31637 &$smtp_active_hostname$& is used.
31638
31639 For a sender callout check, Exim makes SMTP connections to the remote hosts, to
31640 test whether a bounce message could be delivered to the sender address. The
31641 following SMTP commands are sent:
31642 .display
31643 &`HELO `&<&'local host name'&>
31644 &`MAIL FROM:<>`&
31645 &`RCPT TO:`&<&'the address to be tested'&>
31646 &`QUIT`&
31647 .endd
31648 LHLO is used instead of HELO if the transport's &%protocol%& option is
31649 set to &"lmtp"&.
31650
31651 The callout may use EHLO, AUTH and/or STARTTLS given appropriate option
31652 settings.
31653
31654 A recipient callout check is similar. By default, it also uses an empty address
31655 for the sender. This default is chosen because most hosts do not make use of
31656 the sender address when verifying a recipient. Using the same address means
31657 that a single cache entry can be used for each recipient. Some sites, however,
31658 do make use of the sender address when verifying. These are catered for by the
31659 &%use_sender%& and &%use_postmaster%& options, described in the next section.
31660
31661 If the response to the RCPT command is a 2&'xx'& code, the verification
31662 succeeds. If it is 5&'xx'&, the verification fails. For any other condition,
31663 Exim tries the next host, if any. If there is a problem with all the remote
31664 hosts, the ACL yields &"defer"&, unless the &%defer_ok%& parameter of the
31665 &%callout%& option is given, in which case the condition is forced to succeed.
31666
31667 .cindex "SMTP" "output flushing, disabling for callout"
31668 A callout may take a little time. For this reason, Exim normally flushes SMTP
31669 output before performing a callout in an ACL, to avoid unexpected timeouts in
31670 clients when the SMTP PIPELINING extension is in use. The flushing can be
31671 disabled by using a &%control%& modifier to set &%no_callout_flush%&.
31672
31673
31674
31675
31676 .section "Additional parameters for callouts" "CALLaddparcall"
31677 .cindex "callout" "additional parameters for"
31678 The &%callout%& option can be followed by an equals sign and a number of
31679 optional parameters, separated by commas. For example:
31680 .code
31681 verify = recipient/callout=10s,defer_ok
31682 .endd
31683 The old syntax, which had &%callout_defer_ok%& and &%check_postmaster%& as
31684 separate verify options, is retained for backwards compatibility, but is now
31685 deprecated. The additional parameters for &%callout%& are as follows:
31686
31687
31688 .vlist
31689 .vitem <&'a&~time&~interval'&>
31690 .cindex "callout" "timeout, specifying"
31691 This specifies the timeout that applies for the callout attempt to each host.
31692 For example:
31693 .code
31694 verify = sender/callout=5s
31695 .endd
31696 The default is 30 seconds. The timeout is used for each response from the
31697 remote host. It is also used for the initial connection, unless overridden by
31698 the &%connect%& parameter.
31699
31700
31701 .vitem &*connect&~=&~*&<&'time&~interval'&>
31702 .cindex "callout" "connection timeout, specifying"
31703 This parameter makes it possible to set a different (usually smaller) timeout
31704 for making the SMTP connection. For example:
31705 .code
31706 verify = sender/callout=5s,connect=1s
31707 .endd
31708 If not specified, this timeout defaults to the general timeout value.
31709
31710 .vitem &*defer_ok*&
31711 .cindex "callout" "defer, action on"
31712 When this parameter is present, failure to contact any host, or any other kind
31713 of temporary error, is treated as success by the ACL. However, the cache is not
31714 updated in this circumstance.
31715
31716 .vitem &*fullpostmaster*&
31717 .cindex "callout" "full postmaster check"
31718 This operates like the &%postmaster%& option (see below), but if the check for
31719 &'postmaster@domain'& fails, it tries just &'postmaster'&, without a domain, in
31720 accordance with the specification in RFC 2821. The RFC states that the
31721 unqualified address &'postmaster'& should be accepted.
31722
31723
31724 .vitem &*mailfrom&~=&~*&<&'email&~address'&>
31725 .cindex "callout" "sender when verifying header"
31726 When verifying addresses in header lines using the &%header_sender%&
31727 verification option, Exim behaves by default as if the addresses are envelope
31728 sender addresses from a message. Callout verification therefore tests to see
31729 whether a bounce message could be delivered, by using an empty address in the
31730 MAIL command. However, it is arguable that these addresses might never be used
31731 as envelope senders, and could therefore justifiably reject bounce messages
31732 (empty senders). The &%mailfrom%& callout parameter allows you to specify what
31733 address to use in the MAIL command. For example:
31734 .code
31735 require  verify = header_sender/callout=mailfrom=abcd@x.y.z
31736 .endd
31737 This parameter is available only for the &%header_sender%& verification option.
31738
31739
31740 .vitem &*maxwait&~=&~*&<&'time&~interval'&>
31741 .cindex "callout" "overall timeout, specifying"
31742 This parameter sets an overall timeout for performing a callout verification.
31743 For example:
31744 .code
31745 verify = sender/callout=5s,maxwait=30s
31746 .endd
31747 This timeout defaults to four times the callout timeout for individual SMTP
31748 commands. The overall timeout applies when there is more than one host that can
31749 be tried. The timeout is checked before trying the next host. This prevents
31750 very long delays if there are a large number of hosts and all are timing out
31751 (for example, when network connections are timing out).
31752
31753
31754 .vitem &*no_cache*&
31755 .cindex "callout" "cache, suppressing"
31756 .cindex "caching callout, suppressing"
31757 When this parameter is given, the callout cache is neither read nor updated.
31758
31759 .vitem &*postmaster*&
31760 .cindex "callout" "postmaster; checking"
31761 When this parameter is set, a successful callout check is followed by a similar
31762 check for the local part &'postmaster'& at the same domain. If this address is
31763 rejected, the callout fails (but see &%fullpostmaster%& above). The result of
31764 the postmaster check is recorded in a cache record; if it is a failure, this is
31765 used to fail subsequent callouts for the domain without a connection being
31766 made, until the cache record expires.
31767
31768 .vitem &*postmaster_mailfrom&~=&~*&<&'email&~address'&>
31769 The postmaster check uses an empty sender in the MAIL command by default.
31770 You can use this parameter to do a postmaster check using a different address.
31771 For example:
31772 .code
31773 require  verify = sender/callout=postmaster_mailfrom=abc@x.y.z
31774 .endd
31775 If both &%postmaster%& and &%postmaster_mailfrom%& are present, the rightmost
31776 one overrides. The &%postmaster%& parameter is equivalent to this example:
31777 .code
31778 require  verify = sender/callout=postmaster_mailfrom=
31779 .endd
31780 &*Warning*&: The caching arrangements for postmaster checking do not take
31781 account of the sender address. It is assumed that either the empty address or
31782 a fixed non-empty address will be used. All that Exim remembers is that the
31783 postmaster check for the domain succeeded or failed.
31784
31785
31786 .vitem &*random*&
31787 .cindex "callout" "&""random""& check"
31788 When this parameter is set, before doing the normal callout check, Exim does a
31789 check for a &"random"& local part at the same domain. The local part is not
31790 really random &-- it is defined by the expansion of the option
31791 &%callout_random_local_part%&, which defaults to
31792 .code
31793 $primary_hostname-$tod_epoch-testing
31794 .endd
31795 The idea here is to try to determine whether the remote host accepts all local
31796 parts without checking. If it does, there is no point in doing callouts for
31797 specific local parts. If the &"random"& check succeeds, the result is saved in
31798 a cache record, and used to force the current and subsequent callout checks to
31799 succeed without a connection being made, until the cache record expires.
31800
31801 .vitem &*use_postmaster*&
31802 .cindex "callout" "sender for recipient check"
31803 This parameter applies to recipient callouts only. For example:
31804 .code
31805 deny  !verify = recipient/callout=use_postmaster
31806 .endd
31807 .vindex "&$qualify_domain$&"
31808 It causes a non-empty postmaster address to be used in the MAIL command when
31809 performing the callout for the recipient, and also for a &"random"& check if
31810 that is configured. The local part of the address is &`postmaster`& and the
31811 domain is the contents of &$qualify_domain$&.
31812
31813 .vitem &*use_sender*&
31814 This option applies to recipient callouts only. For example:
31815 .code
31816 require  verify = recipient/callout=use_sender
31817 .endd
31818 It causes the message's actual sender address to be used in the MAIL
31819 command when performing the callout, instead of an empty address. There is no
31820 need to use this option unless you know that the called hosts make use of the
31821 sender when checking recipients. If used indiscriminately, it reduces the
31822 usefulness of callout caching.
31823
31824 .vitem &*hold*&
31825 This option applies to recipient callouts only. For example:
31826 .code
31827 require  verify = recipient/callout=use_sender,hold
31828 .endd
31829 It causes the connection to be held open and used for any further recipients
31830 and for eventual delivery (should that be done quickly).
31831 Doing this saves on TCP and SMTP startup costs, and TLS costs also
31832 when that is used for the connections.
31833 The advantage is only gained if there are no callout cache hits
31834 (which could be enforced by the no_cache option),
31835 if the use_sender option is used,
31836 if neither the random nor the use_postmaster option is used,
31837 and if no other callouts intervene.
31838 .endlist
31839
31840 If you use any of the parameters that set a non-empty sender for the MAIL
31841 command (&%mailfrom%&, &%postmaster_mailfrom%&, &%use_postmaster%&, or
31842 &%use_sender%&), you should think about possible loops. Recipient checking is
31843 usually done between two hosts that are under the same management, and the host
31844 that receives the callouts is not normally configured to do callouts itself.
31845 Therefore, it is normally safe to use &%use_postmaster%& or &%use_sender%& in
31846 these circumstances.
31847
31848 However, if you use a non-empty sender address for a callout to an arbitrary
31849 host, there is the likelihood that the remote host will itself initiate a
31850 callout check back to your host. As it is checking what appears to be a message
31851 sender, it is likely to use an empty address in MAIL, thus avoiding a
31852 callout loop. However, to be on the safe side it would be best to set up your
31853 own ACLs so that they do not do sender verification checks when the recipient
31854 is the address you use for header sender or postmaster callout checking.
31855
31856 Another issue to think about when using non-empty senders for callouts is
31857 caching. When you set &%mailfrom%& or &%use_sender%&, the cache record is keyed
31858 by the sender/recipient combination; thus, for any given recipient, many more
31859 actual callouts are performed than when an empty sender or postmaster is used.
31860
31861
31862
31863
31864 .section "Callout caching" "SECTcallvercache"
31865 .cindex "hints database" "callout cache"
31866 .cindex "callout" "cache, description of"
31867 .cindex "caching" "callout"
31868 Exim caches the results of callouts in order to reduce the amount of resources
31869 used, unless you specify the &%no_cache%& parameter with the &%callout%&
31870 option. A hints database called &"callout"& is used for the cache. Two
31871 different record types are used: one records the result of a callout check for
31872 a specific address, and the other records information that applies to the
31873 entire domain (for example, that it accepts the local part &'postmaster'&).
31874
31875 When an original callout fails, a detailed SMTP error message is given about
31876 the failure. However, for subsequent failures use the cache data, this message
31877 is not available.
31878
31879 The expiry times for negative and positive address cache records are
31880 independent, and can be set by the global options &%callout_negative_expire%&
31881 (default 2h) and &%callout_positive_expire%& (default 24h), respectively.
31882
31883 If a host gives a negative response to an SMTP connection, or rejects any
31884 commands up to and including
31885 .code
31886 MAIL FROM:<>
31887 .endd
31888 (but not including the MAIL command with a non-empty address),
31889 any callout attempt is bound to fail. Exim remembers such failures in a
31890 domain cache record, which it uses to fail callouts for the domain without
31891 making new connections, until the domain record times out. There are two
31892 separate expiry times for domain cache records:
31893 &%callout_domain_negative_expire%& (default 3h) and
31894 &%callout_domain_positive_expire%& (default 7d).
31895
31896 Domain records expire when the negative expiry time is reached if callouts
31897 cannot be made for the domain, or if the postmaster check failed.
31898 Otherwise, they expire when the positive expiry time is reached. This
31899 ensures that, for example, a host that stops accepting &"random"& local parts
31900 will eventually be noticed.
31901
31902 The callout caching mechanism is based on the domain of the address that is
31903 being tested. If the domain routes to several hosts, it is assumed that their
31904 behaviour will be the same.
31905
31906
31907
31908 .section "Sender address verification reporting" "SECTsenaddver"
31909 .cindex "verifying" "suppressing error details"
31910 See section &<<SECTaddressverification>>& for a general discussion of
31911 verification. When sender verification fails in an ACL, the details of the
31912 failure are given as additional output lines before the 550 response to the
31913 relevant SMTP command (RCPT or DATA). For example, if sender callout is in use,
31914 you might see:
31915 .code
31916 MAIL FROM:<xyz@abc.example>
31917 250 OK
31918 RCPT TO:<pqr@def.example>
31919 550-Verification failed for <xyz@abc.example>
31920 550-Called:   192.168.34.43
31921 550-Sent:     RCPT TO:<xyz@abc.example>
31922 550-Response: 550 Unknown local part xyz in <xyz@abc.example>
31923 550 Sender verification failed
31924 .endd
31925 If more than one RCPT command fails in the same way, the details are given
31926 only for the first of them. However, some administrators do not want to send
31927 out this much information. You can suppress the details by adding
31928 &`/no_details`& to the ACL statement that requests sender verification. For
31929 example:
31930 .code
31931 verify = sender/no_details
31932 .endd
31933
31934 .section "Redirection while verifying" "SECTredirwhilveri"
31935 .cindex "verifying" "redirection while"
31936 .cindex "address redirection" "while verifying"
31937 A dilemma arises when a local address is redirected by aliasing or forwarding
31938 during verification: should the generated addresses themselves be verified,
31939 or should the successful expansion of the original address be enough to verify
31940 it? By default, Exim takes the following pragmatic approach:
31941
31942 .ilist
31943 When an incoming address is redirected to just one child address, verification
31944 continues with the child address, and if that fails to verify, the original
31945 verification also fails.
31946 .next
31947 When an incoming address is redirected to more than one child address,
31948 verification does not continue. A success result is returned.
31949 .endlist
31950
31951 This seems the most reasonable behaviour for the common use of aliasing as a
31952 way of redirecting different local parts to the same mailbox. It means, for
31953 example, that a pair of alias entries of the form
31954 .code
31955 A.Wol:   aw123
31956 aw123:   :fail: Gone away, no forwarding address
31957 .endd
31958 work as expected, with both local parts causing verification failure. When a
31959 redirection generates more than one address, the behaviour is more like a
31960 mailing list, where the existence of the alias itself is sufficient for
31961 verification to succeed.
31962
31963 It is possible, however, to change the default behaviour so that all successful
31964 redirections count as successful verifications, however many new addresses are
31965 generated. This is specified by the &%success_on_redirect%& verification
31966 option. For example:
31967 .code
31968 require verify = recipient/success_on_redirect/callout=10s
31969 .endd
31970 In this example, verification succeeds if a router generates a new address, and
31971 the callout does not occur, because no address was routed to a remote host.
31972
31973 When verification is being tested via the &%-bv%& option, the treatment of
31974 redirections is as just described, unless the &%-v%& or any debugging option is
31975 also specified. In that case, full verification is done for every generated
31976 address and a report is output for each of them.
31977
31978
31979
31980 .section "Client SMTP authorization (CSA)" "SECTverifyCSA"
31981 .cindex "CSA" "verifying"
31982 Client SMTP Authorization is a system that allows a site to advertise
31983 which machines are and are not permitted to send email. This is done by placing
31984 special SRV records in the DNS; these are looked up using the client's HELO
31985 domain. At the time of writing, CSA is still an Internet Draft. Client SMTP
31986 Authorization checks in Exim are performed by the ACL condition:
31987 .code
31988 verify = csa
31989 .endd
31990 This fails if the client is not authorized. If there is a DNS problem, or if no
31991 valid CSA SRV record is found, or if the client is authorized, the condition
31992 succeeds. These three cases can be distinguished using the expansion variable
31993 &$csa_status$&, which can take one of the values &"fail"&, &"defer"&,
31994 &"unknown"&, or &"ok"&. The condition does not itself defer because that would
31995 be likely to cause problems for legitimate email.
31996
31997 The error messages produced by the CSA code include slightly more
31998 detail. If &$csa_status$& is &"defer"&, this may be because of problems
31999 looking up the CSA SRV record, or problems looking up the CSA target
32000 address record. There are four reasons for &$csa_status$& being &"fail"&:
32001
32002 .ilist
32003 The client's host name is explicitly not authorized.
32004 .next
32005 The client's IP address does not match any of the CSA target IP addresses.
32006 .next
32007 The client's host name is authorized but it has no valid target IP addresses
32008 (for example, the target's addresses are IPv6 and the client is using IPv4).
32009 .next
32010 The client's host name has no CSA SRV record but a parent domain has asserted
32011 that all subdomains must be explicitly authorized.
32012 .endlist
32013
32014 The &%csa%& verification condition can take an argument which is the domain to
32015 use for the DNS query. The default is:
32016 .code
32017 verify = csa/$sender_helo_name
32018 .endd
32019 This implementation includes an extension to CSA. If the query domain
32020 is an address literal such as [192.0.2.95], or if it is a bare IP
32021 address, Exim searches for CSA SRV records in the reverse DNS as if
32022 the HELO domain was (for example) &'95.2.0.192.in-addr.arpa'&. Therefore it is
32023 meaningful to say:
32024 .code
32025 verify = csa/$sender_host_address
32026 .endd
32027 In fact, this is the check that Exim performs if the client does not say HELO.
32028 This extension can be turned off by setting the main configuration option
32029 &%dns_csa_use_reverse%& to be false.
32030
32031 If a CSA SRV record is not found for the domain itself, a search
32032 is performed through its parent domains for a record which might be
32033 making assertions about subdomains. The maximum depth of this search is limited
32034 using the main configuration option &%dns_csa_search_limit%&, which is 5 by
32035 default. Exim does not look for CSA SRV records in a top level domain, so the
32036 default settings handle HELO domains as long as seven
32037 (&'hostname.five.four.three.two.one.com'&). This encompasses the vast majority
32038 of legitimate HELO domains.
32039
32040 The &'dnsdb'& lookup also has support for CSA. Although &'dnsdb'& also supports
32041 direct SRV lookups, this is not sufficient because of the extra parent domain
32042 search behaviour of CSA, and (as with PTR lookups) &'dnsdb'& also turns IP
32043 addresses into lookups in the reverse DNS space. The result of a successful
32044 lookup such as:
32045 .code
32046 ${lookup dnsdb {csa=$sender_helo_name}}
32047 .endd
32048 has two space-separated fields: an authorization code and a target host name.
32049 The authorization code can be &"Y"& for yes, &"N"& for no, &"X"& for explicit
32050 authorization required but absent, or &"?"& for unknown.
32051
32052
32053
32054
32055 .section "Bounce address tag validation" "SECTverifyPRVS"
32056 .cindex "BATV, verifying"
32057 Bounce address tag validation (BATV) is a scheme whereby the envelope senders
32058 of outgoing messages have a cryptographic, timestamped &"tag"& added to them.
32059 Genuine incoming bounce messages should therefore always be addressed to
32060 recipients that have a valid tag. This scheme is a way of detecting unwanted
32061 bounce messages caused by sender address forgeries (often called &"collateral
32062 spam"&), because the recipients of such messages do not include valid tags.
32063
32064 There are two expansion items to help with the implementation of the BATV
32065 &"prvs"& (private signature) scheme in an Exim configuration. This scheme signs
32066 the original envelope sender address by using a simple key to add a hash of the
32067 address and some time-based randomizing information. The &%prvs%& expansion
32068 item creates a signed address, and the &%prvscheck%& expansion item checks one.
32069 The syntax of these expansion items is described in section
32070 &<<SECTexpansionitems>>&.
32071 The validity period on signed addresses is seven days.
32072
32073 As an example, suppose the secret per-address keys are stored in an MySQL
32074 database. A query to look up the key for an address could be defined as a macro
32075 like this:
32076 .code
32077 PRVSCHECK_SQL = ${lookup mysql{SELECT secret FROM batv_prvs \
32078                 WHERE sender='${quote_mysql:$prvscheck_address}'\
32079                 }{$value}}
32080 .endd
32081 Suppose also that the senders who make use of BATV are defined by an address
32082 list called &%batv_senders%&. Then, in the ACL for RCPT commands, you could
32083 use this:
32084 .code
32085 # Bounces: drop unsigned addresses for BATV senders
32086 deny message = This address does not send an unsigned reverse path
32087      senders = :
32088      recipients = +batv_senders
32089
32090 # Bounces: In case of prvs-signed address, check signature.
32091 deny message = Invalid reverse path signature.
32092      senders = :
32093      condition  = ${prvscheck {$local_part@$domain}\
32094                   {PRVSCHECK_SQL}{1}}
32095      !condition = $prvscheck_result
32096 .endd
32097 The first statement rejects recipients for bounce messages that are addressed
32098 to plain BATV sender addresses, because it is known that BATV senders do not
32099 send out messages with plain sender addresses. The second statement rejects
32100 recipients that are prvs-signed, but with invalid signatures (either because
32101 the key is wrong, or the signature has timed out).
32102
32103 A non-prvs-signed address is not rejected by the second statement, because the
32104 &%prvscheck%& expansion yields an empty string if its first argument is not a
32105 prvs-signed address, thus causing the &%condition%& condition to be false. If
32106 the first argument is a syntactically valid prvs-signed address, the yield is
32107 the third string (in this case &"1"&), whether or not the cryptographic and
32108 timeout checks succeed. The &$prvscheck_result$& variable contains the result
32109 of the checks (empty for failure, &"1"& for success).
32110
32111 There is one more issue you must consider when implementing prvs-signing:
32112 you have to ensure that the routers accept prvs-signed addresses and
32113 deliver them correctly. The easiest way to handle this is to use a &(redirect)&
32114 router to remove the signature with a configuration along these lines:
32115 .code
32116 batv_redirect:
32117   driver = redirect
32118   data = ${prvscheck {$local_part@$domain}{PRVSCHECK_SQL}}
32119 .endd
32120 This works because, if the third argument of &%prvscheck%& is empty, the result
32121 of the expansion of a prvs-signed address is the decoded value of the original
32122 address. This router should probably be the first of your routers that handles
32123 local addresses.
32124
32125 To create BATV-signed addresses in the first place, a transport of this form
32126 can be used:
32127 .code
32128 external_smtp_batv:
32129   driver = smtp
32130   return_path = ${prvs {$return_path} \
32131                        {${lookup mysql{SELECT \
32132                        secret FROM batv_prvs WHERE \
32133                        sender='${quote_mysql:$sender_address}'} \
32134                        {$value}fail}}}
32135 .endd
32136 If no key can be found for the existing return path, no signing takes place.
32137
32138
32139
32140 .section "Using an ACL to control relaying" "SECTrelaycontrol"
32141 .cindex "&ACL;" "relay control"
32142 .cindex "relaying" "control by ACL"
32143 .cindex "policy control" "relay control"
32144 An MTA is said to &'relay'& a message if it receives it from some host and
32145 delivers it directly to another host as a result of a remote address contained
32146 within it. Redirecting a local address via an alias or forward file and then
32147 passing the message on to another host is not relaying,
32148 .cindex "&""percent hack""&"
32149 but a redirection as a result of the &"percent hack"& is.
32150
32151 Two kinds of relaying exist, which are termed &"incoming"& and &"outgoing"&.
32152 A host which is acting as a gateway or an MX backup is concerned with incoming
32153 relaying from arbitrary hosts to a specific set of domains. On the other hand,
32154 a host which is acting as a smart host for a number of clients is concerned
32155 with outgoing relaying from those clients to the Internet at large. Often the
32156 same host is fulfilling both functions,
32157 . ///
32158 . as illustrated in the diagram below,
32159 . ///
32160 but in principle these two kinds of relaying are entirely independent. What is
32161 not wanted is the transmission of mail from arbitrary remote hosts through your
32162 system to arbitrary domains.
32163
32164
32165 You can implement relay control by means of suitable statements in the ACL that
32166 runs for each RCPT command. For convenience, it is often easiest to use
32167 Exim's named list facility to define the domains and hosts involved. For
32168 example, suppose you want to do the following:
32169
32170 .ilist
32171 Deliver a number of domains to mailboxes on the local host (or process them
32172 locally in some other way). Let's say these are &'my.dom1.example'& and
32173 &'my.dom2.example'&.
32174 .next
32175 Relay mail for a number of other domains for which you are the secondary MX.
32176 These might be &'friend1.example'& and &'friend2.example'&.
32177 .next
32178 Relay mail from the hosts on your local LAN, to whatever domains are involved.
32179 Suppose your LAN is 192.168.45.0/24.
32180 .endlist
32181
32182
32183 In the main part of the configuration, you put the following definitions:
32184 .code
32185 domainlist local_domains    = my.dom1.example : my.dom2.example
32186 domainlist relay_to_domains = friend1.example : friend2.example
32187 hostlist   relay_from_hosts = 192.168.45.0/24
32188 .endd
32189 Now you can use these definitions in the ACL that is run for every RCPT
32190 command:
32191 .code
32192 acl_check_rcpt:
32193   accept domains = +local_domains : +relay_to_domains
32194   accept hosts   = +relay_from_hosts
32195 .endd
32196 The first statement accepts any RCPT command that contains an address in
32197 the local or relay domains. For any other domain, control passes to the second
32198 statement, which accepts the command only if it comes from one of the relay
32199 hosts. In practice, you will probably want to make your ACL more sophisticated
32200 than this, for example, by including sender and recipient verification. The
32201 default configuration includes a more comprehensive example, which is described
32202 in chapter &<<CHAPdefconfil>>&.
32203
32204
32205
32206 .section "Checking a relay configuration" "SECTcheralcon"
32207 .cindex "relaying" "checking control of"
32208 You can check the relay characteristics of your configuration in the same way
32209 that you can test any ACL behaviour for an incoming SMTP connection, by using
32210 the &%-bh%& option to run a fake SMTP session with which you interact.
32211 .ecindex IIDacl
32212
32213
32214
32215 . ////////////////////////////////////////////////////////////////////////////
32216 . ////////////////////////////////////////////////////////////////////////////
32217
32218 .chapter "Content scanning at ACL time" "CHAPexiscan"
32219 .scindex IIDcosca "content scanning" "at ACL time"
32220 The extension of Exim to include content scanning at ACL time, formerly known
32221 as &"exiscan"&, was originally implemented as a patch by Tom Kistner. The code
32222 was integrated into the main source for Exim release 4.50, and Tom continues to
32223 maintain it. Most of the wording of this chapter is taken from Tom's
32224 specification.
32225
32226 It is also possible to scan the content of messages at other times. The
32227 &[local_scan()]& function (see chapter &<<CHAPlocalscan>>&) allows for content
32228 scanning after all the ACLs have run. A transport filter can be used to scan
32229 messages at delivery time (see the &%transport_filter%& option, described in
32230 chapter &<<CHAPtransportgeneric>>&).
32231
32232 If you want to include the ACL-time content-scanning features when you compile
32233 Exim, you need to arrange for WITH_CONTENT_SCAN to be defined in your
32234 &_Local/Makefile_&. When you do that, the Exim binary is built with:
32235
32236 .ilist
32237 Two additional ACLs (&%acl_smtp_mime%& and &%acl_not_smtp_mime%&) that are run
32238 for all MIME parts for SMTP and non-SMTP messages, respectively.
32239 .next
32240 Additional ACL conditions and modifiers: &%decode%&, &%malware%&,
32241 &%mime_regex%&, &%regex%&, and &%spam%&. These can be used in the ACL that is
32242 run at the end of message reception (the &%acl_smtp_data%& ACL).
32243 .next
32244 An additional control feature (&"no_mbox_unspool"&) that saves spooled copies
32245 of messages, or parts of messages, for debugging purposes.
32246 .next
32247 Additional expansion variables that are set in the new ACL and by the new
32248 conditions.
32249 .next
32250 Two new main configuration options: &%av_scanner%& and &%spamd_address%&.
32251 .endlist
32252
32253 Content-scanning is continually evolving, and new features are still being
32254 added. While such features are still unstable and liable to incompatible
32255 changes, they are made available in Exim by setting options whose names begin
32256 EXPERIMENTAL_ in &_Local/Makefile_&. Such features are not documented in
32257 this manual. You can find out about them by reading the file called
32258 &_doc/experimental.txt_&.
32259
32260 All the content-scanning facilities work on a MBOX copy of the message that is
32261 temporarily created in a file called:
32262 .display
32263 <&'spool_directory'&>&`/scan/`&<&'message_id'&>/<&'message_id'&>&`.eml`&
32264 .endd
32265 The &_.eml_& extension is a friendly hint to virus scanners that they can
32266 expect an MBOX-like structure inside that file. The file is created when the
32267 first content scanning facility is called. Subsequent calls to content
32268 scanning conditions open the same file again. The directory is recursively
32269 removed when the &%acl_smtp_data%& ACL has finished running, unless
32270 .code
32271 control = no_mbox_unspool
32272 .endd
32273 has been encountered. When the MIME ACL decodes files, they are put into the
32274 same directory by default.
32275
32276
32277
32278 .section "Scanning for viruses" "SECTscanvirus"
32279 .cindex "virus scanning"
32280 .cindex "content scanning" "for viruses"
32281 .cindex "content scanning" "the &%malware%& condition"
32282 The &%malware%& ACL condition lets you connect virus scanner software to Exim.
32283 It supports a &"generic"& interface to scanners called via the shell, and
32284 specialized interfaces for &"daemon"& type virus scanners, which are resident
32285 in memory and thus are much faster.
32286
32287 A timeout of 2 minutes is applied to a scanner call (by default);
32288 if it expires then a defer action is taken.
32289
32290 .oindex "&%av_scanner%&"
32291 You can set the &%av_scanner%& option in the main part of the configuration
32292 to specify which scanner to use, together with any additional options that
32293 are needed. The basic syntax is as follows:
32294 .display
32295 &`av_scanner = <`&&'scanner-type'&&`>:<`&&'option1'&&`>:<`&&'option2'&&`>:[...]`&
32296 .endd
32297 If you do not set &%av_scanner%&, it defaults to
32298 .code
32299 av_scanner = sophie:/var/run/sophie
32300 .endd
32301 If the value of &%av_scanner%& starts with a dollar character, it is expanded
32302 before use.
32303 The usual list-parsing of the content (see &<<SECTlistconstruct>>&) applies.
32304 The following scanner types are supported in this release,
32305 though individual ones can be included or not at build time:
32306
32307 .vlist
32308 .vitem &%avast%&
32309 .cindex "virus scanners" "avast"
32310 This is the scanner daemon of Avast. It has been tested with Avast Core
32311 Security (currently at version 2.2.0).
32312 You can get a trial version at &url(https://www.avast.com) or for Linux
32313 at &url(https://www.avast.com/linux-server-antivirus).
32314 This scanner type takes one option,
32315 which can be either a full path to a UNIX socket,
32316 or host and port specifiers separated by white space.
32317 The host may be a name or an IP address; the port is either a
32318 single number or a pair of numbers with a dash between.
32319 A list of options may follow. These options are interpreted on the
32320 Exim's side of the malware scanner, or are given on separate lines to
32321 the daemon as options before the main scan command.
32322
32323 .cindex &`pass_unscanned`& "avast"
32324 If &`pass_unscanned`&
32325 is set, any files the Avast scanner can't scan (e.g.
32326 decompression bombs, or invalid archives) are considered clean. Use with
32327 care.
32328
32329 For example:
32330 .code
32331 av_scanner = avast:/var/run/avast/scan.sock:FLAGS -fullfiles:SENSITIVITY -pup
32332 av_scanner = avast:/var/run/avast/scan.sock:pass_unscanned:FLAGS -fullfiles:SENSITIVITY -pup
32333 av_scanner = avast:192.168.2.22 5036
32334 .endd
32335 If you omit the argument, the default path
32336 &_/var/run/avast/scan.sock_&
32337 is used.
32338 If you use a remote host,
32339 you need to make Exim's spool directory available to it,
32340 as the scanner is passed a file path, not file contents.
32341 For information about available commands and their options you may use
32342 .code
32343 $ socat UNIX:/var/run/avast/scan.sock STDIO:
32344     FLAGS
32345     SENSITIVITY
32346     PACK
32347 .endd
32348
32349 If the scanner returns a temporary failure (e.g. license issues, or
32350 permission problems), the message is deferred and a paniclog entry is
32351 written.  The usual &`defer_ok`& option is available.
32352
32353 .vitem &%aveserver%&
32354 .cindex "virus scanners" "Kaspersky"
32355 This is the scanner daemon of Kaspersky Version 5. You can get a trial version
32356 at &url(https://www.kaspersky.com/). This scanner type takes one option,
32357 which is the path to the daemon's UNIX socket. The default is shown in this
32358 example:
32359 .code
32360 av_scanner = aveserver:/var/run/aveserver
32361 .endd
32362
32363
32364 .vitem &%clamd%&
32365 .cindex "virus scanners" "clamd"
32366 This daemon-type scanner is GPL and free. You can get it at
32367 &url(https://www.clamav.net/). Some older versions of clamd do not seem to
32368 unpack MIME containers, so it used to be recommended to unpack MIME attachments
32369 in the MIME ACL. This is no longer believed to be necessary.
32370
32371 The options are a list of server specifiers, which may be
32372 a UNIX socket specification,
32373 a TCP socket specification,
32374 or a (global) option.
32375
32376 A socket specification consists of a space-separated list.
32377 For a Unix socket the first element is a full path for the socket,
32378 for a TCP socket the first element is the IP address
32379 and the second a port number,
32380 Any further elements are per-server (non-global) options.
32381 These per-server options are supported:
32382 .code
32383 retry=<timespec>        Retry on connect fail
32384 .endd
32385
32386 The &`retry`& option specifies a time after which a single retry for
32387 a failed connect is made.  The default is to not retry.
32388
32389 If a Unix socket file is specified, only one server is supported.
32390
32391 Examples:
32392 .code
32393 av_scanner = clamd:/opt/clamd/socket
32394 av_scanner = clamd:192.0.2.3 1234
32395 av_scanner = clamd:192.0.2.3 1234:local
32396 av_scanner = clamd:192.0.2.3 1234 retry=10s
32397 av_scanner = clamd:192.0.2.3 1234 : 192.0.2.4 1234
32398 .endd
32399 If the value of av_scanner points to a UNIX socket file or contains the
32400 &`local`&
32401 option, then the ClamAV interface will pass a filename containing the data
32402 to be scanned, which should normally result in less I/O happening and be
32403 more efficient.  Normally in the TCP case, the data is streamed to ClamAV as
32404 Exim does not assume that there is a common filesystem with the remote host.
32405
32406 The final example shows that multiple TCP targets can be specified.  Exim will
32407 randomly use one for each incoming email (i.e. it load balances them).  Note
32408 that only TCP targets may be used if specifying a list of scanners; a UNIX
32409 socket cannot be mixed in with TCP targets.  If one of the servers becomes
32410 unavailable, Exim will try the remaining one(s) until it finds one that works.
32411 When a clamd server becomes unreachable, Exim will log a message.  Exim does
32412 not keep track of scanner state between multiple messages, and the scanner
32413 selection is random, so the message will get logged in the mainlog for each
32414 email that the down scanner gets chosen first (message wrapped to be readable):
32415 .code
32416 2013-10-09 14:30:39 1VTumd-0000Y8-BQ malware acl condition:
32417    clamd: connection to localhost, port 3310 failed
32418    (Connection refused)
32419 .endd
32420
32421 If the option is unset, the default is &_/tmp/clamd_&. Thanks to David Saez for
32422 contributing the code for this scanner.
32423
32424 .vitem &%cmdline%&
32425 .cindex "virus scanners" "command line interface"
32426 This is the keyword for the generic command line scanner interface. It can be
32427 used to attach virus scanners that are invoked from the shell. This scanner
32428 type takes 3 mandatory options:
32429
32430 .olist
32431 The full path and name of the scanner binary, with all command line options,
32432 and a placeholder (&`%s`&) for the directory to scan.
32433
32434 .next
32435 A regular expression to match against the STDOUT and STDERR output of the
32436 virus scanner. If the expression matches, a virus was found. You must make
32437 absolutely sure that this expression matches on &"virus found"&. This is called
32438 the &"trigger"& expression.
32439
32440 .next
32441 Another regular expression, containing exactly one pair of parentheses, to
32442 match the name of the virus found in the scanners output. This is called the
32443 &"name"& expression.
32444 .endlist olist
32445
32446 For example, Sophos Sweep reports a virus on a line like this:
32447 .code
32448 Virus 'W32/Magistr-B' found in file ./those.bat
32449 .endd
32450 For the trigger expression, we can match the phrase &"found in file"&. For the
32451 name expression, we want to extract the W32/Magistr-B string, so we can match
32452 for the single quotes left and right of it. Altogether, this makes the
32453 configuration setting:
32454 .code
32455 av_scanner = cmdline:\
32456              /path/to/sweep -ss -all -rec -archive %s:\
32457              found in file:'(.+)'
32458 .endd
32459 .vitem &%drweb%&
32460 .cindex "virus scanners" "DrWeb"
32461 The DrWeb daemon scanner (&url(https://www.sald.ru/)) interface
32462 takes one option,
32463 either a full path to a UNIX socket,
32464 or host and port specifiers separated by white space.
32465 The host may be a name or an IP address; the port is either a
32466 single number or a pair of numbers with a dash between.
32467 For example:
32468 .code
32469 av_scanner = drweb:/var/run/drwebd.sock
32470 av_scanner = drweb:192.168.2.20 31337
32471 .endd
32472 If you omit the argument, the default path &_/usr/local/drweb/run/drwebd.sock_&
32473 is used. Thanks to Alex Miller for contributing the code for this scanner.
32474
32475 .vitem &%f-protd%&
32476 .cindex "virus scanners" "f-protd"
32477 The f-protd scanner is accessed via HTTP over TCP.
32478 One argument is taken, being a space-separated hostname and port number
32479 (or port-range).
32480 For example:
32481 .code
32482 av_scanner = f-protd:localhost 10200-10204
32483 .endd
32484 If you omit the argument, the default values shown above are used.
32485
32486 .vitem &%f-prot6d%&
32487 .cindex "virus scanners" "f-prot6d"
32488 The f-prot6d scanner is accessed using the FPSCAND protocol over TCP.
32489 One argument is taken, being a space-separated hostname and port number.
32490 For example:
32491 .code
32492 av_scanner = f-prot6d:localhost 10200
32493 .endd
32494 If you omit the argument, the default values show above are used.
32495
32496 .vitem &%fsecure%&
32497 .cindex "virus scanners" "F-Secure"
32498 The F-Secure daemon scanner (&url(https://www.f-secure.com/)) takes one
32499 argument which is the path to a UNIX socket. For example:
32500 .code
32501 av_scanner = fsecure:/path/to/.fsav
32502 .endd
32503 If no argument is given, the default is &_/var/run/.fsav_&. Thanks to Johan
32504 Thelmen for contributing the code for this scanner.
32505
32506 .vitem &%kavdaemon%&
32507 .cindex "virus scanners" "Kaspersky"
32508 This is the scanner daemon of Kaspersky Version 4. This version of the
32509 Kaspersky scanner is outdated. Please upgrade (see &%aveserver%& above). This
32510 scanner type takes one option, which is the path to the daemon's UNIX socket.
32511 For example:
32512 .code
32513 av_scanner = kavdaemon:/opt/AVP/AvpCtl
32514 .endd
32515 The default path is &_/var/run/AvpCtl_&.
32516
32517 .vitem &%mksd%&
32518 .cindex "virus scanners" "mksd"
32519 This was a daemon type scanner that is aimed mainly at Polish users,
32520 though some documentation was available in English.
32521 The history can be shown at &url(https://en.wikipedia.org/wiki/Mks_vir)
32522 and this appears to be a candidate for removal from Exim, unless
32523 we are informed of other virus scanners which use the same protocol
32524 to integrate.
32525 The only option for this scanner type is
32526 the maximum number of processes used simultaneously to scan the attachments,
32527 provided that mksd has
32528 been run with at least the same number of child processes. For example:
32529 .code
32530 av_scanner = mksd:2
32531 .endd
32532 You can safely omit this option (the default value is 1).
32533
32534 .vitem &%sock%&
32535 .cindex "virus scanners" "simple socket-connected"
32536 This is a general-purpose way of talking to simple scanner daemons
32537 running on the local machine.
32538 There are four options:
32539 an address (which may be an IP address and port, or the path of a Unix socket),
32540 a commandline to send (may include a single %s which will be replaced with
32541 the path to the mail file to be scanned),
32542 an RE to trigger on from the returned data,
32543 and an RE to extract malware_name from the returned data.
32544 For example:
32545 .code
32546 av_scanner = sock:127.0.0.1 6001:%s:(SPAM|VIRUS):(.*)$
32547 .endd
32548 Note that surrounding whitespace is stripped from each option, meaning
32549 there is no way to specify a trailing newline.
32550 The socket specifier and both regular-expressions are required.
32551 Default for the commandline is &_%s\n_& (note this does have a trailing newline);
32552 specify an empty element to get this.
32553
32554 .vitem &%sophie%&
32555 .cindex "virus scanners" "Sophos and Sophie"
32556 Sophie is a daemon that uses Sophos' &%libsavi%& library to scan for viruses.
32557 You can get Sophie at &url(http://sophie.sourceforge.net/). The only option
32558 for this scanner type is the path to the UNIX socket that Sophie uses for
32559 client communication. For example:
32560 .code
32561 av_scanner = sophie:/tmp/sophie
32562 .endd
32563 The default path is &_/var/run/sophie_&, so if you are using this, you can omit
32564 the option.
32565 .endlist
32566
32567 When &%av_scanner%& is correctly set, you can use the &%malware%& condition in
32568 the DATA ACL. &*Note*&: You cannot use the &%malware%& condition in the MIME
32569 ACL.
32570
32571 The &%av_scanner%& option is expanded each time &%malware%& is called. This
32572 makes it possible to use different scanners. See further below for an example.
32573 The &%malware%& condition caches its results, so when you use it multiple times
32574 for the same message, the actual scanning process is only carried out once.
32575 However, using expandable items in &%av_scanner%& disables this caching, in
32576 which case each use of the &%malware%& condition causes a new scan of the
32577 message.
32578
32579 The &%malware%& condition takes a right-hand argument that is expanded before
32580 use and taken as a list, slash-separated by default.
32581 The first element can then be one of
32582
32583 .ilist
32584 &"true"&, &"*"&, or &"1"&, in which case the message is scanned for viruses.
32585 The condition succeeds if a virus was found, and fail otherwise. This is the
32586 recommended usage.
32587 .next
32588 &"false"& or &"0"& or an empty string, in which case no scanning is done and
32589 the condition fails immediately.
32590 .next
32591 A regular expression, in which case the message is scanned for viruses. The
32592 condition succeeds if a virus is found and its name matches the regular
32593 expression. This allows you to take special actions on certain types of virus.
32594 Note that &"/"& characters in the RE must be doubled due to the list-processing,
32595 unless the separator is changed (in the usual way).
32596 .endlist
32597
32598 You can append a &`defer_ok`& element to the &%malware%& argument list to accept
32599 messages even if there is a problem with the virus scanner.
32600 Otherwise, such a problem causes the ACL to defer.
32601
32602 You can append a &`tmo=<val>`& element to the &%malware%& argument list to
32603 specify a non-default timeout.  The default is two minutes.
32604 For example:
32605 .code
32606 malware = * / defer_ok / tmo=10s
32607 .endd
32608 A timeout causes the ACL to defer.
32609
32610 .vindex "&$callout_address$&"
32611 When a connection is made to the scanner the expansion variable &$callout_address$&
32612 is set to record the actual address used.
32613
32614 .vindex "&$malware_name$&"
32615 When a virus is found, the condition sets up an expansion variable called
32616 &$malware_name$& that contains the name of the virus. You can use it in a
32617 &%message%& modifier that specifies the error returned to the sender, and/or in
32618 logging data.
32619
32620 Beware the interaction of Exim's &%message_size_limit%& with any size limits
32621 imposed by your anti-virus scanner.
32622
32623 Here is a very simple scanning example:
32624 .code
32625 deny message = This message contains malware ($malware_name)
32626      malware = *
32627 .endd
32628 The next example accepts messages when there is a problem with the scanner:
32629 .code
32630 deny message = This message contains malware ($malware_name)
32631      malware = */defer_ok
32632 .endd
32633 The next example shows how to use an ACL variable to scan with both sophie and
32634 aveserver. It assumes you have set:
32635 .code
32636 av_scanner = $acl_m0
32637 .endd
32638 in the main Exim configuration.
32639 .code
32640 deny message = This message contains malware ($malware_name)
32641      set acl_m0 = sophie
32642      malware = *
32643
32644 deny message = This message contains malware ($malware_name)
32645      set acl_m0 = aveserver
32646      malware = *
32647 .endd
32648
32649
32650 .section "Scanning with SpamAssassin and Rspamd" "SECTscanspamass"
32651 .cindex "content scanning" "for spam"
32652 .cindex "spam scanning"
32653 .cindex "SpamAssassin"
32654 .cindex "Rspamd"
32655 The &%spam%& ACL condition calls SpamAssassin's &%spamd%& daemon to get a spam
32656 score and a report for the message.
32657 Support is also provided for Rspamd.
32658
32659 For more information about installation and configuration of SpamAssassin or
32660 Rspamd refer to their respective websites at
32661 &url(https://spamassassin.apache.org/) and &url(https://www.rspamd.com/)
32662
32663 SpamAssassin can be installed with CPAN by running:
32664 .code
32665 perl -MCPAN -e 'install Mail::SpamAssassin'
32666 .endd
32667 SpamAssassin has its own set of configuration files. Please review its
32668 documentation to see how you can tweak it. The default installation should work
32669 nicely, however.
32670
32671 .oindex "&%spamd_address%&"
32672 By default, SpamAssassin listens on 127.0.0.1, TCP port 783 and if you
32673 intend to use an instance running on the local host you do not need to set
32674 &%spamd_address%&. If you intend to use another host or port for SpamAssassin,
32675 you must set the &%spamd_address%& option in the global part of the Exim
32676 configuration as follows (example):
32677 .code
32678 spamd_address = 192.168.99.45 387
32679 .endd
32680 The SpamAssassin protocol relies on a TCP half-close from the client.
32681 If your SpamAssassin client side is running a Linux system with an
32682 iptables firewall, consider setting
32683 &%net.netfilter.nf_conntrack_tcp_timeout_close_wait%& to at least the
32684 timeout, Exim uses when waiting for a response from the SpamAssassin
32685 server (currently defaulting to 120s).  With a lower value the Linux
32686 connection tracking may consider your half-closed connection as dead too
32687 soon.
32688
32689
32690 To use Rspamd (which by default listens on all local addresses
32691 on TCP port 11333)
32692 you should add &%variant=rspamd%& after the address/port pair, for example:
32693 .code
32694 spamd_address = 127.0.0.1 11333 variant=rspamd
32695 .endd
32696
32697 As of version 2.60, &%SpamAssassin%& also supports communication over UNIX
32698 sockets. If you want to us these, supply &%spamd_address%& with an absolute
32699 file name instead of an address/port pair:
32700 .code
32701 spamd_address = /var/run/spamd_socket
32702 .endd
32703 You can have multiple &%spamd%& servers to improve scalability. These can
32704 reside on other hardware reachable over the network. To specify multiple
32705 &%spamd%& servers, put multiple address/port pairs in the &%spamd_address%&
32706 option, separated with colons (the separator can be changed in the usual way):
32707 .code
32708 spamd_address = 192.168.2.10 783 : \
32709                 192.168.2.11 783 : \
32710                 192.168.2.12 783
32711 .endd
32712 Up to 32 &%spamd%& servers are supported.
32713 When a server fails to respond to the connection attempt, all other
32714 servers are tried until one succeeds. If no server responds, the &%spam%&
32715 condition defers.
32716
32717 Unix and TCP socket specifications may be mixed in any order.
32718 Each element of the list is a list itself, space-separated by default
32719 and changeable in the usual way; take care to not double the separator.
32720
32721 For TCP socket specifications a host name or IP (v4 or v6, but
32722 subject to list-separator quoting rules) address can be used,
32723 and the port can be one or a dash-separated pair.
32724 In the latter case, the range is tried in strict order.
32725
32726 Elements after the first for Unix sockets, or second for TCP socket,
32727 are options.
32728 The supported options are:
32729 .code
32730 pri=<priority>      Selection priority
32731 weight=<value>      Selection bias
32732 time=<start>-<end>  Use only between these times of day
32733 retry=<timespec>    Retry on connect fail
32734 tmo=<timespec>      Connection time limit
32735 variant=rspamd      Use Rspamd rather than SpamAssassin protocol
32736 .endd
32737
32738 The &`pri`& option specifies a priority for the server within the list,
32739 higher values being tried first.
32740 The default priority is 1.
32741
32742 The &`weight`& option specifies a selection bias.
32743 Within a priority set
32744 servers are queried in a random fashion, weighted by this value.
32745 The default value for selection bias is 1.
32746
32747 Time specifications for the &`time`& option are <hour>.<minute>.<second>
32748 in the local time zone; each element being one or more digits.
32749 Either the seconds or both minutes and seconds, plus the leading &`.`&
32750 characters, may be omitted and will be taken as zero.
32751
32752 Timeout specifications for the &`retry`& and &`tmo`& options
32753 are the usual Exim time interval standard, e.g. &`20s`& or &`1m`&.
32754
32755 The &`tmo`& option specifies an overall timeout for communication.
32756 The default value is two minutes.
32757
32758 The &`retry`& option specifies a time after which a single retry for
32759 a failed connect is made.
32760 The default is to not retry.
32761
32762 The &%spamd_address%& variable is expanded before use if it starts with
32763 a dollar sign. In this case, the expansion may return a string that is
32764 used as the list so that multiple spamd servers can be the result of an
32765 expansion.
32766
32767 .vindex "&$callout_address$&"
32768 When a connection is made to the server the expansion variable &$callout_address$&
32769 is set to record the actual address used.
32770
32771 .section "Calling SpamAssassin from an Exim ACL" "SECID206"
32772 Here is a simple example of the use of the &%spam%& condition in a DATA ACL:
32773 .code
32774 deny message = This message was classified as SPAM
32775      spam = joe
32776 .endd
32777 The right-hand side of the &%spam%& condition specifies a name. This is
32778 relevant if you have set up multiple SpamAssassin profiles. If you do not want
32779 to scan using a specific profile, but rather use the SpamAssassin system-wide
32780 default profile, you can scan for an unknown name, or simply use &"nobody"&.
32781 Rspamd does not use this setting. However, you must put something on the
32782 right-hand side.
32783
32784 The name allows you to use per-domain or per-user antispam profiles in
32785 principle, but this is not straightforward in practice, because a message may
32786 have multiple recipients, not necessarily all in the same domain. Because the
32787 &%spam%& condition has to be called from a DATA-time ACL in order to be able to
32788 read the contents of the message, the variables &$local_part$& and &$domain$&
32789 are not set.
32790 Careful enforcement of single-recipient messages
32791 (e.g. by responding with defer in the recipient ACL for all recipients
32792 after the first),
32793 or the use of PRDR,
32794 .cindex "PRDR" "use for per-user SpamAssassin profiles"
32795 are needed to use this feature.
32796
32797 The right-hand side of the &%spam%& condition is expanded before being used, so
32798 you can put lookups or conditions there. When the right-hand side evaluates to
32799 &"0"& or &"false"&, no scanning is done and the condition fails immediately.
32800
32801
32802 Scanning with SpamAssassin uses a lot of resources. If you scan every message,
32803 large ones may cause significant performance degradation. As most spam messages
32804 are quite small, it is recommended that you do not scan the big ones. For
32805 example:
32806 .code
32807 deny message = This message was classified as SPAM
32808      condition = ${if < {$message_size}{10K}}
32809      spam = nobody
32810 .endd
32811
32812 The &%spam%& condition returns true if the threshold specified in the user's
32813 SpamAssassin profile has been matched or exceeded. If you want to use the
32814 &%spam%& condition for its side effects (see the variables below), you can make
32815 it always return &"true"& by appending &`:true`& to the username.
32816
32817 .cindex "spam scanning" "returned variables"
32818 When the &%spam%& condition is run, it sets up a number of expansion
32819 variables.
32820 Except for &$spam_report$&,
32821 these variables are saved with the received message so are
32822 available for use at delivery time.
32823
32824 .vlist
32825 .vitem &$spam_score$&
32826 The spam score of the message, for example &"3.4"& or &"30.5"&. This is useful
32827 for inclusion in log or reject messages.
32828
32829 .vitem &$spam_score_int$&
32830 The spam score of the message, multiplied by ten, as an integer value. For
32831 example &"34"& or &"305"&. It may appear to disagree with &$spam_score$&
32832 because &$spam_score$& is rounded and &$spam_score_int$& is truncated.
32833 The integer value is useful for numeric comparisons in conditions.
32834
32835 .vitem &$spam_bar$&
32836 A string consisting of a number of &"+"& or &"-"& characters, representing the
32837 integer part of the spam score value. A spam score of 4.4 would have a
32838 &$spam_bar$& value of &"++++"&. This is useful for inclusion in warning
32839 headers, since MUAs can match on such strings. The maximum length of the
32840 spam bar is 50 characters.
32841
32842 .vitem &$spam_report$&
32843 A multiline text table, containing the full SpamAssassin report for the
32844 message. Useful for inclusion in headers or reject messages.
32845 This variable is only usable in a DATA-time ACL.
32846 Beware that SpamAssassin may return non-ASCII characters, especially
32847 when running in country-specific locales, which are not legal
32848 unencoded in headers.
32849
32850 .vitem &$spam_action$&
32851 For SpamAssassin either 'reject' or 'no action' depending on the
32852 spam score versus threshold.
32853 For Rspamd, the recommended action.
32854
32855 .endlist
32856
32857 The &%spam%& condition caches its results unless expansion in
32858 spamd_address was used. If you call it again with the same user name, it
32859 does not scan again, but rather returns the same values as before.
32860
32861 The &%spam%& condition returns DEFER if there is any error while running
32862 the message through SpamAssassin or if the expansion of spamd_address
32863 failed. If you want to treat DEFER as FAIL (to pass on to the next ACL
32864 statement block), append &`/defer_ok`& to the right-hand side of the
32865 spam condition, like this:
32866 .code
32867 deny message = This message was classified as SPAM
32868      spam    = joe/defer_ok
32869 .endd
32870 This causes messages to be accepted even if there is a problem with &%spamd%&.
32871
32872 Here is a longer, commented example of the use of the &%spam%&
32873 condition:
32874 .code
32875 # put headers in all messages (no matter if spam or not)
32876 warn  spam = nobody:true
32877       add_header = X-Spam-Score: $spam_score ($spam_bar)
32878       add_header = X-Spam-Report: $spam_report
32879
32880 # add second subject line with *SPAM* marker when message
32881 # is over threshold
32882 warn  spam = nobody
32883       add_header = Subject: *SPAM* $h_Subject:
32884
32885 # reject spam at high scores (> 12)
32886 deny  message = This message scored $spam_score spam points.
32887       spam = nobody:true
32888       condition = ${if >{$spam_score_int}{120}{1}{0}}
32889 .endd
32890
32891
32892
32893 .section "Scanning MIME parts" "SECTscanmimepart"
32894 .cindex "content scanning" "MIME parts"
32895 .cindex "MIME content scanning"
32896 .oindex "&%acl_smtp_mime%&"
32897 .oindex "&%acl_not_smtp_mime%&"
32898 The &%acl_smtp_mime%& global option specifies an ACL that is called once for
32899 each MIME part of an SMTP message, including multipart types, in the sequence
32900 of their position in the message. Similarly, the &%acl_not_smtp_mime%& option
32901 specifies an ACL that is used for the MIME parts of non-SMTP messages. These
32902 options may both refer to the same ACL if you want the same processing in both
32903 cases.
32904
32905 These ACLs are called (possibly many times) just before the &%acl_smtp_data%&
32906 ACL in the case of an SMTP message, or just before the &%acl_not_smtp%& ACL in
32907 the case of a non-SMTP message. However, a MIME ACL is called only if the
32908 message contains a &'Content-Type:'& header line. When a call to a MIME
32909 ACL does not yield &"accept"&, ACL processing is aborted and the appropriate
32910 result code is sent to the client. In the case of an SMTP message, the
32911 &%acl_smtp_data%& ACL is not called when this happens.
32912
32913 You cannot use the &%malware%& or &%spam%& conditions in a MIME ACL; these can
32914 only be used in the DATA or non-SMTP ACLs. However, you can use the &%regex%&
32915 condition to match against the raw MIME part. You can also use the
32916 &%mime_regex%& condition to match against the decoded MIME part (see section
32917 &<<SECTscanregex>>&).
32918
32919 At the start of a MIME ACL, a number of variables are set from the header
32920 information for the relevant MIME part. These are described below. The contents
32921 of the MIME part are not by default decoded into a disk file except for MIME
32922 parts whose content-type is &"message/rfc822"&. If you want to decode a MIME
32923 part into a disk file, you can use the &%decode%& condition. The general
32924 syntax is:
32925 .display
32926 &`decode = [/`&<&'path'&>&`/]`&<&'filename'&>
32927 .endd
32928 The right hand side is expanded before use. After expansion,
32929 the value can be:
32930
32931 .olist
32932 &"0"& or &"false"&, in which case no decoding is done.
32933 .next
32934 The string &"default"&. In that case, the file is put in the temporary
32935 &"default"& directory <&'spool_directory'&>&_/scan/_&<&'message_id'&>&_/_& with
32936 a sequential file name consisting of the message id and a sequence number. The
32937 full path and name is available in &$mime_decoded_filename$& after decoding.
32938 .next
32939 A full path name starting with a slash. If the full name is an existing
32940 directory, it is used as a replacement for the default directory. The filename
32941 is then sequentially assigned. If the path does not exist, it is used as
32942 the full path and file name.
32943 .next
32944 If the string does not start with a slash, it is used as the
32945 filename, and the default path is then used.
32946 .endlist
32947 The &%decode%& condition normally succeeds. It is only false for syntax
32948 errors or unusual circumstances such as memory shortages. You can easily decode
32949 a file with its original, proposed filename using
32950 .code
32951 decode = $mime_filename
32952 .endd
32953 However, you should keep in mind that &$mime_filename$& might contain
32954 anything. If you place files outside of the default path, they are not
32955 automatically unlinked.
32956
32957 For RFC822 attachments (these are messages attached to messages, with a
32958 content-type of &"message/rfc822"&), the ACL is called again in the same manner
32959 as for the primary message, only that the &$mime_is_rfc822$& expansion
32960 variable is set (see below). Attached messages are always decoded to disk
32961 before being checked, and the files are unlinked once the check is done.
32962
32963 The MIME ACL supports the &%regex%& and &%mime_regex%& conditions. These can be
32964 used to match regular expressions against raw and decoded MIME parts,
32965 respectively. They are described in section &<<SECTscanregex>>&.
32966
32967 .cindex "MIME content scanning" "returned variables"
32968 The following list describes all expansion variables that are
32969 available in the MIME ACL:
32970
32971 .vlist
32972 .vitem &$mime_boundary$&
32973 If the current part is a multipart (see &$mime_is_multipart$&) below, it should
32974 have a boundary string, which is stored in this variable. If the current part
32975 has no boundary parameter in the &'Content-Type:'& header, this variable
32976 contains the empty string.
32977
32978 .vitem &$mime_charset$&
32979 This variable contains the character set identifier, if one was found in the
32980 &'Content-Type:'& header. Examples for charset identifiers are:
32981 .code
32982 us-ascii
32983 gb2312 (Chinese)
32984 iso-8859-1
32985 .endd
32986 Please note that this value is not normalized, so you should do matches
32987 case-insensitively.
32988
32989 .vitem &$mime_content_description$&
32990 This variable contains the normalized content of the &'Content-Description:'&
32991 header. It can contain a human-readable description of the parts content. Some
32992 implementations repeat the filename for attachments here, but they are usually
32993 only used for display purposes.
32994
32995 .vitem &$mime_content_disposition$&
32996 This variable contains the normalized content of the &'Content-Disposition:'&
32997 header. You can expect strings like &"attachment"& or &"inline"& here.
32998
32999 .vitem &$mime_content_id$&
33000 This variable contains the normalized content of the &'Content-ID:'& header.
33001 This is a unique ID that can be used to reference a part from another part.
33002
33003 .vitem &$mime_content_size$&
33004 This variable is set only after the &%decode%& modifier (see above) has been
33005 successfully run. It contains the size of the decoded part in kilobytes. The
33006 size is always rounded up to full kilobytes, so only a completely empty part
33007 has a &$mime_content_size$& of zero.
33008
33009 .vitem &$mime_content_transfer_encoding$&
33010 This variable contains the normalized content of the
33011 &'Content-transfer-encoding:'& header. This is a symbolic name for an encoding
33012 type. Typical values are &"base64"& and &"quoted-printable"&.
33013
33014 .vitem &$mime_content_type$&
33015 If the MIME part has a &'Content-Type:'& header, this variable contains its
33016 value, lowercased, and without any options (like &"name"& or &"charset"&). Here
33017 are some examples of popular MIME types, as they may appear in this variable:
33018 .code
33019 text/plain
33020 text/html
33021 application/octet-stream
33022 image/jpeg
33023 audio/midi
33024 .endd
33025 If the MIME part has no &'Content-Type:'& header, this variable contains the
33026 empty string.
33027
33028 .vitem &$mime_decoded_filename$&
33029 This variable is set only after the &%decode%& modifier (see above) has been
33030 successfully run. It contains the full path and file name of the file
33031 containing the decoded data.
33032 .endlist
33033
33034 .cindex "RFC 2047"
33035 .vlist
33036 .vitem &$mime_filename$&
33037 This is perhaps the most important of the MIME variables. It contains a
33038 proposed filename for an attachment, if one was found in either the
33039 &'Content-Type:'& or &'Content-Disposition:'& headers. The filename will be
33040 RFC2047
33041 or RFC2231
33042 decoded, but no additional sanity checks are done.
33043  If no filename was
33044 found, this variable contains the empty string.
33045
33046 .vitem &$mime_is_coverletter$&
33047 This variable attempts to differentiate the &"cover letter"& of an e-mail from
33048 attached data. It can be used to clamp down on flashy or unnecessarily encoded
33049 content in the cover letter, while not restricting attachments at all.
33050
33051 The variable contains 1 (true) for a MIME part believed to be part of the
33052 cover letter, and 0 (false) for an attachment. At present, the algorithm is as
33053 follows:
33054
33055 .olist
33056 The outermost MIME part of a message is always a cover letter.
33057
33058 .next
33059 If a multipart/alternative or multipart/related MIME part is a cover letter,
33060 so are all MIME subparts within that multipart.
33061
33062 .next
33063 If any other multipart is a cover letter, the first subpart is a cover letter,
33064 and the rest are attachments.
33065
33066 .next
33067 All parts contained within an attachment multipart are attachments.
33068 .endlist olist
33069
33070 As an example, the following will ban &"HTML mail"& (including that sent with
33071 alternative plain text), while allowing HTML files to be attached. HTML
33072 coverletter mail attached to non-HTML coverletter mail will also be allowed:
33073 .code
33074 deny message = HTML mail is not accepted here
33075 !condition = $mime_is_rfc822
33076 condition = $mime_is_coverletter
33077 condition = ${if eq{$mime_content_type}{text/html}{1}{0}}
33078 .endd
33079 .vitem &$mime_is_multipart$&
33080 This variable has the value 1 (true) when the current part has the main type
33081 &"multipart"&, for example &"multipart/alternative"& or &"multipart/mixed"&.
33082 Since multipart entities only serve as containers for other parts, you may not
33083 want to carry out specific actions on them.
33084
33085 .vitem &$mime_is_rfc822$&
33086 This variable has the value 1 (true) if the current part is not a part of the
33087 checked message itself, but part of an attached message. Attached message
33088 decoding is fully recursive.
33089
33090 .vitem &$mime_part_count$&
33091 This variable is a counter that is raised for each processed MIME part. It
33092 starts at zero for the very first part (which is usually a multipart). The
33093 counter is per-message, so it is reset when processing RFC822 attachments (see
33094 &$mime_is_rfc822$&). The counter stays set after &%acl_smtp_mime%& is
33095 complete, so you can use it in the DATA ACL to determine the number of MIME
33096 parts of a message. For non-MIME messages, this variable contains the value -1.
33097 .endlist
33098
33099
33100
33101 .section "Scanning with regular expressions" "SECTscanregex"
33102 .cindex "content scanning" "with regular expressions"
33103 .cindex "regular expressions" "content scanning with"
33104 You can specify your own custom regular expression matches on the full body of
33105 the message, or on individual MIME parts.
33106
33107 The &%regex%& condition takes one or more regular expressions as arguments and
33108 matches them against the full message (when called in the DATA ACL) or a raw
33109 MIME part (when called in the MIME ACL). The &%regex%& condition matches
33110 linewise, with a maximum line length of 32K characters. That means you cannot
33111 have multiline matches with the &%regex%& condition.
33112
33113 The &%mime_regex%& condition can be called only in the MIME ACL. It matches up
33114 to 32K of decoded content (the whole content at once, not linewise). If the
33115 part has not been decoded with the &%decode%& modifier earlier in the ACL, it
33116 is decoded automatically when &%mime_regex%& is executed (using default path
33117 and filename values). If the decoded data is larger than  32K, only the first
33118 32K characters are checked.
33119
33120 The regular expressions are passed as a colon-separated list. To include a
33121 literal colon, you must double it. Since the whole right-hand side string is
33122 expanded before being used, you must also escape dollar signs and backslashes
33123 with more backslashes, or use the &`\N`& facility to disable expansion.
33124 Here is a simple example that contains two regular expressions:
33125 .code
33126 deny message = contains blacklisted regex ($regex_match_string)
33127      regex = [Mm]ortgage : URGENT BUSINESS PROPOSAL
33128 .endd
33129 The conditions returns true if any one of the regular expressions matches. The
33130 &$regex_match_string$& expansion variable is then set up and contains the
33131 matching regular expression.
33132 The expansion variables &$regex1$& &$regex2$& etc
33133 are set to any substrings captured by the regular expression.
33134
33135 &*Warning*&: With large messages, these conditions can be fairly
33136 CPU-intensive.
33137
33138 .ecindex IIDcosca
33139
33140
33141
33142
33143 . ////////////////////////////////////////////////////////////////////////////
33144 . ////////////////////////////////////////////////////////////////////////////
33145
33146 .chapter "Adding a local scan function to Exim" "CHAPlocalscan" &&&
33147          "Local scan function"
33148 .scindex IIDlosca "&[local_scan()]& function" "description of"
33149 .cindex "customizing" "input scan using C function"
33150 .cindex "policy control" "by local scan function"
33151 In these days of email worms, viruses, and ever-increasing spam, some sites
33152 want to apply a lot of checking to messages before accepting them.
33153
33154 The content scanning extension (chapter &<<CHAPexiscan>>&) has facilities for
33155 passing messages to external virus and spam scanning software. You can also do
33156 a certain amount in Exim itself through string expansions and the &%condition%&
33157 condition in the ACL that runs after the SMTP DATA command or the ACL for
33158 non-SMTP messages (see chapter &<<CHAPACL>>&), but this has its limitations.
33159
33160 To allow for further customization to a site's own requirements, there is the
33161 possibility of linking Exim with a private message scanning function, written
33162 in C. If you want to run code that is written in something other than C, you
33163 can of course use a little C stub to call it.
33164
33165 The local scan function is run once for every incoming message, at the point
33166 when Exim is just about to accept the message.
33167 It can therefore be used to control non-SMTP messages from local processes as
33168 well as messages arriving via SMTP.
33169
33170 Exim applies a timeout to calls of the local scan function, and there is an
33171 option called &%local_scan_timeout%& for setting it. The default is 5 minutes.
33172 Zero means &"no timeout"&.
33173 Exim also sets up signal handlers for SIGSEGV, SIGILL, SIGFPE, and SIGBUS
33174 before calling the local scan function, so that the most common types of crash
33175 are caught. If the timeout is exceeded or one of those signals is caught, the
33176 incoming message is rejected with a temporary error if it is an SMTP message.
33177 For a non-SMTP message, the message is dropped and Exim ends with a non-zero
33178 code. The incident is logged on the main and reject logs.
33179
33180
33181
33182 .section "Building Exim to use a local scan function" "SECID207"
33183 .cindex "&[local_scan()]& function" "building Exim to use"
33184 To make use of the local scan function feature, you must tell Exim where your
33185 function is before building Exim, by setting
33186 .new
33187 both HAVE_LOCAL_SCAN and
33188 .wen
33189 LOCAL_SCAN_SOURCE in your
33190 &_Local/Makefile_&. A recommended place to put it is in the &_Local_&
33191 directory, so you might set
33192 .code
33193 HAVE_LOCAL_SCAN=yes
33194 LOCAL_SCAN_SOURCE=Local/local_scan.c
33195 .endd
33196 for example. The function must be called &[local_scan()]&. It is called by
33197 Exim after it has received a message, when the success return code is about to
33198 be sent. This is after all the ACLs have been run. The return code from your
33199 function controls whether the message is actually accepted or not. There is a
33200 commented template function (that just accepts the message) in the file
33201 _src/local_scan.c_.
33202
33203 If you want to make use of Exim's run time configuration file to set options
33204 for your &[local_scan()]& function, you must also set
33205 .code
33206 LOCAL_SCAN_HAS_OPTIONS=yes
33207 .endd
33208 in &_Local/Makefile_& (see section &<<SECTconoptloc>>& below).
33209
33210
33211
33212
33213 .section "API for local_scan()" "SECTapiforloc"
33214 .cindex "&[local_scan()]& function" "API description"
33215 You must include this line near the start of your code:
33216 .code
33217 #include "local_scan.h"
33218 .endd
33219 This header file defines a number of variables and other values, and the
33220 prototype for the function itself. Exim is coded to use unsigned char values
33221 almost exclusively, and one of the things this header defines is a shorthand
33222 for &`unsigned char`& called &`uschar`&.
33223 It also contains the following macro definitions, to simplify casting character
33224 strings and pointers to character strings:
33225 .code
33226 #define CS   (char *)
33227 #define CCS  (const char *)
33228 #define CSS  (char **)
33229 #define US   (unsigned char *)
33230 #define CUS  (const unsigned char *)
33231 #define USS  (unsigned char **)
33232 .endd
33233 The function prototype for &[local_scan()]& is:
33234 .code
33235 extern int local_scan(int fd, uschar **return_text);
33236 .endd
33237 The arguments are as follows:
33238
33239 .ilist
33240 &%fd%& is a file descriptor for the file that contains the body of the message
33241 (the -D file). The file is open for reading and writing, but updating it is not
33242 recommended. &*Warning*&: You must &'not'& close this file descriptor.
33243
33244 The descriptor is positioned at character 19 of the file, which is the first
33245 character of the body itself, because the first 19 characters are the message
33246 id followed by &`-D`& and a newline. If you rewind the file, you should use the
33247 macro SPOOL_DATA_START_OFFSET to reset to the start of the data, just in
33248 case this changes in some future version.
33249 .next
33250 &%return_text%& is an address which you can use to return a pointer to a text
33251 string at the end of the function. The value it points to on entry is NULL.
33252 .endlist
33253
33254 The function must return an &%int%& value which is one of the following macros:
33255
33256 .vlist
33257 .vitem &`LOCAL_SCAN_ACCEPT`&
33258 .vindex "&$local_scan_data$&"
33259 The message is accepted. If you pass back a string of text, it is saved with
33260 the message, and made available in the variable &$local_scan_data$&. No
33261 newlines are permitted (if there are any, they are turned into spaces) and the
33262 maximum length of text is 1000 characters.
33263
33264 .vitem &`LOCAL_SCAN_ACCEPT_FREEZE`&
33265 This behaves as LOCAL_SCAN_ACCEPT, except that the accepted message is
33266 queued without immediate delivery, and is frozen.
33267
33268 .vitem &`LOCAL_SCAN_ACCEPT_QUEUE`&
33269 This behaves as LOCAL_SCAN_ACCEPT, except that the accepted message is
33270 queued without immediate delivery.
33271
33272 .vitem &`LOCAL_SCAN_REJECT`&
33273 The message is rejected; the returned text is used as an error message which is
33274 passed back to the sender and which is also logged. Newlines are permitted &--
33275 they cause a multiline response for SMTP rejections, but are converted to
33276 &`\n`& in log lines. If no message is given, &"Administrative prohibition"& is
33277 used.
33278
33279 .vitem &`LOCAL_SCAN_TEMPREJECT`&
33280 The message is temporarily rejected; the returned text is used as an error
33281 message as for LOCAL_SCAN_REJECT. If no message is given, &"Temporary local
33282 problem"& is used.
33283
33284 .vitem &`LOCAL_SCAN_REJECT_NOLOGHDR`&
33285 This behaves as LOCAL_SCAN_REJECT, except that the header of the rejected
33286 message is not written to the reject log. It has the effect of unsetting the
33287 &%rejected_header%& log selector for just this rejection. If
33288 &%rejected_header%& is already unset (see the discussion of the
33289 &%log_selection%& option in section &<<SECTlogselector>>&), this code is the
33290 same as LOCAL_SCAN_REJECT.
33291
33292 .vitem &`LOCAL_SCAN_TEMPREJECT_NOLOGHDR`&
33293 This code is a variation of LOCAL_SCAN_TEMPREJECT in the same way that
33294 LOCAL_SCAN_REJECT_NOLOGHDR is a variation of LOCAL_SCAN_REJECT.
33295 .endlist
33296
33297 If the message is not being received by interactive SMTP, rejections are
33298 reported by writing to &%stderr%& or by sending an email, as configured by the
33299 &%-oe%& command line options.
33300
33301
33302
33303 .section "Configuration options for local_scan()" "SECTconoptloc"
33304 .cindex "&[local_scan()]& function" "configuration options"
33305 It is possible to have option settings in the main configuration file
33306 that set values in static variables in the &[local_scan()]& module. If you
33307 want to do this, you must have the line
33308 .code
33309 LOCAL_SCAN_HAS_OPTIONS=yes
33310 .endd
33311 in your &_Local/Makefile_& when you build Exim. (This line is in
33312 &_OS/Makefile-Default_&, commented out). Then, in the &[local_scan()]& source
33313 file, you must define static variables to hold the option values, and a table
33314 to define them.
33315
33316 The table must be a vector called &%local_scan_options%&, of type
33317 &`optionlist`&. Each entry is a triplet, consisting of a name, an option type,
33318 and a pointer to the variable that holds the value. The entries must appear in
33319 alphabetical order. Following &%local_scan_options%& you must also define a
33320 variable called &%local_scan_options_count%& that contains the number of
33321 entries in the table. Here is a short example, showing two kinds of option:
33322 .code
33323 static int my_integer_option = 42;
33324 static uschar *my_string_option = US"a default string";
33325
33326 optionlist local_scan_options[] = {
33327   { "my_integer", opt_int,       &my_integer_option },
33328   { "my_string",  opt_stringptr, &my_string_option }
33329 };
33330
33331 int local_scan_options_count =
33332   sizeof(local_scan_options)/sizeof(optionlist);
33333 .endd
33334 The values of the variables can now be changed from Exim's runtime
33335 configuration file by including a local scan section as in this example:
33336 .code
33337 begin local_scan
33338 my_integer = 99
33339 my_string = some string of text...
33340 .endd
33341 The available types of option data are as follows:
33342
33343 .vlist
33344 .vitem &*opt_bool*&
33345 This specifies a boolean (true/false) option. The address should point to a
33346 variable of type &`BOOL`&, which will be set to TRUE or FALSE, which are macros
33347 that are defined as &"1"& and &"0"&, respectively. If you want to detect
33348 whether such a variable has been set at all, you can initialize it to
33349 TRUE_UNSET. (BOOL variables are integers underneath, so can hold more than two
33350 values.)
33351
33352 .vitem &*opt_fixed*&
33353 This specifies a fixed point number, such as is used for load averages.
33354 The address should point to a variable of type &`int`&. The value is stored
33355 multiplied by 1000, so, for example, 1.4142 is truncated and stored as 1414.
33356
33357 .vitem &*opt_int*&
33358 This specifies an integer; the address should point to a variable of type
33359 &`int`&. The value may be specified in any of the integer formats accepted by
33360 Exim.
33361
33362 .vitem &*opt_mkint*&
33363 This is the same as &%opt_int%&, except that when such a value is output in a
33364 &%-bP%& listing, if it is an exact number of kilobytes or megabytes, it is
33365 printed with the suffix K or M.
33366
33367 .vitem &*opt_octint*&
33368 This also specifies an integer, but the value is always interpreted as an
33369 octal integer, whether or not it starts with the digit zero, and it is
33370 always output in octal.
33371
33372 .vitem &*opt_stringptr*&
33373 This specifies a string value; the address must be a pointer to a
33374 variable that points to a string (for example, of type &`uschar *`&).
33375
33376 .vitem &*opt_time*&
33377 This specifies a time interval value. The address must point to a variable of
33378 type &`int`&. The value that is placed there is a number of seconds.
33379 .endlist
33380
33381 If the &%-bP%& command line option is followed by &`local_scan`&, Exim prints
33382 out the values of all the &[local_scan()]& options.
33383
33384
33385
33386 .section "Available Exim variables" "SECID208"
33387 .cindex "&[local_scan()]& function" "available Exim variables"
33388 The header &_local_scan.h_& gives you access to a number of C variables. These
33389 are the only ones that are guaranteed to be maintained from release to release.
33390 Note, however, that you can obtain the value of any Exim expansion variable,
33391 including &$recipients$&, by calling &'expand_string()'&. The exported
33392 C variables are as follows:
33393
33394 .vlist
33395 .vitem &*int&~body_linecount*&
33396 This variable contains the number of lines in the message's body.
33397 It is not valid if the &%spool_files_wireformat%& option is used.
33398
33399 .vitem &*int&~body_zerocount*&
33400 This variable contains the number of binary zero bytes in the message's body.
33401 It is not valid if the &%spool_files_wireformat%& option is used.
33402
33403 .vitem &*unsigned&~int&~debug_selector*&
33404 This variable is set to zero when no debugging is taking place. Otherwise, it
33405 is a bitmap of debugging selectors. Two bits are identified for use in
33406 &[local_scan()]&; they are defined as macros:
33407
33408 .ilist
33409 The &`D_v`& bit is set when &%-v%& was present on the command line. This is a
33410 testing option that is not privileged &-- any caller may set it. All the
33411 other selector bits can be set only by admin users.
33412
33413 .next
33414 The &`D_local_scan`& bit is provided for use by &[local_scan()]&; it is set
33415 by the &`+local_scan`& debug selector. It is not included in the default set
33416 of debugging bits.
33417 .endlist ilist
33418
33419 Thus, to write to the debugging output only when &`+local_scan`& has been
33420 selected, you should use code like this:
33421 .code
33422 if ((debug_selector & D_local_scan) != 0)
33423   debug_printf("xxx", ...);
33424 .endd
33425 .vitem &*uschar&~*expand_string_message*&
33426 After a failing call to &'expand_string()'& (returned value NULL), the
33427 variable &%expand_string_message%& contains the error message, zero-terminated.
33428
33429 .vitem &*header_line&~*header_list*&
33430 A pointer to a chain of header lines. The &%header_line%& structure is
33431 discussed below.
33432
33433 .vitem &*header_line&~*header_last*&
33434 A pointer to the last of the header lines.
33435
33436 .vitem &*uschar&~*headers_charset*&
33437 The value of the &%headers_charset%& configuration option.
33438
33439 .vitem &*BOOL&~host_checking*&
33440 This variable is TRUE during a host checking session that is initiated by the
33441 &%-bh%& command line option.
33442
33443 .vitem &*uschar&~*interface_address*&
33444 The IP address of the interface that received the message, as a string. This
33445 is NULL for locally submitted messages.
33446
33447 .vitem &*int&~interface_port*&
33448 The port on which this message was received. When testing with the &%-bh%&
33449 command line option, the value of this variable is -1 unless a port has been
33450 specified via the &%-oMi%& option.
33451
33452 .vitem &*uschar&~*message_id*&
33453 This variable contains Exim's message id for the incoming message (the value of
33454 &$message_exim_id$&) as a zero-terminated string.
33455
33456 .vitem &*uschar&~*received_protocol*&
33457 The name of the protocol by which the message was received.
33458
33459 .vitem &*int&~recipients_count*&
33460 The number of accepted recipients.
33461
33462 .vitem &*recipient_item&~*recipients_list*&
33463 .cindex "recipient" "adding in local scan"
33464 .cindex "recipient" "removing in local scan"
33465 The list of accepted recipients, held in a vector of length
33466 &%recipients_count%&. The &%recipient_item%& structure is discussed below. You
33467 can add additional recipients by calling &'receive_add_recipient()'& (see
33468 below). You can delete recipients by removing them from the vector and
33469 adjusting the value in &%recipients_count%&. In particular, by setting
33470 &%recipients_count%& to zero you remove all recipients. If you then return the
33471 value &`LOCAL_SCAN_ACCEPT`&, the message is accepted, but immediately
33472 blackholed. To replace the recipients, you can set &%recipients_count%& to zero
33473 and then call &'receive_add_recipient()'& as often as needed.
33474
33475 .vitem &*uschar&~*sender_address*&
33476 The envelope sender address. For bounce messages this is the empty string.
33477
33478 .vitem &*uschar&~*sender_host_address*&
33479 The IP address of the sending host, as a string. This is NULL for
33480 locally-submitted messages.
33481
33482 .vitem &*uschar&~*sender_host_authenticated*&
33483 The name of the authentication mechanism that was used, or NULL if the message
33484 was not received over an authenticated SMTP connection.
33485
33486 .vitem &*uschar&~*sender_host_name*&
33487 The name of the sending host, if known.
33488
33489 .vitem &*int&~sender_host_port*&
33490 The port on the sending host.
33491
33492 .vitem &*BOOL&~smtp_input*&
33493 This variable is TRUE for all SMTP input, including BSMTP.
33494
33495 .vitem &*BOOL&~smtp_batched_input*&
33496 This variable is TRUE for BSMTP input.
33497
33498 .vitem &*int&~store_pool*&
33499 The contents of this variable control which pool of memory is used for new
33500 requests. See section &<<SECTmemhanloc>>& for details.
33501 .endlist
33502
33503
33504 .section "Structure of header lines" "SECID209"
33505 The &%header_line%& structure contains the members listed below.
33506 You can add additional header lines by calling the &'header_add()'& function
33507 (see below). You can cause header lines to be ignored (deleted) by setting
33508 their type to *.
33509
33510
33511 .vlist
33512 .vitem &*struct&~header_line&~*next*&
33513 A pointer to the next header line, or NULL for the last line.
33514
33515 .vitem &*int&~type*&
33516 A code identifying certain headers that Exim recognizes. The codes are printing
33517 characters, and are documented in chapter &<<CHAPspool>>& of this manual.
33518 Notice in particular that any header line whose type is * is not transmitted
33519 with the message. This flagging is used for header lines that have been
33520 rewritten, or are to be removed (for example, &'Envelope-sender:'& header
33521 lines.) Effectively, * means &"deleted"&.
33522
33523 .vitem &*int&~slen*&
33524 The number of characters in the header line, including the terminating and any
33525 internal newlines.
33526
33527 .vitem &*uschar&~*text*&
33528 A pointer to the text of the header. It always ends with a newline, followed by
33529 a zero byte. Internal newlines are preserved.
33530 .endlist
33531
33532
33533
33534 .section "Structure of recipient items" "SECID210"
33535 The &%recipient_item%& structure contains these members:
33536
33537 .vlist
33538 .vitem &*uschar&~*address*&
33539 This is a pointer to the recipient address as it was received.
33540
33541 .vitem &*int&~pno*&
33542 This is used in later Exim processing when top level addresses are created by
33543 the &%one_time%& option. It is not relevant at the time &[local_scan()]& is run
33544 and must always contain -1 at this stage.
33545
33546 .vitem &*uschar&~*errors_to*&
33547 If this value is not NULL, bounce messages caused by failing to deliver to the
33548 recipient are sent to the address it contains. In other words, it overrides the
33549 envelope sender for this one recipient. (Compare the &%errors_to%& generic
33550 router option.) If a &[local_scan()]& function sets an &%errors_to%& field to
33551 an unqualified address, Exim qualifies it using the domain from
33552 &%qualify_recipient%&. When &[local_scan()]& is called, the &%errors_to%& field
33553 is NULL for all recipients.
33554 .endlist
33555
33556
33557
33558 .section "Available Exim functions" "SECID211"
33559 .cindex "&[local_scan()]& function" "available Exim functions"
33560 The header &_local_scan.h_& gives you access to a number of Exim functions.
33561 These are the only ones that are guaranteed to be maintained from release to
33562 release:
33563
33564 .vlist
33565 .vitem "&*pid_t&~child_open(uschar&~**argv,&~uschar&~**envp,&~int&~newumask,&&&
33566        &~int&~*infdptr,&~int&~*outfdptr, &~&~BOOL&~make_leader)*&"
33567
33568 This function creates a child process that runs the command specified by
33569 &%argv%&. The environment for the process is specified by &%envp%&, which can
33570 be NULL if no environment variables are to be passed. A new umask is supplied
33571 for the process in &%newumask%&.
33572
33573 Pipes to the standard input and output of the new process are set up
33574 and returned to the caller via the &%infdptr%& and &%outfdptr%& arguments. The
33575 standard error is cloned to the standard output. If there are any file
33576 descriptors &"in the way"& in the new process, they are closed. If the final
33577 argument is TRUE, the new process is made into a process group leader.
33578
33579 The function returns the pid of the new process, or -1 if things go wrong.
33580
33581 .vitem &*int&~child_close(pid_t&~pid,&~int&~timeout)*&
33582 This function waits for a child process to terminate, or for a timeout (in
33583 seconds) to expire. A timeout value of zero means wait as long as it takes. The
33584 return value is as follows:
33585
33586 .ilist
33587 >= 0
33588
33589 The process terminated by a normal exit and the value is the process
33590 ending status.
33591
33592 .next
33593 < 0 and > &--256
33594
33595 The process was terminated by a signal and the value is the negation of the
33596 signal number.
33597
33598 .next
33599 &--256
33600
33601 The process timed out.
33602 .next
33603 &--257
33604
33605 The was some other error in wait(); &%errno%& is still set.
33606 .endlist
33607
33608 .vitem &*pid_t&~child_open_exim(int&~*fd)*&
33609 This function provide you with a means of submitting a new message to
33610 Exim. (Of course, you can also call &_/usr/sbin/sendmail_& yourself if you
33611 want, but this packages it all up for you.) The function creates a pipe,
33612 forks a subprocess that is running
33613 .code
33614 exim -t -oem -oi -f <>
33615 .endd
33616 and returns to you (via the &`int *`& argument) a file descriptor for the pipe
33617 that is connected to the standard input. The yield of the function is the PID
33618 of the subprocess. You can then write a message to the file descriptor, with
33619 recipients in &'To:'&, &'Cc:'&, and/or &'Bcc:'& header lines.
33620
33621 When you have finished, call &'child_close()'& to wait for the process to
33622 finish and to collect its ending status. A timeout value of zero is usually
33623 fine in this circumstance. Unless you have made a mistake with the recipient
33624 addresses, you should get a return code of zero.
33625
33626
33627 .vitem &*pid_t&~child_open_exim2(int&~*fd,&~uschar&~*sender,&~uschar&~&&&
33628        *sender_authentication)*&
33629 This function is a more sophisticated version of &'child_open()'&. The command
33630 that it runs is:
33631 .display
33632 &`exim -t -oem -oi -f `&&'sender'&&` -oMas `&&'sender_authentication'&
33633 .endd
33634 The third argument may be NULL, in which case the &%-oMas%& option is omitted.
33635
33636
33637 .vitem &*void&~debug_printf(char&~*,&~...)*&
33638 This is Exim's debugging function, with arguments as for &'(printf()'&. The
33639 output is written to the standard error stream. If no debugging is selected,
33640 calls to &'debug_printf()'& have no effect. Normally, you should make calls
33641 conditional on the &`local_scan`& debug selector by coding like this:
33642 .code
33643 if ((debug_selector & D_local_scan) != 0)
33644   debug_printf("xxx", ...);
33645 .endd
33646
33647 .vitem &*uschar&~*expand_string(uschar&~*string)*&
33648 This is an interface to Exim's string expansion code. The return value is the
33649 expanded string, or NULL if there was an expansion failure.
33650 The C variable &%expand_string_message%& contains an error message after an
33651 expansion failure. If expansion does not change the string, the return value is
33652 the pointer to the input string. Otherwise, the return value points to a new
33653 block of memory that was obtained by a call to &'store_get()'&. See section
33654 &<<SECTmemhanloc>>& below for a discussion of memory handling.
33655
33656 .vitem &*void&~header_add(int&~type,&~char&~*format,&~...)*&
33657 This function allows you to an add additional header line at the end of the
33658 existing ones. The first argument is the type, and should normally be a space
33659 character. The second argument is a format string and any number of
33660 substitution arguments as for &[sprintf()]&. You may include internal newlines
33661 if you want, and you must ensure that the string ends with a newline.
33662
33663 .vitem "&*void&~header_add_at_position(BOOL&~after,&~uschar&~*name,&~&&&
33664         BOOL&~topnot,&~int&~type,&~char&~*format, &~&~...)*&"
33665 This function adds a new header line at a specified point in the header
33666 chain. The header itself is specified as for &'header_add()'&.
33667
33668 If &%name%& is NULL, the new header is added at the end of the chain if
33669 &%after%& is true, or at the start if &%after%& is false. If &%name%& is not
33670 NULL, the header lines are searched for the first non-deleted header that
33671 matches the name. If one is found, the new header is added before it if
33672 &%after%& is false. If &%after%& is true, the new header is added after the
33673 found header and any adjacent subsequent ones with the same name (even if
33674 marked &"deleted"&). If no matching non-deleted header is found, the &%topnot%&
33675 option controls where the header is added. If it is true, addition is at the
33676 top; otherwise at the bottom. Thus, to add a header after all the &'Received:'&
33677 headers, or at the top if there are no &'Received:'& headers, you could use
33678 .code
33679 header_add_at_position(TRUE, US"Received", TRUE,
33680   ' ', "X-xxx: ...");
33681 .endd
33682 Normally, there is always at least one non-deleted &'Received:'& header, but
33683 there may not be if &%received_header_text%& expands to an empty string.
33684
33685
33686 .vitem &*void&~header_remove(int&~occurrence,&~uschar&~*name)*&
33687 This function removes header lines. If &%occurrence%& is zero or negative, all
33688 occurrences of the header are removed. If occurrence is greater than zero, that
33689 particular instance of the header is removed. If no header(s) can be found that
33690 match the specification, the function does nothing.
33691
33692
33693 .vitem "&*BOOL&~header_testname(header_line&~*hdr,&~uschar&~*name,&~&&&
33694         int&~length,&~BOOL&~notdel)*&"
33695 This function tests whether the given header has the given name. It is not just
33696 a string comparison, because white space is permitted between the name and the
33697 colon. If the &%notdel%& argument is true, a false return is forced for all
33698 &"deleted"& headers; otherwise they are not treated specially. For example:
33699 .code
33700 if (header_testname(h, US"X-Spam", 6, TRUE)) ...
33701 .endd
33702 .vitem &*uschar&~*lss_b64encode(uschar&~*cleartext,&~int&~length)*&
33703 .cindex "base64 encoding" "functions for &[local_scan()]& use"
33704 This function base64-encodes a string, which is passed by address and length.
33705 The text may contain bytes of any value, including zero. The result is passed
33706 back in dynamic memory that is obtained by calling &'store_get()'&. It is
33707 zero-terminated.
33708
33709 .vitem &*int&~lss_b64decode(uschar&~*codetext,&~uschar&~**cleartext)*&
33710 This function decodes a base64-encoded string. Its arguments are a
33711 zero-terminated base64-encoded string and the address of a variable that is set
33712 to point to the result, which is in dynamic memory. The length of the decoded
33713 string is the yield of the function. If the input is invalid base64 data, the
33714 yield is -1. A zero byte is added to the end of the output string to make it
33715 easy to interpret as a C string (assuming it contains no zeros of its own). The
33716 added zero byte is not included in the returned count.
33717
33718 .vitem &*int&~lss_match_domain(uschar&~*domain,&~uschar&~*list)*&
33719 This function checks for a match in a domain list. Domains are always
33720 matched caselessly. The return value is one of the following:
33721 .display
33722 &`OK     `& match succeeded
33723 &`FAIL   `& match failed
33724 &`DEFER  `& match deferred
33725 .endd
33726 DEFER is usually caused by some kind of lookup defer, such as the
33727 inability to contact a database.
33728
33729 .vitem "&*int&~lss_match_local_part(uschar&~*localpart,&~uschar&~*list,&~&&&
33730         BOOL&~caseless)*&"
33731 This function checks for a match in a local part list. The third argument
33732 controls case-sensitivity. The return values are as for
33733 &'lss_match_domain()'&.
33734
33735 .vitem "&*int&~lss_match_address(uschar&~*address,&~uschar&~*list,&~&&&
33736         BOOL&~caseless)*&"
33737 This function checks for a match in an address list. The third argument
33738 controls the case-sensitivity of the local part match. The domain is always
33739 matched caselessly. The return values are as for &'lss_match_domain()'&.
33740
33741 .vitem "&*int&~lss_match_host(uschar&~*host_name,&~uschar&~*host_address,&~&&&
33742         uschar&~*list)*&"
33743 This function checks for a match in a host list. The most common usage is
33744 expected to be
33745 .code
33746 lss_match_host(sender_host_name, sender_host_address, ...)
33747 .endd
33748 .vindex "&$sender_host_address$&"
33749 An empty address field matches an empty item in the host list. If the host name
33750 is NULL, the name corresponding to &$sender_host_address$& is automatically
33751 looked up if a host name is required to match an item in the list. The return
33752 values are as for &'lss_match_domain()'&, but in addition, &'lss_match_host()'&
33753 returns ERROR in the case when it had to look up a host name, but the lookup
33754 failed.
33755
33756 .vitem "&*void&~log_write(unsigned&~int&~selector,&~int&~which,&~char&~&&&
33757         *format,&~...)*&"
33758 This function writes to Exim's log files. The first argument should be zero (it
33759 is concerned with &%log_selector%&). The second argument can be &`LOG_MAIN`& or
33760 &`LOG_REJECT`& or &`LOG_PANIC`& or the inclusive &"or"& of any combination of
33761 them. It specifies to which log or logs the message is written. The remaining
33762 arguments are a format and relevant insertion arguments. The string should not
33763 contain any newlines, not even at the end.
33764
33765
33766 .vitem &*void&~receive_add_recipient(uschar&~*address,&~int&~pno)*&
33767 This function adds an additional recipient to the message. The first argument
33768 is the recipient address. If it is unqualified (has no domain), it is qualified
33769 with the &%qualify_recipient%& domain. The second argument must always be -1.
33770
33771 This function does not allow you to specify a private &%errors_to%& address (as
33772 described with the structure of &%recipient_item%& above), because it pre-dates
33773 the addition of that field to the structure. However, it is easy to add such a
33774 value afterwards. For example:
33775 .code
33776  receive_add_recipient(US"monitor@mydom.example", -1);
33777  recipients_list[recipients_count-1].errors_to =
33778    US"postmaster@mydom.example";
33779 .endd
33780
33781 .vitem &*BOOL&~receive_remove_recipient(uschar&~*recipient)*&
33782 This is a convenience function to remove a named recipient from the list of
33783 recipients. It returns true if a recipient was removed, and false if no
33784 matching recipient could be found. The argument must be a complete email
33785 address.
33786 .endlist
33787
33788
33789 .cindex "RFC 2047"
33790 .vlist
33791 .vitem "&*uschar&~rfc2047_decode(uschar&~*string,&~BOOL&~lencheck,&&&
33792   &~uschar&~*target,&~int&~zeroval,&~int&~*lenptr, &~&~uschar&~**error)*&"
33793 This function decodes strings that are encoded according to RFC 2047. Typically
33794 these are the contents of header lines. First, each &"encoded word"& is decoded
33795 from the Q or B encoding into a byte-string. Then, if provided with the name of
33796 a charset encoding, and if the &[iconv()]& function is available, an attempt is
33797 made  to translate the result to the named character set. If this fails, the
33798 binary string is returned with an error message.
33799
33800 The first argument is the string to be decoded. If &%lencheck%& is TRUE, the
33801 maximum MIME word length is enforced. The third argument is the target
33802 encoding, or NULL if no translation is wanted.
33803
33804 .cindex "binary zero" "in RFC 2047 decoding"
33805 .cindex "RFC 2047" "binary zero in"
33806 If a binary zero is encountered in the decoded string, it is replaced by the
33807 contents of the &%zeroval%& argument. For use with Exim headers, the value must
33808 not be 0 because header lines are handled as zero-terminated strings.
33809
33810 The function returns the result of processing the string, zero-terminated; if
33811 &%lenptr%& is not NULL, the length of the result is set in the variable to
33812 which it points. When &%zeroval%& is 0, &%lenptr%& should not be NULL.
33813
33814 If an error is encountered, the function returns NULL and uses the &%error%&
33815 argument to return an error message. The variable pointed to by &%error%& is
33816 set to NULL if there is no error; it may be set non-NULL even when the function
33817 returns a non-NULL value if decoding was successful, but there was a problem
33818 with translation.
33819
33820
33821 .vitem &*int&~smtp_fflush(void)*&
33822 This function is used in conjunction with &'smtp_printf()'&, as described
33823 below.
33824
33825 .vitem &*void&~smtp_printf(char&~*,&~...)*&
33826 The arguments of this function are like &[printf()]&; it writes to the SMTP
33827 output stream. You should use this function only when there is an SMTP output
33828 stream, that is, when the incoming message is being received via interactive
33829 SMTP. This is the case when &%smtp_input%& is TRUE and &%smtp_batched_input%&
33830 is FALSE. If you want to test for an incoming message from another host (as
33831 opposed to a local process that used the &%-bs%& command line option), you can
33832 test the value of &%sender_host_address%&, which is non-NULL when a remote host
33833 is involved.
33834
33835 If an SMTP TLS connection is established, &'smtp_printf()'& uses the TLS
33836 output function, so it can be used for all forms of SMTP connection.
33837
33838 Strings that are written by &'smtp_printf()'& from within &[local_scan()]&
33839 must start with an appropriate response code: 550 if you are going to return
33840 LOCAL_SCAN_REJECT, 451 if you are going to return
33841 LOCAL_SCAN_TEMPREJECT, and 250 otherwise. Because you are writing the
33842 initial lines of a multi-line response, the code must be followed by a hyphen
33843 to indicate that the line is not the final response line. You must also ensure
33844 that the lines you write terminate with CRLF. For example:
33845 .code
33846 smtp_printf("550-this is some extra info\r\n");
33847 return LOCAL_SCAN_REJECT;
33848 .endd
33849 Note that you can also create multi-line responses by including newlines in
33850 the data returned via the &%return_text%& argument. The added value of using
33851 &'smtp_printf()'& is that, for instance, you could introduce delays between
33852 multiple output lines.
33853
33854 The &'smtp_printf()'& function does not return any error indication, because it
33855 does not automatically flush pending output, and therefore does not test
33856 the state of the stream. (In the main code of Exim, flushing and error
33857 detection is done when Exim is ready for the next SMTP input command.) If
33858 you want to flush the output and check for an error (for example, the
33859 dropping of a TCP/IP connection), you can call &'smtp_fflush()'&, which has no
33860 arguments. It flushes the output stream, and returns a non-zero value if there
33861 is an error.
33862
33863 .vitem &*void&~*store_get(int)*&
33864 This function accesses Exim's internal store (memory) manager. It gets a new
33865 chunk of memory whose size is given by the argument. Exim bombs out if it ever
33866 runs out of memory. See the next section for a discussion of memory handling.
33867
33868 .vitem &*void&~*store_get_perm(int)*&
33869 This function is like &'store_get()'&, but it always gets memory from the
33870 permanent pool. See the next section for a discussion of memory handling.
33871
33872 .vitem &*uschar&~*string_copy(uschar&~*string)*&
33873 See below.
33874
33875 .vitem &*uschar&~*string_copyn(uschar&~*string,&~int&~length)*&
33876 See below.
33877
33878 .vitem &*uschar&~*string_sprintf(char&~*format,&~...)*&
33879 These three functions create strings using Exim's dynamic memory facilities.
33880 The first makes a copy of an entire string. The second copies up to a maximum
33881 number of characters, indicated by the second argument. The third uses a format
33882 and insertion arguments to create a new string. In each case, the result is a
33883 pointer to a new string in the current memory pool. See the next section for
33884 more discussion.
33885 .endlist
33886
33887
33888
33889 .section "More about Exim's memory handling" "SECTmemhanloc"
33890 .cindex "&[local_scan()]& function" "memory handling"
33891 No function is provided for freeing memory, because that is never needed.
33892 The dynamic memory that Exim uses when receiving a message is automatically
33893 recycled if another message is received by the same process (this applies only
33894 to incoming SMTP connections &-- other input methods can supply only one
33895 message at a time). After receiving the last message, a reception process
33896 terminates.
33897
33898 Because it is recycled, the normal dynamic memory cannot be used for holding
33899 data that must be preserved over a number of incoming messages on the same SMTP
33900 connection. However, Exim in fact uses two pools of dynamic memory; the second
33901 one is not recycled, and can be used for this purpose.
33902
33903 If you want to allocate memory that remains available for subsequent messages
33904 in the same SMTP connection, you should set
33905 .code
33906 store_pool = POOL_PERM
33907 .endd
33908 before calling the function that does the allocation. There is no need to
33909 restore the value if you do not need to; however, if you do want to revert to
33910 the normal pool, you can either restore the previous value of &%store_pool%& or
33911 set it explicitly to POOL_MAIN.
33912
33913 The pool setting applies to all functions that get dynamic memory, including
33914 &'expand_string()'&, &'store_get()'&, and the &'string_xxx()'& functions.
33915 There is also a convenience function called &'store_get_perm()'& that gets a
33916 block of memory from the permanent pool while preserving the value of
33917 &%store_pool%&.
33918 .ecindex IIDlosca
33919
33920
33921
33922
33923 . ////////////////////////////////////////////////////////////////////////////
33924 . ////////////////////////////////////////////////////////////////////////////
33925
33926 .chapter "System-wide message filtering" "CHAPsystemfilter"
33927 .scindex IIDsysfil1 "filter" "system filter"
33928 .scindex IIDsysfil2 "filtering all mail"
33929 .scindex IIDsysfil3 "system filter"
33930 The previous chapters (on ACLs and the local scan function) describe checks
33931 that can be applied to messages before they are accepted by a host. There is
33932 also a mechanism for checking messages once they have been received, but before
33933 they are delivered. This is called the &'system filter'&.
33934
33935 The system filter operates in a similar manner to users' filter files, but it
33936 is run just once per message (however many recipients the message has).
33937 It should not normally be used as a substitute for routing, because &%deliver%&
33938 commands in a system router provide new envelope recipient addresses.
33939 The system filter must be an Exim filter. It cannot be a Sieve filter.
33940
33941 The system filter is run at the start of a delivery attempt, before any routing
33942 is done. If a message fails to be completely delivered at the first attempt,
33943 the system filter is run again at the start of every retry.
33944 If you want your filter to do something only once per message, you can make use
33945 of the &%first_delivery%& condition in an &%if%& command in the filter to
33946 prevent it happening on retries.
33947
33948 .vindex "&$domain$&"
33949 .vindex "&$local_part$&"
33950 &*Warning*&: Because the system filter runs just once, variables that are
33951 specific to individual recipient addresses, such as &$local_part$& and
33952 &$domain$&, are not set, and the &"personal"& condition is not meaningful. If
33953 you want to run a centrally-specified filter for each recipient address
33954 independently, you can do so by setting up a suitable &(redirect)& router, as
33955 described in section &<<SECTperaddfil>>& below.
33956
33957
33958 .section "Specifying a system filter" "SECID212"
33959 .cindex "uid (user id)" "system filter"
33960 .cindex "gid (group id)" "system filter"
33961 The name of the file that contains the system filter must be specified by
33962 setting &%system_filter%&. If you want the filter to run under a uid and gid
33963 other than root, you must also set &%system_filter_user%& and
33964 &%system_filter_group%& as appropriate. For example:
33965 .code
33966 system_filter = /etc/mail/exim.filter
33967 system_filter_user = exim
33968 .endd
33969 If a system filter generates any deliveries directly to files or pipes (via the
33970 &%save%& or &%pipe%& commands), transports to handle these deliveries must be
33971 specified by setting &%system_filter_file_transport%& and
33972 &%system_filter_pipe_transport%&, respectively. Similarly,
33973 &%system_filter_reply_transport%& must be set to handle any messages generated
33974 by the &%reply%& command.
33975
33976
33977 .section "Testing a system filter" "SECID213"
33978 You can run simple tests of a system filter in the same way as for a user
33979 filter, but you should use &%-bF%& rather than &%-bf%&, so that features that
33980 are permitted only in system filters are recognized.
33981
33982 If you want to test the combined effect of a system filter and a user filter,
33983 you can use both &%-bF%& and &%-bf%& on the same command line.
33984
33985
33986
33987 .section "Contents of a system filter" "SECID214"
33988 The language used to specify system filters is the same as for users' filter
33989 files. It is described in the separate end-user document &'Exim's interface to
33990 mail filtering'&. However, there are some additional features that are
33991 available only in system filters; these are described in subsequent sections.
33992 If they are encountered in a user's filter file or when testing with &%-bf%&,
33993 they cause errors.
33994
33995 .cindex "frozen messages" "manual thaw; testing in filter"
33996 There are two special conditions which, though available in users' filter
33997 files, are designed for use in system filters. The condition &%first_delivery%&
33998 is true only for the first attempt at delivering a message, and
33999 &%manually_thawed%& is true only if the message has been frozen, and
34000 subsequently thawed by an admin user. An explicit forced delivery counts as a
34001 manual thaw, but thawing as a result of the &%auto_thaw%& setting does not.
34002
34003 &*Warning*&: If a system filter uses the &%first_delivery%& condition to
34004 specify an &"unseen"& (non-significant) delivery, and that delivery does not
34005 succeed, it will not be tried again.
34006 If you want Exim to retry an unseen delivery until it succeeds, you should
34007 arrange to set it up every time the filter runs.
34008
34009 When a system filter finishes running, the values of the variables &$n0$& &--
34010 &$n9$& are copied into &$sn0$& &-- &$sn9$& and are thereby made available to
34011 users' filter files. Thus a system filter can, for example, set up &"scores"&
34012 to which users' filter files can refer.
34013
34014
34015
34016 .section "Additional variable for system filters" "SECID215"
34017 .vindex "&$recipients$&"
34018 The expansion variable &$recipients$&, containing a list of all the recipients
34019 of the message (separated by commas and white space), is available in system
34020 filters. It is not available in users' filters for privacy reasons.
34021
34022
34023
34024 .section "Defer, freeze, and fail commands for system filters" "SECID216"
34025 .cindex "freezing messages"
34026 .cindex "message" "freezing"
34027 .cindex "message" "forced failure"
34028 .cindex "&%fail%&" "in system filter"
34029 .cindex "&%freeze%& in system filter"
34030 .cindex "&%defer%& in system filter"
34031 There are three extra commands (&%defer%&, &%freeze%& and &%fail%&) which are
34032 always available in system filters, but are not normally enabled in users'
34033 filters. (See the &%allow_defer%&, &%allow_freeze%& and &%allow_fail%& options
34034 for the &(redirect)& router.) These commands can optionally be followed by the
34035 word &%text%& and a string containing an error message, for example:
34036 .code
34037 fail text "this message looks like spam to me"
34038 .endd
34039 The keyword &%text%& is optional if the next character is a double quote.
34040
34041 The &%defer%& command defers delivery of the original recipients of the
34042 message. The &%fail%& command causes all the original recipients to be failed,
34043 and a bounce message to be created. The &%freeze%& command suspends all
34044 delivery attempts for the original recipients. In all cases, any new deliveries
34045 that are specified by the filter are attempted as normal after the filter has
34046 run.
34047
34048 The &%freeze%& command is ignored if the message has been manually unfrozen and
34049 not manually frozen since. This means that automatic freezing by a system
34050 filter can be used as a way of checking out suspicious messages. If a message
34051 is found to be all right, manually unfreezing it allows it to be delivered.
34052
34053 .cindex "log" "&%fail%& command log line"
34054 .cindex "&%fail%&" "log line; reducing"
34055 The text given with a fail command is used as part of the bounce message as
34056 well as being written to the log. If the message is quite long, this can fill
34057 up a lot of log space when such failures are common. To reduce the size of the
34058 log message, Exim interprets the text in a special way if it starts with the
34059 two characters &`<<`& and contains &`>>`& later. The text between these two
34060 strings is written to the log, and the rest of the text is used in the bounce
34061 message. For example:
34062 .code
34063 fail "<<filter test 1>>Your message is rejected \
34064      because it contains attachments that we are \
34065      not prepared to receive."
34066 .endd
34067
34068 .cindex "loop" "caused by &%fail%&"
34069 Take great care with the &%fail%& command when basing the decision to fail on
34070 the contents of the message, because the bounce message will of course include
34071 the contents of the original message and will therefore trigger the &%fail%&
34072 command again (causing a mail loop) unless steps are taken to prevent this.
34073 Testing the &%error_message%& condition is one way to prevent this. You could
34074 use, for example
34075 .code
34076 if $message_body contains "this is spam" and not error_message
34077 then fail text "spam is not wanted here" endif
34078 .endd
34079 though of course that might let through unwanted bounce messages. The
34080 alternative is clever checking of the body and/or headers to detect bounces
34081 generated by the filter.
34082
34083 The interpretation of a system filter file ceases after a
34084 &%defer%&,
34085 &%freeze%&, or &%fail%& command is obeyed. However, any deliveries that were
34086 set up earlier in the filter file are honoured, so you can use a sequence such
34087 as
34088 .code
34089 mail ...
34090 freeze
34091 .endd
34092 to send a specified message when the system filter is freezing (or deferring or
34093 failing) a message. The normal deliveries for the message do not, of course,
34094 take place.
34095
34096
34097
34098 .section "Adding and removing headers in a system filter" "SECTaddremheasys"
34099 .cindex "header lines" "adding; in system filter"
34100 .cindex "header lines" "removing; in system filter"
34101 .cindex "filter" "header lines; adding/removing"
34102 Two filter commands that are available only in system filters are:
34103 .code
34104 headers add <string>
34105 headers remove <string>
34106 .endd
34107 The argument for the &%headers add%& is a string that is expanded and then
34108 added to the end of the message's headers. It is the responsibility of the
34109 filter maintainer to make sure it conforms to RFC 2822 syntax. Leading white
34110 space is ignored, and if the string is otherwise empty, or if the expansion is
34111 forced to fail, the command has no effect.
34112
34113 You can use &"\n"& within the string, followed by white space, to specify
34114 continued header lines. More than one header may be added in one command by
34115 including &"\n"& within the string without any following white space. For
34116 example:
34117 .code
34118 headers add "X-header-1: ....\n  \
34119              continuation of X-header-1 ...\n\
34120              X-header-2: ...."
34121 .endd
34122 Note that the header line continuation white space after the first newline must
34123 be placed before the backslash that continues the input string, because white
34124 space after input continuations is ignored.
34125
34126 The argument for &%headers remove%& is a colon-separated list of header names.
34127 This command applies only to those headers that are stored with the message;
34128 those that are added at delivery time (such as &'Envelope-To:'& and
34129 &'Return-Path:'&) cannot be removed by this means. If there is more than one
34130 header with the same name, they are all removed.
34131
34132 The &%headers%& command in a system filter makes an immediate change to the set
34133 of header lines that was received with the message (with possible additions
34134 from ACL processing). Subsequent commands in the system filter operate on the
34135 modified set, which also forms the basis for subsequent message delivery.
34136 Unless further modified during routing or transporting, this set of headers is
34137 used for all recipients of the message.
34138
34139 During routing and transporting, the variables that refer to the contents of
34140 header lines refer only to those lines that are in this set. Thus, header lines
34141 that are added by a system filter are visible to users' filter files and to all
34142 routers and transports. This contrasts with the manipulation of header lines by
34143 routers and transports, which is not immediate, but which instead is saved up
34144 until the message is actually being written (see section
34145 &<<SECTheadersaddrem>>&).
34146
34147 If the message is not delivered at the first attempt, header lines that were
34148 added by the system filter are stored with the message, and so are still
34149 present at the next delivery attempt. Header lines that were removed are still
34150 present, but marked &"deleted"& so that they are not transported with the
34151 message. For this reason, it is usual to make the &%headers%& command
34152 conditional on &%first_delivery%& so that the set of header lines is not
34153 modified more than once.
34154
34155 Because header modification in a system filter acts immediately, you have to
34156 use an indirect approach if you want to modify the contents of a header line.
34157 For example:
34158 .code
34159 headers add "Old-Subject: $h_subject:"
34160 headers remove "Subject"
34161 headers add "Subject: new subject (was: $h_old-subject:)"
34162 headers remove "Old-Subject"
34163 .endd
34164
34165
34166
34167 .section "Setting an errors address in a system filter" "SECID217"
34168 .cindex "envelope sender"
34169 In a system filter, if a &%deliver%& command is followed by
34170 .code
34171 errors_to <some address>
34172 .endd
34173 in order to change the envelope sender (and hence the error reporting) for that
34174 delivery, any address may be specified. (In a user filter, only the current
34175 user's address can be set.) For example, if some mail is being monitored, you
34176 might use
34177 .code
34178 unseen deliver monitor@spying.example errors_to root@local.example
34179 .endd
34180 to take a copy which would not be sent back to the normal error reporting
34181 address if its delivery failed.
34182
34183
34184
34185 .section "Per-address filtering" "SECTperaddfil"
34186 .vindex "&$domain$&"
34187 .vindex "&$local_part$&"
34188 In contrast to the system filter, which is run just once per message for each
34189 delivery attempt, it is also possible to set up a system-wide filtering
34190 operation that runs once for each recipient address. In this case, variables
34191 such as &$local_part$& and &$domain$& can be used, and indeed, the choice of
34192 filter file could be made dependent on them. This is an example of a router
34193 which implements such a filter:
34194 .code
34195 central_filter:
34196   check_local_user
34197   driver = redirect
34198   domains = +local_domains
34199   file = /central/filters/$local_part
34200   no_verify
34201   allow_filter
34202   allow_freeze
34203 .endd
34204 The filter is run in a separate process under its own uid. Therefore, either
34205 &%check_local_user%& must be set (as above), in which case the filter is run as
34206 the local user, or the &%user%& option must be used to specify which user to
34207 use. If both are set, &%user%& overrides.
34208
34209 Care should be taken to ensure that none of the commands in the filter file
34210 specify a significant delivery if the message is to go on to be delivered to
34211 its intended recipient. The router will not then claim to have dealt with the
34212 address, so it will be passed on to subsequent routers to be delivered in the
34213 normal way.
34214 .ecindex IIDsysfil1
34215 .ecindex IIDsysfil2
34216 .ecindex IIDsysfil3
34217
34218
34219
34220
34221
34222
34223 . ////////////////////////////////////////////////////////////////////////////
34224 . ////////////////////////////////////////////////////////////////////////////
34225
34226 .chapter "Message processing" "CHAPmsgproc"
34227 .scindex IIDmesproc "message" "general processing"
34228 Exim performs various transformations on the sender and recipient addresses of
34229 all messages that it handles, and also on the messages' header lines. Some of
34230 these are optional and configurable, while others always take place. All of
34231 this processing, except rewriting as a result of routing, and the addition or
34232 removal of header lines while delivering, happens when a message is received,
34233 before it is placed on Exim's queue.
34234
34235 Some of the automatic processing takes place by default only for
34236 &"locally-originated"& messages. This adjective is used to describe messages
34237 that are not received over TCP/IP, but instead are passed to an Exim process on
34238 its standard input. This includes the interactive &"local SMTP"& case that is
34239 set up by the &%-bs%& command line option.
34240
34241 &*Note*&: Messages received over TCP/IP on the loopback interface (127.0.0.1
34242 or ::1) are not considered to be locally-originated. Exim does not treat the
34243 loopback interface specially in any way.
34244
34245 If you want the loopback interface to be treated specially, you must ensure
34246 that there are appropriate entries in your ACLs.
34247
34248
34249
34250
34251 .section "Submission mode for non-local messages" "SECTsubmodnon"
34252 .cindex "message" "submission"
34253 .cindex "submission mode"
34254 Processing that happens automatically for locally-originated messages (unless
34255 &%suppress_local_fixups%& is set) can also be requested for messages that are
34256 received over TCP/IP. The term &"submission mode"& is used to describe this
34257 state. Submission mode is set by the modifier
34258 .code
34259 control = submission
34260 .endd
34261 in a MAIL, RCPT, or pre-data ACL for an incoming message (see sections
34262 &<<SECTACLmodi>>& and &<<SECTcontrols>>&). This makes Exim treat the message as
34263 a local submission, and is normally used when the source of the message is
34264 known to be an MUA running on a client host (as opposed to an MTA). For
34265 example, to set submission mode for messages originating on the IPv4 loopback
34266 interface, you could include the following in the MAIL ACL:
34267 .code
34268 warn  hosts = 127.0.0.1
34269       control = submission
34270 .endd
34271 .cindex "&%sender_retain%& submission option"
34272 There are some options that can be used when setting submission mode. A slash
34273 is used to separate options. For example:
34274 .code
34275 control = submission/sender_retain
34276 .endd
34277 Specifying &%sender_retain%& has the effect of setting &%local_sender_retain%&
34278 true and &%local_from_check%& false for the current incoming message. The first
34279 of these allows an existing &'Sender:'& header in the message to remain, and
34280 the second suppresses the check to ensure that &'From:'& matches the
34281 authenticated sender. With this setting, Exim still fixes up messages by adding
34282 &'Date:'& and &'Message-ID:'& header lines if they are missing, but makes no
34283 attempt to check sender authenticity in header lines.
34284
34285 When &%sender_retain%& is not set, a submission mode setting may specify a
34286 domain to be used when generating a &'From:'& or &'Sender:'& header line. For
34287 example:
34288 .code
34289 control = submission/domain=some.domain
34290 .endd
34291 The domain may be empty. How this value is used is described in sections
34292 &<<SECTthefrohea>>& and &<<SECTthesenhea>>&. There is also a &%name%& option
34293 that allows you to specify the user's full name for inclusion in a created
34294 &'Sender:'& or &'From:'& header line. For example:
34295 .code
34296 accept authenticated = *
34297        control = submission/domain=wonderland.example/\
34298                             name=${lookup {$authenticated_id} \
34299                                    lsearch {/etc/exim/namelist}}
34300 .endd
34301 Because the name may contain any characters, including slashes, the &%name%&
34302 option must be given last. The remainder of the string is used as the name. For
34303 the example above, if &_/etc/exim/namelist_& contains:
34304 .code
34305 bigegg:  Humpty Dumpty
34306 .endd
34307 then when the sender has authenticated as &'bigegg'&, the generated &'Sender:'&
34308 line would be:
34309 .code
34310 Sender: Humpty Dumpty <bigegg@wonderland.example>
34311 .endd
34312 .cindex "return path" "in submission mode"
34313 By default, submission mode forces the return path to the same address as is
34314 used to create the &'Sender:'& header. However, if &%sender_retain%& is
34315 specified, the return path is also left unchanged.
34316
34317 &*Note*&: The changes caused by submission mode take effect after the predata
34318 ACL. This means that any sender checks performed before the fix-ups use the
34319 untrusted sender address specified by the user, not the trusted sender address
34320 specified by submission mode. Although this might be slightly unexpected, it
34321 does mean that you can configure ACL checks to spot that a user is trying to
34322 spoof another's address.
34323
34324 .section "Line endings" "SECTlineendings"
34325 .cindex "line endings"
34326 .cindex "carriage return"
34327 .cindex "linefeed"
34328 RFC 2821 specifies that CRLF (two characters: carriage-return, followed by
34329 linefeed) is the line ending for messages transmitted over the Internet using
34330 SMTP over TCP/IP. However, within individual operating systems, different
34331 conventions are used. For example, Unix-like systems use just LF, but others
34332 use CRLF or just CR.
34333
34334 Exim was designed for Unix-like systems, and internally, it stores messages
34335 using the system's convention of a single LF as a line terminator. When
34336 receiving a message, all line endings are translated to this standard format.
34337 Originally, it was thought that programs that passed messages directly to an
34338 MTA within an operating system would use that system's convention. Experience
34339 has shown that this is not the case; for example, there are Unix applications
34340 that use CRLF in this circumstance. For this reason, and for compatibility with
34341 other MTAs, the way Exim handles line endings for all messages is now as
34342 follows:
34343
34344 .ilist
34345 LF not preceded by CR is treated as a line ending.
34346 .next
34347 CR is treated as a line ending; if it is immediately followed by LF, the LF
34348 is ignored.
34349 .next
34350 The sequence &"CR, dot, CR"& does not terminate an incoming SMTP message,
34351 nor a local message in the state where a line containing only a dot is a
34352 terminator.
34353 .next
34354 If a bare CR is encountered within a header line, an extra space is added after
34355 the line terminator so as not to end the header line. The reasoning behind this
34356 is that bare CRs in header lines are most likely either to be mistakes, or
34357 people trying to play silly games.
34358 .next
34359 If the first header line received in a message ends with CRLF, a subsequent
34360 bare LF in a header line is treated in the same way as a bare CR in a header
34361 line.
34362 .endlist
34363
34364
34365
34366
34367
34368 .section "Unqualified addresses" "SECID218"
34369 .cindex "unqualified addresses"
34370 .cindex "address" "qualification"
34371 By default, Exim expects every envelope address it receives from an external
34372 host to be fully qualified. Unqualified addresses cause negative responses to
34373 SMTP commands. However, because SMTP is used as a means of transporting
34374 messages from MUAs running on personal workstations, there is sometimes a
34375 requirement to accept unqualified addresses from specific hosts or IP networks.
34376
34377 Exim has two options that separately control which hosts may send unqualified
34378 sender or recipient addresses in SMTP commands, namely
34379 &%sender_unqualified_hosts%& and &%recipient_unqualified_hosts%&. In both
34380 cases, if an unqualified address is accepted, it is qualified by adding the
34381 value of &%qualify_domain%& or &%qualify_recipient%&, as appropriate.
34382
34383 .oindex "&%qualify_domain%&"
34384 .oindex "&%qualify_recipient%&"
34385 Unqualified addresses in header lines are automatically qualified for messages
34386 that are locally originated, unless the &%-bnq%& option is given on the command
34387 line. For messages received over SMTP, unqualified addresses in header lines
34388 are qualified only if unqualified addresses are permitted in SMTP commands. In
34389 other words, such qualification is also controlled by
34390 &%sender_unqualified_hosts%& and &%recipient_unqualified_hosts%&,
34391
34392
34393
34394
34395 .section "The UUCP From line" "SECID219"
34396 .cindex "&""From""& line"
34397 .cindex "UUCP" "&""From""& line"
34398 .cindex "sender" "address"
34399 .oindex "&%uucp_from_pattern%&"
34400 .oindex "&%uucp_from_sender%&"
34401 .cindex "envelope sender"
34402 .cindex "Sendmail compatibility" "&""From""& line"
34403 Messages that have come from UUCP (and some other applications) often begin
34404 with a line containing the envelope sender and a timestamp, following the word
34405 &"From"&. Examples of two common formats are:
34406 .code
34407 From a.oakley@berlin.mus Fri Jan  5 12:35 GMT 1996
34408 From f.butler@berlin.mus Fri, 7 Jan 97 14:00:00 GMT
34409 .endd
34410 This line precedes the RFC 2822 header lines. For compatibility with Sendmail,
34411 Exim recognizes such lines at the start of messages that are submitted to it
34412 via the command line (that is, on the standard input). It does not recognize
34413 such lines in incoming SMTP messages, unless the sending host matches
34414 &%ignore_fromline_hosts%& or the &%-bs%& option was used for a local message
34415 and &%ignore_fromline_local%& is set. The recognition is controlled by a
34416 regular expression that is defined by the &%uucp_from_pattern%& option, whose
34417 default value matches the two common cases shown above and puts the address
34418 that follows &"From"& into &$1$&.
34419
34420 .cindex "numerical variables (&$1$& &$2$& etc)" "in &""From ""& line handling"
34421 When the caller of Exim for a non-SMTP message that contains a &"From"& line is
34422 a trusted user, the message's sender address is constructed by expanding the
34423 contents of &%uucp_sender_address%&, whose default value is &"$1"&. This is
34424 then parsed as an RFC 2822 address. If there is no domain, the local part is
34425 qualified with &%qualify_domain%& unless it is the empty string. However, if
34426 the command line &%-f%& option is used, it overrides the &"From"& line.
34427
34428 If the caller of Exim is not trusted, the &"From"& line is recognized, but the
34429 sender address is not changed. This is also the case for incoming SMTP messages
34430 that are permitted to contain &"From"& lines.
34431
34432 Only one &"From"& line is recognized. If there is more than one, the second is
34433 treated as a data line that starts the body of the message, as it is not valid
34434 as a header line. This also happens if a &"From"& line is present in an
34435 incoming SMTP message from a source that is not permitted to send them.
34436
34437
34438
34439 .section "Resent- header lines" "SECID220"
34440 .cindex "&%Resent-%& header lines"
34441 .cindex "header lines" "Resent-"
34442 RFC 2822 makes provision for sets of header lines starting with the string
34443 &`Resent-`& to be added to a message when it is resent by the original
34444 recipient to somebody else. These headers are &'Resent-Date:'&,
34445 &'Resent-From:'&, &'Resent-Sender:'&, &'Resent-To:'&, &'Resent-Cc:'&,
34446 &'Resent-Bcc:'& and &'Resent-Message-ID:'&. The RFC says:
34447
34448 .blockquote
34449 &'Resent fields are strictly informational. They MUST NOT be used in the normal
34450 processing of replies or other such automatic actions on messages.'&
34451 .endblockquote
34452
34453 This leaves things a bit vague as far as other processing actions such as
34454 address rewriting are concerned. Exim treats &%Resent-%& header lines as
34455 follows:
34456
34457 .ilist
34458 A &'Resent-From:'& line that just contains the login id of the submitting user
34459 is automatically rewritten in the same way as &'From:'& (see below).
34460 .next
34461 If there's a rewriting rule for a particular header line, it is also applied to
34462 &%Resent-%& header lines of the same type. For example, a rule that rewrites
34463 &'From:'& also rewrites &'Resent-From:'&.
34464 .next
34465 For local messages, if &'Sender:'& is removed on input, &'Resent-Sender:'& is
34466 also removed.
34467 .next
34468 For a locally-submitted message,
34469 if there are any &%Resent-%& header lines but no &'Resent-Date:'&,
34470 &'Resent-From:'&, or &'Resent-Message-Id:'&, they are added as necessary. It is
34471 the contents of &'Resent-Message-Id:'& (rather than &'Message-Id:'&) which are
34472 included in log lines in this case.
34473 .next
34474 The logic for adding &'Sender:'& is duplicated for &'Resent-Sender:'& when any
34475 &%Resent-%& header lines are present.
34476 .endlist
34477
34478
34479
34480
34481 .section "The Auto-Submitted: header line" "SECID221"
34482 Whenever Exim generates an autoreply, a bounce, or a delay warning message, it
34483 includes the header line:
34484 .code
34485 Auto-Submitted: auto-replied
34486 .endd
34487
34488 .section "The Bcc: header line" "SECID222"
34489 .cindex "&'Bcc:'& header line"
34490 If Exim is called with the &%-t%& option, to take recipient addresses from a
34491 message's header, it removes any &'Bcc:'& header line that may exist (after
34492 extracting its addresses). If &%-t%& is not present on the command line, any
34493 existing &'Bcc:'& is not removed.
34494
34495
34496 .section "The Date: header line" "SECID223"
34497 .cindex "&'Date:'& header line"
34498 .cindex "header lines" "Date:"
34499 If a locally-generated or submission-mode message has no &'Date:'& header line,
34500 Exim adds one, using the current date and time, unless the
34501 &%suppress_local_fixups%& control has been specified.
34502
34503 .section "The Delivery-date: header line" "SECID224"
34504 .cindex "&'Delivery-date:'& header line"
34505 .oindex "&%delivery_date_remove%&"
34506 &'Delivery-date:'& header lines are not part of the standard RFC 2822 header
34507 set. Exim can be configured to add them to the final delivery of messages. (See
34508 the generic &%delivery_date_add%& transport option.) They should not be present
34509 in messages in transit. If the &%delivery_date_remove%& configuration option is
34510 set (the default), Exim removes &'Delivery-date:'& header lines from incoming
34511 messages.
34512
34513
34514 .section "The Envelope-to: header line" "SECID225"
34515 .cindex "&'Envelope-to:'& header line"
34516 .cindex "header lines" "Envelope-to:"
34517 .oindex "&%envelope_to_remove%&"
34518 &'Envelope-to:'& header lines are not part of the standard RFC 2822 header set.
34519 Exim can be configured to add them to the final delivery of messages. (See the
34520 generic &%envelope_to_add%& transport option.) They should not be present in
34521 messages in transit. If the &%envelope_to_remove%& configuration option is set
34522 (the default), Exim removes &'Envelope-to:'& header lines from incoming
34523 messages.
34524
34525
34526 .section "The From: header line" "SECTthefrohea"
34527 .cindex "&'From:'& header line"
34528 .cindex "header lines" "From:"
34529 .cindex "Sendmail compatibility" "&""From""& line"
34530 .cindex "message" "submission"
34531 .cindex "submission mode"
34532 If a submission-mode message does not contain a &'From:'& header line, Exim
34533 adds one if either of the following conditions is true:
34534
34535 .ilist
34536 The envelope sender address is not empty (that is, this is not a bounce
34537 message). The added header line copies the envelope sender address.
34538 .next
34539 .vindex "&$authenticated_id$&"
34540 The SMTP session is authenticated and &$authenticated_id$& is not empty.
34541 .olist
34542 .vindex "&$qualify_domain$&"
34543 If no domain is specified by the submission control, the local part is
34544 &$authenticated_id$& and the domain is &$qualify_domain$&.
34545 .next
34546 If a non-empty domain is specified by the submission control, the local
34547 part is &$authenticated_id$&, and the domain is the specified domain.
34548 .next
34549 If an empty domain is specified by the submission control,
34550 &$authenticated_id$& is assumed to be the complete address.
34551 .endlist
34552 .endlist
34553
34554 A non-empty envelope sender takes precedence.
34555
34556 If a locally-generated incoming message does not contain a &'From:'& header
34557 line, and the &%suppress_local_fixups%& control is not set, Exim adds one
34558 containing the sender's address. The calling user's login name and full name
34559 are used to construct the address, as described in section &<<SECTconstr>>&.
34560 They are obtained from the password data by calling &[getpwuid()]& (but see the
34561 &%unknown_login%& configuration option). The address is qualified with
34562 &%qualify_domain%&.
34563
34564 For compatibility with Sendmail, if an incoming, non-SMTP message has a
34565 &'From:'& header line containing just the unqualified login name of the calling
34566 user, this is replaced by an address containing the user's login name and full
34567 name as described in section &<<SECTconstr>>&.
34568
34569
34570 .section "The Message-ID: header line" "SECID226"
34571 .cindex "&'Message-ID:'& header line"
34572 .cindex "header lines" "Message-ID:"
34573 .cindex "message" "submission"
34574 .oindex "&%message_id_header_text%&"
34575 If a locally-generated or submission-mode incoming message does not contain a
34576 &'Message-ID:'& or &'Resent-Message-ID:'& header line, and the
34577 &%suppress_local_fixups%& control is not set, Exim adds a suitable header line
34578 to the message. If there are any &'Resent-:'& headers in the message, it
34579 creates &'Resent-Message-ID:'&. The id is constructed from Exim's internal
34580 message id, preceded by the letter E to ensure it starts with a letter, and
34581 followed by @ and the primary host name. Additional information can be included
34582 in this header line by setting the &%message_id_header_text%& and/or
34583 &%message_id_header_domain%& options.
34584
34585
34586 .section "The Received: header line" "SECID227"
34587 .cindex "&'Received:'& header line"
34588 .cindex "header lines" "Received:"
34589 A &'Received:'& header line is added at the start of every message. The
34590 contents are defined by the &%received_header_text%& configuration option, and
34591 Exim automatically adds a semicolon and a timestamp to the configured string.
34592
34593 The &'Received:'& header is generated as soon as the message's header lines
34594 have been received. At this stage, the timestamp in the &'Received:'& header
34595 line is the time that the message started to be received. This is the value
34596 that is seen by the DATA ACL and by the &[local_scan()]& function.
34597
34598 Once a message is accepted, the timestamp in the &'Received:'& header line is
34599 changed to the time of acceptance, which is (apart from a small delay while the
34600 -H spool file is written) the earliest time at which delivery could start.
34601
34602
34603 .section "The References: header line" "SECID228"
34604 .cindex "&'References:'& header line"
34605 .cindex "header lines" "References:"
34606 Messages created by the &(autoreply)& transport include a &'References:'&
34607 header line. This is constructed according to the rules that are described in
34608 section 3.64 of RFC 2822 (which states that replies should contain such a
34609 header line), and section 3.14 of RFC 3834 (which states that automatic
34610 responses are not different in this respect). However, because some mail
34611 processing software does not cope well with very long header lines, no more
34612 than 12 message IDs are copied from the &'References:'& header line in the
34613 incoming message. If there are more than 12, the first one and then the final
34614 11 are copied, before adding the message ID of the incoming message.
34615
34616
34617
34618 .section "The Return-path: header line" "SECID229"
34619 .cindex "&'Return-path:'& header line"
34620 .cindex "header lines" "Return-path:"
34621 .oindex "&%return_path_remove%&"
34622 &'Return-path:'& header lines are defined as something an MTA may insert when
34623 it does the final delivery of messages. (See the generic &%return_path_add%&
34624 transport option.) Therefore, they should not be present in messages in
34625 transit. If the &%return_path_remove%& configuration option is set (the
34626 default), Exim removes &'Return-path:'& header lines from incoming messages.
34627
34628
34629
34630 .section "The Sender: header line" "SECTthesenhea"
34631 .cindex "&'Sender:'& header line"
34632 .cindex "message" "submission"
34633 .cindex "header lines" "Sender:"
34634 For a locally-originated message from an untrusted user, Exim may remove an
34635 existing &'Sender:'& header line, and it may add a new one. You can modify
34636 these actions by setting the &%local_sender_retain%& option true, the
34637 &%local_from_check%& option false, or by using the &%suppress_local_fixups%&
34638 control setting.
34639
34640 When a local message is received from an untrusted user and
34641 &%local_from_check%& is true (the default), and the &%suppress_local_fixups%&
34642 control has not been set, a check is made to see if the address given in the
34643 &'From:'& header line is the correct (local) sender of the message. The address
34644 that is expected has the login name as the local part and the value of
34645 &%qualify_domain%& as the domain. Prefixes and suffixes for the local part can
34646 be permitted by setting &%local_from_prefix%& and &%local_from_suffix%&
34647 appropriately. If &'From:'& does not contain the correct sender, a &'Sender:'&
34648 line is added to the message.
34649
34650 If you set &%local_from_check%& false, this checking does not occur. However,
34651 the removal of an existing &'Sender:'& line still happens, unless you also set
34652 &%local_sender_retain%& to be true. It is not possible to set both of these
34653 options true at the same time.
34654
34655 .cindex "submission mode"
34656 By default, no processing of &'Sender:'& header lines is done for messages
34657 received over TCP/IP or for messages submitted by trusted users. However, when
34658 a message is received over TCP/IP in submission mode, and &%sender_retain%& is
34659 not specified on the submission control, the following processing takes place:
34660
34661 .vindex "&$authenticated_id$&"
34662 First, any existing &'Sender:'& lines are removed. Then, if the SMTP session is
34663 authenticated, and &$authenticated_id$& is not empty, a sender address is
34664 created as follows:
34665
34666 .ilist
34667 .vindex "&$qualify_domain$&"
34668 If no domain is specified by the submission control, the local part is
34669 &$authenticated_id$& and the domain is &$qualify_domain$&.
34670 .next
34671 If a non-empty domain is specified by the submission control, the local part
34672 is &$authenticated_id$&, and the domain is the specified domain.
34673 .next
34674 If an empty domain is specified by the submission control,
34675 &$authenticated_id$& is assumed to be the complete address.
34676 .endlist
34677
34678 This address is compared with the address in the &'From:'& header line. If they
34679 are different, a &'Sender:'& header line containing the created address is
34680 added. Prefixes and suffixes for the local part in &'From:'& can be permitted
34681 by setting &%local_from_prefix%& and &%local_from_suffix%& appropriately.
34682
34683 .cindex "return path" "created from &'Sender:'&"
34684 &*Note*&: Whenever a &'Sender:'& header line is created, the return path for
34685 the message (the envelope sender address) is changed to be the same address,
34686 except in the case of submission mode when &%sender_retain%& is specified.
34687
34688
34689
34690 .section "Adding and removing header lines in routers and transports" &&&
34691          "SECTheadersaddrem"
34692 .cindex "header lines" "adding; in router or transport"
34693 .cindex "header lines" "removing; in router or transport"
34694 When a message is delivered, the addition and removal of header lines can be
34695 specified in a system filter, or on any of the routers and transports that
34696 process the message. Section &<<SECTaddremheasys>>& contains details about
34697 modifying headers in a system filter. Header lines can also be added in an ACL
34698 as a message is received (see section &<<SECTaddheadacl>>&).
34699
34700 In contrast to what happens in a system filter, header modifications that are
34701 specified on routers and transports apply only to the particular recipient
34702 addresses that are being processed by those routers and transports. These
34703 changes do not actually take place until a copy of the message is being
34704 transported. Therefore, they do not affect the basic set of header lines, and
34705 they do not affect the values of the variables that refer to header lines.
34706
34707 &*Note*&: In particular, this means that any expansions in the configuration of
34708 the transport cannot refer to the modified header lines, because such
34709 expansions all occur before the message is actually transported.
34710
34711 For both routers and transports, the argument of a &%headers_add%&
34712 option must be in the form of one or more RFC 2822 header lines, separated by
34713 newlines (coded as &"\n"&). For example:
34714 .code
34715 headers_add = X-added-header: added by $primary_hostname\n\
34716               X-added-second: another added header line
34717 .endd
34718 Exim does not check the syntax of these added header lines.
34719
34720 Multiple &%headers_add%& options for a single router or transport can be
34721 specified; the values will append to a single list of header lines.
34722 Each header-line is separately expanded.
34723
34724 The argument of a &%headers_remove%& option must consist of a colon-separated
34725 list of header names. This is confusing, because header names themselves are
34726 often terminated by colons. In this case, the colons are the list separators,
34727 not part of the names. For example:
34728 .code
34729 headers_remove = return-receipt-to:acknowledge-to
34730 .endd
34731
34732 Multiple &%headers_remove%& options for a single router or transport can be
34733 specified; the arguments will append to a single header-names list.
34734 Each item is separately expanded.
34735 Note that colons in complex expansions which are used to
34736 form all or part of a &%headers_remove%& list
34737 will act as list separators.
34738
34739 When &%headers_add%& or &%headers_remove%& is specified on a router,
34740 items are expanded at routing time,
34741 and then associated with all addresses that are
34742 accepted by that router, and also with any new addresses that it generates. If
34743 an address passes through several routers as a result of aliasing or
34744 forwarding, the changes are cumulative.
34745
34746 .oindex "&%unseen%&"
34747 However, this does not apply to multiple routers that result from the use of
34748 the &%unseen%& option. Any header modifications that were specified by the
34749 &"unseen"& router or its predecessors apply only to the &"unseen"& delivery.
34750
34751 Addresses that end up with different &%headers_add%& or &%headers_remove%&
34752 settings cannot be delivered together in a batch, so a transport is always
34753 dealing with a set of addresses that have the same header-processing
34754 requirements.
34755
34756 The transport starts by writing the original set of header lines that arrived
34757 with the message, possibly modified by the system filter. As it writes out
34758 these lines, it consults the list of header names that were attached to the
34759 recipient address(es) by &%headers_remove%& options in routers, and it also
34760 consults the transport's own &%headers_remove%& option. Header lines whose
34761 names are on either of these lists are not written out. If there are multiple
34762 instances of any listed header, they are all skipped.
34763
34764 After the remaining original header lines have been written, new header
34765 lines that were specified by routers' &%headers_add%& options are written, in
34766 the order in which they were attached to the address. These are followed by any
34767 header lines specified by the transport's &%headers_add%& option.
34768
34769 This way of handling header line modifications in routers and transports has
34770 the following consequences:
34771
34772 .ilist
34773 The original set of header lines, possibly modified by the system filter,
34774 remains &"visible"&, in the sense that the &$header_$&&'xxx'& variables refer
34775 to it, at all times.
34776 .next
34777 Header lines that are added by a router's
34778 &%headers_add%& option are not accessible by means of the &$header_$&&'xxx'&
34779 expansion syntax in subsequent routers or the transport.
34780 .next
34781 Conversely, header lines that are specified for removal by &%headers_remove%&
34782 in a router remain visible to subsequent routers and the transport.
34783 .next
34784 Headers added to an address by &%headers_add%& in a router cannot be removed by
34785 a later router or by a transport.
34786 .next
34787 An added header can refer to the contents of an original header that is to be
34788 removed, even it has the same name as the added header. For example:
34789 .code
34790 headers_remove = subject
34791 headers_add = Subject: new subject (was: $h_subject:)
34792 .endd
34793 .endlist
34794
34795 &*Warning*&: The &%headers_add%& and &%headers_remove%& options cannot be used
34796 for a &(redirect)& router that has the &%one_time%& option set.
34797
34798
34799
34800
34801
34802 .section "Constructed addresses" "SECTconstr"
34803 .cindex "address" "constructed"
34804 .cindex "constructed address"
34805 When Exim constructs a sender address for a locally-generated message, it uses
34806 the form
34807 .display
34808 <&'user name'&>&~&~<&'login'&&`@`&&'qualify_domain'&>
34809 .endd
34810 For example:
34811 .code
34812 Zaphod Beeblebrox <zaphod@end.univ.example>
34813 .endd
34814 The user name is obtained from the &%-F%& command line option if set, or
34815 otherwise by looking up the calling user by &[getpwuid()]& and extracting the
34816 &"gecos"& field from the password entry. If the &"gecos"& field contains an
34817 ampersand character, this is replaced by the login name with the first letter
34818 upper cased, as is conventional in a number of operating systems. See the
34819 &%gecos_name%& option for a way to tailor the handling of the &"gecos"& field.
34820 The &%unknown_username%& option can be used to specify user names in cases when
34821 there is no password file entry.
34822
34823 .cindex "RFC 2047"
34824 In all cases, the user name is made to conform to RFC 2822 by quoting all or
34825 parts of it if necessary. In addition, if it contains any non-printing
34826 characters, it is encoded as described in RFC 2047, which defines a way of
34827 including non-ASCII characters in header lines. The value of the
34828 &%headers_charset%& option specifies the name of the encoding that is used (the
34829 characters are assumed to be in this encoding). The setting of
34830 &%print_topbitchars%& controls whether characters with the top bit set (that
34831 is, with codes greater than 127) count as printing characters or not.
34832
34833
34834
34835 .section "Case of local parts" "SECID230"
34836 .cindex "case of local parts"
34837 .cindex "local part" "case of"
34838 RFC 2822 states that the case of letters in the local parts of addresses cannot
34839 be assumed to be non-significant. Exim preserves the case of local parts of
34840 addresses, but by default it uses a lower-cased form when it is routing,
34841 because on most Unix systems, usernames are in lower case and case-insensitive
34842 routing is required. However, any particular router can be made to use the
34843 original case for local parts by setting the &%caseful_local_part%& generic
34844 router option.
34845
34846 .cindex "mixed-case login names"
34847 If you must have mixed-case user names on your system, the best way to proceed,
34848 assuming you want case-independent handling of incoming email, is to set up
34849 your first router to convert incoming local parts in your domains to the
34850 correct case by means of a file lookup. For example:
34851 .code
34852 correct_case:
34853   driver = redirect
34854   domains = +local_domains
34855   data = ${lookup{$local_part}cdb\
34856               {/etc/usercased.cdb}{$value}fail}\
34857               @$domain
34858 .endd
34859 For this router, the local part is forced to lower case by the default action
34860 (&%caseful_local_part%& is not set). The lower-cased local part is used to look
34861 up a new local part in the correct case. If you then set &%caseful_local_part%&
34862 on any subsequent routers which process your domains, they will operate on
34863 local parts with the correct case in a case-sensitive manner.
34864
34865
34866
34867 .section "Dots in local parts" "SECID231"
34868 .cindex "dot" "in local part"
34869 .cindex "local part" "dots in"
34870 RFC 2822 forbids empty components in local parts. That is, an unquoted local
34871 part may not begin or end with a dot, nor have two consecutive dots in the
34872 middle. However, it seems that many MTAs do not enforce this, so Exim permits
34873 empty components for compatibility.
34874
34875
34876
34877 .section "Rewriting addresses" "SECID232"
34878 .cindex "rewriting" "addresses"
34879 Rewriting of sender and recipient addresses, and addresses in headers, can
34880 happen automatically, or as the result of configuration options, as described
34881 in chapter &<<CHAPrewrite>>&. The headers that may be affected by this are
34882 &'Bcc:'&, &'Cc:'&, &'From:'&, &'Reply-To:'&, &'Sender:'&, and &'To:'&.
34883
34884 Automatic rewriting includes qualification, as mentioned above. The other case
34885 in which it can happen is when an incomplete non-local domain is given. The
34886 routing process may cause this to be expanded into the full domain name. For
34887 example, a header such as
34888 .code
34889 To: hare@teaparty
34890 .endd
34891 might get rewritten as
34892 .code
34893 To: hare@teaparty.wonderland.fict.example
34894 .endd
34895 Rewriting as a result of routing is the one kind of message processing that
34896 does not happen at input time, as it cannot be done until the address has
34897 been routed.
34898
34899 Strictly, one should not do &'any'& deliveries of a message until all its
34900 addresses have been routed, in case any of the headers get changed as a
34901 result of routing. However, doing this in practice would hold up many
34902 deliveries for unreasonable amounts of time, just because one address could not
34903 immediately be routed. Exim therefore does not delay other deliveries when
34904 routing of one or more addresses is deferred.
34905 .ecindex IIDmesproc
34906
34907
34908
34909 . ////////////////////////////////////////////////////////////////////////////
34910 . ////////////////////////////////////////////////////////////////////////////
34911
34912 .chapter "SMTP processing" "CHAPSMTP"
34913 .scindex IIDsmtpproc1 "SMTP" "processing details"
34914 .scindex IIDsmtpproc2 "LMTP" "processing details"
34915 Exim supports a number of different ways of using the SMTP protocol, and its
34916 LMTP variant, which is an interactive protocol for transferring messages into a
34917 closed mail store application. This chapter contains details of how SMTP is
34918 processed. For incoming mail, the following are available:
34919
34920 .ilist
34921 SMTP over TCP/IP (Exim daemon or &'inetd'&);
34922 .next
34923 SMTP over the standard input and output (the &%-bs%& option);
34924 .next
34925 Batched SMTP on the standard input (the &%-bS%& option).
34926 .endlist
34927
34928 For mail delivery, the following are available:
34929
34930 .ilist
34931 SMTP over TCP/IP (the &(smtp)& transport);
34932 .next
34933 LMTP over TCP/IP (the &(smtp)& transport with the &%protocol%& option set to
34934 &"lmtp"&);
34935 .next
34936 LMTP over a pipe to a process running in the local host (the &(lmtp)&
34937 transport);
34938 .next
34939 Batched SMTP to a file or pipe (the &(appendfile)& and &(pipe)& transports with
34940 the &%use_bsmtp%& option set).
34941 .endlist
34942
34943 &'Batched SMTP'& is the name for a process in which batches of messages are
34944 stored in or read from files (or pipes), in a format in which SMTP commands are
34945 used to contain the envelope information.
34946
34947
34948
34949 .section "Outgoing SMTP and LMTP over TCP/IP" "SECToutSMTPTCP"
34950 .cindex "SMTP" "outgoing over TCP/IP"
34951 .cindex "outgoing SMTP over TCP/IP"
34952 .cindex "LMTP" "over TCP/IP"
34953 .cindex "outgoing LMTP over TCP/IP"
34954 .cindex "EHLO"
34955 .cindex "HELO"
34956 .cindex "SIZE option on MAIL command"
34957 Outgoing SMTP and LMTP over TCP/IP is implemented by the &(smtp)& transport.
34958 The &%protocol%& option selects which protocol is to be used, but the actual
34959 processing is the same in both cases.
34960
34961 If, in response to its EHLO command, Exim is told that the SIZE
34962 parameter is supported, it adds SIZE=<&'n'&> to each subsequent MAIL
34963 command. The value of <&'n'&> is the message size plus the value of the
34964 &%size_addition%& option (default 1024) to allow for additions to the message
34965 such as per-transport header lines, or changes made in a
34966 .cindex "transport" "filter"
34967 .cindex "filter" "transport filter"
34968 transport filter. If &%size_addition%& is set negative, the use of SIZE is
34969 suppressed.
34970
34971 If the remote server advertises support for PIPELINING, Exim uses the
34972 pipelining extension to SMTP (RFC 2197) to reduce the number of TCP/IP packets
34973 required for the transaction.
34974
34975 If the remote server advertises support for the STARTTLS command, and Exim
34976 was built to support TLS encryption, it tries to start a TLS session unless the
34977 server matches &%hosts_avoid_tls%&. See chapter &<<CHAPTLS>>& for more details.
34978 Either a match in that or &%hosts_verify_avoid_tls%& apply when the transport
34979 is called for verification.
34980
34981 If the remote server advertises support for the AUTH command, Exim scans
34982 the authenticators configuration for any suitable client settings, as described
34983 in chapter &<<CHAPSMTPAUTH>>&.
34984
34985 .cindex "carriage return"
34986 .cindex "linefeed"
34987 Responses from the remote host are supposed to be terminated by CR followed by
34988 LF. However, there are known to be hosts that do not send CR characters, so in
34989 order to be able to interwork with such hosts, Exim treats LF on its own as a
34990 line terminator.
34991
34992 If a message contains a number of different addresses, all those with the same
34993 characteristics (for example, the same envelope sender) that resolve to the
34994 same set of hosts, in the same order, are sent in a single SMTP transaction,
34995 even if they are for different domains, unless there are more than the setting
34996 of the &%max_rcpt%&s option in the &(smtp)& transport allows, in which case
34997 they are split into groups containing no more than &%max_rcpt%&s addresses
34998 each. If &%remote_max_parallel%& is greater than one, such groups may be sent
34999 in parallel sessions. The order of hosts with identical MX values is not
35000 significant when checking whether addresses can be batched in this way.
35001
35002 When the &(smtp)& transport suffers a temporary failure that is not
35003 message-related, Exim updates its transport-specific database, which contains
35004 records indexed by host name that remember which messages are waiting for each
35005 particular host. It also updates the retry database with new retry times.
35006
35007 .cindex "hints database" "retry keys"
35008 Exim's retry hints are based on host name plus IP address, so if one address of
35009 a multi-homed host is broken, it will soon be skipped most of the time.
35010 See the next section for more detail about error handling.
35011
35012 .cindex "SMTP" "passed connection"
35013 .cindex "SMTP" "batching over TCP/IP"
35014 When a message is successfully delivered over a TCP/IP SMTP connection, Exim
35015 looks in the hints database for the transport to see if there are any queued
35016 messages waiting for the host to which it is connected. If it finds one, it
35017 creates a new Exim process using the &%-MC%& option (which can only be used by
35018 a process running as root or the Exim user) and passes the TCP/IP socket to it
35019 so that it can deliver another message using the same socket. The new process
35020 does only those deliveries that are routed to the connected host, and may in
35021 turn pass the socket on to a third process, and so on.
35022
35023 The &%connection_max_messages%& option of the &(smtp)& transport can be used to
35024 limit the number of messages sent down a single TCP/IP connection.
35025
35026 .cindex "asterisk" "after IP address"
35027 The second and subsequent messages delivered down an existing connection are
35028 identified in the main log by the addition of an asterisk after the closing
35029 square bracket of the IP address.
35030
35031
35032
35033
35034 .section "Errors in outgoing SMTP" "SECToutSMTPerr"
35035 .cindex "error" "in outgoing SMTP"
35036 .cindex "SMTP" "errors in outgoing"
35037 .cindex "host" "error"
35038 Three different kinds of error are recognized for outgoing SMTP: host errors,
35039 message errors, and recipient errors.
35040
35041 .vlist
35042 .vitem "&*Host errors*&"
35043 A host error is not associated with a particular message or with a
35044 particular recipient of a message. The host errors are:
35045
35046 .ilist
35047 Connection refused or timed out,
35048 .next
35049 Any error response code on connection,
35050 .next
35051 Any error response code to EHLO or HELO,
35052 .next
35053 Loss of connection at any time, except after &"."&,
35054 .next
35055 I/O errors at any time,
35056 .next
35057 Timeouts during the session, other than in response to MAIL, RCPT or
35058 the &"."& at the end of the data.
35059 .endlist ilist
35060
35061 For a host error, a permanent error response on connection, or in response to
35062 EHLO, causes all addresses routed to the host to be failed. Any other host
35063 error causes all addresses to be deferred, and retry data to be created for the
35064 host. It is not tried again, for any message, until its retry time arrives. If
35065 the current set of addresses are not all delivered in this run (to some
35066 alternative host), the message is added to the list of those waiting for this
35067 host, so if it is still undelivered when a subsequent successful delivery is
35068 made to the host, it will be sent down the same SMTP connection.
35069
35070 .vitem "&*Message errors*&"
35071 .cindex "message" "error"
35072 A message error is associated with a particular message when sent to a
35073 particular host, but not with a particular recipient of the message. The
35074 message errors are:
35075
35076 .ilist
35077 Any error response code to MAIL, DATA, or the &"."& that terminates
35078 the data,
35079 .next
35080 Timeout after MAIL,
35081 .next
35082 Timeout or loss of connection after the &"."& that terminates the data. A
35083 timeout after the DATA command itself is treated as a host error, as is loss of
35084 connection at any other time.
35085 .endlist ilist
35086
35087 For a message error, a permanent error response (5&'xx'&) causes all addresses
35088 to be failed, and a delivery error report to be returned to the sender. A
35089 temporary error response (4&'xx'&), or one of the timeouts, causes all
35090 addresses to be deferred. Retry data is not created for the host, but instead,
35091 a retry record for the combination of host plus message id is created. The
35092 message is not added to the list of those waiting for this host. This ensures
35093 that the failing message will not be sent to this host again until the retry
35094 time arrives. However, other messages that are routed to the host are not
35095 affected, so if it is some property of the message that is causing the error,
35096 it will not stop the delivery of other mail.
35097
35098 If the remote host specified support for the SIZE parameter in its response
35099 to EHLO, Exim adds SIZE=&'nnn'& to the MAIL command, so an
35100 over-large message will cause a message error because the error arrives as a
35101 response to MAIL.
35102
35103 .vitem "&*Recipient errors*&"
35104 .cindex "recipient" "error"
35105 A recipient error is associated with a particular recipient of a message. The
35106 recipient errors are:
35107
35108 .ilist
35109 Any error response to RCPT,
35110 .next
35111 Timeout after RCPT.
35112 .endlist
35113
35114 For a recipient error, a permanent error response (5&'xx'&) causes the
35115 recipient address to be failed, and a bounce message to be returned to the
35116 sender. A temporary error response (4&'xx'&) or a timeout causes the failing
35117 address to be deferred, and routing retry data to be created for it. This is
35118 used to delay processing of the address in subsequent queue runs, until its
35119 routing retry time arrives. This applies to all messages, but because it
35120 operates only in queue runs, one attempt will be made to deliver a new message
35121 to the failing address before the delay starts to operate. This ensures that,
35122 if the failure is really related to the message rather than the recipient
35123 (&"message too big for this recipient"& is a possible example), other messages
35124 have a chance of getting delivered. If a delivery to the address does succeed,
35125 the retry information gets cleared, so all stuck messages get tried again, and
35126 the retry clock is reset.
35127
35128 The message is not added to the list of those waiting for this host. Use of the
35129 host for other messages is unaffected, and except in the case of a timeout,
35130 other recipients are processed independently, and may be successfully delivered
35131 in the current SMTP session. After a timeout it is of course impossible to
35132 proceed with the session, so all addresses get deferred. However, those other
35133 than the one that failed do not suffer any subsequent retry delays. Therefore,
35134 if one recipient is causing trouble, the others have a chance of getting
35135 through when a subsequent delivery attempt occurs before the failing
35136 recipient's retry time.
35137 .endlist
35138
35139 In all cases, if there are other hosts (or IP addresses) available for the
35140 current set of addresses (for example, from multiple MX records), they are
35141 tried in this run for any undelivered addresses, subject of course to their
35142 own retry data. In other words, recipient error retry data does not take effect
35143 until the next delivery attempt.
35144
35145 Some hosts have been observed to give temporary error responses to every
35146 MAIL command at certain times (&"insufficient space"& has been seen). It
35147 would be nice if such circumstances could be recognized, and defer data for the
35148 host itself created, but this is not possible within the current Exim design.
35149 What actually happens is that retry data for every (host, message) combination
35150 is created.
35151
35152 The reason that timeouts after MAIL and RCPT are treated specially is that
35153 these can sometimes arise as a result of the remote host's verification
35154 procedures. Exim makes this assumption, and treats them as if a temporary error
35155 response had been received. A timeout after &"."& is treated specially because
35156 it is known that some broken implementations fail to recognize the end of the
35157 message if the last character of the last line is a binary zero. Thus, it is
35158 helpful to treat this case as a message error.
35159
35160 Timeouts at other times are treated as host errors, assuming a problem with the
35161 host, or the connection to it. If a timeout after MAIL, RCPT,
35162 or &"."& is really a connection problem, the assumption is that at the next try
35163 the timeout is likely to occur at some other point in the dialogue, causing it
35164 then to be treated as a host error.
35165
35166 There is experimental evidence that some MTAs drop the connection after the
35167 terminating &"."& if they do not like the contents of the message for some
35168 reason, in contravention of the RFC, which indicates that a 5&'xx'& response
35169 should be given. That is why Exim treats this case as a message rather than a
35170 host error, in order not to delay other messages to the same host.
35171
35172
35173
35174
35175 .section "Incoming SMTP messages over TCP/IP" "SECID233"
35176 .cindex "SMTP" "incoming over TCP/IP"
35177 .cindex "incoming SMTP over TCP/IP"
35178 .cindex "inetd"
35179 .cindex "daemon"
35180 Incoming SMTP messages can be accepted in one of two ways: by running a
35181 listening daemon, or by using &'inetd'&. In the latter case, the entry in
35182 &_/etc/inetd.conf_& should be like this:
35183 .code
35184 smtp stream tcp nowait exim /opt/exim/bin/exim in.exim -bs
35185 .endd
35186 Exim distinguishes between this case and the case of a locally running user
35187 agent using the &%-bs%& option by checking whether or not the standard input is
35188 a socket. When it is, either the port must be privileged (less than 1024), or
35189 the caller must be root or the Exim user. If any other user passes a socket
35190 with an unprivileged port number, Exim prints a message on the standard error
35191 stream and exits with an error code.
35192
35193 By default, Exim does not make a log entry when a remote host connects or
35194 disconnects (either via the daemon or &'inetd'&), unless the disconnection is
35195 unexpected. It can be made to write such log entries by setting the
35196 &%smtp_connection%& log selector.
35197
35198 .cindex "carriage return"
35199 .cindex "linefeed"
35200 Commands from the remote host are supposed to be terminated by CR followed by
35201 LF. However, there are known to be hosts that do not send CR characters. In
35202 order to be able to interwork with such hosts, Exim treats LF on its own as a
35203 line terminator.
35204 Furthermore, because common code is used for receiving messages from all
35205 sources, a CR on its own is also interpreted as a line terminator. However, the
35206 sequence &"CR, dot, CR"& does not terminate incoming SMTP data.
35207
35208 .cindex "EHLO" "invalid data"
35209 .cindex "HELO" "invalid data"
35210 One area that sometimes gives rise to problems concerns the EHLO or
35211 HELO commands. Some clients send syntactically invalid versions of these
35212 commands, which Exim rejects by default. (This is nothing to do with verifying
35213 the data that is sent, so &%helo_verify_hosts%& is not relevant.) You can tell
35214 Exim not to apply a syntax check by setting &%helo_accept_junk_hosts%& to
35215 match the broken hosts that send invalid commands.
35216
35217 .cindex "SIZE option on MAIL command"
35218 .cindex "MAIL" "SIZE option"
35219 The amount of disk space available is checked whenever SIZE is received on
35220 a MAIL command, independently of whether &%message_size_limit%& or
35221 &%check_spool_space%& is configured, unless &%smtp_check_spool_space%& is set
35222 false. A temporary error is given if there is not enough space. If
35223 &%check_spool_space%& is set, the check is for that amount of space plus the
35224 value given with SIZE, that is, it checks that the addition of the incoming
35225 message will not reduce the space below the threshold.
35226
35227 When a message is successfully received, Exim includes the local message id in
35228 its response to the final &"."& that terminates the data. If the remote host
35229 logs this text it can help with tracing what has happened to a message.
35230
35231 The Exim daemon can limit the number of simultaneous incoming connections it is
35232 prepared to handle (see the &%smtp_accept_max%& option). It can also limit the
35233 number of simultaneous incoming connections from a single remote host (see the
35234 &%smtp_accept_max_per_host%& option). Additional connection attempts are
35235 rejected using the SMTP temporary error code 421.
35236
35237 The Exim daemon does not rely on the SIGCHLD signal to detect when a
35238 subprocess has finished, as this can get lost at busy times. Instead, it looks
35239 for completed subprocesses every time it wakes up. Provided there are other
35240 things happening (new incoming calls, starts of queue runs), completed
35241 processes will be noticed and tidied away. On very quiet systems you may
35242 sometimes see a &"defunct"& Exim process hanging about. This is not a problem;
35243 it will be noticed when the daemon next wakes up.
35244
35245 When running as a daemon, Exim can reserve some SMTP slots for specific hosts,
35246 and can also be set up to reject SMTP calls from non-reserved hosts at times of
35247 high system load &-- for details see the &%smtp_accept_reserve%&,
35248 &%smtp_load_reserve%&, and &%smtp_reserve_hosts%& options. The load check
35249 applies in both the daemon and &'inetd'& cases.
35250
35251 Exim normally starts a delivery process for each message received, though this
35252 can be varied by means of the &%-odq%& command line option and the
35253 &%queue_only%&, &%queue_only_file%&, and &%queue_only_load%& options. The
35254 number of simultaneously running delivery processes started in this way from
35255 SMTP input can be limited by the &%smtp_accept_queue%& and
35256 &%smtp_accept_queue_per_connection%& options. When either limit is reached,
35257 subsequently received messages are just put on the input queue without starting
35258 a delivery process.
35259
35260 The controls that involve counts of incoming SMTP calls (&%smtp_accept_max%&,
35261 &%smtp_accept_queue%&, &%smtp_accept_reserve%&) are not available when Exim is
35262 started up from the &'inetd'& daemon, because in that case each connection is
35263 handled by an entirely independent Exim process. Control by load average is,
35264 however, available with &'inetd'&.
35265
35266 Exim can be configured to verify addresses in incoming SMTP commands as they
35267 are received. See chapter &<<CHAPACL>>& for details. It can also be configured
35268 to rewrite addresses at this time &-- before any syntax checking is done. See
35269 section &<<SECTrewriteS>>&.
35270
35271 Exim can also be configured to limit the rate at which a client host submits
35272 MAIL and RCPT commands in a single SMTP session. See the
35273 &%smtp_ratelimit_hosts%& option.
35274
35275
35276
35277 .section "Unrecognized SMTP commands" "SECID234"
35278 .cindex "SMTP" "unrecognized commands"
35279 If Exim receives more than &%smtp_max_unknown_commands%& unrecognized SMTP
35280 commands during a single SMTP connection, it drops the connection after sending
35281 the error response to the last command. The default value for
35282 &%smtp_max_unknown_commands%& is 3. This is a defence against some kinds of
35283 abuse that subvert web servers into making connections to SMTP ports; in these
35284 circumstances, a number of non-SMTP lines are sent first.
35285
35286
35287 .section "Syntax and protocol errors in SMTP commands" "SECID235"
35288 .cindex "SMTP" "syntax errors"
35289 .cindex "SMTP" "protocol errors"
35290 A syntax error is detected if an SMTP command is recognized, but there is
35291 something syntactically wrong with its data, for example, a malformed email
35292 address in a RCPT command. Protocol errors include invalid command
35293 sequencing such as RCPT before MAIL. If Exim receives more than
35294 &%smtp_max_synprot_errors%& such commands during a single SMTP connection, it
35295 drops the connection after sending the error response to the last command. The
35296 default value for &%smtp_max_synprot_errors%& is 3. This is a defence against
35297 broken clients that loop sending bad commands (yes, it has been seen).
35298
35299
35300
35301 .section "Use of non-mail SMTP commands" "SECID236"
35302 .cindex "SMTP" "non-mail commands"
35303 The &"non-mail"& SMTP commands are those other than MAIL, RCPT, and
35304 DATA. Exim counts such commands, and drops the connection if there are too
35305 many of them in a single SMTP session. This action catches some
35306 denial-of-service attempts and things like repeated failing AUTHs, or a mad
35307 client looping sending EHLO. The global option &%smtp_accept_max_nonmail%&
35308 defines what &"too many"& means. Its default value is 10.
35309
35310 When a new message is expected, one occurrence of RSET is not counted. This
35311 allows a client to send one RSET between messages (this is not necessary,
35312 but some clients do it). Exim also allows one uncounted occurrence of HELO
35313 or EHLO, and one occurrence of STARTTLS between messages. After
35314 starting up a TLS session, another EHLO is expected, and so it too is not
35315 counted.
35316
35317 The first occurrence of AUTH in a connection, or immediately following
35318 STARTTLS is also not counted. Otherwise, all commands other than MAIL,
35319 RCPT, DATA, and QUIT are counted.
35320
35321 You can control which hosts are subject to the limit set by
35322 &%smtp_accept_max_nonmail%& by setting
35323 &%smtp_accept_max_nonmail_hosts%&. The default value is &`*`&, which makes
35324 the limit apply to all hosts. This option means that you can exclude any
35325 specific badly-behaved hosts that you have to live with.
35326
35327
35328
35329
35330 .section "The VRFY and EXPN commands" "SECID237"
35331 When Exim receives a VRFY or EXPN command on a TCP/IP connection, it
35332 runs the ACL specified by &%acl_smtp_vrfy%& or &%acl_smtp_expn%& (as
35333 appropriate) in order to decide whether the command should be accepted or not.
35334
35335 .cindex "VRFY" "processing"
35336 When no ACL is defined for VRFY, or if it rejects without
35337 setting an explicit response code, the command is accepted
35338 (with a 252 SMTP response code)
35339 in order to support awkward clients that do a VRFY before every RCPT.
35340 When VRFY is accepted, it runs exactly the same code as when Exim is
35341 called with the &%-bv%& option, and returns 250/451/550
35342 SMTP response codes.
35343
35344 .cindex "EXPN" "processing"
35345 If no ACL for EXPN is defined, the command is rejected.
35346 When EXPN is accepted, a single-level expansion of the address is done.
35347 EXPN is treated as an &"address test"& (similar to the &%-bt%& option) rather
35348 than a verification (the &%-bv%& option). If an unqualified local part is given
35349 as the argument to EXPN, it is qualified with &%qualify_domain%&. Rejections
35350 of VRFY and EXPN commands are logged on the main and reject logs, and
35351 VRFY verification failures are logged on the main log for consistency with
35352 RCPT failures.
35353
35354
35355
35356 .section "The ETRN command" "SECTETRN"
35357 .cindex "ETRN" "processing"
35358 RFC 1985 describes an SMTP command called ETRN that is designed to
35359 overcome the security problems of the TURN command (which has fallen into
35360 disuse). When Exim receives an ETRN command on a TCP/IP connection, it runs
35361 the ACL specified by &%acl_smtp_etrn%& in order to decide whether the command
35362 should be accepted or not. If no ACL is defined, the command is rejected.
35363
35364 The ETRN command is concerned with &"releasing"& messages that are awaiting
35365 delivery to certain hosts. As Exim does not organize its message queue by host,
35366 the only form of ETRN that is supported by default is the one where the
35367 text starts with the &"#"& prefix, in which case the remainder of the text is
35368 specific to the SMTP server. A valid ETRN command causes a run of Exim with
35369 the &%-R%& option to happen, with the remainder of the ETRN text as its
35370 argument. For example,
35371 .code
35372 ETRN #brigadoon
35373 .endd
35374 runs the command
35375 .code
35376 exim -R brigadoon
35377 .endd
35378 which causes a delivery attempt on all messages with undelivered addresses
35379 containing the text &"brigadoon"&. When &%smtp_etrn_serialize%& is set (the
35380 default), Exim prevents the simultaneous execution of more than one queue run
35381 for the same argument string as a result of an ETRN command. This stops
35382 a misbehaving client from starting more than one queue runner at once.
35383
35384 .cindex "hints database" "ETRN serialization"
35385 Exim implements the serialization by means of a hints database in which a
35386 record is written whenever a process is started by ETRN, and deleted when
35387 the process completes. However, Exim does not keep the SMTP session waiting for
35388 the ETRN process to complete. Once ETRN is accepted, the client is sent
35389 a &"success"& return code. Obviously there is scope for hints records to get
35390 left lying around if there is a system or program crash. To guard against this,
35391 Exim ignores any records that are more than six hours old.
35392
35393 .oindex "&%smtp_etrn_command%&"
35394 For more control over what ETRN does, the &%smtp_etrn_command%& option can
35395 used. This specifies a command that is run whenever ETRN is received,
35396 whatever the form of its argument. For
35397 example:
35398 .code
35399 smtp_etrn_command = /etc/etrn_command $domain \
35400                     $sender_host_address
35401 .endd
35402 .vindex "&$domain$&"
35403 The string is split up into arguments which are independently expanded. The
35404 expansion variable &$domain$& is set to the argument of the ETRN command,
35405 and no syntax checking is done on the contents of this argument. Exim does not
35406 wait for the command to complete, so its status code is not checked. Exim runs
35407 under its own uid and gid when receiving incoming SMTP, so it is not possible
35408 for it to change them before running the command.
35409
35410
35411
35412 .section "Incoming local SMTP" "SECID238"
35413 .cindex "SMTP" "local incoming"
35414 Some user agents use SMTP to pass messages to their local MTA using the
35415 standard input and output, as opposed to passing the envelope on the command
35416 line and writing the message to the standard input. This is supported by the
35417 &%-bs%& option. This form of SMTP is handled in the same way as incoming
35418 messages over TCP/IP (including the use of ACLs), except that the envelope
35419 sender given in a MAIL command is ignored unless the caller is trusted. In
35420 an ACL you can detect this form of SMTP input by testing for an empty host
35421 identification. It is common to have this as the first line in the ACL that
35422 runs for RCPT commands:
35423 .code
35424 accept hosts = :
35425 .endd
35426 This accepts SMTP messages from local processes without doing any other tests.
35427
35428
35429
35430 .section "Outgoing batched SMTP" "SECTbatchSMTP"
35431 .cindex "SMTP" "batched outgoing"
35432 .cindex "batched SMTP output"
35433 Both the &(appendfile)& and &(pipe)& transports can be used for handling
35434 batched SMTP. Each has an option called &%use_bsmtp%& which causes messages to
35435 be output in BSMTP format. No SMTP responses are possible for this form of
35436 delivery. All it is doing is using SMTP commands as a way of transmitting the
35437 envelope along with the message.
35438
35439 The message is written to the file or pipe preceded by the SMTP commands
35440 MAIL and RCPT, and followed by a line containing a single dot. Lines in
35441 the message that start with a dot have an extra dot added. The SMTP command
35442 HELO is not normally used. If it is required, the &%message_prefix%& option
35443 can be used to specify it.
35444
35445 Because &(appendfile)& and &(pipe)& are both local transports, they accept only
35446 one recipient address at a time by default. However, you can arrange for them
35447 to handle several addresses at once by setting the &%batch_max%& option. When
35448 this is done for BSMTP, messages may contain multiple RCPT commands. See
35449 chapter &<<CHAPbatching>>& for more details.
35450
35451 .vindex "&$host$&"
35452 When one or more addresses are routed to a BSMTP transport by a router that
35453 sets up a host list, the name of the first host on the list is available to the
35454 transport in the variable &$host$&. Here is an example of such a transport and
35455 router:
35456 .code
35457 begin routers
35458 route_append:
35459   driver = manualroute
35460   transport = smtp_appendfile
35461   route_list = domain.example  batch.host.example
35462
35463 begin transports
35464 smtp_appendfile:
35465   driver = appendfile
35466   directory = /var/bsmtp/$host
35467   batch_max = 1000
35468   use_bsmtp
35469   user = exim
35470 .endd
35471 This causes messages addressed to &'domain.example'& to be written in BSMTP
35472 format to &_/var/bsmtp/batch.host.example_&, with only a single copy of each
35473 message (unless there are more than 1000 recipients).
35474
35475
35476
35477 .section "Incoming batched SMTP" "SECTincomingbatchedSMTP"
35478 .cindex "SMTP" "batched incoming"
35479 .cindex "batched SMTP input"
35480 The &%-bS%& command line option causes Exim to accept one or more messages by
35481 reading SMTP on the standard input, but to generate no responses. If the caller
35482 is trusted, the senders in the MAIL commands are believed; otherwise the
35483 sender is always the caller of Exim. Unqualified senders and receivers are not
35484 rejected (there seems little point) but instead just get qualified. HELO
35485 and EHLO act as RSET; VRFY, EXPN, ETRN and  HELP, act
35486 as NOOP; QUIT quits.
35487
35488 Minimal policy checking is done for BSMTP input. Only the non-SMTP
35489 ACL is run in the same way as for non-SMTP local input.
35490
35491 If an error is detected while reading a message, including a missing &"."& at
35492 the end, Exim gives up immediately. It writes details of the error to the
35493 standard output in a stylized way that the calling program should be able to
35494 make some use of automatically, for example:
35495 .code
35496 554 Unexpected end of file
35497 Transaction started in line 10
35498 Error detected in line 14
35499 .endd
35500 It writes a more verbose version, for human consumption, to the standard error
35501 file, for example:
35502 .code
35503 An error was detected while processing a file of BSMTP input.
35504 The error message was:
35505
35506 501 '>' missing at end of address
35507
35508 The SMTP transaction started in line 10.
35509 The error was detected in line 12.
35510 The SMTP command at fault was:
35511
35512 rcpt to:<malformed@in.com.plete
35513
35514 1 previous message was successfully processed.
35515 The rest of the batch was abandoned.
35516 .endd
35517 The return code from Exim is zero only if there were no errors. It is 1 if some
35518 messages were accepted before an error was detected, and 2 if no messages were
35519 accepted.
35520 .ecindex IIDsmtpproc1
35521 .ecindex IIDsmtpproc2
35522
35523
35524
35525 . ////////////////////////////////////////////////////////////////////////////
35526 . ////////////////////////////////////////////////////////////////////////////
35527
35528 .chapter "Customizing bounce and warning messages" "CHAPemsgcust" &&&
35529          "Customizing messages"
35530 When a message fails to be delivered, or remains on the queue for more than a
35531 configured amount of time, Exim sends a message to the original sender, or
35532 to an alternative configured address. The text of these messages is built into
35533 the code of Exim, but it is possible to change it, either by adding a single
35534 string, or by replacing each of the paragraphs by text supplied in a file.
35535
35536 The &'From:'& and &'To:'& header lines are automatically generated; you can
35537 cause a &'Reply-To:'& line to be added by setting the &%errors_reply_to%&
35538 option. Exim also adds the line
35539 .code
35540 Auto-Submitted: auto-generated
35541 .endd
35542 to all warning and bounce messages,
35543
35544
35545 .section "Customizing bounce messages" "SECID239"
35546 .cindex "customizing" "bounce message"
35547 .cindex "bounce message" "customizing"
35548 If &%bounce_message_text%& is set, its contents are included in the default
35549 message immediately after &"This message was created automatically by mail
35550 delivery software."& The string is not expanded. It is not used if
35551 &%bounce_message_file%& is set.
35552
35553 When &%bounce_message_file%& is set, it must point to a template file for
35554 constructing error messages. The file consists of a series of text items,
35555 separated by lines consisting of exactly four asterisks. If the file cannot be
35556 opened, default text is used and a message is written to the main and panic
35557 logs. If any text item in the file is empty, default text is used for that
35558 item.
35559
35560 .vindex "&$bounce_recipient$&"
35561 .vindex "&$bounce_return_size_limit$&"
35562 Each item of text that is read from the file is expanded, and there are two
35563 expansion variables which can be of use here: &$bounce_recipient$& is set to
35564 the recipient of an error message while it is being created, and
35565 &$bounce_return_size_limit$& contains the value of the &%return_size_limit%&
35566 option, rounded to a whole number.
35567
35568 The items must appear in the file in the following order:
35569
35570 .ilist
35571 The first item is included in the headers, and should include at least a
35572 &'Subject:'& header. Exim does not check the syntax of these headers.
35573 .next
35574 The second item forms the start of the error message. After it, Exim lists the
35575 failing addresses with their error messages.
35576 .next
35577 The third item is used to introduce any text from pipe transports that is to be
35578 returned to the sender. It is omitted if there is no such text.
35579 .next
35580 The fourth, fifth and sixth items will be ignored and may be empty.
35581 The fields exist for back-compatibility
35582 .endlist
35583
35584 The default state (&%bounce_message_file%& unset) is equivalent to the
35585 following file, in which the sixth item is empty. The &'Subject:'& and some
35586 other lines have been split in order to fit them on the page:
35587 .code
35588 Subject: Mail delivery failed
35589   ${if eq{$sender_address}{$bounce_recipient}
35590   {: returning message to sender}}
35591 ****
35592 This message was created automatically by mail delivery software.
35593
35594 A message ${if eq{$sender_address}{$bounce_recipient}
35595   {that you sent }{sent by
35596
35597 <$sender_address>
35598
35599 }}could not be delivered to all of its recipients.
35600 This is a permanent error. The following address(es) failed:
35601 ****
35602 The following text was generated during the delivery attempt(s):
35603 ****
35604 ------ This is a copy of the message, including all the headers.
35605   ------
35606 ****
35607 ------ The body of the message is $message_size characters long;
35608   only the first
35609 ------ $bounce_return_size_limit or so are included here.
35610 ****
35611 .endd
35612 .section "Customizing warning messages" "SECTcustwarn"
35613 .cindex "customizing" "warning message"
35614 .cindex "warning of delay" "customizing the message"
35615 The option &%warn_message_file%& can be pointed at a template file for use when
35616 warnings about message delays are created. In this case there are only three
35617 text sections:
35618
35619 .ilist
35620 The first item is included in the headers, and should include at least a
35621 &'Subject:'& header. Exim does not check the syntax of these headers.
35622 .next
35623 The second item forms the start of the warning message. After it, Exim lists
35624 the delayed addresses.
35625 .next
35626 The third item then ends the message.
35627 .endlist
35628
35629 The default state is equivalent to the following file, except that some lines
35630 have been split here, in order to fit them on the page:
35631 .code
35632 Subject: Warning: message $message_exim_id delayed
35633   $warn_message_delay
35634 ****
35635 This message was created automatically by mail delivery software.
35636
35637 A message ${if eq{$sender_address}{$warn_message_recipients}
35638 {that you sent }{sent by
35639
35640 <$sender_address>
35641
35642 }}has not been delivered to all of its recipients after
35643 more than $warn_message_delay on the queue on $primary_hostname.
35644
35645 The message identifier is:     $message_exim_id
35646 The subject of the message is: $h_subject
35647 The date of the message is:    $h_date
35648
35649 The following address(es) have not yet been delivered:
35650 ****
35651 No action is required on your part. Delivery attempts will
35652 continue for some time, and this warning may be repeated at
35653 intervals if the message remains undelivered. Eventually the
35654 mail delivery software will give up, and when that happens,
35655 the message will be returned to you.
35656 .endd
35657 .vindex "&$warn_message_delay$&"
35658 .vindex "&$warn_message_recipients$&"
35659 However, in the default state the subject and date lines are omitted if no
35660 appropriate headers exist. During the expansion of this file,
35661 &$warn_message_delay$& is set to the delay time in one of the forms &"<&'n'&>
35662 minutes"& or &"<&'n'&> hours"&, and &$warn_message_recipients$& contains a list
35663 of recipients for the warning message. There may be more than one if there are
35664 multiple addresses with different &%errors_to%& settings on the routers that
35665 handled them.
35666
35667
35668
35669
35670 . ////////////////////////////////////////////////////////////////////////////
35671 . ////////////////////////////////////////////////////////////////////////////
35672
35673 .chapter "Some common configuration settings" "CHAPcomconreq"
35674 This chapter discusses some configuration settings that seem to be fairly
35675 common. More examples and discussion can be found in the Exim book.
35676
35677
35678
35679 .section "Sending mail to a smart host" "SECID240"
35680 .cindex "smart host" "example router"
35681 If you want to send all mail for non-local domains to a &"smart host"&, you
35682 should replace the default &(dnslookup)& router with a router which does the
35683 routing explicitly:
35684 .code
35685 send_to_smart_host:
35686   driver = manualroute
35687   route_list = !+local_domains smart.host.name
35688   transport = remote_smtp
35689 .endd
35690 You can use the smart host's IP address instead of the name if you wish.
35691 If you are using Exim only to submit messages to a smart host, and not for
35692 receiving incoming messages, you can arrange for it to do the submission
35693 synchronously by setting the &%mua_wrapper%& option (see chapter
35694 &<<CHAPnonqueueing>>&).
35695
35696
35697
35698
35699 .section "Using Exim to handle mailing lists" "SECTmailinglists"
35700 .cindex "mailing lists"
35701 Exim can be used to run simple mailing lists, but for large and/or complicated
35702 requirements, the use of additional specialized mailing list software such as
35703 Majordomo or Mailman is recommended.
35704
35705 The &(redirect)& router can be used to handle mailing lists where each list
35706 is maintained in a separate file, which can therefore be managed by an
35707 independent manager. The &%domains%& router option can be used to run these
35708 lists in a separate domain from normal mail. For example:
35709 .code
35710 lists:
35711   driver = redirect
35712   domains = lists.example
35713   file = /usr/lists/$local_part
35714   forbid_pipe
35715   forbid_file
35716   errors_to = $local_part-request@lists.example
35717   no_more
35718 .endd
35719 This router is skipped for domains other than &'lists.example'&. For addresses
35720 in that domain, it looks for a file that matches the local part. If there is no
35721 such file, the router declines, but because &%no_more%& is set, no subsequent
35722 routers are tried, and so the whole delivery fails.
35723
35724 The &%forbid_pipe%& and &%forbid_file%& options prevent a local part from being
35725 expanded into a file name or a pipe delivery, which is usually inappropriate in
35726 a mailing list.
35727
35728 .oindex "&%errors_to%&"
35729 The &%errors_to%& option specifies that any delivery errors caused by addresses
35730 taken from a mailing list are to be sent to the given address rather than the
35731 original sender of the message. However, before acting on this, Exim verifies
35732 the error address, and ignores it if verification fails.
35733
35734 For example, using the configuration above, mail sent to
35735 &'dicts@lists.example'& is passed on to those addresses contained in
35736 &_/usr/lists/dicts_&, with error reports directed to
35737 &'dicts-request@lists.example'&, provided that this address can be verified.
35738 There could be a file called &_/usr/lists/dicts-request_& containing
35739 the address(es) of this particular list's manager(s), but other approaches,
35740 such as setting up an earlier router (possibly using the &%local_part_prefix%&
35741 or &%local_part_suffix%& options) to handle addresses of the form
35742 &%owner-%&&'xxx'& or &%xxx-%&&'request'&, are also possible.
35743
35744
35745
35746 .section "Syntax errors in mailing lists" "SECID241"
35747 .cindex "mailing lists" "syntax errors in"
35748 If an entry in redirection data contains a syntax error, Exim normally defers
35749 delivery of the original address. That means that a syntax error in a mailing
35750 list holds up all deliveries to the list. This may not be appropriate when a
35751 list is being maintained automatically from data supplied by users, and the
35752 addresses are not rigorously checked.
35753
35754 If the &%skip_syntax_errors%& option is set, the &(redirect)& router just skips
35755 entries that fail to parse, noting the incident in the log. If in addition
35756 &%syntax_errors_to%& is set to a verifiable address, a message is sent to it
35757 whenever a broken address is skipped. It is usually appropriate to set
35758 &%syntax_errors_to%& to the same address as &%errors_to%&.
35759
35760
35761
35762 .section "Re-expansion of mailing lists" "SECID242"
35763 .cindex "mailing lists" "re-expansion of"
35764 Exim remembers every individual address to which a message has been delivered,
35765 in order to avoid duplication, but it normally stores only the original
35766 recipient addresses with a message. If all the deliveries to a mailing list
35767 cannot be done at the first attempt, the mailing list is re-expanded when the
35768 delivery is next tried. This means that alterations to the list are taken into
35769 account at each delivery attempt, so addresses that have been added to
35770 the list since the message arrived will therefore receive a copy of the
35771 message, even though it pre-dates their subscription.
35772
35773 If this behaviour is felt to be undesirable, the &%one_time%& option can be set
35774 on the &(redirect)& router. If this is done, any addresses generated by the
35775 router that fail to deliver at the first attempt are added to the message as
35776 &"top level"& addresses, and the parent address that generated them is marked
35777 &"delivered"&. Thus, expansion of the mailing list does not happen again at the
35778 subsequent delivery attempts. The disadvantage of this is that if any of the
35779 failing addresses are incorrect, correcting them in the file has no effect on
35780 pre-existing messages.
35781
35782 The original top-level address is remembered with each of the generated
35783 addresses, and is output in any log messages. However, any intermediate parent
35784 addresses are not recorded. This makes a difference to the log only if the
35785 &%all_parents%& selector is set, but for mailing lists there is normally only
35786 one level of expansion anyway.
35787
35788
35789
35790 .section "Closed mailing lists" "SECID243"
35791 .cindex "mailing lists" "closed"
35792 The examples so far have assumed open mailing lists, to which anybody may
35793 send mail. It is also possible to set up closed lists, where mail is accepted
35794 from specified senders only. This is done by making use of the generic
35795 &%senders%& option to restrict the router that handles the list.
35796
35797 The following example uses the same file as a list of recipients and as a list
35798 of permitted senders. It requires three routers:
35799 .code
35800 lists_request:
35801   driver = redirect
35802   domains = lists.example
35803   local_part_suffix = -request
35804   file = /usr/lists/$local_part$local_part_suffix
35805   no_more
35806
35807 lists_post:
35808   driver = redirect
35809   domains = lists.example
35810   senders = ${if exists {/usr/lists/$local_part}\
35811              {lsearch;/usr/lists/$local_part}{*}}
35812   file = /usr/lists/$local_part
35813   forbid_pipe
35814   forbid_file
35815   errors_to = $local_part-request@lists.example
35816   no_more
35817
35818 lists_closed:
35819   driver = redirect
35820   domains = lists.example
35821   allow_fail
35822   data = :fail: $local_part@lists.example is a closed mailing list
35823 .endd
35824 All three routers have the same &%domains%& setting, so for any other domains,
35825 they are all skipped. The first router runs only if the local part ends in
35826 &%-request%&. It handles messages to the list manager(s) by means of an open
35827 mailing list.
35828
35829 The second router runs only if the &%senders%& precondition is satisfied. It
35830 checks for the existence of a list that corresponds to the local part, and then
35831 checks that the sender is on the list by means of a linear search. It is
35832 necessary to check for the existence of the file before trying to search it,
35833 because otherwise Exim thinks there is a configuration error. If the file does
35834 not exist, the expansion of &%senders%& is *, which matches all senders. This
35835 means that the router runs, but because there is no list, declines, and
35836 &%no_more%& ensures that no further routers are run. The address fails with an
35837 &"unrouteable address"& error.
35838
35839 The third router runs only if the second router is skipped, which happens when
35840 a mailing list exists, but the sender is not on it. This router forcibly fails
35841 the address, giving a suitable error message.
35842
35843
35844
35845
35846 .section "Variable Envelope Return Paths (VERP)" "SECTverp"
35847 .cindex "VERP"
35848 .cindex "Variable Envelope Return Paths"
35849 .cindex "envelope sender"
35850 Variable Envelope Return Paths &-- see &url(https://cr.yp.to/proto/verp.txt) &--
35851 are a way of helping mailing list administrators discover which subscription
35852 address is the cause of a particular delivery failure. The idea is to encode
35853 the original recipient address in the outgoing envelope sender address, so that
35854 if the message is forwarded by another host and then subsequently bounces, the
35855 original recipient can be extracted from the recipient address of the bounce.
35856
35857 .oindex &%errors_to%&
35858 .oindex &%return_path%&
35859 Envelope sender addresses can be modified by Exim using two different
35860 facilities: the &%errors_to%& option on a router (as shown in previous mailing
35861 list examples), or the &%return_path%& option on a transport. The second of
35862 these is effective only if the message is successfully delivered to another
35863 host; it is not used for errors detected on the local host (see the description
35864 of &%return_path%& in chapter &<<CHAPtransportgeneric>>&). Here is an example
35865 of the use of &%return_path%& to implement VERP on an &(smtp)& transport:
35866 .code
35867 verp_smtp:
35868   driver = smtp
35869   max_rcpt = 1
35870   return_path = \
35871     ${if match {$return_path}{^(.+?)-request@your.dom.example\$}\
35872       {$1-request+$local_part=$domain@your.dom.example}fail}
35873 .endd
35874 This has the effect of rewriting the return path (envelope sender) on outgoing
35875 SMTP messages, if the local part of the original return path ends in
35876 &"-request"&, and the domain is &'your.dom.example'&. The rewriting inserts the
35877 local part and domain of the recipient into the return path. Suppose, for
35878 example, that a message whose return path has been set to
35879 &'somelist-request@your.dom.example'& is sent to
35880 &'subscriber@other.dom.example'&. In the transport, the return path is
35881 rewritten as
35882 .code
35883 somelist-request+subscriber=other.dom.example@your.dom.example
35884 .endd
35885 .vindex "&$local_part$&"
35886 For this to work, you must tell Exim to send multiple copies of messages that
35887 have more than one recipient, so that each copy has just one recipient. This is
35888 achieved by setting &%max_rcpt%& to 1. Without this, a single copy of a message
35889 might be sent to several different recipients in the same domain, in which case
35890 &$local_part$& is not available in the transport, because it is not unique.
35891
35892 Unless your host is doing nothing but mailing list deliveries, you should
35893 probably use a separate transport for the VERP deliveries, so as not to use
35894 extra resources in making one-per-recipient copies for other deliveries. This
35895 can easily be done by expanding the &%transport%& option in the router:
35896 .code
35897 dnslookup:
35898   driver = dnslookup
35899   domains = ! +local_domains
35900   transport = \
35901     ${if match {$return_path}{^(.+?)-request@your.dom.example\$}\
35902       {verp_smtp}{remote_smtp}}
35903   no_more
35904 .endd
35905 If you want to change the return path using &%errors_to%& in a router instead
35906 of using &%return_path%& in the transport, you need to set &%errors_to%& on all
35907 routers that handle mailing list addresses. This will ensure that all delivery
35908 errors, including those detected on the local host, are sent to the VERP
35909 address.
35910
35911 On a host that does no local deliveries and has no manual routing, only the
35912 &(dnslookup)& router needs to be changed. A special transport is not needed for
35913 SMTP deliveries. Every mailing list recipient has its own return path value,
35914 and so Exim must hand them to the transport one at a time. Here is an example
35915 of a &(dnslookup)& router that implements VERP:
35916 .code
35917 verp_dnslookup:
35918   driver = dnslookup
35919   domains = ! +local_domains
35920   transport = remote_smtp
35921   errors_to = \
35922     ${if match {$return_path}{^(.+?)-request@your.dom.example\$}}
35923      {$1-request+$local_part=$domain@your.dom.example}fail}
35924   no_more
35925 .endd
35926 Before you start sending out messages with VERPed return paths, you must also
35927 configure Exim to accept the bounce messages that come back to those paths.
35928 Typically this is done by setting a &%local_part_suffix%& option for a
35929 router, and using this to route the messages to wherever you want to handle
35930 them.
35931
35932 The overhead incurred in using VERP depends very much on the size of the
35933 message, the number of recipient addresses that resolve to the same remote
35934 host, and the speed of the connection over which the message is being sent. If
35935 a lot of addresses resolve to the same host and the connection is slow, sending
35936 a separate copy of the message for each address may take substantially longer
35937 than sending a single copy with many recipients (for which VERP cannot be
35938 used).
35939
35940
35941
35942
35943
35944
35945 .section "Virtual domains" "SECTvirtualdomains"
35946 .cindex "virtual domains"
35947 .cindex "domain" "virtual"
35948 The phrase &'virtual domain'& is unfortunately used with two rather different
35949 meanings:
35950
35951 .ilist
35952 A domain for which there are no real mailboxes; all valid local parts are
35953 aliases for other email addresses. Common examples are organizational
35954 top-level domains and &"vanity"& domains.
35955 .next
35956 One of a number of independent domains that are all handled by the same host,
35957 with mailboxes on that host, but where the mailbox owners do not necessarily
35958 have login accounts on that host.
35959 .endlist
35960
35961 The first usage is probably more common, and does seem more &"virtual"& than
35962 the second. This kind of domain can be handled in Exim with a straightforward
35963 aliasing router. One approach is to create a separate alias file for each
35964 virtual domain. Exim can test for the existence of the alias file to determine
35965 whether the domain exists. The &(dsearch)& lookup type is useful here, leading
35966 to a router of this form:
35967 .code
35968 virtual:
35969   driver = redirect
35970   domains = dsearch;/etc/mail/virtual
35971   data = ${lookup{$local_part}lsearch{/etc/mail/virtual/$domain}}
35972   no_more
35973 .endd
35974 The &%domains%& option specifies that the router is to be skipped, unless there
35975 is a file in the &_/etc/mail/virtual_& directory whose name is the same as the
35976 domain that is being processed. When the router runs, it looks up the local
35977 part in the file to find a new address (or list of addresses). The &%no_more%&
35978 setting ensures that if the lookup fails (leading to &%data%& being an empty
35979 string), Exim gives up on the address without trying any subsequent routers.
35980
35981 This one router can handle all the virtual domains because the alias file names
35982 follow a fixed pattern. Permissions can be arranged so that appropriate people
35983 can edit the different alias files. A successful aliasing operation results in
35984 a new envelope recipient address, which is then routed from scratch.
35985
35986 The other kind of &"virtual"& domain can also be handled in a straightforward
35987 way. One approach is to create a file for each domain containing a list of
35988 valid local parts, and use it in a router like this:
35989 .code
35990 my_domains:
35991   driver = accept
35992   domains = dsearch;/etc/mail/domains
35993   local_parts = lsearch;/etc/mail/domains/$domain
35994   transport = my_mailboxes
35995 .endd
35996 The address is accepted if there is a file for the domain, and the local part
35997 can be found in the file. The &%domains%& option is used to check for the
35998 file's existence because &%domains%& is tested before the &%local_parts%&
35999 option (see section &<<SECTrouprecon>>&). You cannot use &%require_files%&,
36000 because that option is tested after &%local_parts%&. The transport is as
36001 follows:
36002 .code
36003 my_mailboxes:
36004   driver = appendfile
36005   file = /var/mail/$domain/$local_part
36006   user = mail
36007 .endd
36008 This uses a directory of mailboxes for each domain. The &%user%& setting is
36009 required, to specify which uid is to be used for writing to the mailboxes.
36010
36011 The configuration shown here is just one example of how you might support this
36012 requirement. There are many other ways this kind of configuration can be set
36013 up, for example, by using a database instead of separate files to hold all the
36014 information about the domains.
36015
36016
36017
36018 .section "Multiple user mailboxes" "SECTmulbox"
36019 .cindex "multiple mailboxes"
36020 .cindex "mailbox" "multiple"
36021 .cindex "local part" "prefix"
36022 .cindex "local part" "suffix"
36023 Heavy email users often want to operate with multiple mailboxes, into which
36024 incoming mail is automatically sorted. A popular way of handling this is to
36025 allow users to use multiple sender addresses, so that replies can easily be
36026 identified. Users are permitted to add prefixes or suffixes to their local
36027 parts for this purpose. The wildcard facility of the generic router options
36028 &%local_part_prefix%& and &%local_part_suffix%& can be used for this. For
36029 example, consider this router:
36030 .code
36031 userforward:
36032   driver = redirect
36033   check_local_user
36034   file = $home/.forward
36035   local_part_suffix = -*
36036   local_part_suffix_optional
36037   allow_filter
36038 .endd
36039 .vindex "&$local_part_suffix$&"
36040 It runs a user's &_.forward_& file for all local parts of the form
36041 &'username-*'&. Within the filter file the user can distinguish different
36042 cases by testing the variable &$local_part_suffix$&. For example:
36043 .code
36044 if $local_part_suffix contains -special then
36045 save /home/$local_part/Mail/special
36046 endif
36047 .endd
36048 If the filter file does not exist, or does not deal with such addresses, they
36049 fall through to subsequent routers, and, assuming no subsequent use of the
36050 &%local_part_suffix%& option is made, they presumably fail. Thus, users have
36051 control over which suffixes are valid.
36052
36053 Alternatively, a suffix can be used to trigger the use of a different
36054 &_.forward_& file &-- which is the way a similar facility is implemented in
36055 another MTA:
36056 .code
36057 userforward:
36058   driver = redirect
36059   check_local_user
36060   file = $home/.forward$local_part_suffix
36061   local_part_suffix = -*
36062   local_part_suffix_optional
36063   allow_filter
36064 .endd
36065 If there is no suffix, &_.forward_& is used; if the suffix is &'-special'&, for
36066 example, &_.forward-special_& is used. Once again, if the appropriate file
36067 does not exist, or does not deal with the address, it is passed on to
36068 subsequent routers, which could, if required, look for an unqualified
36069 &_.forward_& file to use as a default.
36070
36071
36072
36073 .section "Simplified vacation processing" "SECID244"
36074 .cindex "vacation processing"
36075 The traditional way of running the &'vacation'& program is for a user to set up
36076 a pipe command in a &_.forward_& file
36077 (see section &<<SECTspecitredli>>& for syntax details).
36078 This is prone to error by inexperienced users. There are two features of Exim
36079 that can be used to make this process simpler for users:
36080
36081 .ilist
36082 A local part prefix such as &"vacation-"& can be specified on a router which
36083 can cause the message to be delivered directly to the &'vacation'& program, or
36084 alternatively can use Exim's &(autoreply)& transport. The contents of a user's
36085 &_.forward_& file are then much simpler. For example:
36086 .code
36087 spqr, vacation-spqr
36088 .endd
36089 .next
36090 The &%require_files%& generic router option can be used to trigger a
36091 vacation delivery by checking for the existence of a certain file in the
36092 user's home directory. The &%unseen%& generic option should also be used, to
36093 ensure that the original delivery also proceeds. In this case, all the user has
36094 to do is to create a file called, say, &_.vacation_&, containing a vacation
36095 message.
36096 .endlist
36097
36098 Another advantage of both these methods is that they both work even when the
36099 use of arbitrary pipes by users is locked out.
36100
36101
36102
36103 .section "Taking copies of mail" "SECID245"
36104 .cindex "message" "copying every"
36105 Some installations have policies that require archive copies of all messages to
36106 be made. A single copy of each message can easily be taken by an appropriate
36107 command in a system filter, which could, for example, use a different file for
36108 each day's messages.
36109
36110 There is also a shadow transport mechanism that can be used to take copies of
36111 messages that are successfully delivered by local transports, one copy per
36112 delivery. This could be used, &'inter alia'&, to implement automatic
36113 notification of delivery by sites that insist on doing such things.
36114
36115
36116
36117 .section "Intermittently connected hosts" "SECID246"
36118 .cindex "intermittently connected hosts"
36119 It has become quite common (because it is cheaper) for hosts to connect to the
36120 Internet periodically rather than remain connected all the time. The normal
36121 arrangement is that mail for such hosts accumulates on a system that is
36122 permanently connected.
36123
36124 Exim was designed for use on permanently connected hosts, and so it is not
36125 particularly well-suited to use in an intermittently connected environment.
36126 Nevertheless there are some features that can be used.
36127
36128
36129 .section "Exim on the upstream server host" "SECID247"
36130 It is tempting to arrange for incoming mail for the intermittently connected
36131 host to remain on Exim's queue until the client connects. However, this
36132 approach does not scale very well. Two different kinds of waiting message are
36133 being mixed up in the same queue &-- those that cannot be delivered because of
36134 some temporary problem, and those that are waiting for their destination host
36135 to connect. This makes it hard to manage the queue, as well as wasting
36136 resources, because each queue runner scans the entire queue.
36137
36138 A better approach is to separate off those messages that are waiting for an
36139 intermittently connected host. This can be done by delivering these messages
36140 into local files in batch SMTP, &"mailstore"&, or other envelope-preserving
36141 format, from where they are transmitted by other software when their
36142 destination connects. This makes it easy to collect all the mail for one host
36143 in a single directory, and to apply local timeout rules on a per-message basis
36144 if required.
36145
36146 On a very small scale, leaving the mail on Exim's queue can be made to work. If
36147 you are doing this, you should configure Exim with a long retry period for the
36148 intermittent host. For example:
36149 .code
36150 cheshire.wonderland.fict.example    *   F,5d,24h
36151 .endd
36152 This stops a lot of failed delivery attempts from occurring, but Exim remembers
36153 which messages it has queued up for that host. Once the intermittent host comes
36154 online, forcing delivery of one message (either by using the &%-M%& or &%-R%&
36155 options, or by using the ETRN SMTP command (see section &<<SECTETRN>>&)
36156 causes all the queued up messages to be delivered, often down a single SMTP
36157 connection. While the host remains connected, any new messages get delivered
36158 immediately.
36159
36160 If the connecting hosts do not have fixed IP addresses, that is, if a host is
36161 issued with a different IP address each time it connects, Exim's retry
36162 mechanisms on the holding host get confused, because the IP address is normally
36163 used as part of the key string for holding retry information. This can be
36164 avoided by unsetting &%retry_include_ip_address%& on the &(smtp)& transport.
36165 Since this has disadvantages for permanently connected hosts, it is best to
36166 arrange a separate transport for the intermittently connected ones.
36167
36168
36169
36170 .section "Exim on the intermittently connected client host" "SECID248"
36171 The value of &%smtp_accept_queue_per_connection%& should probably be
36172 increased, or even set to zero (that is, disabled) on the intermittently
36173 connected host, so that all incoming messages down a single connection get
36174 delivered immediately.
36175
36176 .cindex "SMTP" "passed connection"
36177 .cindex "SMTP" "multiple deliveries"
36178 .cindex "multiple SMTP deliveries"
36179 Mail waiting to be sent from an intermittently connected host will probably
36180 not have been routed, because without a connection DNS lookups are not
36181 possible. This means that if a normal queue run is done at connection time,
36182 each message is likely to be sent in a separate SMTP session. This can be
36183 avoided by starting the queue run with a command line option beginning with
36184 &%-qq%& instead of &%-q%&. In this case, the queue is scanned twice. In the
36185 first pass, routing is done but no deliveries take place. The second pass is a
36186 normal queue run; since all the messages have been previously routed, those
36187 destined for the same host are likely to get sent as multiple deliveries in a
36188 single SMTP connection.
36189
36190
36191
36192 . ////////////////////////////////////////////////////////////////////////////
36193 . ////////////////////////////////////////////////////////////////////////////
36194
36195 .chapter "Using Exim as a non-queueing client" "CHAPnonqueueing" &&&
36196          "Exim as a non-queueing client"
36197 .cindex "client, non-queueing"
36198 .cindex "smart host" "suppressing queueing"
36199 On a personal computer, it is a common requirement for all
36200 email to be sent to a &"smart host"&. There are plenty of MUAs that can be
36201 configured to operate that way, for all the popular operating systems.
36202 However, there are some MUAs for Unix-like systems that cannot be so
36203 configured: they submit messages using the command line interface of
36204 &_/usr/sbin/sendmail_&. Furthermore, utility programs such as &'cron'& submit
36205 messages this way.
36206
36207 If the personal computer runs continuously, there is no problem, because it can
36208 run a conventional MTA that handles delivery to the smart host, and deal with
36209 any delays via its queueing mechanism. However, if the computer does not run
36210 continuously or runs different operating systems at different times, queueing
36211 email is not desirable.
36212
36213 There is therefore a requirement for something that can provide the
36214 &_/usr/sbin/sendmail_& interface but deliver messages to a smart host without
36215 any queueing or retrying facilities. Furthermore, the delivery to the smart
36216 host should be synchronous, so that if it fails, the sending MUA is immediately
36217 informed. In other words, we want something that extends an MUA that submits
36218 to a local MTA via the command line so that it behaves like one that submits
36219 to a remote smart host using TCP/SMTP.
36220
36221 There are a number of applications (for example, there is one called &'ssmtp'&)
36222 that do this job. However, people have found them to be lacking in various
36223 ways. For instance, you might want to allow aliasing and forwarding to be done
36224 before sending a message to the smart host.
36225
36226 Exim already had the necessary infrastructure for doing this job. Just a few
36227 tweaks were needed to make it behave as required, though it is somewhat of an
36228 overkill to use a fully-featured MTA for this purpose.
36229
36230 .oindex "&%mua_wrapper%&"
36231 There is a Boolean global option called &%mua_wrapper%&, defaulting false.
36232 Setting &%mua_wrapper%& true causes Exim to run in a special mode where it
36233 assumes that it is being used to &"wrap"& a command-line MUA in the manner
36234 just described. As well as setting &%mua_wrapper%&, you also need to provide a
36235 compatible router and transport configuration. Typically there will be just one
36236 router and one transport, sending everything to a smart host.
36237
36238 When run in MUA wrapping mode, the behaviour of Exim changes in the
36239 following ways:
36240
36241 .ilist
36242 A daemon cannot be run, nor will Exim accept incoming messages from &'inetd'&.
36243 In other words, the only way to submit messages is via the command line.
36244 .next
36245 Each message is synchronously delivered as soon as it is received (&%-odi%& is
36246 assumed). All queueing options (&%queue_only%&, &%queue_smtp_domains%&,
36247 &%control%& in an ACL, etc.) are quietly ignored. The Exim reception process
36248 does not finish until the delivery attempt is complete. If the delivery is
36249 successful, a zero return code is given.
36250 .next
36251 Address redirection is permitted, but the final routing for all addresses must
36252 be to the same remote transport, and to the same list of hosts. Furthermore,
36253 the return address (envelope sender) must be the same for all recipients, as
36254 must any added or deleted header lines. In other words, it must be possible to
36255 deliver the message in a single SMTP transaction, however many recipients there
36256 are.
36257 .next
36258 If these conditions are not met, or if routing any address results in a
36259 failure or defer status, or if Exim is unable to deliver all the recipients
36260 successfully to one of the smart hosts, delivery of the entire message fails.
36261 .next
36262 Because no queueing is allowed, all failures are treated as permanent; there
36263 is no distinction between 4&'xx'& and 5&'xx'& SMTP response codes from the
36264 smart host. Furthermore, because only a single yes/no response can be given to
36265 the caller, it is not possible to deliver to some recipients and not others. If
36266 there is an error (temporary or permanent) for any recipient, all are failed.
36267 .next
36268 If more than one smart host is listed, Exim will try another host after a
36269 connection failure or a timeout, in the normal way. However, if this kind of
36270 failure happens for all the hosts, the delivery fails.
36271 .next
36272 When delivery fails, an error message is written to the standard error stream
36273 (as well as to Exim's log), and Exim exits to the caller with a return code
36274 value 1. The message is expunged from Exim's spool files. No bounce messages
36275 are ever generated.
36276 .next
36277 No retry data is maintained, and any retry rules are ignored.
36278 .next
36279 A number of Exim options are overridden: &%deliver_drop_privilege%& is forced
36280 true, &%max_rcpt%& in the &(smtp)& transport is forced to &"unlimited"&,
36281 &%remote_max_parallel%& is forced to one, and fallback hosts are ignored.
36282 .endlist
36283
36284 The overall effect is that Exim makes a single synchronous attempt to deliver
36285 the message, failing if there is any kind of problem. Because no local
36286 deliveries are done and no daemon can be run, Exim does not need root
36287 privilege. It should be possible to run it setuid to &'exim'& instead of setuid
36288 to &'root'&. See section &<<SECTrunexiwitpri>>& for a general discussion about
36289 the advantages and disadvantages of running without root privilege.
36290
36291
36292
36293
36294 . ////////////////////////////////////////////////////////////////////////////
36295 . ////////////////////////////////////////////////////////////////////////////
36296
36297 .chapter "Log files" "CHAPlog"
36298 .scindex IIDloggen "log" "general description"
36299 .cindex "log" "types of"
36300 Exim writes three different logs, referred to as the main log, the reject log,
36301 and the panic log:
36302
36303 .ilist
36304 .cindex "main log"
36305 The main log records the arrival of each message and each delivery in a single
36306 line in each case. The format is as compact as possible, in an attempt to keep
36307 down the size of log files. Two-character flag sequences make it easy to pick
36308 out these lines. A number of other events are recorded in the main log. Some of
36309 them are optional, in which case the &%log_selector%& option controls whether
36310 they are included or not. A Perl script called &'eximstats'&, which does simple
36311 analysis of main log files, is provided in the Exim distribution (see section
36312 &<<SECTmailstat>>&).
36313 .next
36314 .cindex "reject log"
36315 The reject log records information from messages that are rejected as a result
36316 of a configuration option (that is, for policy reasons).
36317 The first line of each rejection is a copy of the line that is also written to
36318 the main log. Then, if the message's header has been read at the time the log
36319 is written, its contents are written to this log. Only the original header
36320 lines are available; header lines added by ACLs are not logged. You can use the
36321 reject log to check that your policy controls are working correctly; on a busy
36322 host this may be easier than scanning the main log for rejection messages. You
36323 can suppress the writing of the reject log by setting &%write_rejectlog%&
36324 false.
36325 .next
36326 .cindex "panic log"
36327 .cindex "system log"
36328 When certain serious errors occur, Exim writes entries to its panic log. If the
36329 error is sufficiently disastrous, Exim bombs out afterwards. Panic log entries
36330 are usually written to the main log as well, but can get lost amid the mass of
36331 other entries. The panic log should be empty under normal circumstances. It is
36332 therefore a good idea to check it (or to have a &'cron'& script check it)
36333 regularly, in order to become aware of any problems. When Exim cannot open its
36334 panic log, it tries as a last resort to write to the system log (syslog). This
36335 is opened with LOG_PID+LOG_CONS and the facility code of LOG_MAIL. The
36336 message itself is written at priority LOG_CRIT.
36337 .endlist
36338
36339 Every log line starts with a timestamp, in the format shown in the following
36340 example. Note that many of the examples shown in this chapter are line-wrapped.
36341 In the log file, this would be all on one line:
36342 .code
36343 2001-09-16 16:09:47 SMTP connection from [127.0.0.1] closed
36344   by QUIT
36345 .endd
36346 By default, the timestamps are in the local timezone. There are two
36347 ways of changing this:
36348
36349 .ilist
36350 You can set the &%timezone%& option to a different time zone; in particular, if
36351 you set
36352 .code
36353 timezone = UTC
36354 .endd
36355 the timestamps will be in UTC (aka GMT).
36356 .next
36357 If you set &%log_timezone%& true, the time zone is added to the timestamp, for
36358 example:
36359 .code
36360 2003-04-25 11:17:07 +0100 Start queue run: pid=12762
36361 .endd
36362 .endlist
36363
36364 .cindex "log" "process ids in"
36365 .cindex "pid (process id)" "in log lines"
36366 Exim does not include its process id in log lines by default, but you can
36367 request that it does so by specifying the &`pid`& log selector (see section
36368 &<<SECTlogselector>>&). When this is set, the process id is output, in square
36369 brackets, immediately after the time and date.
36370
36371
36372
36373
36374 .section "Where the logs are written" "SECTwhelogwri"
36375 .cindex "log" "destination"
36376 .cindex "log" "to file"
36377 .cindex "log" "to syslog"
36378 .cindex "syslog"
36379 The logs may be written to local files, or to syslog, or both. However, it
36380 should be noted that many syslog implementations use UDP as a transport, and
36381 are therefore unreliable in the sense that messages are not guaranteed to
36382 arrive at the loghost, nor is the ordering of messages necessarily maintained.
36383 It has also been reported that on large log files (tens of megabytes) you may
36384 need to tweak syslog to prevent it syncing the file with each write &-- on
36385 Linux this has been seen to make syslog take 90% plus of CPU time.
36386
36387 The destination for Exim's logs is configured by setting LOG_FILE_PATH in
36388 &_Local/Makefile_& or by setting &%log_file_path%& in the run time
36389 configuration. This latter string is expanded, so it can contain, for example,
36390 references to the host name:
36391 .code
36392 log_file_path = /var/log/$primary_hostname/exim_%slog
36393 .endd
36394 It is generally advisable, however, to set the string in &_Local/Makefile_&
36395 rather than at run time, because then the setting is available right from the
36396 start of Exim's execution. Otherwise, if there's something it wants to log
36397 before it has read the configuration file (for example, an error in the
36398 configuration file) it will not use the path you want, and may not be able to
36399 log at all.
36400
36401 The value of LOG_FILE_PATH or &%log_file_path%& is a colon-separated
36402 list, currently limited to at most two items. This is one option where the
36403 facility for changing a list separator may not be used. The list must always be
36404 colon-separated. If an item in the list is &"syslog"& then syslog is used;
36405 otherwise the item must either be an absolute path, containing &`%s`& at the
36406 point where &"main"&, &"reject"&, or &"panic"& is to be inserted, or be empty,
36407 implying the use of a default path.
36408
36409 When Exim encounters an empty item in the list, it searches the list defined by
36410 LOG_FILE_PATH, and uses the first item it finds that is neither empty nor
36411 &"syslog"&. This means that an empty item in &%log_file_path%& can be used to
36412 mean &"use the path specified at build time"&. It no such item exists, log
36413 files are written in the &_log_& subdirectory of the spool directory. This is
36414 equivalent to the setting:
36415 .code
36416 log_file_path = $spool_directory/log/%slog
36417 .endd
36418 If you do not specify anything at build time or run time,
36419 or if you unset the option at run time (i.e. &`log_file_path = `&),
36420 that is where the logs are written.
36421
36422 A log file path may also contain &`%D`& or &`%M`& if datestamped log file names
36423 are in use &-- see section &<<SECTdatlogfil>>& below.
36424
36425 Here are some examples of possible settings:
36426 .display
36427 &`LOG_FILE_PATH=syslog                    `& syslog only
36428 &`LOG_FILE_PATH=:syslog                   `& syslog and default path
36429 &`LOG_FILE_PATH=syslog : /usr/log/exim_%s `& syslog and specified path
36430 &`LOG_FILE_PATH=/usr/log/exim_%s          `& specified path only
36431 .endd
36432 If there are more than two paths in the list, the first is used and a panic
36433 error is logged.
36434
36435
36436
36437 .section "Logging to local files that are periodically &""cycled""&" "SECID285"
36438 .cindex "log" "cycling local files"
36439 .cindex "cycling logs"
36440 .cindex "&'exicyclog'&"
36441 .cindex "log" "local files; writing to"
36442 Some operating systems provide centralized and standardized methods for cycling
36443 log files. For those that do not, a utility script called &'exicyclog'& is
36444 provided (see section &<<SECTcyclogfil>>&). This renames and compresses the
36445 main and reject logs each time it is called. The maximum number of old logs to
36446 keep can be set. It is suggested this script is run as a daily &'cron'& job.
36447
36448 An Exim delivery process opens the main log when it first needs to write to it,
36449 and it keeps the file open in case subsequent entries are required &-- for
36450 example, if a number of different deliveries are being done for the same
36451 message. However, remote SMTP deliveries can take a long time, and this means
36452 that the file may be kept open long after it is renamed if &'exicyclog'& or
36453 something similar is being used to rename log files on a regular basis. To
36454 ensure that a switch of log files is noticed as soon as possible, Exim calls
36455 &[stat()]& on the main log's name before reusing an open file, and if the file
36456 does not exist, or its inode has changed, the old file is closed and Exim
36457 tries to open the main log from scratch. Thus, an old log file may remain open
36458 for quite some time, but no Exim processes should write to it once it has been
36459 renamed.
36460
36461
36462
36463 .section "Datestamped log files" "SECTdatlogfil"
36464 .cindex "log" "datestamped files"
36465 Instead of cycling the main and reject log files by renaming them
36466 periodically, some sites like to use files whose names contain a datestamp,
36467 for example, &_mainlog-20031225_&. The datestamp is in the form &_yyyymmdd_& or
36468 &_yyyymm_&. Exim has support for this way of working. It is enabled by setting
36469 the &%log_file_path%& option to a path that includes &`%D`& or &`%M`& at the
36470 point where the datestamp is required. For example:
36471 .code
36472 log_file_path = /var/spool/exim/log/%slog-%D
36473 log_file_path = /var/log/exim-%s-%D.log
36474 log_file_path = /var/spool/exim/log/%D-%slog
36475 log_file_path = /var/log/exim/%s.%M
36476 .endd
36477 As before, &`%s`& is replaced by &"main"& or &"reject"&; the following are
36478 examples of names generated by the above examples:
36479 .code
36480 /var/spool/exim/log/mainlog-20021225
36481 /var/log/exim-reject-20021225.log
36482 /var/spool/exim/log/20021225-mainlog
36483 /var/log/exim/main.200212
36484 .endd
36485 When this form of log file is specified, Exim automatically switches to new
36486 files at midnight. It does not make any attempt to compress old logs; you
36487 will need to write your own script if you require this. You should not
36488 run &'exicyclog'& with this form of logging.
36489
36490 The location of the panic log is also determined by &%log_file_path%&, but it
36491 is not datestamped, because rotation of the panic log does not make sense.
36492 When generating the name of the panic log, &`%D`& or &`%M`& are removed from
36493 the string. In addition, if it immediately follows a slash, a following
36494 non-alphanumeric character is removed; otherwise a preceding non-alphanumeric
36495 character is removed. Thus, the four examples above would give these panic
36496 log names:
36497 .code
36498 /var/spool/exim/log/paniclog
36499 /var/log/exim-panic.log
36500 /var/spool/exim/log/paniclog
36501 /var/log/exim/panic
36502 .endd
36503
36504
36505 .section "Logging to syslog" "SECID249"
36506 .cindex "log" "syslog; writing to"
36507 The use of syslog does not change what Exim logs or the format of its messages,
36508 except in one respect. If &%syslog_timestamp%& is set false, the timestamps on
36509 Exim's log lines are omitted when these lines are sent to syslog. Apart from
36510 that, the same strings are written to syslog as to log files. The syslog
36511 &"facility"& is set to LOG_MAIL, and the program name to &"exim"&
36512 by default, but you can change these by setting the &%syslog_facility%& and
36513 &%syslog_processname%& options, respectively. If Exim was compiled with
36514 SYSLOG_LOG_PID set in &_Local/Makefile_& (this is the default in
36515 &_src/EDITME_&), then, on systems that permit it (all except ULTRIX), the
36516 LOG_PID flag is set so that the &[syslog()]& call adds the pid as well as
36517 the time and host name to each line.
36518 The three log streams are mapped onto syslog priorities as follows:
36519
36520 .ilist
36521 &'mainlog'& is mapped to LOG_INFO
36522 .next
36523 &'rejectlog'& is mapped to LOG_NOTICE
36524 .next
36525 &'paniclog'& is mapped to LOG_ALERT
36526 .endlist
36527
36528 Many log lines are written to both &'mainlog'& and &'rejectlog'&, and some are
36529 written to both &'mainlog'& and &'paniclog'&, so there will be duplicates if
36530 these are routed by syslog to the same place. You can suppress this duplication
36531 by setting &%syslog_duplication%& false.
36532
36533 Exim's log lines can sometimes be very long, and some of its &'rejectlog'&
36534 entries contain multiple lines when headers are included. To cope with both
36535 these cases, entries written to syslog are split into separate &[syslog()]&
36536 calls at each internal newline, and also after a maximum of
36537 870 data characters. (This allows for a total syslog line length of 1024, when
36538 additions such as timestamps are added.) If you are running a syslog
36539 replacement that can handle lines longer than the 1024 characters allowed by
36540 RFC 3164, you should set
36541 .code
36542 SYSLOG_LONG_LINES=yes
36543 .endd
36544 in &_Local/Makefile_& before building Exim. That stops Exim from splitting long
36545 lines, but it still splits at internal newlines in &'reject'& log entries.
36546
36547 To make it easy to re-assemble split lines later, each component of a split
36548 entry starts with a string of the form [<&'n'&>/<&'m'&>] or [<&'n'&>\<&'m'&>]
36549 where <&'n'&> is the component number and <&'m'&> is the total number of
36550 components in the entry. The / delimiter is used when the line was split
36551 because it was too long; if it was split because of an internal newline, the \
36552 delimiter is used. For example, supposing the length limit to be 50 instead of
36553 870, the following would be the result of a typical rejection message to
36554 &'mainlog'& (LOG_INFO), each line in addition being preceded by the time, host
36555 name, and pid as added by syslog:
36556 .code
36557 [1/5] 2002-09-16 16:09:43 16RdAL-0006pc-00 rejected from
36558 [2/5]  [127.0.0.1] (ph10): syntax error in 'From' header
36559 [3/5]  when scanning for sender: missing or malformed lo
36560 [4/5] cal part in "<>" (envelope sender is <ph10@cam.exa
36561 [5/5] mple>)
36562 .endd
36563 The same error might cause the following lines to be written to &"rejectlog"&
36564 (LOG_NOTICE):
36565 .code
36566 [1/18] 2002-09-16 16:09:43 16RdAL-0006pc-00 rejected fro
36567 [2/18] m [127.0.0.1] (ph10): syntax error in 'From' head
36568 [3/18] er when scanning for sender: missing or malformed
36569 [4/18]  local part in "<>" (envelope sender is <ph10@cam
36570 [5\18] .example>)
36571 [6\18] Recipients: ph10@some.domain.cam.example
36572 [7\18] P Received: from [127.0.0.1] (ident=ph10)
36573 [8\18]        by xxxxx.cam.example with smtp (Exim 4.00)
36574 [9\18]        id 16RdAL-0006pc-00
36575 [10/18]        for ph10@cam.example; Mon, 16 Sep 2002 16:
36576 [11\18] 09:43 +0100
36577 [12\18] F From: <>
36578 [13\18]   Subject: this is a test header
36579 [18\18]   X-something: this is another header
36580 [15/18] I Message-Id: <E16RdAL-0006pc-00@xxxxx.cam.examp
36581 [16\18] le>
36582 [17\18] B Bcc:
36583 [18/18]   Date: Mon, 16 Sep 2002 16:09:43 +0100
36584 .endd
36585 Log lines that are neither too long nor contain newlines are written to syslog
36586 without modification.
36587
36588 If only syslog is being used, the Exim monitor is unable to provide a log tail
36589 display, unless syslog is routing &'mainlog'& to a file on the local host and
36590 the environment variable EXIMON_LOG_FILE_PATH is set to tell the monitor
36591 where it is.
36592
36593
36594
36595 .section "Log line flags" "SECID250"
36596 One line is written to the main log for each message received, and for each
36597 successful, unsuccessful, and delayed delivery. These lines can readily be
36598 picked out by the distinctive two-character flags that immediately follow the
36599 timestamp. The flags are:
36600 .display
36601 &`<=`&     message arrival
36602 &`(=`&     message fakereject
36603 &`=>`&     normal message delivery
36604 &`->`&     additional address in same delivery
36605 &`>>`&     cutthrough message delivery
36606 &`*>`&     delivery suppressed by &%-N%&
36607 &`**`&     delivery failed; address bounced
36608 &`==`&     delivery deferred; temporary problem
36609 .endd
36610
36611
36612 .section "Logging message reception" "SECID251"
36613 .cindex "log" "reception line"
36614 The format of the single-line entry in the main log that is written for every
36615 message received is shown in the basic example below, which is split over
36616 several lines in order to fit it on the page:
36617 .code
36618 2002-10-31 08:57:53 16ZCW1-0005MB-00 <= kryten@dwarf.fict.example
36619   H=mailer.fict.example [192.168.123.123] U=exim
36620   P=smtp S=5678 id=<incoming message id>
36621 .endd
36622 The address immediately following &"<="& is the envelope sender address. A
36623 bounce message is shown with the sender address &"<>"&, and if it is locally
36624 generated, this is followed by an item of the form
36625 .code
36626 R=<message id>
36627 .endd
36628 which is a reference to the message that caused the bounce to be sent.
36629
36630 .cindex "HELO"
36631 .cindex "EHLO"
36632 For messages from other hosts, the H and U fields identify the remote host and
36633 record the RFC 1413 identity of the user that sent the message, if one was
36634 received. The number given in square brackets is the IP address of the sending
36635 host. If there is a single, unparenthesized  host name in the H field, as
36636 above, it has been verified to correspond to the IP address (see the
36637 &%host_lookup%& option). If the name is in parentheses, it was the name quoted
36638 by the remote host in the SMTP HELO or EHLO command, and has not been
36639 verified. If verification yields a different name to that given for HELO or
36640 EHLO, the verified name appears first, followed by the HELO or EHLO
36641 name in parentheses.
36642
36643 Misconfigured hosts (and mail forgers) sometimes put an IP address, with or
36644 without brackets, in the HELO or EHLO command, leading to entries in
36645 the log containing text like these examples:
36646 .code
36647 H=(10.21.32.43) [192.168.8.34]
36648 H=([10.21.32.43]) [192.168.8.34]
36649 .endd
36650 This can be confusing. Only the final address in square brackets can be relied
36651 on.
36652
36653 For locally generated messages (that is, messages not received over TCP/IP),
36654 the H field is omitted, and the U field contains the login name of the caller
36655 of Exim.
36656
36657 .cindex "authentication" "logging"
36658 .cindex "AUTH" "logging"
36659 For all messages, the P field specifies the protocol used to receive the
36660 message. This is the value that is stored in &$received_protocol$&. In the case
36661 of incoming SMTP messages, the value indicates whether or not any SMTP
36662 extensions (ESMTP), encryption, or authentication were used. If the SMTP
36663 session was encrypted, there is an additional X field that records the cipher
36664 suite that was used.
36665
36666 .cindex log protocol
36667 The protocol is set to &"esmtpsa"& or &"esmtpa"& for messages received from
36668 hosts that have authenticated themselves using the SMTP AUTH command. The first
36669 value is used when the SMTP connection was encrypted (&"secure"&). In this case
36670 there is an additional item A= followed by the name of the authenticator that
36671 was used. If an authenticated identification was set up by the authenticator's
36672 &%server_set_id%& option, this is logged too, separated by a colon from the
36673 authenticator name.
36674
36675 .cindex "size" "of message"
36676 The id field records the existing message id, if present. The size of the
36677 received message is given by the S field. When the message is delivered,
36678 headers may be removed or added, so that the size of delivered copies of the
36679 message may not correspond with this value (and indeed may be different to each
36680 other).
36681
36682 The &%log_selector%& option can be used to request the logging of additional
36683 data when a message is received. See section &<<SECTlogselector>>& below.
36684
36685
36686
36687 .section "Logging deliveries" "SECID252"
36688 .cindex "log" "delivery line"
36689 The format of the single-line entry in the main log that is written for every
36690 delivery is shown in one of the examples below, for local and remote
36691 deliveries, respectively. Each example has been split into multiple lines in order
36692 to fit it on the page:
36693 .code
36694 2002-10-31 08:59:13 16ZCW1-0005MB-00 => marv
36695   <marv@hitch.fict.example> R=localuser T=local_delivery
36696 2002-10-31 09:00:10 16ZCW1-0005MB-00 =>
36697   monk@holistic.fict.example R=dnslookup T=remote_smtp
36698   H=holistic.fict.example [192.168.234.234]
36699 .endd
36700 For ordinary local deliveries, the original address is given in angle brackets
36701 after the final delivery address, which might be a pipe or a file. If
36702 intermediate address(es) exist between the original and the final address, the
36703 last of these is given in parentheses after the final address. The R and T
36704 fields record the router and transport that were used to process the address.
36705
36706 If SMTP AUTH was used for the delivery there is an additional item A=
36707 followed by the name of the authenticator that was used.
36708 If an authenticated identification was set up by the authenticator's &%client_set_id%&
36709 option, this is logged too, separated by a colon from the authenticator name.
36710
36711 If a shadow transport was run after a successful local delivery, the log line
36712 for the successful delivery has an item added on the end, of the form
36713 .display
36714 &`ST=<`&&'shadow transport name'&&`>`&
36715 .endd
36716 If the shadow transport did not succeed, the error message is put in
36717 parentheses afterwards.
36718
36719 .cindex "asterisk" "after IP address"
36720 When more than one address is included in a single delivery (for example, two
36721 SMTP RCPT commands in one transaction) the second and subsequent addresses are
36722 flagged with &`->`& instead of &`=>`&. When two or more messages are delivered
36723 down a single SMTP connection, an asterisk follows the IP address in the log
36724 lines for the second and subsequent messages.
36725 When two or more messages are delivered down a single TLS connection, the
36726 DNS and some TLS-related information logged for the first message delivered
36727 will not be present in the log lines for the second and subsequent messages.
36728 TLS cipher information is still available.
36729
36730 .cindex "delivery" "cutthrough; logging"
36731 .cindex "cutthrough" "logging"
36732 When delivery is done in cutthrough mode it is flagged with &`>>`& and the log
36733 line precedes the reception line, since cutthrough waits for a possible
36734 rejection from the destination in case it can reject the sourced item.
36735
36736 The generation of a reply message by a filter file gets logged as a
36737 &"delivery"& to the addressee, preceded by &">"&.
36738
36739 The &%log_selector%& option can be used to request the logging of additional
36740 data when a message is delivered. See section &<<SECTlogselector>>& below.
36741
36742
36743 .section "Discarded deliveries" "SECID253"
36744 .cindex "discarded messages"
36745 .cindex "message" "discarded"
36746 .cindex "delivery" "discarded; logging"
36747 When a message is discarded as a result of the command &"seen finish"& being
36748 obeyed in a filter file which generates no deliveries, a log entry of the form
36749 .code
36750 2002-12-10 00:50:49 16auJc-0001UB-00 => discarded
36751   <low.club@bridge.example> R=userforward
36752 .endd
36753 is written, to record why no deliveries are logged. When a message is discarded
36754 because it is aliased to &":blackhole:"& the log line is like this:
36755 .code
36756 1999-03-02 09:44:33 10HmaX-0005vi-00 => :blackhole:
36757   <hole@nowhere.example> R=blackhole_router
36758 .endd
36759
36760
36761 .section "Deferred deliveries" "SECID254"
36762 When a delivery is deferred, a line of the following form is logged:
36763 .code
36764 2002-12-19 16:20:23 16aiQz-0002Q5-00 == marvin@endrest.example
36765   R=dnslookup T=smtp defer (146): Connection refused
36766 .endd
36767 In the case of remote deliveries, the error is the one that was given for the
36768 last IP address that was tried. Details of individual SMTP failures are also
36769 written to the log, so the above line would be preceded by something like
36770 .code
36771 2002-12-19 16:20:23 16aiQz-0002Q5-00 Failed to connect to
36772   mail1.endrest.example [192.168.239.239]: Connection refused
36773 .endd
36774 When a deferred address is skipped because its retry time has not been reached,
36775 a message is written to the log, but this can be suppressed by setting an
36776 appropriate value in &%log_selector%&.
36777
36778
36779
36780 .section "Delivery failures" "SECID255"
36781 .cindex "delivery" "failure; logging"
36782 If a delivery fails because an address cannot be routed, a line of the
36783 following form is logged:
36784 .code
36785 1995-12-19 16:20:23 0tRiQz-0002Q5-00 ** jim@trek99.example
36786   <jim@trek99.example>: unknown mail domain
36787 .endd
36788 If a delivery fails at transport time, the router and transport are shown, and
36789 the response from the remote host is included, as in this example:
36790 .code
36791 2002-07-11 07:14:17 17SXDU-000189-00 ** ace400@pb.example
36792   R=dnslookup T=remote_smtp: SMTP error from remote mailer
36793   after pipelined RCPT TO:<ace400@pb.example>: host
36794   pbmail3.py.example [192.168.63.111]: 553 5.3.0
36795   <ace400@pb.example>...Addressee unknown
36796 .endd
36797 The word &"pipelined"& indicates that the SMTP PIPELINING extension was being
36798 used. See &%hosts_avoid_esmtp%& in the &(smtp)& transport for a way of
36799 disabling PIPELINING. The log lines for all forms of delivery failure are
36800 flagged with &`**`&.
36801
36802
36803
36804 .section "Fake deliveries" "SECID256"
36805 .cindex "delivery" "fake; logging"
36806 If a delivery does not actually take place because the &%-N%& option has been
36807 used to suppress it, a normal delivery line is written to the log, except that
36808 &"=>"& is replaced by &"*>"&.
36809
36810
36811
36812 .section "Completion" "SECID257"
36813 A line of the form
36814 .code
36815 2002-10-31 09:00:11 16ZCW1-0005MB-00 Completed
36816 .endd
36817 is written to the main log when a message is about to be removed from the spool
36818 at the end of its processing.
36819
36820
36821
36822
36823 .section "Summary of Fields in Log Lines" "SECID258"
36824 .cindex "log" "summary of fields"
36825 A summary of the field identifiers that are used in log lines is shown in
36826 the following table:
36827 .display
36828 &`A   `&        authenticator name (and optional id and sender)
36829 &`C   `&        SMTP confirmation on delivery
36830 &`    `&        command list for &"no mail in SMTP session"&
36831 &`CV  `&        certificate verification status
36832 &`D   `&        duration of &"no mail in SMTP session"&
36833 &`DKIM`&        domain verified in incoming message
36834 &`DN  `&        distinguished name from peer certificate
36835 &`DS  `&        DNSSEC secured lookups
36836 &`DT  `&        on &`=>`& lines: time taken for a delivery
36837 &`F   `&        sender address (on delivery lines)
36838 &`H   `&        host name and IP address
36839 &`I   `&        local interface used
36840 &`id  `&        message id for incoming message
36841 &`K   `&        CHUNKING extension used
36842 &`L   `&        on &`<=`& and &`=>`& lines: PIPELINING extension used
36843 &`M8S `&        8BITMIME status for incoming message
36844 &`P   `&        on &`<=`& lines: protocol used
36845 &`    `&        on &`=>`& and &`**`& lines: return path
36846 &`PRDR`&        PRDR extension used
36847 &`PRX `&        on &`<=`& and &`=>`& lines: proxy address
36848 &`Q   `&        alternate queue name
36849 &`QT  `&        on &`=>`& lines: time spent on queue so far
36850 &`    `&        on &"Completed"& lines: time spent on queue
36851 &`R   `&        on &`<=`& lines: reference for local bounce
36852 &`    `&        on &`=>`&  &`>>`& &`**`& and &`==`& lines: router name
36853 &`RT  `&        on &`<=`& lines: time taken for reception
36854 &`S   `&        size of message in bytes
36855 &`SNI `&        server name indication from TLS client hello
36856 &`ST  `&        shadow transport name
36857 &`T   `&        on &`<=`& lines: message subject (topic)
36858 &`TFO `&        connection took advantage of TCP Fast Open
36859 &`    `&        on &`=>`& &`**`& and &`==`& lines: transport name
36860 &`U   `&        local user or RFC 1413 identity
36861 &`X   `&        TLS cipher suite
36862 .endd
36863
36864
36865 .section "Other log entries" "SECID259"
36866 Various other types of log entry are written from time to time. Most should be
36867 self-explanatory. Among the more common are:
36868
36869 .ilist
36870 .cindex "retry" "time not reached"
36871 &'retry time not reached'&&~&~An address previously suffered a temporary error
36872 during routing or local delivery, and the time to retry has not yet arrived.
36873 This message is not written to an individual message log file unless it happens
36874 during the first delivery attempt.
36875 .next
36876 &'retry time not reached for any host'&&~&~An address previously suffered
36877 temporary errors during remote delivery, and the retry time has not yet arrived
36878 for any of the hosts to which it is routed.
36879 .next
36880 .cindex "spool directory" "file locked"
36881 &'spool file locked'&&~&~An attempt to deliver a message cannot proceed because
36882 some other Exim process is already working on the message. This can be quite
36883 common if queue running processes are started at frequent intervals. The
36884 &'exiwhat'& utility script can be used to find out what Exim processes are
36885 doing.
36886 .next
36887 .cindex "error" "ignored"
36888 &'error ignored'&&~&~There are several circumstances that give rise to this
36889 message:
36890 .olist
36891 Exim failed to deliver a bounce message whose age was greater than
36892 &%ignore_bounce_errors_after%&. The bounce was discarded.
36893 .next
36894 A filter file set up a delivery using the &"noerror"& option, and the delivery
36895 failed. The delivery was discarded.
36896 .next
36897 A delivery set up by a router configured with
36898 . ==== As this is a nested list, any displays it contains must be indented
36899 . ==== as otherwise they are too far to the left.
36900 .code
36901     errors_to = <>
36902 .endd
36903 failed. The delivery was discarded.
36904 .endlist olist
36905 .next
36906 .cindex DKIM "log line"
36907 &'DKIM: d='&&~&~Verbose results of a DKIM verification attempt, if enabled for
36908 logging and the message has a DKIM signature header.
36909 .endlist ilist
36910
36911
36912
36913
36914
36915 .section "Reducing or increasing what is logged" "SECTlogselector"
36916 .cindex "log" "selectors"
36917 By setting the &%log_selector%& global option, you can disable some of Exim's
36918 default logging, or you can request additional logging. The value of
36919 &%log_selector%& is made up of names preceded by plus or minus characters. For
36920 example:
36921 .code
36922 log_selector = +arguments -retry_defer
36923 .endd
36924 The list of optional log items is in the following table, with the default
36925 selection marked by asterisks:
36926 .display
36927 &` 8bitmime                   `&  received 8BITMIME status
36928 &`*acl_warn_skipped           `&  skipped &%warn%& statement in ACL
36929 &` address_rewrite            `&  address rewriting
36930 &` all_parents                `&  all parents in => lines
36931 &` arguments                  `&  command line arguments
36932 &`*connection_reject          `&  connection rejections
36933 &`*delay_delivery             `&  immediate delivery delayed
36934 &` deliver_time               `&  time taken to perform delivery
36935 &` delivery_size              `&  add &`S=`&&'nnn'& to => lines
36936 &`*dkim                       `&  DKIM verified domain on <= lines
36937 &` dkim_verbose               `&  separate full DKIM verification result line, per signature
36938 &`*dnslist_defer              `&  defers of DNS list (aka RBL) lookups
36939 &` dnssec                     `&  DNSSEC secured lookups
36940 &`*etrn                       `&  ETRN commands
36941 &`*host_lookup_failed         `&  as it says
36942 &` ident_timeout              `&  timeout for ident connection
36943 &` incoming_interface         `&  local interface on <= and => lines
36944 &` incoming_port              `&  remote port on <= lines
36945 &`*lost_incoming_connection   `&  as it says (includes timeouts)
36946 &` millisec                   `&  millisecond timestamps and RT,QT,DT,D times
36947 &` outgoing_interface         `&  local interface on => lines
36948 &` outgoing_port              `&  add remote port to => lines
36949 &`*queue_run                  `&  start and end queue runs
36950 &` queue_time                 `&  time on queue for one recipient
36951 &` queue_time_overall         `&  time on queue for whole message
36952 &` pid                        `&  Exim process id
36953 &` pipelining                 `&  PIPELINING use, on <= and => lines
36954 &` proxy                      `&  proxy address on <= and => lines
36955 &` receive_time               `&  time taken to receive message
36956 &` received_recipients        `&  recipients on <= lines
36957 &` received_sender            `&  sender on <= lines
36958 &`*rejected_header            `&  header contents on reject log
36959 &`*retry_defer                `&  &"retry time not reached"&
36960 &` return_path_on_delivery    `&  put return path on => and ** lines
36961 &` sender_on_delivery         `&  add sender to => lines
36962 &`*sender_verify_fail         `&  sender verification failures
36963 &`*size_reject                `&  rejection because too big
36964 &`*skip_delivery              `&  delivery skipped in a queue run
36965 &`*smtp_confirmation          `&  SMTP confirmation on => lines
36966 &` smtp_connection            `&  incoming SMTP connections
36967 &` smtp_incomplete_transaction`&  incomplete SMTP transactions
36968 &` smtp_mailauth              `&  AUTH argument to MAIL commands
36969 &` smtp_no_mail               `&  session with no MAIL commands
36970 &` smtp_protocol_error        `&  SMTP protocol errors
36971 &` smtp_syntax_error          `&  SMTP syntax errors
36972 &` subject                    `&  contents of &'Subject:'& on <= lines
36973 &`*tls_certificate_verified   `&  certificate verification status
36974 &`*tls_cipher                 `&  TLS cipher suite on <= and => lines
36975 &` tls_peerdn                 `&  TLS peer DN on <= and => lines
36976 &` tls_sni                    `&  TLS SNI on <= lines
36977 &` unknown_in_list            `&  DNS lookup failed in list match
36978
36979 &` all                        `&  all of the above
36980 .endd
36981 See also the &%slow_lookup_log%& main configuration option,
36982 section &<<SECID99>>&
36983
36984 More details on each of these items follows:
36985
36986 .ilist
36987 .cindex "8BITMIME"
36988 .cindex "log" "8BITMIME"
36989 &%8bitmime%&: This causes Exim to log any 8BITMIME status of received messages,
36990 which may help in tracking down interoperability issues with ancient MTAs
36991 that are not 8bit clean.  This is added to the &"<="& line, tagged with
36992 &`M8S=`& and a value of &`0`&, &`7`& or &`8`&, corresponding to "not given",
36993 &`7BIT`& and &`8BITMIME`& respectively.
36994 .next
36995 .cindex "&%warn%& ACL verb" "log when skipping"
36996 &%acl_warn_skipped%&: When an ACL &%warn%& statement is skipped because one of
36997 its conditions cannot be evaluated, a log line to this effect is written if
36998 this log selector is set.
36999 .next
37000 .cindex "log" "rewriting"
37001 .cindex "rewriting" "logging"
37002 &%address_rewrite%&: This applies both to global rewrites and per-transport
37003 rewrites, but not to rewrites in filters run as an unprivileged user (because
37004 such users cannot access the log).
37005 .next
37006 .cindex "log" "full parentage"
37007 &%all_parents%&: Normally only the original and final addresses are logged on
37008 delivery lines; with this selector, intermediate parents are given in
37009 parentheses between them.
37010 .next
37011 .cindex "log" "Exim arguments"
37012 .cindex "Exim arguments, logging"
37013 &%arguments%&: This causes Exim to write the arguments with which it was called
37014 to the main log, preceded by the current working directory. This is a debugging
37015 feature, added to make it easier to find out how certain MUAs call
37016 &_/usr/sbin/sendmail_&. The logging does not happen if Exim has given up root
37017 privilege because it was called with the &%-C%& or &%-D%& options. Arguments
37018 that are empty or that contain white space are quoted. Non-printing characters
37019 are shown as escape sequences. This facility cannot log unrecognized arguments,
37020 because the arguments are checked before the configuration file is read. The
37021 only way to log such cases is to interpose a script such as &_util/logargs.sh_&
37022 between the caller and Exim.
37023 .next
37024 .cindex "log" "connection rejections"
37025 &%connection_reject%&: A log entry is written whenever an incoming SMTP
37026 connection is rejected, for whatever reason.
37027 .next
37028 .cindex "log" "delayed delivery"
37029 .cindex "delayed delivery, logging"
37030 &%delay_delivery%&: A log entry is written whenever a delivery process is not
37031 started for an incoming message because the load is too high or too many
37032 messages were received on one connection. Logging does not occur if no delivery
37033 process is started because &%queue_only%& is set or &%-odq%& was used.
37034 .next
37035 .cindex "log" "delivery duration"
37036 &%deliver_time%&: For each delivery, the amount of real time it has taken to
37037 perform the actual delivery is logged as DT=<&'time'&>, for example, &`DT=1s`&.
37038 If millisecond logging is enabled, short times will be shown with greater
37039 precision, eg. &`DT=0.304s`&.
37040 .next
37041 .cindex "log" "message size on delivery"
37042 .cindex "size" "of message"
37043 &%delivery_size%&: For each delivery, the size of message delivered is added to
37044 the &"=>"& line, tagged with S=.
37045 .next
37046 .cindex log "DKIM verification"
37047 .cindex DKIM "verification logging"
37048 &%dkim%&: For message acceptance log lines, when an DKIM signature in the header
37049 verifies successfully a tag of DKIM is added, with one of the verified domains.
37050 .next
37051 .cindex log "DKIM verification"
37052 .cindex DKIM "verification logging"
37053 &%dkim_verbose%&: A log entry is written for each attempted DKIM verification.
37054 .next
37055 .cindex "log" "dnslist defer"
37056 .cindex "DNS list" "logging defer"
37057 .cindex "black list (DNS)"
37058 &%dnslist_defer%&: A log entry is written if an attempt to look up a host in a
37059 DNS black list suffers a temporary error.
37060 .next
37061 .cindex log dnssec
37062 .cindex dnssec logging
37063 &%dnssec%&: For message acceptance and (attempted) delivery log lines, when
37064 dns lookups gave secure results a tag of DS is added.
37065 For acceptance this covers the reverse and forward lookups for host name verification.
37066 It does not cover helo-name verification.
37067 For delivery this covers the SRV, MX, A and/or AAAA lookups.
37068 .next
37069 .cindex "log" "ETRN commands"
37070 .cindex "ETRN" "logging"
37071 &%etrn%&: Every valid ETRN command that is received is logged, before the ACL
37072 is run to determine whether or not it is actually accepted. An invalid ETRN
37073 command, or one received within a message transaction is not logged by this
37074 selector (see &%smtp_syntax_error%& and &%smtp_protocol_error%&).
37075 .next
37076 .cindex "log" "host lookup failure"
37077 &%host_lookup_failed%&: When a lookup of a host's IP addresses fails to find
37078 any addresses, or when a lookup of an IP address fails to find a host name, a
37079 log line is written. This logging does not apply to direct DNS lookups when
37080 routing email addresses, but it does apply to &"byname"& lookups.
37081 .next
37082 .cindex "log" "ident timeout"
37083 .cindex "RFC 1413" "logging timeout"
37084 &%ident_timeout%&: A log line is written whenever an attempt to connect to a
37085 client's ident port times out.
37086 .next
37087 .cindex "log" "incoming interface"
37088 .cindex "log" "local interface"
37089 .cindex "log" "local address and port"
37090 .cindex "TCP/IP" "logging local address and port"
37091 .cindex "interface" "logging"
37092 &%incoming_interface%&: The interface on which a message was received is added
37093 to the &"<="& line as an IP address in square brackets, tagged by I= and
37094 followed by a colon and the port number. The local interface and port are also
37095 added to other SMTP log lines, for example &"SMTP connection from"&, to
37096 rejection lines, and (despite the name) to outgoing &"=>"& and &"->"& lines.
37097 The latter can be disabled by turning off the &%outgoing_interface%& option.
37098 .next
37099 .cindex log "incoming proxy address"
37100 .cindex proxy "logging proxy address"
37101 .cindex "TCP/IP" "logging proxy address"
37102 &%proxy%&: The internal (closest to the system running Exim) IP address
37103 of the proxy, tagged by PRX=, on the &"<="& line for a message accepted
37104 on a proxied connection
37105 or the &"=>"& line for a message delivered on a proxied connection.
37106 See &<<SECTproxyInbound>>& for more information.
37107 .next
37108 .cindex "log" "incoming remote port"
37109 .cindex "port" "logging remote"
37110 .cindex "TCP/IP" "logging incoming remote port"
37111 .vindex "&$sender_fullhost$&"
37112 .vindex "&$sender_rcvhost$&"
37113 &%incoming_port%&: The remote port number from which a message was received is
37114 added to log entries and &'Received:'& header lines, following the IP address
37115 in square brackets, and separated from it by a colon. This is implemented by
37116 changing the value that is put in the &$sender_fullhost$& and
37117 &$sender_rcvhost$& variables. Recording the remote port number has become more
37118 important with the widening use of NAT (see RFC 2505).
37119 .next
37120 .cindex "log" "dropped connection"
37121 &%lost_incoming_connection%&: A log line is written when an incoming SMTP
37122 connection is unexpectedly dropped.
37123 .next
37124 .cindex "log" "millisecond timestamps"
37125 .cindex millisecond logging
37126 .cindex timestamps "millisecond, in logs"
37127 &%millisec%&: Timestamps have a period and three decimal places of finer granularity
37128 appended to the seconds value.
37129 .next
37130 .cindex "log" "outgoing interface"
37131 .cindex "log" "local interface"
37132 .cindex "log" "local address and port"
37133 .cindex "TCP/IP" "logging local address and port"
37134 .cindex "interface" "logging"
37135 &%outgoing_interface%&: If &%incoming_interface%& is turned on, then the
37136 interface on which a message was sent is added to delivery lines as an I= tag
37137 followed by IP address in square brackets. You can disable this by turning
37138 off the &%outgoing_interface%& option.
37139 .next
37140 .cindex "log" "outgoing remote port"
37141 .cindex "port" "logging outgoing remote"
37142 .cindex "TCP/IP" "logging outgoing remote port"
37143 &%outgoing_port%&: The remote port number is added to delivery log lines (those
37144 containing => tags) following the IP address.
37145 The local port is also added if &%incoming_interface%& and
37146 &%outgoing_interface%& are both enabled.
37147 This option is not included in the default setting, because for most ordinary
37148 configurations, the remote port number is always 25 (the SMTP port), and the
37149 local port is a random ephemeral port.
37150 .next
37151 .cindex "log" "process ids in"
37152 .cindex "pid (process id)" "in log lines"
37153 &%pid%&: The current process id is added to every log line, in square brackets,
37154 immediately after the time and date.
37155 .next
37156 .new
37157 .cindex log pipelining
37158 .cindex pipelining "logging outgoing"
37159 &%pipelining%&: A field is added to delivery and accept
37160 log lines when the ESMTP PIPELINING extension was used.
37161 The field is a single "L".
37162
37163 On accept lines, where PIPELINING was offered but not used by the client,
37164 the field has a minus appended.
37165 .next
37166 .cindex "log" "queue run"
37167 .cindex "queue runner" "logging"
37168 &%queue_run%&: The start and end of every queue run are logged.
37169 .next
37170 .cindex "log" "queue time"
37171 &%queue_time%&: The amount of time the message has been in the queue on the
37172 local host is logged as QT=<&'time'&> on delivery (&`=>`&) lines, for example,
37173 &`QT=3m45s`&. The clock starts when Exim starts to receive the message, so it
37174 includes reception time as well as the delivery time for the current address.
37175 This means that it may be longer than the difference between the arrival and
37176 delivery log line times, because the arrival log line is not written until the
37177 message has been successfully received.
37178 If millisecond logging is enabled, short times will be shown with greater
37179 precision, eg. &`QT=1.578s`&.
37180 .next
37181 &%queue_time_overall%&: The amount of time the message has been in the queue on
37182 the local host is logged as QT=<&'time'&> on &"Completed"& lines, for
37183 example, &`QT=3m45s`&. The clock starts when Exim starts to receive the
37184 message, so it includes reception time as well as the total delivery time.
37185 .next
37186 .cindex "log" "receive duration"
37187 &%receive_time%&: For each message, the amount of real time it has taken to
37188 perform the reception is logged as RT=<&'time'&>, for example, &`RT=1s`&.
37189 If millisecond logging is enabled, short times will be shown with greater
37190 precision, eg. &`RT=0.204s`&.
37191 .next
37192 .cindex "log" "recipients"
37193 &%received_recipients%&: The recipients of a message are listed in the main log
37194 as soon as the message is received. The list appears at the end of the log line
37195 that is written when a message is received, preceded by the word &"for"&. The
37196 addresses are listed after they have been qualified, but before any rewriting
37197 has taken place.
37198 Recipients that were discarded by an ACL for MAIL or RCPT do not appear
37199 in the list.
37200 .next
37201 .cindex "log" "sender reception"
37202 &%received_sender%&: The unrewritten original sender of a message is added to
37203 the end of the log line that records the message's arrival, after the word
37204 &"from"& (before the recipients if &%received_recipients%& is also set).
37205 .next
37206 .cindex "log" "header lines for rejection"
37207 &%rejected_header%&: If a message's header has been received at the time a
37208 rejection is written to the reject log, the complete header is added to the
37209 log. Header logging can be turned off individually for messages that are
37210 rejected by the &[local_scan()]& function (see section &<<SECTapiforloc>>&).
37211 .next
37212 .cindex "log" "retry defer"
37213 &%retry_defer%&: A log line is written if a delivery is deferred because a
37214 retry time has not yet been reached. However, this &"retry time not reached"&
37215 message is always omitted from individual message logs after the first delivery
37216 attempt.
37217 .next
37218 .cindex "log" "return path"
37219 &%return_path_on_delivery%&: The return path that is being transmitted with
37220 the message is included in delivery and bounce lines, using the tag P=.
37221 This is omitted if no delivery actually happens, for example, if routing fails,
37222 or if delivery is to &_/dev/null_& or to &`:blackhole:`&.
37223 .next
37224 .cindex "log" "sender on delivery"
37225 &%sender_on_delivery%&: The message's sender address is added to every delivery
37226 and bounce line, tagged by F= (for &"from"&).
37227 This is the original sender that was received with the message; it is not
37228 necessarily the same as the outgoing return path.
37229 .next
37230 .cindex "log" "sender verify failure"
37231 &%sender_verify_fail%&: If this selector is unset, the separate log line that
37232 gives details of a sender verification failure is not written. Log lines for
37233 the rejection of SMTP commands contain just &"sender verify failed"&, so some
37234 detail is lost.
37235 .next
37236 .cindex "log" "size rejection"
37237 &%size_reject%&: A log line is written whenever a message is rejected because
37238 it is too big.
37239 .next
37240 .cindex "log" "frozen messages; skipped"
37241 .cindex "frozen messages" "logging skipping"
37242 &%skip_delivery%&: A log line is written whenever a message is skipped during a
37243 queue run because it is frozen or because another process is already delivering
37244 it.
37245 .cindex "&""spool file is locked""&"
37246 The message that is written is &"spool file is locked"&.
37247 .next
37248 .cindex "log" "smtp confirmation"
37249 .cindex "SMTP" "logging confirmation"
37250 .cindex "LMTP" "logging confirmation"
37251 &%smtp_confirmation%&: The response to the final &"."& in the SMTP or LMTP dialogue for
37252 outgoing messages is added to delivery log lines in the form &`C=`&<&'text'&>.
37253 A number of MTAs (including Exim) return an identifying string in this
37254 response.
37255 .next
37256 .cindex "log" "SMTP connections"
37257 .cindex "SMTP" "logging connections"
37258 &%smtp_connection%&: A log line is written whenever an incoming SMTP connection is
37259 established or closed, unless the connection is from a host that matches
37260 &%hosts_connection_nolog%&. (In contrast, &%lost_incoming_connection%& applies
37261 only when the closure is unexpected.) This applies to connections from local
37262 processes that use &%-bs%& as well as to TCP/IP connections. If a connection is
37263 dropped in the middle of a message, a log line is always written, whether or
37264 not this selector is set, but otherwise nothing is written at the start and end
37265 of connections unless this selector is enabled.
37266
37267 For TCP/IP connections to an Exim daemon, the current number of connections is
37268 included in the log message for each new connection, but note that the count is
37269 reset if the daemon is restarted.
37270 Also, because connections are closed (and the closure is logged) in
37271 subprocesses, the count may not include connections that have been closed but
37272 whose termination the daemon has not yet noticed. Thus, while it is possible to
37273 match up the opening and closing of connections in the log, the value of the
37274 logged counts may not be entirely accurate.
37275 .next
37276 .cindex "log" "SMTP transaction; incomplete"
37277 .cindex "SMTP" "logging incomplete transactions"
37278 &%smtp_incomplete_transaction%&: When a mail transaction is aborted by
37279 RSET, QUIT, loss of connection, or otherwise, the incident is logged,
37280 and the message sender plus any accepted recipients are included in the log
37281 line. This can provide evidence of dictionary attacks.
37282 .next
37283 .cindex "log" "non-MAIL SMTP sessions"
37284 .cindex "MAIL" "logging session without"
37285 &%smtp_no_mail%&: A line is written to the main log whenever an accepted SMTP
37286 connection terminates without having issued a MAIL command. This includes both
37287 the case when the connection is dropped, and the case when QUIT is used. It
37288 does not include cases where the connection is rejected right at the start (by
37289 an ACL, or because there are too many connections, or whatever). These cases
37290 already have their own log lines.
37291
37292 The log line that is written contains the identity of the client in the usual
37293 way, followed by D= and a time, which records the duration of the connection.
37294 If the connection was authenticated, this fact is logged exactly as it is for
37295 an incoming message, with an A= item. If the connection was encrypted, CV=,
37296 DN=, and X= items may appear as they do for an incoming message, controlled by
37297 the same logging options.
37298
37299 Finally, if any SMTP commands were issued during the connection, a C= item
37300 is added to the line, listing the commands that were used. For example,
37301 .code
37302 C=EHLO,QUIT
37303 .endd
37304 shows that the client issued QUIT straight after EHLO. If there were fewer
37305 than 20 commands, they are all listed. If there were more than 20 commands,
37306 the last 20 are listed, preceded by &"..."&. However, with the default
37307 setting of 10 for &%smtp_accept_max_nonmail%&, the connection will in any case
37308 have been aborted before 20 non-mail commands are processed.
37309 .next
37310 &%smtp_mailauth%&: A third subfield with the authenticated sender,
37311 colon-separated, is appended to the A= item for a message arrival or delivery
37312 log line, if an AUTH argument to the SMTP MAIL command (see &<<SECTauthparamail>>&)
37313 was accepted or used.
37314 .next
37315 .cindex "log" "SMTP protocol error"
37316 .cindex "SMTP" "logging protocol error"
37317 &%smtp_protocol_error%&: A log line is written for every SMTP protocol error
37318 encountered. Exim does not have perfect detection of all protocol errors
37319 because of transmission delays and the use of pipelining. If PIPELINING has
37320 been advertised to a client, an Exim server assumes that the client will use
37321 it, and therefore it does not count &"expected"& errors (for example, RCPT
37322 received after rejecting MAIL) as protocol errors.
37323 .next
37324 .cindex "SMTP" "logging syntax errors"
37325 .cindex "SMTP" "syntax errors; logging"
37326 .cindex "SMTP" "unknown command; logging"
37327 .cindex "log" "unknown SMTP command"
37328 .cindex "log" "SMTP syntax error"
37329 &%smtp_syntax_error%&: A log line is written for every SMTP syntax error
37330 encountered. An unrecognized command is treated as a syntax error. For an
37331 external connection, the host identity is given; for an internal connection
37332 using &%-bs%& the sender identification (normally the calling user) is given.
37333 .next
37334 .cindex "log" "subject"
37335 .cindex "subject, logging"
37336 &%subject%&: The subject of the message is added to the arrival log line,
37337 preceded by &"T="& (T for &"topic"&, since S is already used for &"size"&).
37338 Any MIME &"words"& in the subject are decoded. The &%print_topbitchars%& option
37339 specifies whether characters with values greater than 127 should be logged
37340 unchanged, or whether they should be rendered as escape sequences.
37341 .next
37342 .cindex "log" "certificate verification"
37343 .cindex log DANE
37344 .cindex DANE logging
37345 &%tls_certificate_verified%&: An extra item is added to <= and => log lines
37346 when TLS is in use. The item is &`CV=yes`& if the peer's certificate was
37347 verified
37348 using a CA trust anchor,
37349 &`CA=dane`& if using a DNS trust anchor,
37350 and &`CV=no`& if not.
37351 .next
37352 .cindex "log" "TLS cipher"
37353 .cindex "TLS" "logging cipher"
37354 &%tls_cipher%&: When a message is sent or received over an encrypted
37355 connection, the cipher suite used is added to the log line, preceded by X=.
37356 .next
37357 .cindex "log" "TLS peer DN"
37358 .cindex "TLS" "logging peer DN"
37359 &%tls_peerdn%&: When a message is sent or received over an encrypted
37360 connection, and a certificate is supplied by the remote host, the peer DN is
37361 added to the log line, preceded by DN=.
37362 .next
37363 .cindex "log" "TLS SNI"
37364 .cindex "TLS" "logging SNI"
37365 &%tls_sni%&: When a message is received over an encrypted connection, and
37366 the remote host provided the Server Name Indication extension, the SNI is
37367 added to the log line, preceded by SNI=.
37368 .next
37369 .cindex "log" "DNS failure in list"
37370 &%unknown_in_list%&: This setting causes a log entry to be written when the
37371 result of a list match is failure because a DNS lookup failed.
37372 .endlist
37373
37374
37375 .section "Message log" "SECID260"
37376 .cindex "message" "log file for"
37377 .cindex "log" "message log; description of"
37378 .cindex "&_msglog_& directory"
37379 .oindex "&%preserve_message_logs%&"
37380 In addition to the general log files, Exim writes a log file for each message
37381 that it handles. The names of these per-message logs are the message ids, and
37382 they are kept in the &_msglog_& sub-directory of the spool directory. Each
37383 message log contains copies of the log lines that apply to the message. This
37384 makes it easier to inspect the status of an individual message without having
37385 to search the main log. A message log is deleted when processing of the message
37386 is complete, unless &%preserve_message_logs%& is set, but this should be used
37387 only with great care because they can fill up your disk very quickly.
37388
37389 On a heavily loaded system, it may be desirable to disable the use of
37390 per-message logs, in order to reduce disk I/O. This can be done by setting the
37391 &%message_logs%& option false.
37392 .ecindex IIDloggen
37393
37394
37395
37396
37397 . ////////////////////////////////////////////////////////////////////////////
37398 . ////////////////////////////////////////////////////////////////////////////
37399
37400 .chapter "Exim utilities" "CHAPutils"
37401 .scindex IIDutils "utilities"
37402 A number of utility scripts and programs are supplied with Exim and are
37403 described in this chapter. There is also the Exim Monitor, which is covered in
37404 the next chapter. The utilities described here are:
37405
37406 .itable none 0 0 3  7* left  15* left  40* left
37407 .irow &<<SECTfinoutwha>>&     &'exiwhat'&       &&&
37408   "list what Exim processes are doing"
37409 .irow &<<SECTgreptheque>>&    &'exiqgrep'&      "grep the queue"
37410 .irow &<<SECTsumtheque>>&     &'exiqsumm'&      "summarize the queue"
37411 .irow &<<SECTextspeinf>>&     &'exigrep'&       "search the main log"
37412 .irow &<<SECTexipick>>&       &'exipick'&       "select messages on &&&
37413                                                 various criteria"
37414 .irow &<<SECTcyclogfil>>&     &'exicyclog'&     "cycle (rotate) log files"
37415 .irow &<<SECTmailstat>>&      &'eximstats'&     &&&
37416   "extract statistics from the log"
37417 .irow &<<SECTcheckaccess>>&   &'exim_checkaccess'& &&&
37418   "check address acceptance from given IP"
37419 .irow &<<SECTdbmbuild>>&      &'exim_dbmbuild'& "build a DBM file"
37420 .irow &<<SECTfinindret>>&     &'exinext'&       "extract retry information"
37421 .irow &<<SECThindatmai>>&     &'exim_dumpdb'&   "dump a hints database"
37422 .irow &<<SECThindatmai>>&     &'exim_tidydb'&   "clean up a hints database"
37423 .irow &<<SECThindatmai>>&     &'exim_fixdb'&    "patch a hints database"
37424 .irow &<<SECTmailboxmaint>>&  &'exim_lock'&     "lock a mailbox file"
37425 .endtable
37426
37427 Another utility that might be of use to sites with many MTAs is Tom Kistner's
37428 &'exilog'&. It provides log visualizations across multiple Exim servers. See
37429 &url(https://duncanthrax.net/exilog/) for details.
37430
37431
37432
37433
37434 .section "Finding out what Exim processes are doing (exiwhat)" "SECTfinoutwha"
37435 .cindex "&'exiwhat'&"
37436 .cindex "process, querying"
37437 .cindex "SIGUSR1"
37438 On operating systems that can restart a system call after receiving a signal
37439 (most modern OS), an Exim process responds to the SIGUSR1 signal by writing
37440 a line describing what it is doing to the file &_exim-process.info_& in the
37441 Exim spool directory. The &'exiwhat'& script sends the signal to all Exim
37442 processes it can find, having first emptied the file. It then waits for one
37443 second to allow the Exim processes to react before displaying the results. In
37444 order to run &'exiwhat'& successfully you have to have sufficient privilege to
37445 send the signal to the Exim processes, so it is normally run as root.
37446
37447 &*Warning*&: This is not an efficient process. It is intended for occasional
37448 use by system administrators. It is not sensible, for example, to set up a
37449 script that sends SIGUSR1 signals to Exim processes at short intervals.
37450
37451
37452 Unfortunately, the &'ps'& command that &'exiwhat'& uses to find Exim processes
37453 varies in different operating systems. Not only are different options used,
37454 but the format of the output is different. For this reason, there are some
37455 system configuration options that configure exactly how &'exiwhat'& works. If
37456 it doesn't seem to be working for you, check the following compile-time
37457 options:
37458 .display
37459 &`EXIWHAT_PS_CMD    `& the command for running &'ps'&
37460 &`EXIWHAT_PS_ARG    `& the argument for &'ps'&
37461 &`EXIWHAT_EGREP_ARG `& the argument for &'egrep'& to select from &'ps'& output
37462 &`EXIWHAT_KILL_ARG  `& the argument for the &'kill'& command
37463 .endd
37464 An example of typical output from &'exiwhat'& is
37465 .code
37466 164 daemon: -q1h, listening on port 25
37467 10483 running queue: waiting for 0tAycK-0002ij-00 (10492)
37468 10492 delivering 0tAycK-0002ij-00 to mail.ref.example
37469   [10.19.42.42] (editor@ref.example)
37470 10592 handling incoming call from [192.168.243.242]
37471 10628 accepting a local non-SMTP message
37472 .endd
37473 The first number in the output line is the process number. The third line has
37474 been split here, in order to fit it on the page.
37475
37476
37477
37478 .section "Selective queue listing (exiqgrep)" "SECTgreptheque"
37479 .cindex "&'exiqgrep'&"
37480 .cindex "queue" "grepping"
37481 This utility is a Perl script contributed by Matt Hubbard. It runs
37482 .code
37483 exim -bpu
37484 .endd
37485 or (in case &*-a*& switch is specified)
37486 .code
37487 exim -bp
37488 .endd
37489 The &*-C*& option is used to specify an alternate &_exim.conf_& which might
37490 contain alternate exim configuration the queue management might be using.
37491
37492 to obtain a queue listing, and then greps the output to select messages
37493 that match given criteria. The following selection options are available:
37494
37495 .vlist
37496 .vitem &*-f*&&~<&'regex'&>
37497 Match the sender address using a case-insensitive search. The field that is
37498 tested is enclosed in angle brackets, so you can test for bounce messages with
37499 .code
37500 exiqgrep -f '^<>$'
37501 .endd
37502 .vitem &*-r*&&~<&'regex'&>
37503 Match a recipient address using a case-insensitive search. The field that is
37504 tested is not enclosed in angle brackets.
37505
37506 .vitem &*-s*&&~<&'regex'&>
37507 Match against the size field.
37508
37509 .vitem &*-y*&&~<&'seconds'&>
37510 Match messages that are younger than the given time.
37511
37512 .vitem &*-o*&&~<&'seconds'&>
37513 Match messages that are older than the given time.
37514
37515 .vitem &*-z*&
37516 Match only frozen messages.
37517
37518 .vitem &*-x*&
37519 Match only non-frozen messages.
37520 .endlist
37521
37522 The following options control the format of the output:
37523
37524 .vlist
37525 .vitem &*-c*&
37526 Display only the count of matching messages.
37527
37528 .vitem &*-l*&
37529 Long format &-- display the full message information as output by Exim. This is
37530 the default.
37531
37532 .vitem &*-i*&
37533 Display message ids only.
37534
37535 .vitem &*-b*&
37536 Brief format &-- one line per message.
37537
37538 .vitem &*-R*&
37539 Display messages in reverse order.
37540
37541 .vitem &*-a*&
37542 Include delivered recipients in queue listing.
37543 .endlist
37544
37545 There is one more option, &%-h%&, which outputs a list of options.
37546
37547
37548
37549 .section "Summarizing the queue (exiqsumm)" "SECTsumtheque"
37550 .cindex "&'exiqsumm'&"
37551 .cindex "queue" "summary"
37552 The &'exiqsumm'& utility is a Perl script which reads the output of &`exim
37553 -bp`& and produces a summary of the messages on the queue. Thus, you use it by
37554 running a command such as
37555 .code
37556 exim -bp | exiqsumm
37557 .endd
37558 The output consists of one line for each domain that has messages waiting for
37559 it, as in the following example:
37560 .code
37561 3   2322   74m   66m  msn.com.example
37562 .endd
37563 Each line lists the number of pending deliveries for a domain, their total
37564 volume, and the length of time that the oldest and the newest messages have
37565 been waiting. Note that the number of pending deliveries is greater than the
37566 number of messages when messages have more than one recipient.
37567
37568 A summary line is output at the end. By default the output is sorted on the
37569 domain name, but &'exiqsumm'& has the options &%-a%& and &%-c%&, which cause
37570 the output to be sorted by oldest message and by count of messages,
37571 respectively. There are also three options that split the messages for each
37572 domain into two or more subcounts: &%-b%& separates bounce messages, &%-f%&
37573 separates frozen messages, and &%-s%& separates messages according to their
37574 sender.
37575
37576 The output of &'exim -bp'& contains the original addresses in the message, so
37577 this also applies to the output from &'exiqsumm'&. No domains from addresses
37578 generated by aliasing or forwarding are included (unless the &%one_time%&
37579 option of the &(redirect)& router has been used to convert them into &"top
37580 level"& addresses).
37581
37582
37583
37584
37585 .section "Extracting specific information from the log (exigrep)" &&&
37586          "SECTextspeinf"
37587 .cindex "&'exigrep'&"
37588 .cindex "log" "extracts; grepping for"
37589 The &'exigrep'& utility is a Perl script that searches one or more main log
37590 files for entries that match a given pattern. When it finds a match, it
37591 extracts all the log entries for the relevant message, not just those that
37592 match the pattern. Thus, &'exigrep'& can extract complete log entries for a
37593 given message, or all mail for a given user, or for a given host, for example.
37594 The input files can be in Exim log format or syslog format.
37595 If a matching log line is not associated with a specific message, it is
37596 included in &'exigrep'&'s output without any additional lines. The usage is:
37597 .display
37598 &`exigrep [-t<`&&'n'&&`>] [-I] [-l] [-M] [-v] <`&&'pattern'&&`> [<`&&'log file'&&`>] ...`&
37599 .endd
37600 If no log file names are given on the command line, the standard input is read.
37601
37602 The &%-t%& argument specifies a number of seconds. It adds an additional
37603 condition for message selection. Messages that are complete are shown only if
37604 they spent more than <&'n'&> seconds on the queue.
37605
37606 By default, &'exigrep'& does case-insensitive matching. The &%-I%& option
37607 makes it case-sensitive. This may give a performance improvement when searching
37608 large log files. Without &%-I%&, the Perl pattern matches use Perl's &`/i`&
37609 option; with &%-I%& they do not. In both cases it is possible to change the
37610 case sensitivity within the pattern by using &`(?i)`& or &`(?-i)`&.
37611
37612 The &%-l%& option means &"literal"&, that is, treat all characters in the
37613 pattern as standing for themselves. Otherwise the pattern must be a Perl
37614 regular expression.
37615
37616 The &%-v%& option inverts the matching condition. That is, a line is selected
37617 if it does &'not'& match the pattern.
37618
37619 The &%-M%& options means &"related messages"&. &'exigrep'& will show messages
37620 that are generated as a result/response to a message that &'exigrep'& matched
37621 normally.
37622
37623 Example of &%-M%&:
37624 user_a sends a message to user_b, which generates a bounce back to user_b. If
37625 &'exigrep'& is used to search for &"user_a"&, only the first message will be
37626 displayed.  But if &'exigrep'& is used to search for &"user_b"&, the first and
37627 the second (bounce) message will be displayed. Using &%-M%& with &'exigrep'&
37628 when searching for &"user_a"& will show both messages since the bounce is
37629 &"related"& to or a &"result"& of the first message that was found by the
37630 search term.
37631
37632 If the location of a &'zcat'& command is known from the definition of
37633 ZCAT_COMMAND in &_Local/Makefile_&, &'exigrep'& automatically passes any file
37634 whose name ends in COMPRESS_SUFFIX through &'zcat'& as it searches it.
37635 If the ZCAT_COMMAND is not executable, &'exigrep'& tries to use
37636 autodetection of some well known compression extensions.
37637
37638
37639 .section "Selecting messages by various criteria (exipick)" "SECTexipick"
37640 .cindex "&'exipick'&"
37641 John Jetmore's &'exipick'& utility is included in the Exim distribution. It
37642 lists messages from the queue according to a variety of criteria. For details
37643 of &'exipick'&'s facilities, run &'exipick'& with
37644 the &%--help%& option.
37645
37646
37647 .section "Cycling log files (exicyclog)" "SECTcyclogfil"
37648 .cindex "log" "cycling local files"
37649 .cindex "cycling logs"
37650 .cindex "&'exicyclog'&"
37651 The &'exicyclog'& script can be used to cycle (rotate) &'mainlog'& and
37652 &'rejectlog'& files. This is not necessary if only syslog is being used, or if
37653 you are using log files with datestamps in their names (see section
37654 &<<SECTdatlogfil>>&). Some operating systems have their own standard mechanisms
37655 for log cycling, and these can be used instead of &'exicyclog'& if preferred.
37656 There are two command line options for &'exicyclog'&:
37657 .ilist
37658 &%-k%& <&'count'&> specifies the number of log files to keep, overriding the
37659 default that is set when Exim is built. The default default is 10.
37660 .next
37661 &%-l%& <&'path'&> specifies the log file path, in the same format as Exim's
37662 &%log_file_path%& option (for example, &`/var/log/exim_%slog`&), again
37663 overriding the script's default, which is to find the setting from Exim's
37664 configuration.
37665 .endlist
37666
37667 Each time &'exicyclog'& is run the file names get &"shuffled down"& by one. If
37668 the main log file name is &_mainlog_& (the default) then when &'exicyclog'& is
37669 run &_mainlog_& becomes &_mainlog.01_&, the previous &_mainlog.01_& becomes
37670 &_mainlog.02_& and so on, up to the limit that is set in the script or by the
37671 &%-k%& option. Log files whose numbers exceed the limit are discarded. Reject
37672 logs are handled similarly.
37673
37674 If the limit is greater than 99, the script uses 3-digit numbers such as
37675 &_mainlog.001_&, &_mainlog.002_&, etc. If you change from a number less than 99
37676 to one that is greater, or &'vice versa'&, you will have to fix the names of
37677 any existing log files.
37678
37679 If no &_mainlog_& file exists, the script does nothing. Files that &"drop off"&
37680 the end are deleted. All files with numbers greater than 01 are compressed,
37681 using a compression command which is configured by the COMPRESS_COMMAND
37682 setting in &_Local/Makefile_&. It is usual to run &'exicyclog'& daily from a
37683 root &%crontab%& entry of the form
37684 .code
37685 1 0 * * * su exim -c /usr/exim/bin/exicyclog
37686 .endd
37687 assuming you have used the name &"exim"& for the Exim user. You can run
37688 &'exicyclog'& as root if you wish, but there is no need.
37689
37690
37691
37692 .section "Mail statistics (eximstats)" "SECTmailstat"
37693 .cindex "statistics"
37694 .cindex "&'eximstats'&"
37695 A Perl script called &'eximstats'& is provided for extracting statistical
37696 information from log files. The output is either plain text, or HTML.
37697 . --- 2018-09-07: LogReport's Lire appears to be dead; website is a Yahoo Japan
37698 . --- 404 error and everything else points to that.
37699
37700 The &'eximstats'& script has been hacked about quite a bit over time. The
37701 latest version is the result of some extensive revision by Steve Campbell. A
37702 lot of information is given by default, but there are options for suppressing
37703 various parts of it. Following any options, the arguments to the script are a
37704 list of files, which should be main log files. For example:
37705 .code
37706 eximstats -nr /var/spool/exim/log/mainlog.01
37707 .endd
37708 By default, &'eximstats'& extracts information about the number and volume of
37709 messages received from or delivered to various hosts. The information is sorted
37710 both by message count and by volume, and the top fifty hosts in each category
37711 are listed on the standard output. Similar information, based on email
37712 addresses or domains instead of hosts can be requested by means of various
37713 options. For messages delivered and received locally, similar statistics are
37714 also produced per user.
37715
37716 The output also includes total counts and statistics about delivery errors, and
37717 histograms showing the number of messages received and deliveries made in each
37718 hour of the day. A delivery with more than one address in its envelope (for
37719 example, an SMTP transaction with more than one RCPT command) is counted
37720 as a single delivery by &'eximstats'&.
37721
37722 Though normally more deliveries than receipts are reported (as messages may
37723 have multiple recipients), it is possible for &'eximstats'& to report more
37724 messages received than delivered, even though the queue is empty at the start
37725 and end of the period in question. If an incoming message contains no valid
37726 recipients, no deliveries are recorded for it. A bounce message is handled as
37727 an entirely separate message.
37728
37729 &'eximstats'& always outputs a grand total summary giving the volume and number
37730 of messages received and deliveries made, and the number of hosts involved in
37731 each case. It also outputs the number of messages that were delayed (that is,
37732 not completely delivered at the first attempt), and the number that had at
37733 least one address that failed.
37734
37735 The remainder of the output is in sections that can be independently disabled
37736 or modified by various options. It consists of a summary of deliveries by
37737 transport, histograms of messages received and delivered per time interval
37738 (default per hour), information about the time messages spent on the queue,
37739 a list of relayed messages, lists of the top fifty sending hosts, local
37740 senders, destination hosts, and destination local users by count and by volume,
37741 and a list of delivery errors that occurred.
37742
37743 The relay information lists messages that were actually relayed, that is, they
37744 came from a remote host and were directly delivered to some other remote host,
37745 without being processed (for example, for aliasing or forwarding) locally.
37746
37747 There are quite a few options for &'eximstats'& to control exactly what it
37748 outputs. These are documented in the Perl script itself, and can be extracted
37749 by running the command &(perldoc)& on the script. For example:
37750 .code
37751 perldoc /usr/exim/bin/eximstats
37752 .endd
37753
37754 .section "Checking access policy (exim_checkaccess)" "SECTcheckaccess"
37755 .cindex "&'exim_checkaccess'&"
37756 .cindex "policy control" "checking access"
37757 .cindex "checking access"
37758 The &%-bh%& command line argument allows you to run a fake SMTP session with
37759 debugging output, in order to check what Exim is doing when it is applying
37760 policy controls to incoming SMTP mail. However, not everybody is sufficiently
37761 familiar with the SMTP protocol to be able to make full use of &%-bh%&, and
37762 sometimes you just want to answer the question &"Does this address have
37763 access?"& without bothering with any further details.
37764
37765 The &'exim_checkaccess'& utility is a &"packaged"& version of &%-bh%&. It takes
37766 two arguments, an IP address and an email address:
37767 .code
37768 exim_checkaccess 10.9.8.7 A.User@a.domain.example
37769 .endd
37770 The utility runs a call to Exim with the &%-bh%& option, to test whether the
37771 given email address would be accepted in a RCPT command in a TCP/IP
37772 connection from the host with the given IP address. The output of the utility
37773 is either the word &"accepted"&, or the SMTP error response, for example:
37774 .code
37775 Rejected:
37776 550 Relay not permitted
37777 .endd
37778 When running this test, the utility uses &`<>`& as the envelope sender address
37779 for the MAIL command, but you can change this by providing additional
37780 options. These are passed directly to the Exim command. For example, to specify
37781 that the test is to be run with the sender address &'himself@there.example'&
37782 you can use:
37783 .code
37784 exim_checkaccess 10.9.8.7 A.User@a.domain.example \
37785                  -f himself@there.example
37786 .endd
37787 Note that these additional Exim command line items must be given after the two
37788 mandatory arguments.
37789
37790 Because the &%exim_checkaccess%& uses &%-bh%&, it does not perform callouts
37791 while running its checks. You can run checks that include callouts by using
37792 &%-bhc%&, but this is not yet available in a &"packaged"& form.
37793
37794
37795
37796 .section "Making DBM files (exim_dbmbuild)" "SECTdbmbuild"
37797 .cindex "DBM" "building dbm files"
37798 .cindex "building DBM files"
37799 .cindex "&'exim_dbmbuild'&"
37800 .cindex "lower casing"
37801 .cindex "binary zero" "in lookup key"
37802 The &'exim_dbmbuild'& program reads an input file containing keys and data in
37803 the format used by the &(lsearch)& lookup (see section
37804 &<<SECTsinglekeylookups>>&). It writes a DBM file using the lower-cased alias
37805 names as keys and the remainder of the information as data. The lower-casing
37806 can be prevented by calling the program with the &%-nolc%& option.
37807
37808 A terminating zero is included as part of the key string. This is expected by
37809 the &(dbm)& lookup type. However, if the option &%-nozero%& is given,
37810 &'exim_dbmbuild'& creates files without terminating zeroes in either the key
37811 strings or the data strings. The &(dbmnz)& lookup type can be used with such
37812 files.
37813
37814 The program requires two arguments: the name of the input file (which can be a
37815 single hyphen to indicate the standard input), and the name of the output file.
37816 It creates the output under a temporary name, and then renames it if all went
37817 well.
37818
37819 .cindex "USE_DB"
37820 If the native DB interface is in use (USE_DB is set in a compile-time
37821 configuration file &-- this is common in free versions of Unix) the two file
37822 names must be different, because in this mode the Berkeley DB functions create
37823 a single output file using exactly the name given. For example,
37824 .code
37825 exim_dbmbuild /etc/aliases /etc/aliases.db
37826 .endd
37827 reads the system alias file and creates a DBM version of it in
37828 &_/etc/aliases.db_&.
37829
37830 In systems that use the &'ndbm'& routines (mostly proprietary versions of
37831 Unix), two files are used, with the suffixes &_.dir_& and &_.pag_&. In this
37832 environment, the suffixes are added to the second argument of
37833 &'exim_dbmbuild'&, so it can be the same as the first. This is also the case
37834 when the Berkeley functions are used in compatibility mode (though this is not
37835 recommended), because in that case it adds a &_.db_& suffix to the file name.
37836
37837 If a duplicate key is encountered, the program outputs a warning, and when it
37838 finishes, its return code is 1 rather than zero, unless the &%-noduperr%&
37839 option is used. By default, only the first of a set of duplicates is used &--
37840 this makes it compatible with &(lsearch)& lookups. There is an option
37841 &%-lastdup%& which causes it to use the data for the last duplicate instead.
37842 There is also an option &%-nowarn%&, which stops it listing duplicate keys to
37843 &%stderr%&. For other errors, where it doesn't actually make a new file, the
37844 return code is 2.
37845
37846
37847
37848
37849 .section "Finding individual retry times (exinext)" "SECTfinindret"
37850 .cindex "retry" "times"
37851 .cindex "&'exinext'&"
37852 A utility called &'exinext'& (mostly a Perl script) provides the ability to
37853 fish specific information out of the retry database. Given a mail domain (or a
37854 complete address), it looks up the hosts for that domain, and outputs any retry
37855 information for the hosts or for the domain. At present, the retry information
37856 is obtained by running &'exim_dumpdb'& (see below) and post-processing the
37857 output. For example:
37858 .code
37859 $ exinext piglet@milne.fict.example
37860 kanga.milne.example:192.168.8.1 error 146: Connection refused
37861   first failed: 21-Feb-1996 14:57:34
37862   last tried:   21-Feb-1996 14:57:34
37863   next try at:  21-Feb-1996 15:02:34
37864 roo.milne.example:192.168.8.3 error 146: Connection refused
37865   first failed: 20-Jan-1996 13:12:08
37866   last tried:   21-Feb-1996 11:42:03
37867   next try at:  21-Feb-1996 19:42:03
37868   past final cutoff time
37869 .endd
37870 You can also give &'exinext'& a local part, without a domain, and it
37871 will give any retry information for that local part in your default domain.
37872 A message id can be used to obtain retry information pertaining to a specific
37873 message. This exists only when an attempt to deliver a message to a remote host
37874 suffers a message-specific error (see section &<<SECToutSMTPerr>>&).
37875 &'exinext'& is not particularly efficient, but then it is not expected to be
37876 run very often.
37877
37878 The &'exinext'& utility calls Exim to find out information such as the location
37879 of the spool directory. The utility has &%-C%& and &%-D%& options, which are
37880 passed on to the &'exim'& commands. The first specifies an alternate Exim
37881 configuration file, and the second sets macros for use within the configuration
37882 file. These features are mainly to help in testing, but might also be useful in
37883 environments where more than one configuration file is in use.
37884
37885
37886
37887 .section "Hints database maintenance" "SECThindatmai"
37888 .cindex "hints database" "maintenance"
37889 .cindex "maintaining Exim's hints database"
37890 Three utility programs are provided for maintaining the DBM files that Exim
37891 uses to contain its delivery hint information. Each program requires two
37892 arguments. The first specifies the name of Exim's spool directory, and the
37893 second is the name of the database it is to operate on. These are as follows:
37894
37895 .ilist
37896 &'retry'&: the database of retry information
37897 .next
37898 &'wait-'&<&'transport name'&>: databases of information about messages waiting
37899 for remote hosts
37900 .next
37901 &'callout'&: the callout cache
37902 .next
37903 &'ratelimit'&: the data for implementing the ratelimit ACL condition
37904 .next
37905 &'misc'&: other hints data
37906 .endlist
37907
37908 The &'misc'& database is used for
37909
37910 .ilist
37911 Serializing ETRN runs (when &%smtp_etrn_serialize%& is set)
37912 .next
37913 Serializing delivery to a specific host (when &%serialize_hosts%& is set in an
37914 &(smtp)& transport)
37915 .next
37916 Limiting the concurrency of specific transports (when &%max_parallel%& is set
37917 in a transport)
37918 .endlist
37919
37920
37921
37922 .section "exim_dumpdb" "SECID261"
37923 .cindex "&'exim_dumpdb'&"
37924 The entire contents of a database are written to the standard output by the
37925 &'exim_dumpdb'& program, which has no options or arguments other than the
37926 spool and database names. For example, to dump the retry database:
37927 .code
37928 exim_dumpdb /var/spool/exim retry
37929 .endd
37930 Two lines of output are produced for each entry:
37931 .code
37932 T:mail.ref.example:192.168.242.242 146 77 Connection refused
37933 31-Oct-1995 12:00:12 02-Nov-1995 12:21:39 02-Nov-1995 20:21:39 *
37934 .endd
37935 The first item on the first line is the key of the record. It starts with one
37936 of the letters R, or T, depending on whether it refers to a routing or
37937 transport retry. For a local delivery, the next part is the local address; for
37938 a remote delivery it is the name of the remote host, followed by its failing IP
37939 address (unless &%retry_include_ip_address%& is set false on the &(smtp)&
37940 transport). If the remote port is not the standard one (port 25), it is added
37941 to the IP address. Then there follows an error code, an additional error code,
37942 and a textual description of the error.
37943
37944 The three times on the second line are the time of first failure, the time of
37945 the last delivery attempt, and the computed time for the next attempt. The line
37946 ends with an asterisk if the cutoff time for the last retry rule has been
37947 exceeded.
37948
37949 Each output line from &'exim_dumpdb'& for the &'wait-xxx'& databases
37950 consists of a host name followed by a list of ids for messages that are or were
37951 waiting to be delivered to that host. If there are a very large number for any
37952 one host, continuation records, with a sequence number added to the host name,
37953 may be seen. The data in these records is often out of date, because a message
37954 may be routed to several alternative hosts, and Exim makes no effort to keep
37955 cross-references.
37956
37957
37958
37959 .section "exim_tidydb" "SECID262"
37960 .cindex "&'exim_tidydb'&"
37961 The &'exim_tidydb'& utility program is used to tidy up the contents of a hints
37962 database. If run with no options, it removes all records that are more than 30
37963 days old. The age is calculated from the date and time that the record was last
37964 updated. Note that, in the case of the retry database, it is &'not'& the time
37965 since the first delivery failure. Information about a host that has been down
37966 for more than 30 days will remain in the database, provided that the record is
37967 updated sufficiently often.
37968
37969 The cutoff date can be altered by means of the &%-t%& option, which must be
37970 followed by a time. For example, to remove all records older than a week from
37971 the retry database:
37972 .code
37973 exim_tidydb -t 7d /var/spool/exim retry
37974 .endd
37975 Both the &'wait-xxx'& and &'retry'& databases contain items that involve
37976 message ids. In the former these appear as data in records keyed by host &--
37977 they were messages that were waiting for that host &-- and in the latter they
37978 are the keys for retry information for messages that have suffered certain
37979 types of error. When &'exim_tidydb'& is run, a check is made to ensure that
37980 message ids in database records are those of messages that are still on the
37981 queue. Message ids for messages that no longer exist are removed from
37982 &'wait-xxx'& records, and if this leaves any records empty, they are deleted.
37983 For the &'retry'& database, records whose keys are non-existent message ids are
37984 removed. The &'exim_tidydb'& utility outputs comments on the standard output
37985 whenever it removes information from the database.
37986
37987 Certain records are automatically removed by Exim when they are no longer
37988 needed, but others are not. For example, if all the MX hosts for a domain are
37989 down, a retry record is created for each one. If the primary MX host comes back
37990 first, its record is removed when Exim successfully delivers to it, but the
37991 records for the others remain because Exim has not tried to use those hosts.
37992
37993 It is important, therefore, to run &'exim_tidydb'& periodically on all the
37994 hints databases. You should do this at a quiet time of day, because it requires
37995 a database to be locked (and therefore inaccessible to Exim) while it does its
37996 work. Removing records from a DBM file does not normally make the file smaller,
37997 but all the common DBM libraries are able to re-use the space that is released.
37998 After an initial phase of increasing in size, the databases normally reach a
37999 point at which they no longer get any bigger, as long as they are regularly
38000 tidied.
38001
38002 &*Warning*&: If you never run &'exim_tidydb'&, the space used by the hints
38003 databases is likely to keep on increasing.
38004
38005
38006
38007
38008 .section "exim_fixdb" "SECID263"
38009 .cindex "&'exim_fixdb'&"
38010 The &'exim_fixdb'& program is a utility for interactively modifying databases.
38011 Its main use is for testing Exim, but it might also be occasionally useful for
38012 getting round problems in a live system. It has no options, and its interface
38013 is somewhat crude. On entry, it prompts for input with a right angle-bracket. A
38014 key of a database record can then be entered, and the data for that record is
38015 displayed.
38016
38017 If &"d"& is typed at the next prompt, the entire record is deleted. For all
38018 except the &'retry'& database, that is the only operation that can be carried
38019 out. For the &'retry'& database, each field is output preceded by a number, and
38020 data for individual fields can be changed by typing the field number followed
38021 by new data, for example:
38022 .code
38023 > 4 951102:1000
38024 .endd
38025 resets the time of the next delivery attempt. Time values are given as a
38026 sequence of digit pairs for year, month, day, hour, and minute. Colons can be
38027 used as optional separators.
38028
38029
38030
38031
38032 .section "Mailbox maintenance (exim_lock)" "SECTmailboxmaint"
38033 .cindex "mailbox" "maintenance"
38034 .cindex "&'exim_lock'&"
38035 .cindex "locking mailboxes"
38036 The &'exim_lock'& utility locks a mailbox file using the same algorithm as
38037 Exim. For a discussion of locking issues, see section &<<SECTopappend>>&.
38038 &'Exim_lock'& can be used to prevent any modification of a mailbox by Exim or
38039 a user agent while investigating a problem. The utility requires the name of
38040 the file as its first argument. If the locking is successful, the second
38041 argument is run as a command (using C's &[system()]& function); if there is no
38042 second argument, the value of the SHELL environment variable is used; if this
38043 is unset or empty, &_/bin/sh_& is run. When the command finishes, the mailbox
38044 is unlocked and the utility ends. The following options are available:
38045
38046 .vlist
38047 .vitem &%-fcntl%&
38048 Use &[fcntl()]& locking on the open mailbox.
38049
38050 .vitem &%-flock%&
38051 Use &[flock()]& locking on the open mailbox, provided the operating system
38052 supports it.
38053
38054 .vitem &%-interval%&
38055 This must be followed by a number, which is a number of seconds; it sets the
38056 interval to sleep between retries (default 3).
38057
38058 .vitem &%-lockfile%&
38059 Create a lock file before opening the mailbox.
38060
38061 .vitem &%-mbx%&
38062 Lock the mailbox using MBX rules.
38063
38064 .vitem &%-q%&
38065 Suppress verification output.
38066
38067 .vitem &%-retries%&
38068 This must be followed by a number; it sets the number of times to try to get
38069 the lock (default 10).
38070
38071 .vitem &%-restore_time%&
38072 This option causes &%exim_lock%& to restore the modified and read times to the
38073 locked file before exiting. This allows you to access a locked mailbox (for
38074 example, to take a backup copy) without disturbing the times that the user
38075 subsequently sees.
38076
38077 .vitem &%-timeout%&
38078 This must be followed by a number, which is a number of seconds; it sets a
38079 timeout to be used with a blocking &[fcntl()]& lock. If it is not set (the
38080 default), a non-blocking call is used.
38081
38082 .vitem &%-v%&
38083 Generate verbose output.
38084 .endlist
38085
38086 If none of &%-fcntl%&, &%-flock%&, &%-lockfile%& or &%-mbx%& are given, the
38087 default is to create a lock file and also to use &[fcntl()]& locking on the
38088 mailbox, which is the same as Exim's default. The use of &%-flock%& or
38089 &%-fcntl%& requires that the file be writeable; the use of &%-lockfile%&
38090 requires that the directory containing the file be writeable. Locking by lock
38091 file does not last for ever; Exim assumes that a lock file is expired if it is
38092 more than 30 minutes old.
38093
38094 The &%-mbx%& option can be used with either or both of &%-fcntl%& or
38095 &%-flock%&. It assumes &%-fcntl%& by default. MBX locking causes a shared lock
38096 to be taken out on the open mailbox, and an exclusive lock on the file
38097 &_/tmp/.n.m_& where &'n'& and &'m'& are the device number and inode
38098 number of the mailbox file. When the locking is released, if an exclusive lock
38099 can be obtained for the mailbox, the file in &_/tmp_& is deleted.
38100
38101 The default output contains verification of the locking that takes place. The
38102 &%-v%& option causes some additional information to be given. The &%-q%& option
38103 suppresses all output except error messages.
38104
38105 A command such as
38106 .code
38107 exim_lock /var/spool/mail/spqr
38108 .endd
38109 runs an interactive shell while the file is locked, whereas
38110 .display
38111 &`exim_lock -q /var/spool/mail/spqr <<End`&
38112 <&'some commands'&>
38113 &`End`&
38114 .endd
38115 runs a specific non-interactive sequence of commands while the file is locked,
38116 suppressing all verification output. A single command can be run by a command
38117 such as
38118 .code
38119 exim_lock -q /var/spool/mail/spqr \
38120   "cp /var/spool/mail/spqr /some/where"
38121 .endd
38122 Note that if a command is supplied, it must be entirely contained within the
38123 second argument &-- hence the quotes.
38124 .ecindex IIDutils
38125
38126
38127 . ////////////////////////////////////////////////////////////////////////////
38128 . ////////////////////////////////////////////////////////////////////////////
38129
38130 .chapter "The Exim monitor" "CHAPeximon"
38131 .scindex IIDeximon "Exim monitor" "description"
38132 .cindex "X-windows"
38133 .cindex "&'eximon'&"
38134 .cindex "Local/eximon.conf"
38135 .cindex "&_exim_monitor/EDITME_&"
38136 The Exim monitor is an application which displays in an X window information
38137 about the state of Exim's queue and what Exim is doing. An admin user can
38138 perform certain operations on messages from this GUI interface; however all
38139 such facilities are also available from the command line, and indeed, the
38140 monitor itself makes use of the command line to perform any actions requested.
38141
38142
38143
38144 .section "Running the monitor" "SECID264"
38145 The monitor is started by running the script called &'eximon'&. This is a shell
38146 script that sets up a number of environment variables, and then runs the
38147 binary called &_eximon.bin_&. The default appearance of the monitor window can
38148 be changed by editing the &_Local/eximon.conf_& file created by editing
38149 &_exim_monitor/EDITME_&. Comments in that file describe what the various
38150 parameters are for.
38151
38152 The parameters that get built into the &'eximon'& script can be overridden for
38153 a particular invocation by setting up environment variables of the same names,
38154 preceded by &`EXIMON_`&. For example, a shell command such as
38155 .code
38156 EXIMON_LOG_DEPTH=400 eximon
38157 .endd
38158 (in a Bourne-compatible shell) runs &'eximon'& with an overriding setting of
38159 the LOG_DEPTH parameter. If EXIMON_LOG_FILE_PATH is set in the environment, it
38160 overrides the Exim log file configuration. This makes it possible to have
38161 &'eximon'& tailing log data that is written to syslog, provided that MAIL.INFO
38162 syslog messages are routed to a file on the local host.
38163
38164 X resources can be used to change the appearance of the window in the normal
38165 way. For example, a resource setting of the form
38166 .code
38167 Eximon*background: gray94
38168 .endd
38169 changes the colour of the background to light grey rather than white. The
38170 stripcharts are drawn with both the data lines and the reference lines in
38171 black. This means that the reference lines are not visible when on top of the
38172 data. However, their colour can be changed by setting a resource called
38173 &"highlight"& (an odd name, but that's what the Athena stripchart widget uses).
38174 For example, if your X server is running Unix, you could set up lighter
38175 reference lines in the stripcharts by obeying
38176 .code
38177 xrdb -merge <<End
38178 Eximon*highlight: gray
38179 End
38180 .endd
38181 .cindex "admin user"
38182 In order to see the contents of messages on the queue, and to operate on them,
38183 &'eximon'& must either be run as root or by an admin user.
38184
38185 The command-line parameters of &'eximon'& are passed to &_eximon.bin_& and may
38186 contain X11 resource parameters interpreted by the X11 library.  In addition,
38187 if the first parameter starts with the string "gdb" then it is removed and the
38188 binary is invoked under gdb (the parameter is used as the gdb command-name, so
38189 versioned variants of gdb can be invoked).
38190
38191 The monitor's window is divided into three parts. The first contains one or
38192 more stripcharts and two action buttons, the second contains a &"tail"& of the
38193 main log file, and the third is a display of the queue of messages awaiting
38194 delivery, with two more action buttons. The following sections describe these
38195 different parts of the display.
38196
38197
38198
38199
38200 .section "The stripcharts" "SECID265"
38201 .cindex "stripchart"
38202 The first stripchart is always a count of messages on the queue. Its name can
38203 be configured by setting QUEUE_STRIPCHART_NAME in the
38204 &_Local/eximon.conf_& file. The remaining stripcharts are defined in the
38205 configuration script by regular expression matches on log file entries, making
38206 it possible to display, for example, counts of messages delivered to certain
38207 hosts or using certain transports. The supplied defaults display counts of
38208 received and delivered messages, and of local and SMTP deliveries. The default
38209 period between stripchart updates is one minute; this can be adjusted by a
38210 parameter in the &_Local/eximon.conf_& file.
38211
38212 The stripchart displays rescale themselves automatically as the value they are
38213 displaying changes. There are always 10 horizontal lines in each chart; the
38214 title string indicates the value of each division when it is greater than one.
38215 For example, &"x2"& means that each division represents a value of 2.
38216
38217 It is also possible to have a stripchart which shows the percentage fullness of
38218 a particular disk partition, which is useful when local deliveries are confined
38219 to a single partition.
38220
38221 .cindex "&%statvfs%& function"
38222 This relies on the availability of the &[statvfs()]& function or equivalent in
38223 the operating system. Most, but not all versions of Unix that support Exim have
38224 this. For this particular stripchart, the top of the chart always represents
38225 100%, and the scale is given as &"x10%"&. This chart is configured by setting
38226 SIZE_STRIPCHART and (optionally) SIZE_STRIPCHART_NAME in the
38227 &_Local/eximon.conf_& file.
38228
38229
38230
38231
38232 .section "Main action buttons" "SECID266"
38233 .cindex "size" "of monitor window"
38234 .cindex "Exim monitor" "window size"
38235 .cindex "window size"
38236 Below the stripcharts there is an action button for quitting the monitor. Next
38237 to this is another button marked &"Size"&. They are placed here so that
38238 shrinking the window to its default minimum size leaves just the queue count
38239 stripchart and these two buttons visible. Pressing the &"Size"& button causes
38240 the window to expand to its maximum size, unless it is already at the maximum,
38241 in which case it is reduced to its minimum.
38242
38243 When expanding to the maximum, if the window cannot be fully seen where it
38244 currently is, it is moved back to where it was the last time it was at full
38245 size. When it is expanding from its minimum size, the old position is
38246 remembered, and next time it is reduced to the minimum it is moved back there.
38247
38248 The idea is that you can keep a reduced window just showing one or two
38249 stripcharts at a convenient place on your screen, easily expand it to show
38250 the full window when required, and just as easily put it back to what it was.
38251 The idea is copied from what the &'twm'& window manager does for its
38252 &'f.fullzoom'& action. The minimum size of the window can be changed by setting
38253 the MIN_HEIGHT and MIN_WIDTH values in &_Local/eximon.conf_&.
38254
38255 Normally, the monitor starts up with the window at its full size, but it can be
38256 built so that it starts up with the window at its smallest size, by setting
38257 START_SMALL=yes in &_Local/eximon.conf_&.
38258
38259
38260
38261 .section "The log display" "SECID267"
38262 .cindex "log" "tail of; in monitor"
38263 The second section of the window is an area in which a display of the tail of
38264 the main log is maintained.
38265 To save space on the screen, the timestamp on each log line is shortened by
38266 removing the date and, if &%log_timezone%& is set, the timezone.
38267 The log tail is not available when the only destination for logging data is
38268 syslog, unless the syslog lines are routed to a local file whose name is passed
38269 to &'eximon'& via the EXIMON_LOG_FILE_PATH environment variable.
38270
38271 The log sub-window has a scroll bar at its lefthand side which can be used to
38272 move back to look at earlier text, and the up and down arrow keys also have a
38273 scrolling effect. The amount of log that is kept depends on the setting of
38274 LOG_BUFFER in &_Local/eximon.conf_&, which specifies the amount of memory
38275 to use. When this is full, the earlier 50% of data is discarded &-- this is
38276 much more efficient than throwing it away line by line. The sub-window also has
38277 a horizontal scroll bar for accessing the ends of long log lines. This is the
38278 only means of horizontal scrolling; the right and left arrow keys are not
38279 available. Text can be cut from this part of the window using the mouse in the
38280 normal way. The size of this subwindow is controlled by parameters in the
38281 configuration file &_Local/eximon.conf_&.
38282
38283 Searches of the text in the log window can be carried out by means of the ^R
38284 and ^S keystrokes, which default to a reverse and a forward search,
38285 respectively. The search covers only the text that is displayed in the window.
38286 It cannot go further back up the log.
38287
38288 The point from which the search starts is indicated by a caret marker. This is
38289 normally at the end of the text in the window, but can be positioned explicitly
38290 by pointing and clicking with the left mouse button, and is moved automatically
38291 by a successful search. If new text arrives in the window when it is scrolled
38292 back, the caret remains where it is, but if the window is not scrolled back,
38293 the caret is moved to the end of the new text.
38294
38295 Pressing ^R or ^S pops up a window into which the search text can be typed.
38296 There are buttons for selecting forward or reverse searching, for carrying out
38297 the search, and for cancelling. If the &"Search"& button is pressed, the search
38298 happens and the window remains so that further searches can be done. If the
38299 &"Return"& key is pressed, a single search is done and the window is closed. If
38300 ^C is typed the search is cancelled.
38301
38302 The searching facility is implemented using the facilities of the Athena text
38303 widget. By default this pops up a window containing both &"search"& and
38304 &"replace"& options. In order to suppress the unwanted &"replace"& portion for
38305 eximon, a modified version of the &%TextPop%& widget is distributed with Exim.
38306 However, the linkers in BSDI and HP-UX seem unable to handle an externally
38307 provided version of &%TextPop%& when the remaining parts of the text widget
38308 come from the standard libraries. The compile-time option EXIMON_TEXTPOP can be
38309 unset to cut out the modified &%TextPop%&, making it possible to build Eximon
38310 on these systems, at the expense of having unwanted items in the search popup
38311 window.
38312
38313
38314
38315 .section "The queue display" "SECID268"
38316 .cindex "queue" "display in monitor"
38317 The bottom section of the monitor window contains a list of all messages that
38318 are on the queue, which includes those currently being received or delivered,
38319 as well as those awaiting delivery. The size of this subwindow is controlled by
38320 parameters in the configuration file &_Local/eximon.conf_&, and the frequency
38321 at which it is updated is controlled by another parameter in the same file &--
38322 the default is 5 minutes, since queue scans can be quite expensive. However,
38323 there is an &"Update"& action button just above the display which can be used
38324 to force an update of the queue display at any time.
38325
38326 When a host is down for some time, a lot of pending mail can build up for it,
38327 and this can make it hard to deal with other messages on the queue. To help
38328 with this situation there is a button next to &"Update"& called &"Hide"&. If
38329 pressed, a dialogue box called &"Hide addresses ending with"& is put up. If you
38330 type anything in here and press &"Return"&, the text is added to a chain of
38331 such texts, and if every undelivered address in a message matches at least one
38332 of the texts, the message is not displayed.
38333
38334 If there is an address that does not match any of the texts, all the addresses
38335 are displayed as normal. The matching happens on the ends of addresses so, for
38336 example, &'cam.ac.uk'& specifies all addresses in Cambridge, while
38337 &'xxx@foo.com.example'& specifies just one specific address. When any hiding
38338 has been set up, a button called &"Unhide"& is displayed. If pressed, it
38339 cancels all hiding. Also, to ensure that hidden messages do not get forgotten,
38340 a hide request is automatically cancelled after one hour.
38341
38342 While the dialogue box is displayed, you can't press any buttons or do anything
38343 else to the monitor window. For this reason, if you want to cut text from the
38344 queue display to use in the dialogue box, you have to do the cutting before
38345 pressing the &"Hide"& button.
38346
38347 The queue display contains, for each unhidden queued message, the length of
38348 time it has been on the queue, the size of the message, the message id, the
38349 message sender, and the first undelivered recipient, all on one line. If it is
38350 a bounce message, the sender is shown as &"<>"&. If there is more than one
38351 recipient to which the message has not yet been delivered, subsequent ones are
38352 listed on additional lines, up to a maximum configured number, following which
38353 an ellipsis is displayed. Recipients that have already received the message are
38354 not shown.
38355
38356 .cindex "frozen messages" "display"
38357 If a message is frozen, an asterisk is displayed at the left-hand side.
38358
38359 The queue display has a vertical scroll bar, and can also be scrolled by means
38360 of the arrow keys. Text can be cut from it using the mouse in the normal way.
38361 The text searching facilities, as described above for the log window, are also
38362 available, but the caret is always moved to the end of the text when the queue
38363 display is updated.
38364
38365
38366
38367 .section "The queue menu" "SECID269"
38368 .cindex "queue" "menu in monitor"
38369 If the &%shift%& key is held down and the left button is clicked when the mouse
38370 pointer is over the text for any message, an action menu pops up, and the first
38371 line of the queue display for the message is highlighted. This does not affect
38372 any selected text.
38373
38374 If you want to use some other event for popping up the menu, you can set the
38375 MENU_EVENT parameter in &_Local/eximon.conf_& to change the default, or
38376 set EXIMON_MENU_EVENT in the environment before starting the monitor. The
38377 value set in this parameter is a standard X event description. For example, to
38378 run eximon using &%ctrl%& rather than &%shift%& you could use
38379 .code
38380 EXIMON_MENU_EVENT='Ctrl<Btn1Down>' eximon
38381 .endd
38382 The title of the menu is the message id, and it contains entries which act as
38383 follows:
38384
38385 .ilist
38386 &'message log'&: The contents of the message log for the message are displayed
38387 in a new text window.
38388 .next
38389 &'headers'&: Information from the spool file that contains the envelope
38390 information and headers is displayed in a new text window. See chapter
38391 &<<CHAPspool>>& for a description of the format of spool files.
38392 .next
38393 &'body'&: The contents of the spool file containing the body of the message are
38394 displayed in a new text window. There is a default limit of 20,000 bytes to the
38395 amount of data displayed. This can be changed by setting the BODY_MAX
38396 option at compile time, or the EXIMON_BODY_MAX option at run time.
38397 .next
38398 &'deliver message'&: A call to Exim is made using the &%-M%& option to request
38399 delivery of the message. This causes an automatic thaw if the message is
38400 frozen. The &%-v%& option is also set, and the output from Exim is displayed in
38401 a new text window. The delivery is run in a separate process, to avoid holding
38402 up the monitor while the delivery proceeds.
38403 .next
38404 &'freeze message'&: A call to Exim is made using the &%-Mf%& option to request
38405 that the message be frozen.
38406 .next
38407 .cindex "thawing messages"
38408 .cindex "unfreezing messages"
38409 .cindex "frozen messages" "thawing"
38410 &'thaw message'&: A call to Exim is made using the &%-Mt%& option to request
38411 that the message be thawed.
38412 .next
38413 .cindex "delivery" "forcing failure"
38414 &'give up on msg'&: A call to Exim is made using the &%-Mg%& option to request
38415 that Exim gives up trying to deliver the message. A bounce message is generated
38416 for any remaining undelivered addresses.
38417 .next
38418 &'remove message'&: A call to Exim is made using the &%-Mrm%& option to request
38419 that the message be deleted from the system without generating a bounce
38420 message.
38421 .next
38422 &'add recipient'&: A dialog box is displayed into which a recipient address can
38423 be typed. If the address is not qualified and the QUALIFY_DOMAIN parameter
38424 is set in &_Local/eximon.conf_&, the address is qualified with that domain.
38425 Otherwise it must be entered as a fully qualified address. Pressing RETURN
38426 causes a call to Exim to be made using the &%-Mar%& option to request that an
38427 additional recipient be added to the message, unless the entry box is empty, in
38428 which case no action is taken.
38429 .next
38430 &'mark delivered'&: A dialog box is displayed into which a recipient address
38431 can be typed. If the address is not qualified and the QUALIFY_DOMAIN parameter
38432 is set in &_Local/eximon.conf_&, the address is qualified with that domain.
38433 Otherwise it must be entered as a fully qualified address. Pressing RETURN
38434 causes a call to Exim to be made using the &%-Mmd%& option to mark the given
38435 recipient address as already delivered, unless the entry box is empty, in which
38436 case no action is taken.
38437 .next
38438 &'mark all delivered'&: A call to Exim is made using the &%-Mmad%& option to
38439 mark all recipient addresses as already delivered.
38440 .next
38441 &'edit sender'&: A dialog box is displayed initialized with the current
38442 sender's address. Pressing RETURN causes a call to Exim to be made using the
38443 &%-Mes%& option to replace the sender address, unless the entry box is empty,
38444 in which case no action is taken. If you want to set an empty sender (as in
38445 bounce messages), you must specify it as &"<>"&. Otherwise, if the address is
38446 not qualified and the QUALIFY_DOMAIN parameter is set in &_Local/eximon.conf_&,
38447 the address is qualified with that domain.
38448 .endlist
38449
38450 When a delivery is forced, a window showing the &%-v%& output is displayed. In
38451 other cases when a call to Exim is made, if there is any output from Exim (in
38452 particular, if the command fails) a window containing the command and the
38453 output is displayed. Otherwise, the results of the action are normally apparent
38454 from the log and queue displays. However, if you set ACTION_OUTPUT=yes in
38455 &_Local/eximon.conf_&, a window showing the Exim command is always opened, even
38456 if no output is generated.
38457
38458 The queue display is automatically updated for actions such as freezing and
38459 thawing, unless ACTION_QUEUE_UPDATE=no has been set in
38460 &_Local/eximon.conf_&. In this case the &"Update"& button has to be used to
38461 force an update of the display after one of these actions.
38462
38463 In any text window that is displayed as result of a menu action, the normal
38464 cut-and-paste facility is available, and searching can be carried out using ^R
38465 and ^S, as described above for the log tail window.
38466 .ecindex IIDeximon
38467
38468
38469
38470
38471
38472 . ////////////////////////////////////////////////////////////////////////////
38473 . ////////////////////////////////////////////////////////////////////////////
38474
38475 .chapter "Security considerations" "CHAPsecurity"
38476 .scindex IIDsecurcon "security" "discussion of"
38477 This chapter discusses a number of issues concerned with security, some of
38478 which are also covered in other parts of this manual.
38479
38480 For reasons that this author does not understand, some people have promoted
38481 Exim as a &"particularly secure"& mailer. Perhaps it is because of the
38482 existence of this chapter in the documentation. However, the intent of the
38483 chapter is simply to describe the way Exim works in relation to certain
38484 security concerns, not to make any specific claims about the effectiveness of
38485 its security as compared with other MTAs.
38486
38487 What follows is a description of the way Exim is supposed to be. Best efforts
38488 have been made to try to ensure that the code agrees with the theory, but an
38489 absence of bugs can never be guaranteed. Any that are reported will get fixed
38490 as soon as possible.
38491
38492
38493 .section "Building a more &""hardened""& Exim" "SECID286"
38494 .cindex "security" "build-time features"
38495 There are a number of build-time options that can be set in &_Local/Makefile_&
38496 to create Exim binaries that are &"harder"& to attack, in particular by a rogue
38497 Exim administrator who does not have the root password, or by someone who has
38498 penetrated the Exim (but not the root) account. These options are as follows:
38499
38500 .ilist
38501 ALT_CONFIG_PREFIX can be set to a string that is required to match the
38502 start of any file names used with the &%-C%& option. When it is set, these file
38503 names are also not allowed to contain the sequence &"/../"&. (However, if the
38504 value of the &%-C%& option is identical to the value of CONFIGURE_FILE in
38505 &_Local/Makefile_&, Exim ignores &%-C%& and proceeds as usual.) There is no
38506 default setting for &%ALT_CONFIG_PREFIX%&.
38507
38508 If the permitted configuration files are confined to a directory to
38509 which only root has access, this guards against someone who has broken
38510 into the Exim account from running a privileged Exim with an arbitrary
38511 configuration file, and using it to break into other accounts.
38512 .next
38513
38514 If a non-trusted configuration file (i.e. not the default configuration file
38515 or one which is trusted by virtue of being listed in the TRUSTED_CONFIG_LIST
38516 file) is specified with &%-C%&, or if macros are given with &%-D%& (but see
38517 the next item), then root privilege is retained only if the caller of Exim is
38518 root. This locks out the possibility of testing a configuration using &%-C%&
38519 right through message reception and delivery, even if the caller is root. The
38520 reception works, but by that time, Exim is running as the Exim user, so when
38521 it re-execs to regain privilege for the delivery, the use of &%-C%& causes
38522 privilege to be lost. However, root can test reception and delivery using two
38523 separate commands.
38524
38525 .next
38526 The WHITELIST_D_MACROS build option declares some macros to be safe to override
38527 with &%-D%& if the real uid is one of root, the Exim run-time user or the
38528 CONFIGURE_OWNER, if defined.  The potential impact of this option is limited by
38529 requiring the run-time value supplied to &%-D%& to match a regex that errs on
38530 the restrictive side.  Requiring build-time selection of safe macros is onerous
38531 but this option is intended solely as a transition mechanism to permit
38532 previously-working configurations to continue to work after release 4.73.
38533 .next
38534 If DISABLE_D_OPTION is defined, the use of the &%-D%& command line option
38535 is disabled.
38536 .next
38537 FIXED_NEVER_USERS can be set to a colon-separated list of users that are
38538 never to be used for any deliveries. This is like the &%never_users%& runtime
38539 option, but it cannot be overridden; the runtime option adds additional users
38540 to the list. The default setting is &"root"&; this prevents a non-root user who
38541 is permitted to modify the runtime file from using Exim as a way to get root.
38542 .endlist
38543
38544
38545
38546 .section "Root privilege" "SECID270"
38547 .cindex "setuid"
38548 .cindex "root privilege"
38549 The Exim binary is normally setuid to root, which means that it gains root
38550 privilege (runs as root) when it starts execution. In some special cases (for
38551 example, when the daemon is not in use and there are no local deliveries), it
38552 may be possible to run Exim setuid to some user other than root. This is
38553 discussed in the next section. However, in most installations, root privilege
38554 is required for two things:
38555
38556 .ilist
38557 To set up a socket connected to the standard SMTP port (25) when initialising
38558 the listening daemon. If Exim is run from &'inetd'&, this privileged action is
38559 not required.
38560 .next
38561 To be able to change uid and gid in order to read users' &_.forward_& files and
38562 perform local deliveries as the receiving user or as specified in the
38563 configuration.
38564 .endlist
38565
38566 It is not necessary to be root to do any of the other things Exim does, such as
38567 receiving messages and delivering them externally over SMTP, and it is
38568 obviously more secure if Exim does not run as root except when necessary.
38569 For this reason, a user and group for Exim to use must be defined in
38570 &_Local/Makefile_&. These are known as &"the Exim user"& and &"the Exim
38571 group"&. Their values can be changed by the run time configuration, though this
38572 is not recommended. Often a user called &'exim'& is used, but some sites use
38573 &'mail'& or another user name altogether.
38574
38575 Exim uses &[setuid()]& whenever it gives up root privilege. This is a permanent
38576 abdication; the process cannot regain root afterwards. Prior to release 4.00,
38577 &[seteuid()]& was used in some circumstances, but this is no longer the case.
38578
38579 After a new Exim process has interpreted its command line options, it changes
38580 uid and gid in the following cases:
38581
38582 .ilist
38583 .oindex "&%-C%&"
38584 .oindex "&%-D%&"
38585 If the &%-C%& option is used to specify an alternate configuration file, or if
38586 the &%-D%& option is used to define macro values for the configuration, and the
38587 calling process is not running as root, the uid and gid are changed to those of
38588 the calling process.
38589 However, if DISABLE_D_OPTION is defined in &_Local/Makefile_&, the &%-D%&
38590 option may not be used at all.
38591 If WHITELIST_D_MACROS is defined in &_Local/Makefile_&, then some macro values
38592 can be supplied if the calling process is running as root, the Exim run-time
38593 user or CONFIGURE_OWNER, if defined.
38594 .next
38595 .oindex "&%-be%&"
38596 .oindex "&%-bf%&"
38597 .oindex "&%-bF%&"
38598 If the expansion test option (&%-be%&) or one of the filter testing options
38599 (&%-bf%& or &%-bF%&) are used, the uid and gid are changed to those of the
38600 calling process.
38601 .next
38602 If the process is not a daemon process or a queue runner process or a delivery
38603 process or a process for testing address routing (started with &%-bt%&), the
38604 uid and gid are changed to the Exim user and group. This means that Exim always
38605 runs under its own uid and gid when receiving messages. This also applies when
38606 testing address verification
38607 .oindex "&%-bv%&"
38608 .oindex "&%-bh%&"
38609 (the &%-bv%& option) and testing incoming message policy controls (the &%-bh%&
38610 option).
38611 .next
38612 For a daemon, queue runner, delivery, or address testing process, the uid
38613 remains as root at this stage, but the gid is changed to the Exim group.
38614 .endlist
38615
38616 The processes that initially retain root privilege behave as follows:
38617
38618 .ilist
38619 A daemon process changes the gid to the Exim group and the uid to the Exim
38620 user after setting up one or more listening sockets. The &[initgroups()]&
38621 function is called, so that if the Exim user is in any additional groups, they
38622 will be used during message reception.
38623 .next
38624 A queue runner process retains root privilege throughout its execution. Its
38625 job is to fork a controlled sequence of delivery processes.
38626 .next
38627 A delivery process retains root privilege throughout most of its execution,
38628 but any actual deliveries (that is, the transports themselves) are run in
38629 subprocesses which always change to a non-root uid and gid. For local
38630 deliveries this is typically the uid and gid of the owner of the mailbox; for
38631 remote deliveries, the Exim uid and gid are used. Once all the delivery
38632 subprocesses have been run, a delivery process changes to the Exim uid and gid
38633 while doing post-delivery tidying up such as updating the retry database and
38634 generating bounce and warning messages.
38635
38636 While the recipient addresses in a message are being routed, the delivery
38637 process runs as root. However, if a user's filter file has to be processed,
38638 this is done in a subprocess that runs under the individual user's uid and
38639 gid. A system filter is run as root unless &%system_filter_user%& is set.
38640 .next
38641 A process that is testing addresses (the &%-bt%& option) runs as root so that
38642 the routing is done in the same environment as a message delivery.
38643 .endlist
38644
38645
38646
38647
38648 .section "Running Exim without privilege" "SECTrunexiwitpri"
38649 .cindex "privilege, running without"
38650 .cindex "unprivileged running"
38651 .cindex "root privilege" "running without"
38652 Some installations like to run Exim in an unprivileged state for more of its
38653 operation, for added security. Support for this mode of operation is provided
38654 by the global option &%deliver_drop_privilege%&. When this is set, the uid and
38655 gid are changed to the Exim user and group at the start of a delivery process
38656 (and also queue runner and address testing processes). This means that address
38657 routing is no longer run as root, and the deliveries themselves cannot change
38658 to any other uid.
38659
38660 .cindex SIGHUP
38661 .cindex "daemon" "restarting"
38662 Leaving the binary setuid to root, but setting &%deliver_drop_privilege%& means
38663 that the daemon can still be started in the usual way, and it can respond
38664 correctly to SIGHUP because the re-invocation regains root privilege.
38665
38666 An alternative approach is to make Exim setuid to the Exim user and also setgid
38667 to the Exim group. If you do this, the daemon must be started from a root
38668 process. (Calling Exim from a root process makes it behave in the way it does
38669 when it is setuid root.) However, the daemon cannot restart itself after a
38670 SIGHUP signal because it cannot regain privilege.
38671
38672 It is still useful to set &%deliver_drop_privilege%& in this case, because it
38673 stops Exim from trying to re-invoke itself to do a delivery after a message has
38674 been received. Such a re-invocation is a waste of resources because it has no
38675 effect.
38676
38677 If restarting the daemon is not an issue (for example, if &%mua_wrapper%& is
38678 set, or &'inetd'& is being used instead of a daemon), having the binary setuid
38679 to the Exim user seems a clean approach, but there is one complication:
38680
38681 In this style of operation, Exim is running with the real uid and gid set to
38682 those of the calling process, and the effective uid/gid set to Exim's values.
38683 Ideally, any association with the calling process' uid/gid should be dropped,
38684 that is, the real uid/gid should be reset to the effective values so as to
38685 discard any privileges that the caller may have. While some operating systems
38686 have a function that permits this action for a non-root effective uid, quite a
38687 number of them do not. Because of this lack of standardization, Exim does not
38688 address this problem at this time.
38689
38690 For this reason, the recommended approach for &"mostly unprivileged"& running
38691 is to keep the Exim binary setuid to root, and to set
38692 &%deliver_drop_privilege%&. This also has the advantage of allowing a daemon to
38693 be used in the most straightforward way.
38694
38695 If you configure Exim not to run delivery processes as root, there are a
38696 number of restrictions on what you can do:
38697
38698 .ilist
38699 You can deliver only as the Exim user/group. You should  explicitly use the
38700 &%user%& and &%group%& options to override routers or local transports that
38701 normally deliver as the recipient. This makes sure that configurations that
38702 work in this mode function the same way in normal mode. Any implicit or
38703 explicit specification of another user causes an error.
38704 .next
38705 Use of &_.forward_& files is severely restricted, such that it is usually
38706 not worthwhile to include them in the configuration.
38707 .next
38708 Users who wish to use &_.forward_& would have to make their home directory and
38709 the file itself accessible to the Exim user. Pipe and append-to-file entries,
38710 and their equivalents in Exim filters, cannot be used. While they could be
38711 enabled in the Exim user's name, that would be insecure and not very useful.
38712 .next
38713 Unless the local user mailboxes are all owned by the Exim user (possible in
38714 some POP3 or IMAP-only environments):
38715
38716 .olist
38717 They must be owned by the Exim group and be writeable by that group. This
38718 implies you must set &%mode%& in the appendfile configuration, as well as the
38719 mode of the mailbox files themselves.
38720 .next
38721 You must set &%no_check_owner%&, since most or all of the files will not be
38722 owned by the Exim user.
38723 .next
38724 You must set &%file_must_exist%&, because Exim cannot set the owner correctly
38725 on a newly created mailbox when unprivileged. This also implies that new
38726 mailboxes need to be created manually.
38727 .endlist olist
38728 .endlist ilist
38729
38730
38731 These restrictions severely restrict what can be done in local deliveries.
38732 However, there are no restrictions on remote deliveries. If you are running a
38733 gateway host that does no local deliveries, setting &%deliver_drop_privilege%&
38734 gives more security at essentially no cost.
38735
38736 If you are using the &%mua_wrapper%& facility (see chapter
38737 &<<CHAPnonqueueing>>&), &%deliver_drop_privilege%& is forced to be true.
38738
38739
38740
38741
38742 .section "Delivering to local files" "SECID271"
38743 Full details of the checks applied by &(appendfile)& before it writes to a file
38744 are given in chapter &<<CHAPappendfile>>&.
38745
38746
38747
38748 .section "Running local commands" "SECTsecconslocalcmds"
38749 .cindex "security" "local commands"
38750 .cindex "security" "command injection attacks"
38751 There are a number of ways in which an administrator can configure Exim to run
38752 commands based upon received, untrustworthy, data. Further, in some
38753 configurations a user who can control a &_.forward_& file can also arrange to
38754 run commands. Configuration to check includes, but is not limited to:
38755
38756 .ilist
38757 Use of &%use_shell%& in the pipe transport: various forms of shell command
38758 injection may be possible with this option present. It is dangerous and should
38759 be used only with considerable caution. Consider constraints which whitelist
38760 allowed characters in a variable which is to be used in a pipe transport that
38761 has &%use_shell%& enabled.
38762 .next
38763 A number of options such as &%forbid_filter_run%&, &%forbid_filter_perl%&,
38764 &%forbid_filter_dlfunc%& and so forth which restrict facilities available to
38765 &_.forward_& files in a redirect router. If Exim is running on a central mail
38766 hub to which ordinary users do not have shell access, but home directories are
38767 NFS mounted (for instance) then administrators should review the list of these
38768 forbid options available, and should bear in mind that the options that may
38769 need forbidding can change as new features are added between releases.
38770 .next
38771 The &%${run...}%& expansion item does not use a shell by default, but
38772 administrators can configure use of &_/bin/sh_& as part of the command.
38773 Such invocations should be viewed with prejudicial suspicion.
38774 .next
38775 Administrators who use embedded Perl are advised to explore how Perl's
38776 taint checking might apply to their usage.
38777 .next
38778 Use of &%${expand...}%& is somewhat analogous to shell's eval builtin and
38779 administrators are well advised to view its use with suspicion, in case (for
38780 instance) it allows a local-part to contain embedded Exim directives.
38781 .next
38782 Use of &%${match_local_part...}%& and friends becomes more dangerous if
38783 Exim was built with EXPAND_LISTMATCH_RHS defined: the second string in
38784 each can reference arbitrary lists and files, rather than just being a list
38785 of opaque strings.
38786 The EXPAND_LISTMATCH_RHS option was added and set false by default because of
38787 real-world security vulnerabilities caused by its use with untrustworthy data
38788 injected in, for SQL injection attacks.
38789 Consider the use of the &%inlisti%& expansion condition instead.
38790 .endlist
38791
38792
38793
38794
38795 .section "Trust in configuration data" "SECTsecconfdata"
38796 .cindex "security" "data sources"
38797 .cindex "security" "regular expressions"
38798 .cindex "regular expressions" "security"
38799 .cindex "PCRE" "security"
38800 If configuration data for Exim can come from untrustworthy sources, there
38801 are some issues to be aware of:
38802
38803 .ilist
38804 Use of &%${expand...}%& may provide a path for shell injection attacks.
38805 .next
38806 Letting untrusted data provide a regular expression is unwise.
38807 .next
38808 Using &%${match...}%& to apply a fixed regular expression against untrusted
38809 data may result in pathological behaviour within PCRE.  Be aware of what
38810 "backtracking" means and consider options for being more strict with a regular
38811 expression. Avenues to explore include limiting what can match (avoiding &`.`&
38812 when &`[a-z0-9]`& or other character class will do), use of atomic grouping and
38813 possessive quantifiers or just not using regular expressions against untrusted
38814 data.
38815 .next
38816 It can be important to correctly use &%${quote:...}%&,
38817 &%${quote_local_part:...}%& and &%${quote_%&<&'lookup-type'&>&%:...}%& expansion
38818 items to ensure that data is correctly constructed.
38819 .next
38820 Some lookups might return multiple results, even though normal usage is only
38821 expected to yield one result.
38822 .endlist
38823
38824
38825
38826
38827 .section "IPv4 source routing" "SECID272"
38828 .cindex "source routing" "in IP packets"
38829 .cindex "IP source routing"
38830 Many operating systems suppress IP source-routed packets in the kernel, but
38831 some cannot be made to do this, so Exim does its own check. It logs incoming
38832 IPv4 source-routed TCP calls, and then drops them. Things are all different in
38833 IPv6. No special checking is currently done.
38834
38835
38836
38837 .section "The VRFY, EXPN, and ETRN commands in SMTP" "SECID273"
38838 Support for these SMTP commands is disabled by default. If required, they can
38839 be enabled by defining suitable ACLs.
38840
38841
38842
38843
38844 .section "Privileged users" "SECID274"
38845 .cindex "trusted users"
38846 .cindex "admin user"
38847 .cindex "privileged user"
38848 .cindex "user" "trusted"
38849 .cindex "user" "admin"
38850 Exim recognizes two sets of users with special privileges. Trusted users are
38851 able to submit new messages to Exim locally, but supply their own sender
38852 addresses and information about a sending host. For other users submitting
38853 local messages, Exim sets up the sender address from the uid, and doesn't
38854 permit a remote host to be specified.
38855
38856 .oindex "&%-f%&"
38857 However, an untrusted user is permitted to use the &%-f%& command line option
38858 in the special form &%-f <>%& to indicate that a delivery failure for the
38859 message should not cause an error report. This affects the message's envelope,
38860 but it does not affect the &'Sender:'& header. Untrusted users may also be
38861 permitted to use specific forms of address with the &%-f%& option by setting
38862 the &%untrusted_set_sender%& option.
38863
38864 Trusted users are used to run processes that receive mail messages from some
38865 other mail domain and pass them on to Exim for delivery either locally, or over
38866 the Internet. Exim trusts a caller that is running as root, as the Exim user,
38867 as any user listed in the &%trusted_users%& configuration option, or under any
38868 group listed in the &%trusted_groups%& option.
38869
38870 Admin users are permitted to do things to the messages on Exim's queue. They
38871 can freeze or thaw messages, cause them to be returned to their senders, remove
38872 them entirely, or modify them in various ways. In addition, admin users can run
38873 the Exim monitor and see all the information it is capable of providing, which
38874 includes the contents of files on the spool.
38875
38876 .oindex "&%-M%&"
38877 .oindex "&%-q%&"
38878 By default, the use of the &%-M%& and &%-q%& options to cause Exim to attempt
38879 delivery of messages on its queue is restricted to admin users. This
38880 restriction can be relaxed by setting the &%no_prod_requires_admin%& option.
38881 Similarly, the use of &%-bp%& (and its variants) to list the contents of the
38882 queue is also restricted to admin users. This restriction can be relaxed by
38883 setting &%no_queue_list_requires_admin%&.
38884
38885 Exim recognizes an admin user if the calling process is running as root or as
38886 the Exim user or if any of the groups associated with the calling process is
38887 the Exim group. It is not necessary actually to be running under the Exim
38888 group. However, if admin users who are not root or the Exim user are to access
38889 the contents of files on the spool via the Exim monitor (which runs
38890 unprivileged), Exim must be built to allow group read access to its spool
38891 files.
38892
38893 By default, regular users are trusted to perform basic testing and
38894 introspection commands, as themselves.  This setting can be tightened by
38895 setting the &%commandline_checks_require_admin%& option.
38896 This affects most of the checking options,
38897 such as &%-be%& and anything else &%-b*%&.
38898
38899
38900 .section "Spool files" "SECID275"
38901 .cindex "spool directory" "files"
38902 Exim's spool directory and everything it contains is owned by the Exim user and
38903 set to the Exim group. The mode for spool files is defined in the
38904 &_Local/Makefile_& configuration file, and defaults to 0640. This means that
38905 any user who is a member of the Exim group can access these files.
38906
38907
38908
38909 .section "Use of argv[0]" "SECID276"
38910 Exim examines the last component of &%argv[0]%&, and if it matches one of a set
38911 of specific strings, Exim assumes certain options. For example, calling Exim
38912 with the last component of &%argv[0]%& set to &"rsmtp"& is exactly equivalent
38913 to calling it with the option &%-bS%&. There are no security implications in
38914 this.
38915
38916
38917
38918 .section "Use of %f formatting" "SECID277"
38919 The only use made of &"%f"& by Exim is in formatting load average values. These
38920 are actually stored in integer variables as 1000 times the load average.
38921 Consequently, their range is limited and so therefore is the length of the
38922 converted output.
38923
38924
38925
38926 .section "Embedded Exim path" "SECID278"
38927 Exim uses its own path name, which is embedded in the code, only when it needs
38928 to re-exec in order to regain root privilege. Therefore, it is not root when it
38929 does so. If some bug allowed the path to get overwritten, it would lead to an
38930 arbitrary program's being run as exim, not as root.
38931
38932
38933
38934 .section "Dynamic module directory" "SECTdynmoddir"
38935 Any dynamically loadable modules must be installed into the directory
38936 defined in &`LOOKUP_MODULE_DIR`& in &_Local/Makefile_& for Exim to permit
38937 loading it.
38938
38939
38940 .section "Use of sprintf()" "SECID279"
38941 .cindex "&[sprintf()]&"
38942 A large number of occurrences of &"sprintf"& in the code are actually calls to
38943 &'string_sprintf()'&, a function that returns the result in malloc'd store.
38944 The intermediate formatting is done into a large fixed buffer by a function
38945 that runs through the format string itself, and checks the length of each
38946 conversion before performing it, thus preventing buffer overruns.
38947
38948 The remaining uses of &[sprintf()]& happen in controlled circumstances where
38949 the output buffer is known to be sufficiently long to contain the converted
38950 string.
38951
38952
38953
38954 .section "Use of debug_printf() and log_write()" "SECID280"
38955 Arbitrary strings are passed to both these functions, but they do their
38956 formatting by calling the function &'string_vformat()'&, which runs through
38957 the format string itself, and checks the length of each conversion.
38958
38959
38960
38961 .section "Use of strcat() and strcpy()" "SECID281"
38962 These are used only in cases where the output buffer is known to be large
38963 enough to hold the result.
38964 .ecindex IIDsecurcon
38965
38966
38967
38968
38969 . ////////////////////////////////////////////////////////////////////////////
38970 . ////////////////////////////////////////////////////////////////////////////
38971
38972 .chapter "Format of spool files" "CHAPspool"
38973 .scindex IIDforspo1 "format" "spool files"
38974 .scindex IIDforspo2 "spool directory" "format of files"
38975 .scindex IIDforspo3 "spool files" "format of"
38976 .cindex "spool files" "editing"
38977 A message on Exim's queue consists of two files, whose names are the message id
38978 followed by -D and -H, respectively. The data portion of the message is kept in
38979 the -D file on its own. The message's envelope, status, and headers are all
38980 kept in the -H file, whose format is described in this chapter. Each of these
38981 two files contains the final component of its own name as its first line. This
38982 is insurance against disk crashes where the directory is lost but the files
38983 themselves are recoverable.
38984
38985 .new
38986 The file formats may be changed, or new formats added, at any release.
38987 Spool files are not intended as an interface to other programs
38988 and should not be used as such.
38989 .wen
38990
38991 Some people are tempted into editing -D files in order to modify messages. You
38992 need to be extremely careful if you do this; it is not recommended and you are
38993 on your own if you do it. Here are some of the pitfalls:
38994
38995 .ilist
38996 You must ensure that Exim does not try to deliver the message while you are
38997 fiddling with it. The safest way is to take out a write lock on the -D file,
38998 which is what Exim itself does, using &[fcntl()]&. If you update the file in
38999 place, the lock will be retained. If you write a new file and rename it, the
39000 lock will be lost at the instant of rename.
39001 .next
39002 .vindex "&$body_linecount$&"
39003 If you change the number of lines in the file, the value of
39004 &$body_linecount$&, which is stored in the -H file, will be incorrect and can
39005 cause incomplete transmission of messages or undeliverable messages.
39006 .next
39007 If the message is in MIME format, you must take care not to break it.
39008 .next
39009 If the message is cryptographically signed, any change will invalidate the
39010 signature.
39011 .endlist
39012 All in all, modifying -D files is fraught with danger.
39013
39014 Files whose names end with -J may also be seen in the &_input_& directory (or
39015 its subdirectories when &%split_spool_directory%& is set). These are journal
39016 files, used to record addresses to which the message has been delivered during
39017 the course of a delivery attempt. If there are still undelivered recipients at
39018 the end, the -H file is updated, and the -J file is deleted. If, however, there
39019 is some kind of crash (for example, a power outage) before this happens, the -J
39020 file remains in existence. When Exim next processes the message, it notices the
39021 -J file and uses it to update the -H file before starting the next delivery
39022 attempt.
39023
39024 Files whose names end with -K or .eml may also be seen in the spool.
39025 These are temporaries used for DKIM or malware processing, when that is used.
39026 They should be tidied up by normal operations; any old ones are probably
39027 relics of crashes and can be removed.
39028
39029 .section "Format of the -H file" "SECID282"
39030 .cindex "uid (user id)" "in spool file"
39031 .cindex "gid (group id)" "in spool file"
39032 The second line of the -H file contains the login name for the uid of the
39033 process that called Exim to read the message, followed by the numerical uid and
39034 gid. For a locally generated message, this is normally the user who sent the
39035 message. For a message received over TCP/IP via the daemon, it is
39036 normally the Exim user.
39037
39038 The third line of the file contains the address of the message's sender as
39039 transmitted in the envelope, contained in angle brackets. The sender address is
39040 empty for bounce messages. For incoming SMTP mail, the sender address is given
39041 in the MAIL command. For locally generated mail, the sender address is
39042 created by Exim from the login name of the current user and the configured
39043 &%qualify_domain%&. However, this can be overridden by the &%-f%& option or a
39044 leading &"From&~"& line if the caller is trusted, or if the supplied address is
39045 &"<>"& or an address that matches &%untrusted_set_senders%&.
39046
39047 The fourth line contains two numbers. The first is the time that the message
39048 was received, in the conventional Unix form &-- the number of seconds since the
39049 start of the epoch. The second number is a count of the number of messages
39050 warning of delayed delivery that have been sent to the sender.
39051
39052 There follow a number of lines starting with a hyphen. These can appear in any
39053 order, and are omitted when not relevant:
39054
39055 .vlist
39056 .vitem "&%-acl%&&~<&'number'&>&~<&'length'&>"
39057 This item is obsolete, and is not generated from Exim release 4.61 onwards;
39058 &%-aclc%& and &%-aclm%& are used instead. However, &%-acl%& is still
39059 recognized, to provide backward compatibility. In the old format, a line of
39060 this form is present for every ACL variable that is not empty. The number
39061 identifies the variable; the &%acl_c%&&*x*& variables are numbered 0&--9 and
39062 the &%acl_m%&&*x*& variables are numbered 10&--19. The length is the length of
39063 the data string for the variable. The string itself starts at the beginning of
39064 the next line, and is followed by a newline character. It may contain internal
39065 newlines.
39066
39067 .vitem "&%-aclc%&&~<&'rest-of-name'&>&~<&'length'&>"
39068 A line of this form is present for every ACL connection variable that is
39069 defined. Note that there is a space between &%-aclc%& and the rest of the name.
39070 The length is the length of the data string for the variable. The string itself
39071 starts at the beginning of the next line, and is followed by a newline
39072 character. It may contain internal newlines.
39073
39074 .vitem "&%-aclm%&&~<&'rest-of-name'&>&~<&'length'&>"
39075 A line of this form is present for every ACL message variable that is defined.
39076 Note that there is a space between &%-aclm%& and the rest of the name. The
39077 length is the length of the data string for the variable. The string itself
39078 starts at the beginning of the next line, and is followed by a newline
39079 character. It may contain internal newlines.
39080
39081 .vitem "&%-active_hostname%&&~<&'hostname'&>"
39082 This is present if, when the message was received over SMTP, the value of
39083 &$smtp_active_hostname$& was different to the value of &$primary_hostname$&.
39084
39085 .vitem &%-allow_unqualified_recipient%&
39086 This is present if unqualified recipient addresses are permitted in header
39087 lines (to stop such addresses from being qualified if rewriting occurs at
39088 transport time). Local messages that were input using &%-bnq%& and remote
39089 messages from hosts that match &%recipient_unqualified_hosts%& set this flag.
39090
39091 .vitem &%-allow_unqualified_sender%&
39092 This is present if unqualified sender addresses are permitted in header lines
39093 (to stop such addresses from being qualified if rewriting occurs at transport
39094 time). Local messages that were input using &%-bnq%& and remote messages from
39095 hosts that match &%sender_unqualified_hosts%& set this flag.
39096
39097 .vitem "&%-auth_id%&&~<&'text'&>"
39098 The id information for a message received on an authenticated SMTP connection
39099 &-- the value of the &$authenticated_id$& variable.
39100
39101 .vitem "&%-auth_sender%&&~<&'address'&>"
39102 The address of an authenticated sender &-- the value of the
39103 &$authenticated_sender$& variable.
39104
39105 .vitem "&%-body_linecount%&&~<&'number'&>"
39106 This records the number of lines in the body of the message, and is
39107 present unless &%-spool_file_wireformat%& is.
39108
39109 .vitem "&%-body_zerocount%&&~<&'number'&>"
39110 This records the number of binary zero bytes in the body of the message, and is
39111 present if the number is greater than zero.
39112
39113 .vitem &%-deliver_firsttime%&
39114 This is written when a new message is first added to the spool. When the spool
39115 file is updated after a deferral, it is omitted.
39116
39117 .vitem "&%-frozen%&&~<&'time'&>"
39118 .cindex "frozen messages" "spool data"
39119 The message is frozen, and the freezing happened at <&'time'&>.
39120
39121 .vitem "&%-helo_name%&&~<&'text'&>"
39122 This records the host name as specified by a remote host in a HELO or EHLO
39123 command.
39124
39125 .vitem "&%-host_address%&&~<&'address'&>.<&'port'&>"
39126 This records the IP address of the host from which the message was received and
39127 the remote port number that was used. It is omitted for locally generated
39128 messages.
39129
39130 .vitem "&%-host_auth%&&~<&'text'&>"
39131 If the message was received on an authenticated SMTP connection, this records
39132 the name of the authenticator &-- the value of the
39133 &$sender_host_authenticated$& variable.
39134
39135 .vitem &%-host_lookup_failed%&
39136 This is present if an attempt to look up the sending host's name from its IP
39137 address failed. It corresponds to the &$host_lookup_failed$& variable.
39138
39139 .vitem "&%-host_name%&&~<&'text'&>"
39140 .cindex "reverse DNS lookup"
39141 .cindex "DNS" "reverse lookup"
39142 This records the name of the remote host from which the message was received,
39143 if the host name was looked up from the IP address when the message was being
39144 received. It is not present if no reverse lookup was done.
39145
39146 .vitem "&%-ident%&&~<&'text'&>"
39147 For locally submitted messages, this records the login of the originating user,
39148 unless it was a trusted user and the &%-oMt%& option was used to specify an
39149 ident value. For messages received over TCP/IP, this records the ident string
39150 supplied by the remote host, if any.
39151
39152 .vitem "&%-interface_address%&&~<&'address'&>.<&'port'&>"
39153 This records the IP address of the local interface and the port number through
39154 which a message was received from a remote host. It is omitted for locally
39155 generated messages.
39156
39157 .vitem &%-local%&
39158 The message is from a local sender.
39159
39160 .vitem &%-localerror%&
39161 The message is a locally-generated bounce message.
39162
39163 .vitem "&%-local_scan%&&~<&'string'&>"
39164 This records the data string that was returned by the &[local_scan()]& function
39165 when the message was received &-- the value of the &$local_scan_data$&
39166 variable. It is omitted if no data was returned.
39167
39168 .vitem &%-manual_thaw%&
39169 The message was frozen but has been thawed manually, that is, by an explicit
39170 Exim command rather than via the auto-thaw process.
39171
39172 .vitem &%-N%&
39173 A testing delivery process was started using the &%-N%& option to suppress any
39174 actual deliveries, but delivery was deferred. At any further delivery attempts,
39175 &%-N%& is assumed.
39176
39177 .vitem &%-received_protocol%&
39178 This records the value of the &$received_protocol$& variable, which contains
39179 the name of the protocol by which the message was received.
39180
39181 .vitem &%-sender_set_untrusted%&
39182 The envelope sender of this message was set by an untrusted local caller (used
39183 to ensure that the caller is displayed in queue listings).
39184
39185 .vitem "&%-spam_score_int%&&~<&'number'&>"
39186 If a message was scanned by SpamAssassin, this is present. It records the value
39187 of &$spam_score_int$&.
39188
39189 .vitem &%-spool_file_wireformat%&
39190 The -D file for this message is in wire-format (for ESMTP CHUNKING)
39191 rather than Unix-format.
39192 The line-ending is CRLF rather than newline.
39193 There is still, however, no leading-dot-stuffing.
39194
39195 .vitem &%-tls_certificate_verified%&
39196 A TLS certificate was received from the client that sent this message, and the
39197 certificate was verified by the server.
39198
39199 .vitem "&%-tls_cipher%&&~<&'cipher name'&>"
39200 When the message was received over an encrypted connection, this records the
39201 name of the cipher suite that was used.
39202
39203 .vitem "&%-tls_peerdn%&&~<&'peer DN'&>"
39204 When the message was received over an encrypted connection, and a certificate
39205 was received from the client, this records the Distinguished Name from that
39206 certificate.
39207 .endlist
39208
39209 Following the options there is a list of those addresses to which the message
39210 is not to be delivered. This set of addresses is initialized from the command
39211 line when the &%-t%& option is used and &%extract_addresses_remove_arguments%&
39212 is set; otherwise it starts out empty. Whenever a successful delivery is made,
39213 the address is added to this set. The addresses are kept internally as a
39214 balanced binary tree, and it is a representation of that tree which is written
39215 to the spool file. If an address is expanded via an alias or forward file, the
39216 original address is added to the tree when deliveries to all its child
39217 addresses are complete.
39218
39219 If the tree is empty, there is a single line in the spool file containing just
39220 the text &"XX"&. Otherwise, each line consists of two letters, which are either
39221 Y or N, followed by an address. The address is the value for the node of the
39222 tree, and the letters indicate whether the node has a left branch and/or a
39223 right branch attached to it, respectively. If branches exist, they immediately
39224 follow. Here is an example of a three-node tree:
39225 .code
39226 YY darcy@austen.fict.example
39227 NN alice@wonderland.fict.example
39228 NN editor@thesaurus.ref.example
39229 .endd
39230 After the non-recipients tree, there is a list of the message's recipients.
39231 This is a simple list, preceded by a count. It includes all the original
39232 recipients of the message, including those to whom the message has already been
39233 delivered. In the simplest case, the list contains one address per line. For
39234 example:
39235 .code
39236 4
39237 editor@thesaurus.ref.example
39238 darcy@austen.fict.example
39239 rdo@foundation
39240 alice@wonderland.fict.example
39241 .endd
39242 However, when a child address has been added to the top-level addresses as a
39243 result of the use of the &%one_time%& option on a &(redirect)& router, each
39244 line is of the following form:
39245 .display
39246 <&'top-level address'&> <&'errors_to address'&> &&&
39247   <&'length'&>,<&'parent number'&>#<&'flag bits'&>
39248 .endd
39249 The 01 flag bit indicates the presence of the three other fields that follow
39250 the top-level address. Other bits may be used in future to support additional
39251 fields. The <&'parent number'&> is the offset in the recipients list of the
39252 original parent of the &"one time"& address. The first two fields are the
39253 envelope sender that is associated with this address and its length. If the
39254 length is zero, there is no special envelope sender (there are then two space
39255 characters in the line). A non-empty field can arise from a &(redirect)& router
39256 that has an &%errors_to%& setting.
39257
39258
39259 A blank line separates the envelope and status information from the headers
39260 which follow. A header may occupy several lines of the file, and to save effort
39261 when reading it in, each header is preceded by a number and an identifying
39262 character. The number is the number of characters in the header, including any
39263 embedded newlines and the terminating newline. The character is one of the
39264 following:
39265
39266 .table2 50pt
39267 .row <&'blank'&>         "header in which Exim has no special interest"
39268 .row &`B`&               "&'Bcc:'& header"
39269 .row &`C`&               "&'Cc:'& header"
39270 .row &`F`&               "&'From:'& header"
39271 .row &`I`&               "&'Message-id:'& header"
39272 .row &`P`&               "&'Received:'& header &-- P for &""postmark""&"
39273 .row &`R`&               "&'Reply-To:'& header"
39274 .row &`S`&               "&'Sender:'& header"
39275 .row &`T`&               "&'To:'& header"
39276 .row &`*`&               "replaced or deleted header"
39277 .endtable
39278
39279 Deleted or replaced (rewritten) headers remain in the spool file for debugging
39280 purposes. They are not transmitted when the message is delivered. Here is a
39281 typical set of headers:
39282 .code
39283 111P Received: by hobbit.fict.example with local (Exim 4.00)
39284 id 14y9EI-00026G-00; Fri, 11 May 2001 10:28:59 +0100
39285 049  Message-Id: <E14y9EI-00026G-00@hobbit.fict.example>
39286 038* X-rewrote-sender: bb@hobbit.fict.example
39287 042* From: Bilbo Baggins <bb@hobbit.fict.example>
39288 049F From: Bilbo Baggins <B.Baggins@hobbit.fict.example>
39289 099* To: alice@wonderland.fict.example, rdo@foundation,
39290 darcy@austen.fict.example, editor@thesaurus.ref.example
39291 104T To: alice@wonderland.fict.example, rdo@foundation.example,
39292 darcy@austen.fict.example, editor@thesaurus.ref.example
39293 038  Date: Fri, 11 May 2001 10:28:59 +0100
39294 .endd
39295 The asterisked headers indicate that the envelope sender, &'From:'& header, and
39296 &'To:'& header have been rewritten, the last one because routing expanded the
39297 unqualified domain &'foundation'&.
39298 .ecindex IIDforspo1
39299 .ecindex IIDforspo2
39300 .ecindex IIDforspo3
39301
39302 .section "Format of the -D file" "SECID282a"
39303 The data file is traditionally in Unix-standard format: lines are ended with
39304 an ASCII newline character.
39305 However, when the &%spool_wireformat%& main option is used some -D files
39306 can have an alternate format.
39307 This is flagged by a &%-spool_file_wireformat%& line in the corresponding -H file.
39308 The -D file lines (not including the first name-component line) are
39309 suitable for direct copying to the wire when transmitting using the
39310 ESMTP CHUNKING option, meaning lower processing overhead.
39311 Lines are terminated with an ASCII CRLF pair.
39312 There is no dot-stuffing (and no dot-termination).
39313
39314 . ////////////////////////////////////////////////////////////////////////////
39315 . ////////////////////////////////////////////////////////////////////////////
39316
39317 .chapter "DKIM and SPF" "CHAPdkim" &&&
39318          "DKIM and SPF Support"
39319 .cindex "DKIM"
39320
39321 .section "DKIM (DomainKeys Identified Mail)" SECDKIM
39322
39323 DKIM is a mechanism by which messages sent by some entity can be provably
39324 linked to a domain which that entity controls.  It permits reputation to
39325 be tracked on a per-domain basis, rather than merely upon source IP address.
39326 DKIM is documented in RFC 6376.
39327
39328 As DKIM relies on the message being unchanged in transit, messages handled
39329 by a mailing-list (which traditionally adds to the message) will not match
39330 any original DKIM signature.
39331
39332 DKIM support is compiled into Exim by default if TLS support is present.
39333 It can be disabled by setting DISABLE_DKIM=yes in &_Local/Makefile_&.
39334
39335 Exim's DKIM implementation allows for
39336 .olist
39337 Signing outgoing messages: This function is implemented in the SMTP transport.
39338 It can co-exist with all other Exim features
39339 (including transport filters)
39340 except cutthrough delivery.
39341 .next
39342 Verifying signatures in incoming messages: This is implemented by an additional
39343 ACL (acl_smtp_dkim), which can be called several times per message, with
39344 different signature contexts.
39345 .endlist
39346
39347 In typical Exim style, the verification implementation does not include any
39348 default "policy". Instead it enables you to build your own policy using
39349 Exim's standard controls.
39350
39351 Please note that verification of DKIM signatures in incoming mail is turned
39352 on by default for logging (in the <= line) purposes.
39353
39354 Additional log detail can be enabled using the &%dkim_verbose%& log_selector.
39355 When set, for each signature in incoming email,
39356 exim will log a line displaying the most important signature details, and the
39357 signature status. Here is an example (with line-breaks added for clarity):
39358 .code
39359 2009-09-09 10:22:28 1MlIRf-0003LU-U3 DKIM:
39360     d=facebookmail.com s=q1-2009b
39361     c=relaxed/relaxed a=rsa-sha1
39362     i=@facebookmail.com t=1252484542 [verification succeeded]
39363 .endd
39364
39365 You might want to turn off DKIM verification processing entirely for internal
39366 or relay mail sources. To do that, set the &%dkim_disable_verify%& ACL
39367 control modifier. This should typically be done in the RCPT ACL, at points
39368 where you accept mail from relay sources (internal hosts or authenticated
39369 senders).
39370
39371
39372 .section "Signing outgoing messages" "SECDKIMSIGN"
39373 .cindex "DKIM" "signing"
39374
39375 For signing to be usable you must have published a DKIM record in DNS.
39376 Note that RFC 8301 says:
39377 .code
39378 rsa-sha1 MUST NOT be used for signing or verifying.
39379
39380 Signers MUST use RSA keys of at least 1024 bits for all keys.
39381 Signers SHOULD use RSA keys of at least 2048 bits.
39382 .endd
39383
39384 Note also that the key content (the 'p=' field)
39385 in the DNS record is different between RSA and EC keys;
39386 for the former it is the base64 of the ASN.1 for the RSA public key
39387 (equivalent to the private-key .pem with the header/trailer stripped)
39388 but for EC keys it is the base64 of the pure key; no ASN.1 wrapping.
39389
39390 Signing is enabled by setting private options on the SMTP transport.
39391 These options take (expandable) strings as arguments.
39392
39393 .option dkim_domain smtp string list&!! unset
39394 The domain(s) you want to sign with.
39395 After expansion, this can be a list.
39396 Each element in turn is put into the &%$dkim_domain%& expansion variable
39397 while expanding the remaining signing options.
39398 If it is empty after expansion, DKIM signing is not done,
39399 and no error will result even if &%dkim_strict%& is set.
39400
39401 .option dkim_selector smtp string list&!! unset
39402 This sets the key selector string.
39403 After expansion, which can use &$dkim_domain$&, this can be a list.
39404 Each element in turn is put in the expansion
39405 variable &%$dkim_selector%& which may be used in the &%dkim_private_key%&
39406 option along with &%$dkim_domain%&.
39407 If the option is empty after expansion, DKIM signing is not done for this domain,
39408 and no error will result even if &%dkim_strict%& is set.
39409
39410 .option dkim_private_key smtp string&!! unset
39411 This sets the private key to use.
39412 You can use the &%$dkim_domain%& and
39413 &%$dkim_selector%& expansion variables to determine the private key to use.
39414 The result can either
39415 .ilist
39416 be a valid RSA private key in ASCII armor (.pem file), including line breaks
39417 .next
39418 with GnuTLS 3.6.0 or OpenSSL 1.1.1 or later,
39419 be a valid Ed25519 private key (same format as above)
39420 .next
39421 start with a slash, in which case it is treated as a file that contains
39422 the private key
39423 .next
39424 be "0", "false" or the empty string, in which case the message will not
39425 be signed. This case will not result in an error, even if &%dkim_strict%&
39426 is set.
39427 .endlist
39428
39429 To generate keys under OpenSSL:
39430 .code
39431 openssl genrsa -out dkim_rsa.private 2048
39432 openssl rsa -in dkim_rsa.private -out /dev/stdout -pubout -outform PEM
39433 .endd
39434 Take the base-64 lines from the output of the second command, concatenated,
39435 for the DNS TXT record.
39436 See section 3.6 of RFC6376 for the record specification.
39437
39438 Under GnuTLS:
39439 .code
39440 certtool --generate-privkey --rsa --bits=2048 --password='' -8 --outfile=dkim_rsa.private
39441 certtool --load-privkey=dkim_rsa.private --pubkey-info
39442 .endd
39443
39444 Note that RFC 8301 says:
39445 .code
39446 Signers MUST use RSA keys of at least 1024 bits for all keys.
39447 Signers SHOULD use RSA keys of at least 2048 bits.
39448 .endd
39449
39450 Support for EC keys is being developed under
39451 &url(https://datatracker.ietf.org/doc/draft-ietf-dcrup-dkim-crypto/).
39452 They are considerably smaller than RSA keys for equivalent protection.
39453 As they are a recent development, users should consider dual-signing
39454 (by setting a list of selectors, and an expansion for this option)
39455 for some transition period.
39456 The "_CRYPTO_SIGN_ED25519" macro will be defined if support is present
39457 for EC keys.
39458
39459 OpenSSL 1.1.1 and GnuTLS 3.6.0 can create Ed25519 private keys:
39460 .code
39461 openssl genpkey -algorithm ed25519 -out dkim_ed25519.private
39462 certtool --generate-privkey --key-type=ed25519 --outfile=dkim_ed25519.private
39463 .endd
39464
39465 To produce the required public key value for a DNS record:
39466 .code
39467 openssl pkey -outform DER -pubout -in dkim_ed25519.private | tail -c +13 | base64
39468 certtool --load_privkey=dkim_ed25519.private --pubkey_info --outder | tail -c +13 | base64
39469 .endd
39470
39471 Note that the format
39472 of Ed25519 keys in DNS has not yet been decided; this release supports
39473 both of the leading candidates at this time, a future release will
39474 probably drop support for whichever proposal loses.
39475
39476 .option dkim_hash smtp string&!! sha256
39477 Can be set to any one of the supported hash methods, which are:
39478 .ilist
39479 &`sha1`& &-- should not be used, is old and insecure
39480 .next
39481 &`sha256`& &-- the default
39482 .next
39483 &`sha512`& &-- possibly more secure but less well supported
39484 .endlist
39485
39486 Note that RFC 8301 says:
39487 .code
39488 rsa-sha1 MUST NOT be used for signing or verifying.
39489 .endd
39490
39491 .option dkim_identity smtp string&!! unset
39492 If set after expansion, the value is used to set an "i=" tag in
39493 the signing header.  The DKIM standards restrict the permissible
39494 syntax of this optional tag to a mail address, with possibly-empty
39495 local part, an @, and a domain identical to or subdomain of the "d="
39496 tag value.  Note that Exim does not check the value.
39497
39498 .option dkim_canon smtp string&!! unset
39499 This option sets the canonicalization method used when signing a message.
39500 The DKIM RFC currently supports two methods: "simple" and "relaxed".
39501 The option defaults to "relaxed" when unset. Note: the current implementation
39502 only supports signing with the same canonicalization method for both headers and body.
39503
39504 .option dkim_strict smtp string&!! unset
39505 This  option  defines  how  Exim  behaves  when  signing a message that
39506 should be signed fails for some reason.  When the expansion evaluates to
39507 either "1" or "true", Exim will defer. Otherwise Exim will send the message
39508 unsigned. You can use the &%$dkim_domain%& and &%$dkim_selector%& expansion
39509 variables here.
39510
39511 .option dkim_sign_headers smtp string&!! "see below"
39512 If set, this option must expand to a colon-separated
39513 list of header names.
39514 Headers with these names, or the absence or such a header, will be included
39515 in the message signature.
39516 When unspecified, the header names listed in RFC4871 will be used,
39517 whether or not each header is present in the message.
39518 The default list is available for the expansion in the macro
39519 "_DKIM_SIGN_HEADERS".
39520
39521 If a name is repeated, multiple headers by that name (or the absence thereof)
39522 will be signed.  The textually later headers in the headers part of the
39523 message are signed first, if there are multiples.
39524
39525 A name can be prefixed with either an '=' or a '+' character.
39526 If an '=' prefix is used, all headers that are present with this name
39527 will be signed.
39528 If a '+' prefix if used, all headers that are present with this name
39529 will be signed, and one signature added for a missing header with the
39530 name will be appended.
39531
39532 .new
39533 .option dkim_timestamps smtp integer&!! unset
39534 This option controls the inclusion of timestamp information in the signature.
39535 If not set, no such information will be included.
39536 Otherwise, must be an unsigned number giving an offset in seconds from the current time
39537 for the expiry tag
39538 (eg. 1209600 for two weeks);
39539 both creation (t=) and expiry (x=) tags will be included.
39540
39541 RFC 6376 lists these tags as RECOMMENDED.
39542 .wen
39543
39544
39545 .section "Verifying DKIM signatures in incoming mail" "SECDKIMVFY"
39546 .cindex "DKIM" "verification"
39547
39548 .new
39549 Verification of DKIM signatures in SMTP incoming email is done for all
39550 messages for which an ACL control &%dkim_disable_verify%& has not been set.
39551 .cindex authentication "expansion item"
39552 Performing verification sets up information used by the
39553 &$authresults$& expansion item.
39554 .wen
39555
39556 .new The results of that verification are then made available to the
39557 &%acl_smtp_dkim%& ACL, &new(which can examine and modify them).
39558 By default, this ACL is called once for each
39559 syntactically(!) correct signature in the incoming message.
39560 A missing ACL definition defaults to accept.
39561 If any ACL call does not accept, the message is not accepted.
39562 If a cutthrough delivery was in progress for the message, that is
39563 summarily dropped (having wasted the transmission effort).
39564
39565 To evaluate the &new(verification result) in the ACL
39566 a large number of expansion variables
39567 containing the signature status and its details are set up during the
39568 runtime of the ACL.
39569
39570 Calling the ACL only for existing signatures is not sufficient to build
39571 more advanced policies. For that reason, the global option
39572 &%dkim_verify_signers%&, and a global expansion variable
39573 &%$dkim_signers%& exist.
39574
39575 The global option &%dkim_verify_signers%& can be set to a colon-separated
39576 list of DKIM domains or identities for which the ACL &%acl_smtp_dkim%& is
39577 called. It is expanded when the message has been received. At this point,
39578 the expansion variable &%$dkim_signers%& already contains a colon-separated
39579 list of signer domains and identities for the message. When
39580 &%dkim_verify_signers%& is not specified in the main configuration,
39581 it defaults as:
39582 .code
39583 dkim_verify_signers = $dkim_signers
39584 .endd
39585 This leads to the default behaviour of calling &%acl_smtp_dkim%& for each
39586 DKIM signature in the message. Current DKIM verifiers may want to explicitly
39587 call the ACL for known domains or identities. This would be achieved as follows:
39588 .code
39589 dkim_verify_signers = paypal.com:ebay.com:$dkim_signers
39590 .endd
39591 This would result in &%acl_smtp_dkim%& always being called for "paypal.com"
39592 and "ebay.com", plus all domains and identities that have signatures in the message.
39593 You can also be more creative in constructing your policy. For example:
39594 .code
39595 dkim_verify_signers = $sender_address_domain:$dkim_signers
39596 .endd
39597
39598 If a domain or identity is listed several times in the (expanded) value of
39599 &%dkim_verify_signers%&, the ACL is only called once for that domain or identity.
39600
39601 If multiple signatures match a domain (or identity), the ACL is called once
39602 for each matching signature.
39603
39604
39605 Inside the &%acl_smtp_dkim%&, the following expansion variables are
39606 available (from most to least important):
39607
39608
39609 .vlist
39610 .vitem &%$dkim_cur_signer%&
39611 The signer that is being evaluated in this ACL run. This can be a domain or
39612 an identity. This is one of the list items from the expanded main option
39613 &%dkim_verify_signers%& (see above).
39614
39615 .vitem &%$dkim_verify_status%&
39616 Within the DKIM ACL,
39617 a string describing the general status of the signature. One of
39618 .ilist
39619 &%none%&: There is no signature in the message for the current domain or
39620 identity (as reflected by &%$dkim_cur_signer%&).
39621 .next
39622 &%invalid%&: The signature could not be verified due to a processing error.
39623 More detail is available in &%$dkim_verify_reason%&.
39624 .next
39625 &%fail%&: Verification of the signature failed.  More detail is
39626 available in &%$dkim_verify_reason%&.
39627 .next
39628 &%pass%&: The signature passed verification. It is valid.
39629 .endlist
39630
39631 This variable can be overwritten using an ACL 'set' modifier.
39632 This might, for instance, be done to enforce a policy restriction on
39633 hash-method or key-size:
39634 .code
39635   warn condition       = ${if eq {$dkim_verify_status}{pass}}
39636        condition       = ${if eq {${length_3:$dkim_algo}}{rsa}}
39637        condition       = ${if or {{eq {$dkim_algo}{rsa-sha1}} \
39638                                   {< {$dkim_key_length}{1024}}}}
39639        logwrite        = NOTE: forcing DKIM verify fail (was pass)
39640        set dkim_verify_status = fail
39641        set dkim_verify_reason = hash too weak or key too short
39642 .endd
39643
39644 So long as a DKIM ACL is defined (it need do no more than accept),
39645 after all the DKIM ACL runs have completed, the value becomes a
39646 colon-separated list of the values after each run.
39647 This is maintained for the mime, prdr and data ACLs.
39648
39649 .vitem &%$dkim_verify_reason%&
39650 A string giving a little bit more detail when &%$dkim_verify_status%& is either
39651 "fail" or "invalid". One of
39652 .ilist
39653 &%pubkey_unavailable%& (when &%$dkim_verify_status%&="invalid"): The public
39654 key for the domain could not be retrieved. This may be a temporary problem.
39655 .next
39656 &%pubkey_syntax%& (when &%$dkim_verify_status%&="invalid"): The public key
39657 record for the domain is syntactically invalid.
39658 .next
39659 &%bodyhash_mismatch%& (when &%$dkim_verify_status%&="fail"): The calculated
39660 body hash does not match the one specified in the signature header. This
39661 means that the message body was modified in transit.
39662 .next
39663 &%signature_incorrect%& (when &%$dkim_verify_status%&="fail"): The signature
39664 could not be verified. This may mean that headers were modified,
39665 re-written or otherwise changed in a way which is incompatible with
39666 DKIM verification. It may of course also mean that the signature is forged.
39667 .endlist
39668
39669 This variable can be overwritten, with any value, using an ACL 'set' modifier.
39670
39671 .vitem &%$dkim_domain%&
39672 The signing domain. IMPORTANT: This variable is only populated if there is
39673 an actual signature in the message for the current domain or identity (as
39674 reflected by &%$dkim_cur_signer%&).
39675
39676 .vitem &%$dkim_identity%&
39677 The signing identity, if present. IMPORTANT: This variable is only populated
39678 if there is an actual signature in the message for the current domain or
39679 identity (as reflected by &%$dkim_cur_signer%&).
39680
39681 .vitem &%$dkim_selector%&
39682 The key record selector string.
39683
39684 .vitem &%$dkim_algo%&
39685 The algorithm used. One of 'rsa-sha1' or 'rsa-sha256'.
39686 If running under GnuTLS 3.6.0 or OpenSSL 1.1.1 or later,
39687 may also be 'ed25519-sha256'.
39688 The "_CRYPTO_SIGN_ED25519" macro will be defined if support is present
39689 for EC keys.
39690
39691 Note that RFC 8301 says:
39692 .code
39693 rsa-sha1 MUST NOT be used for signing or verifying.
39694
39695 DKIM signatures identified as having been signed with historic
39696 algorithms (currently, rsa-sha1) have permanently failed evaluation
39697 .endd
39698
39699 To enforce this you must have a DKIM ACL which checks this variable
39700 and overwrites the &$dkim_verify_status$& variable as discussed above.
39701
39702 .vitem &%$dkim_canon_body%&
39703 The body canonicalization method. One of 'relaxed' or 'simple'.
39704
39705 .vitem &%$dkim_canon_headers%&
39706 The header canonicalization method. One of 'relaxed' or 'simple'.
39707
39708 .vitem &%$dkim_copiedheaders%&
39709 A transcript of headers and their values which are included in the signature
39710 (copied from the 'z=' tag of the signature).
39711 Note that RFC6376 requires that verification fail if the From: header is
39712 not included in the signature.  Exim does not enforce this; sites wishing
39713 strict enforcement should code the check explicitly.
39714
39715 .vitem &%$dkim_bodylength%&
39716 The number of signed body bytes. If zero ("0"), the body is unsigned. If no
39717 limit was set by the signer, "9999999999999" is returned. This makes sure
39718 that this variable always expands to an integer value.
39719 .new
39720 &*Note:*& The presence of the signature tag specifying a signing body length
39721 is one possible route to spoofing of valid DKIM signatures.
39722 A paranoid implementation might wish to regard signature where this variable
39723 shows less than the "no limit" return as being invalid.
39724 .wen
39725
39726 .vitem &%$dkim_created%&
39727 UNIX timestamp reflecting the date and time when the signature was created.
39728 When this was not specified by the signer, "0" is returned.
39729
39730 .vitem &%$dkim_expires%&
39731 UNIX timestamp reflecting the date and time when the signer wants the
39732 signature to be treated as "expired". When this was not specified by the
39733 signer, "9999999999999" is returned. This makes it possible to do useful
39734 integer size comparisons against this value.
39735 Note that Exim does not check this value.
39736
39737 .vitem &%$dkim_headernames%&
39738 A colon-separated list of names of headers included in the signature.
39739
39740 .vitem &%$dkim_key_testing%&
39741 "1" if the key record has the "testing" flag set, "0" if not.
39742
39743 .vitem &%$dkim_key_nosubdomains%&
39744 "1" if the key record forbids subdomaining, "0" otherwise.
39745
39746 .vitem &%$dkim_key_srvtype%&
39747 Service type (tag s=) from the key record. Defaults to "*" if not specified
39748 in the key record.
39749
39750 .vitem &%$dkim_key_granularity%&
39751 Key granularity (tag g=) from the key record. Defaults to "*" if not specified
39752 in the key record.
39753
39754 .vitem &%$dkim_key_notes%&
39755 Notes from the key record (tag n=).
39756
39757 .vitem &%$dkim_key_length%&
39758 Number of bits in the key.
39759
39760 Note that RFC 8301 says:
39761 .code
39762 Verifiers MUST NOT consider signatures using RSA keys of
39763 less than 1024 bits as valid signatures.
39764 .endd
39765
39766 To enforce this you must have a DKIM ACL which checks this variable
39767 and overwrites the &$dkim_verify_status$& variable as discussed above.
39768 As EC keys are much smaller, the check should only do this for RSA keys.
39769
39770 .endlist
39771
39772 In addition, two ACL conditions are provided:
39773
39774 .vlist
39775 .vitem &%dkim_signers%&
39776 ACL condition that checks a colon-separated list of domains or identities
39777 for a match against the domain or identity that the ACL is currently verifying
39778 (reflected by &%$dkim_cur_signer%&). This is typically used to restrict an ACL
39779 verb to a group of domains or identities. For example:
39780
39781 .code
39782 # Warn when Mail purportedly from GMail has no gmail signature
39783 warn log_message = GMail sender without gmail.com DKIM signature
39784      sender_domains = gmail.com
39785      dkim_signers = gmail.com
39786      dkim_status = none
39787 .endd
39788
39789 Note that the above does not check for a total lack of DKIM signing;
39790 for that check for empty &$h_DKIM-Signature:$& in the data ACL.
39791
39792 .vitem &%dkim_status%&
39793 ACL condition that checks a colon-separated list of possible DKIM verification
39794 results against the actual result of verification. This is typically used
39795 to restrict an ACL verb to a list of verification outcomes, for example:
39796
39797 .code
39798 deny message = Mail from Paypal with invalid/missing signature
39799      sender_domains = paypal.com:paypal.de
39800      dkim_signers = paypal.com:paypal.de
39801      dkim_status = none:invalid:fail
39802 .endd
39803
39804 The possible status keywords are: 'none','invalid','fail' and 'pass'. Please
39805 see the documentation of the &%$dkim_verify_status%& expansion variable above
39806 for more information of what they mean.
39807 .endlist
39808
39809
39810
39811
39812 .section "SPF (Sender Policy Framework)" SECSPF
39813 .cindex SPF verification
39814
39815 SPF is a mechanism whereby a domain may assert which IP addresses may transmit
39816 messages with its domain in the envelope from, documented by RFC 7208.
39817 For more information on SPF see &url(http://www.openspf.org).
39818 . --- 2018-09-07: still not https
39819
39820 Messages sent by a system not authorised will fail checking of such assertions.
39821 This includes retransmissions done by traditional forwarders.
39822
39823 SPF verification support is built into Exim if SUPPORT_SPF=yes is set in
39824 &_Local/Makefile_&.  The support uses the &_libspf2_& library
39825 &url(https://www.libspf2.org/).
39826 There is no Exim involvement in the transmission of messages;
39827 publishing certain DNS records is all that is required.
39828
39829 For verification, an ACL condition and an expansion lookup are provided.
39830 .cindex authentication "expansion item"
39831 Performing verification sets up information used by the
39832 &$authresults$& expansion item.
39833
39834
39835 .cindex SPF "ACL condition"
39836 .cindex ACL "spf condition"
39837 The ACL condition "spf" can be used at or after the MAIL ACL.
39838 It takes as an argument a list of strings giving the outcome of the SPF check,
39839 and will succeed for any matching outcome.
39840 Valid strings are:
39841 .vlist
39842 .vitem &%pass%&
39843 The SPF check passed, the sending host is positively verified by SPF.
39844
39845 .vitem &%fail%&
39846 The SPF check failed, the sending host is NOT allowed to send mail for the
39847 domain in the envelope-from address.
39848
39849 .vitem &%softfail%&
39850 The SPF check failed, but the queried domain can't absolutely confirm that this
39851 is a forgery.
39852
39853 .vitem &%none%&
39854 The queried domain does not publish SPF records.
39855
39856 .vitem &%neutral%&
39857 The SPF check returned a "neutral" state.  This means the queried domain has
39858 published a SPF record, but wants to allow outside servers to send mail under
39859 its domain as well.  This should be treated like "none".
39860
39861 .vitem &%permerror%&
39862 This indicates a syntax error in the SPF record of the queried domain.
39863 You may deny messages when this occurs.
39864
39865 .vitem &%temperror%&
39866 This indicates a temporary error during all processing, including Exim's
39867 SPF processing.  You may defer messages when this occurs.
39868 .endlist
39869
39870 You can prefix each string with an exclamation mark to  invert
39871 its meaning,  for example  "!fail" will  match all  results but
39872 "fail".  The  string  list is  evaluated  left-to-right,  in a
39873 short-circuit fashion.
39874
39875 Example:
39876 .code
39877 deny spf = fail
39878      message = $sender_host_address is not allowed to send mail from \
39879                ${if def:sender_address_domain \
39880                     {$sender_address_domain}{$sender_helo_name}}.  \
39881                Please see http://www.openspf.org/Why?scope=\
39882                ${if def:sender_address_domain {mfrom}{helo}};\
39883                identity=${if def:sender_address_domain \
39884                              {$sender_address}{$sender_helo_name}};\
39885                ip=$sender_host_address
39886 .endd
39887
39888 When the spf condition has run, it sets up several expansion
39889 variables:
39890
39891 .cindex SPF "verification variables"
39892 .vlist
39893 .vitem &$spf_header_comment$&
39894 .vindex &$spf_header_comment$&
39895   This contains a human-readable string describing the outcome
39896   of the SPF check. You can add it to a custom header or use
39897   it for logging purposes.
39898
39899 .vitem &$spf_received$&
39900 .vindex &$spf_received$&
39901   This contains a complete Received-SPF: header that can be
39902   added to the message. Please note that according to the SPF
39903   draft, this header must be added at the top of the header
39904   list. Please see section 10 on how you can do this.
39905
39906   Note: in case of "Best-guess" (see below), the convention is
39907   to put this string in a header called X-SPF-Guess: instead.
39908
39909 .vitem &$spf_result$&
39910 .vindex &$spf_result$&
39911   This contains the outcome of the SPF check in string form,
39912   one of pass, fail, softfail, none, neutral, permerror or
39913   temperror.
39914
39915 .vitem &$spf_result_guessed$&
39916 .vindex &$spf_result_guessed$&
39917   This boolean is true only if a best-guess operation was used
39918   and required in order to obtain a result.
39919
39920 .vitem &$spf_smtp_comment$&
39921 .vindex &$spf_smtp_comment$&
39922   This contains a string that can be used in a SMTP response
39923   to the calling party. Useful for "fail".
39924 .endlist
39925
39926
39927 .cindex SPF "ACL condition"
39928 .cindex ACL "spf_guess condition"
39929 .cindex SPF "best guess"
39930 In addition to SPF, you can also perform checks for so-called
39931 "Best-guess".  Strictly speaking, "Best-guess" is not standard
39932 SPF, but it is supported by the same framework that enables SPF
39933 capability.
39934 Refer to &url(http://www.openspf.org/FAQ/Best_guess_record)
39935 for a description of what it means.
39936 . --- 2018-09-07: still not https:
39937
39938 To access this feature, simply use the spf_guess condition in place
39939 of the spf one.  For example:
39940
39941 .code
39942 deny spf_guess = fail
39943      message = $sender_host_address doesn't look trustworthy to me
39944 .endd
39945
39946 In case you decide to reject messages based on this check, you
39947 should note that although it uses the same framework, "Best-guess"
39948 is not SPF, and therefore you should not mention SPF at all in your
39949 reject message.
39950
39951 When the spf_guess condition has run, it sets up the same expansion
39952 variables as when spf condition is run, described above.
39953
39954 Additionally, since Best-guess is not standardized, you may redefine
39955 what "Best-guess" means to you by redefining the main configuration
39956 &%spf_guess%& option.
39957 For example, the following:
39958
39959 .code
39960 spf_guess = v=spf1 a/16 mx/16 ptr ?all
39961 .endd
39962
39963 would relax host matching rules to a broader network range.
39964
39965
39966 .cindex SPF "lookup expansion"
39967 .cindex lookup spf
39968 A lookup expansion is also available. It takes an email
39969 address as the key and an IP address as the database:
39970
39971 .code
39972   ${lookup {username@domain} spf {ip.ip.ip.ip}}
39973 .endd
39974
39975 The lookup will return the same result strings as can appear in
39976 &$spf_result$& (pass,fail,softfail,neutral,none,err_perm,err_temp).
39977 Currently, only IPv4 addresses are supported.
39978
39979
39980
39981
39982 . ////////////////////////////////////////////////////////////////////////////
39983 . ////////////////////////////////////////////////////////////////////////////
39984
39985 .chapter "Proxies" "CHAPproxies" &&&
39986          "Proxy support"
39987 .cindex "proxy support"
39988 .cindex "proxy" "access via"
39989
39990 A proxy is an intermediate system through which communication is passed.
39991 Proxies may provide a security, availability or load-distribution function.
39992
39993
39994 .section "Inbound proxies" SECTproxyInbound
39995 .cindex proxy inbound
39996 .cindex proxy "server side"
39997 .cindex proxy "Proxy protocol"
39998 .cindex "Proxy protocol" proxy
39999
40000 Exim has support for receiving inbound SMTP connections via a proxy
40001 that uses &"Proxy Protocol"& to speak to it.
40002 To include this support, include &"SUPPORT_PROXY=yes"&
40003 in Local/Makefile.
40004
40005 It was built on the HAProxy specification, found at
40006 &url(https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt).
40007
40008 The purpose of this facility is so that an application load balancer,
40009 such as HAProxy, can sit in front of several Exim servers
40010 to distribute load.
40011 Exim uses the local protocol communication with the proxy to obtain
40012 the remote SMTP system IP address and port information.
40013 There is no logging if a host passes or
40014 fails Proxy Protocol negotiation, but it can easily be determined and
40015 recorded in an ACL (example is below).
40016
40017 Use of a proxy is enabled by setting the &%hosts_proxy%&
40018 main configuration option to a hostlist; connections from these
40019 hosts will use Proxy Protocol.
40020 Exim supports both version 1 and version 2 of the Proxy Protocol and
40021 automatically determines which version is in use.
40022
40023 The Proxy Protocol header is the first data received on a TCP connection
40024 and is inserted before any TLS-on-connect handshake from the client; Exim
40025 negotiates TLS between Exim-as-server and the remote client, not between
40026 Exim and the proxy server.
40027
40028 The following expansion variables are usable
40029 (&"internal"& and &"external"& here refer to the interfaces
40030 of the proxy):
40031 .display
40032 &'proxy_external_address   '& IP of host being proxied or IP of remote interface of proxy
40033 &'proxy_external_port      '& Port of host being proxied or Port on remote interface of proxy
40034 &'proxy_local_address      '& IP of proxy server inbound or IP of local interface of proxy
40035 &'proxy_local_port         '& Port of proxy server inbound or Port on local interface of proxy
40036 &'proxy_session            '& boolean: SMTP connection via proxy
40037 .endd
40038 If &$proxy_session$& is set but &$proxy_external_address$& is empty
40039 there was a protocol error.
40040
40041 Since the real connections are all coming from the proxy, and the
40042 per host connection tracking is done before Proxy Protocol is
40043 evaluated, &%smtp_accept_max_per_host%& must be set high enough to
40044 handle all of the parallel volume you expect per inbound proxy.
40045 With the option set so high, you lose the ability
40046 to protect your server from many connections from one IP.
40047 In order to prevent your server from overload, you
40048 need to add a per connection ratelimit to your connect ACL.
40049 A possible solution is:
40050 .display
40051   # Set max number of connections per host
40052   LIMIT   = 5
40053   # Or do some kind of IP lookup in a flat file or database
40054   # LIMIT = ${lookup{$sender_host_address}iplsearch{/etc/exim/proxy_limits}}
40055
40056   defer   message        = Too many connections from this IP right now
40057           ratelimit      = LIMIT / 5s / per_conn / strict
40058 .endd
40059
40060
40061
40062 .section "Outbound proxies" SECTproxySOCKS
40063 .cindex proxy outbound
40064 .cindex proxy "client side"
40065 .cindex proxy SOCKS
40066 .cindex SOCKS proxy
40067 Exim has support for sending outbound SMTP via a proxy
40068 using a protocol called SOCKS5 (defined by RFC1928).
40069 The support can be optionally included by defining SUPPORT_SOCKS=yes in
40070 Local/Makefile.
40071
40072 Use of a proxy is enabled by setting the &%socks_proxy%& option
40073 on an smtp transport.
40074 The option value is expanded and should then be a list
40075 (colon-separated by default) of proxy specifiers.
40076 Each proxy specifier is a list
40077 (space-separated by default) where the initial element
40078 is an IP address and any subsequent elements are options.
40079
40080 Options are a string <name>=<value>.
40081 The list of options is in the following table:
40082 .display
40083 &'auth   '& authentication method
40084 &'name   '& authentication username
40085 &'pass   '& authentication password
40086 &'port   '& tcp port
40087 &'tmo    '& connection timeout
40088 &'pri    '& priority
40089 &'weight '& selection bias
40090 .endd
40091
40092 More details on each of these options follows:
40093
40094 .ilist
40095 .cindex authentication "to proxy"
40096 .cindex proxy authentication
40097 &%auth%&: Either &"none"& (default) or &"name"&.
40098 Using &"name"& selects username/password authentication per RFC 1929
40099 for access to the proxy.
40100 Default is &"none"&.
40101 .next
40102 &%name%&: sets the username for the &"name"& authentication method.
40103 Default is empty.
40104 .next
40105 &%pass%&: sets the password for the &"name"& authentication method.
40106 Default is empty.
40107 .next
40108 &%port%&: the TCP port number to use for the connection to the proxy.
40109 Default is 1080.
40110 .next
40111 &%tmo%&: sets a connection timeout in seconds for this proxy.
40112 Default is 5.
40113 .next
40114 &%pri%&: specifies a priority for the proxy within the list,
40115 higher values being tried first.
40116 The default priority is 1.
40117 .next
40118 &%weight%&: specifies a selection bias.
40119 Within a priority set servers are queried in a random fashion,
40120 weighted by this value.
40121 The default value for selection bias is 1.
40122 .endlist
40123
40124 Proxies from the list are tried according to their priority
40125 and weight settings until one responds.  The timeout for the
40126 overall connection applies to the set of proxied attempts.
40127
40128 .section Logging SECTproxyLog
40129 To log the (local) IP of a proxy in the incoming or delivery logline,
40130 add &"+proxy"& to the &%log_selector%& option.
40131 This will add a component tagged with &"PRX="& to the line.
40132
40133 . ////////////////////////////////////////////////////////////////////////////
40134 . ////////////////////////////////////////////////////////////////////////////
40135
40136 .chapter "Internationalisation" "CHAPi18n" &&&
40137          "Internationalisation""
40138 .cindex internationalisation "email address"
40139 .cindex EAI
40140 .cindex i18n
40141 .cindex utf8 "mail name handling"
40142
40143 Exim has support for Internationalised mail names.
40144 To include this it must be built with SUPPORT_I18N and the libidn library.
40145 Standards supported are RFCs 2060, 5890, 6530 and 6533.
40146
40147 If Exim is built with SUPPORT_I18N_2008 (in addition to SUPPORT_I18N, not
40148 instead of it) then IDNA2008 is supported; this adds an extra library
40149 requirement, upon libidn2.
40150
40151 .section "MTA operations" SECTi18nMTA
40152 .cindex SMTPUTF8 "ESMTP option"
40153 The main configuration option &%smtputf8_advertise_hosts%& specifies
40154 a host list.  If this matches the sending host and
40155 accept_8bitmime is true (the default) then the ESMTP option
40156 SMTPUTF8 will be advertised.
40157
40158 If the sender specifies the SMTPUTF8 option on a MAIL command
40159 international handling for the message is enabled and
40160 the expansion variable &$message_smtputf8$& will have value TRUE.
40161
40162 The option &%allow_utf8_domains%& is set to true for this
40163 message. All DNS lookups are converted to a-label form
40164 whatever the setting of &%allow_utf8_domains%&
40165 when Exim is built with SUPPORT_I18N.
40166
40167 Both localparts and domain are maintained as the original
40168 UTF-8 form internally; any comparison or regular-expression use will
40169 require appropriate care.  Filenames created, eg. by
40170 the appendfile transport, will have UTF-8 names.
40171
40172 HELO names sent by the smtp transport will have any UTF-8
40173 components expanded to a-label form,
40174 and any certificate name checks will be done using the a-label
40175 form of the name.
40176
40177 .cindex log protocol
40178 .cindex SMTPUTF8 logging
40179 .cindex i18n logging
40180 Log lines and Received-by: header lines will acquire a "utf8"
40181 prefix on the protocol element, eg. utf8esmtp.
40182
40183 The following expansion operators can be used:
40184 .code
40185 ${utf8_domain_to_alabel:str}
40186 ${utf8_domain_from_alabel:str}
40187 ${utf8_localpart_to_alabel:str}
40188 ${utf8_localpart_from_alabel:str}
40189 .endd
40190
40191 .cindex utf8 "address downconversion"
40192 .cindex i18n "utf8 address downconversion"
40193 The RCPT ACL
40194 may use the following modifier:
40195 .display
40196 control = utf8_downconvert
40197 control = utf8_downconvert/<value>
40198 .endd
40199 This sets a flag requiring that addresses are converted to
40200 a-label form before smtp delivery, for use in a
40201 Message Submission Agent context.
40202 If a value is appended it may be:
40203 .display
40204 &`1  `& (default) mandatory downconversion
40205 &`0  `& no downconversion
40206 &`-1 `& if SMTPUTF8 not supported by destination host
40207 .endd
40208
40209 If mua_wrapper is set, the utf8_downconvert control
40210 is initially set to -1.
40211
40212 .new
40213 The smtp transport has an option &%utf8_downconvert%&.
40214 If set it must expand to one of the three values described above,
40215 and it overrides any previously set value.
40216 .wen
40217
40218
40219 There is no explicit support for VRFY and EXPN.
40220 Configurations supporting these should inspect
40221 &$smtp_command_argument$& for an SMTPUTF8 argument.
40222
40223 There is no support for LMTP on Unix sockets.
40224 Using the "lmtp" protocol option on an smtp transport,
40225 for LMTP over TCP, should work as expected.
40226
40227 There is no support for DSN unitext handling,
40228 and no provision for converting logging from or to UTF-8.
40229
40230
40231
40232 .section "MDA operations" SECTi18nMDA
40233 To aid in constructing names suitable for IMAP folders
40234 the following expansion operator can be used:
40235 .code
40236 ${imapfolder {<string>} {<sep>} {<specials>}}
40237 .endd
40238
40239 The string is converted from the charset specified by
40240 the "headers charset" command (in a filter file)
40241 or &%headers_charset%& main configuration option (otherwise),
40242 to the
40243 modified UTF-7 encoding specified by RFC 2060,
40244 with the following exception: All occurrences of <sep>
40245 (which has to be a single character)
40246 are replaced with periods ("."), and all periods and slashes that are not
40247 <sep> and are not in the <specials> string are BASE64 encoded.
40248
40249 The third argument can be omitted, defaulting to an empty string.
40250 The second argument can be omitted, defaulting to "/".
40251
40252 This is the encoding used by Courier for Maildir names on disk, and followed
40253 by many other IMAP servers.
40254
40255 Examples:
40256 .display
40257 &`${imapfolder {Foo/Bar}}       `& yields &`Foo.Bar`&
40258 &`${imapfolder {Foo/Bar}{.}{/}} `& yields &`Foo&&AC8-Bar`&
40259 &`${imapfolder {Räksmörgås}}    `& yields &`R&&AOQ-ksm&&APY-rg&&AOU-s`&
40260 .endd
40261
40262 Note that the source charset setting is vital, and also that characters
40263 must be representable in UTF-16.
40264
40265
40266 . ////////////////////////////////////////////////////////////////////////////
40267 . ////////////////////////////////////////////////////////////////////////////
40268
40269 .chapter "Events" "CHAPevents" &&&
40270          "Events"
40271 .cindex events
40272
40273 The events mechanism in Exim can be used to intercept processing at a number
40274 of points.  It was originally invented to give a way to do customised logging
40275 actions (for example, to a database) but can also be used to modify some
40276 processing actions.
40277
40278 Most installations will never need to use Events.
40279 The support can be left out of a build by defining DISABLE_EVENT=yes
40280 in &_Local/Makefile_&.
40281
40282 There are two major classes of events: main and transport.
40283 The main configuration option &%event_action%& controls reception events;
40284 a transport option &%event_action%& controls delivery events.
40285
40286 Both options are a string which is expanded when the event fires.
40287 An example might look like:
40288 .cindex logging custom
40289 .code
40290 event_action = ${if eq {msg:delivery}{$event_name} \
40291 {${lookup pgsql {SELECT * FROM record_Delivery( \
40292     '${quote_pgsql:$sender_address_domain}',\
40293     '${quote_pgsql:${lc:$sender_address_local_part}}', \
40294     '${quote_pgsql:$domain}', \
40295     '${quote_pgsql:${lc:$local_part}}', \
40296     '${quote_pgsql:$host_address}', \
40297     '${quote_pgsql:${lc:$host}}', \
40298     '${quote_pgsql:$message_exim_id}')}} \
40299 } {}}
40300 .endd
40301
40302 Events have names which correspond to the point in process at which they fire.
40303 The name is placed in the variable &$event_name$& and the event action
40304 expansion must check this, as it will be called for every possible event type.
40305
40306 The current list of events is:
40307 .display
40308 &`dane:fail              after    transport  `& per connection
40309 &`msg:complete           after    main       `& per message
40310 &`msg:delivery           after    transport  `& per recipient
40311 &`msg:rcpt:host:defer    after    transport  `& per recipient per host
40312 &`msg:rcpt:defer         after    transport  `& per recipient
40313 &`msg:host:defer         after    transport  `& per attempt
40314 &`msg:fail:delivery      after    transport  `& per recipient
40315 &`msg:fail:internal      after    main       `& per recipient
40316 &`tcp:connect            before   transport  `& per connection
40317 &`tcp:close              after    transport  `& per connection
40318 &`tls:cert               before   both       `& per certificate in verification chain
40319 &`smtp:connect           after    transport  `& per connection
40320 .endd
40321 New event types may be added in future.
40322
40323 The event name is a colon-separated list, defining the type of
40324 event in a tree of possibilities.  It may be used as a list
40325 or just matched on as a whole.  There will be no spaces in the name.
40326
40327 The second column in the table above describes whether the event fires
40328 before or after the action is associates with.  Those which fire before
40329 can be used to affect that action (more on this below).
40330
40331 The third column in the table above says what section of the configuration
40332 should define the event action.
40333
40334 An additional variable, &$event_data$&, is filled with information varying
40335 with the event type:
40336 .display
40337 &`dane:fail            `& failure reason
40338 &`msg:delivery         `& smtp confirmation message
40339 &`msg:fail:internal    `& failure reason
40340 &`msg:fail:delivery    `& smtp error message
40341 &`msg:rcpt:host:defer  `& error string
40342 &`msg:rcpt:defer       `& error string
40343 &`msg:host:defer       `& error string
40344 &`tls:cert             `& verification chain depth
40345 &`smtp:connect         `& smtp banner
40346 .endd
40347
40348 The :defer events populate one extra variable: &$event_defer_errno$&.
40349
40350 For complex operations an ACL expansion can be used in &%event_action%&
40351 however due to the multiple contexts that Exim operates in during
40352 the course of its processing:
40353 .ilist
40354 variables set in transport events will not be visible outside that
40355 transport call
40356 .next
40357 acl_m variables in a server context are lost on a new connection,
40358 and after smtp helo/ehlo/mail/starttls/rset commands
40359 .endlist
40360 Using an ACL expansion with the logwrite modifier can be
40361 a useful way of writing to the main log.
40362
40363 The expansion of the event_action option should normally
40364 return an empty string.  Should it return anything else the
40365 following will be forced:
40366 .display
40367 &`tcp:connect      `&  do not connect
40368 &`tls:cert         `&  refuse verification
40369 &`smtp:connect     `&  close connection
40370 .endd
40371 All other message types ignore the result string, and
40372 no other use is made of it.
40373
40374 For a tcp:connect event, if the connection is being made to a proxy
40375 then the address and port variables will be that of the proxy and not
40376 the target system.
40377
40378 For tls:cert events, if GnuTLS is in use this will trigger only per
40379 chain element received on the connection.
40380 For OpenSSL it will trigger for every chain element including those
40381 loaded locally.
40382
40383 . ////////////////////////////////////////////////////////////////////////////
40384 . ////////////////////////////////////////////////////////////////////////////
40385
40386 .chapter "Adding new drivers or lookup types" "CHID13" &&&
40387          "Adding drivers or lookups"
40388 .cindex "adding drivers"
40389 .cindex "new drivers, adding"
40390 .cindex "drivers" "adding new"
40391 The following actions have to be taken in order to add a new router, transport,
40392 authenticator, or lookup type to Exim:
40393
40394 .olist
40395 Choose a name for the driver or lookup type that does not conflict with any
40396 existing name; I will use &"newdriver"& in what follows.
40397 .next
40398 Add to &_src/EDITME_& the line:
40399 .display
40400 <&'type'&>&`_NEWDRIVER=yes`&
40401 .endd
40402 where <&'type'&> is ROUTER, TRANSPORT, AUTH, or LOOKUP. If the
40403 code is not to be included in the binary by default, comment this line out. You
40404 should also add any relevant comments about the driver or lookup type.
40405 .next
40406 Add to &_src/config.h.defaults_& the line:
40407 .code
40408 #define <type>_NEWDRIVER
40409 .endd
40410 .next
40411 Edit &_src/drtables.c_&, adding conditional code to pull in the private header
40412 and create a table entry as is done for all the other drivers and lookup types.
40413 .next
40414 Edit &_scripts/lookups-Makefile_& if this is a new lookup; there is a for-loop
40415 near the bottom, ranging the &`name_mod`& variable over a list of all lookups.
40416 Add your &`NEWDRIVER`& to that list.
40417 As long as the dynamic module would be named &_newdriver.so_&, you can use the
40418 simple form that most lookups have.
40419 .next
40420 Edit &_Makefile_& in the appropriate sub-directory (&_src/routers_&,
40421 &_src/transports_&, &_src/auths_&, or &_src/lookups_&); add a line for the new
40422 driver or lookup type and add it to the definition of OBJ.
40423 .next
40424 Create &_newdriver.h_& and &_newdriver.c_& in the appropriate sub-directory of
40425 &_src_&.
40426 .next
40427 Edit &_scripts/MakeLinks_& and add commands to link the &_.h_& and &_.c_& files
40428 as for other drivers and lookups.
40429 .endlist
40430
40431 Then all you need to do is write the code! A good way to start is to make a
40432 proforma by copying an existing module of the same type, globally changing all
40433 occurrences of the name, and cutting out most of the code. Note that any
40434 options you create must be listed in alphabetical order, because the tables are
40435 searched using a binary chop procedure.
40436
40437 There is a &_README_& file in each of the sub-directories of &_src_& describing
40438 the interface that is expected.
40439
40440
40441
40442
40443 . ////////////////////////////////////////////////////////////////////////////
40444 . ////////////////////////////////////////////////////////////////////////////
40445
40446 . /////////////////////////////////////////////////////////////////////////////
40447 . These lines are processing instructions for the Simple DocBook Processor that
40448 . Philip Hazel has developed as a less cumbersome way of making PostScript and
40449 . PDFs than using xmlto and fop. They will be ignored by all other XML
40450 . processors.
40451 . /////////////////////////////////////////////////////////////////////////////
40452
40453 .literal xml
40454 <?sdop
40455   format="newpage"
40456   foot_right_recto="&chaptertitle;"
40457   foot_right_verso="&chaptertitle;"
40458 ?>
40459 .literal off
40460
40461 .makeindex "Options index"   "option"
40462 .makeindex "Variables index" "variable"
40463 .makeindex "Concept index"   "concept"
40464
40465
40466 . /////////////////////////////////////////////////////////////////////////////
40467 . /////////////////////////////////////////////////////////////////////////////