Commit | Line | Data |
---|---|---|
8e669ac1 | 1 | . $Cambridge: exim/doc/doc-src/spec.src,v 1.8 2005/02/17 11:58:25 ph10 Exp $ |
495ae4b0 | 2 | . |
4964e932 PH |
3 | .set version "4.50" |
4 | .set previousversion "4.40" | |
d43194df | 5 | .set versionmonth "February" |
4964e932 | 6 | .set versionyear "2005" |
495ae4b0 PH |
7 | .set ACL "ACL" |
8 | ||
9 | . The last of those is to make ACL index entries easier to type. It is put | |
10 | . up here so that it gets picked up by the HTML converter, which otherwise | |
11 | . skips to the first chapter. A longer version is set below for use in the | |
12 | . printed index. | |
13 | ||
14 | .set sgcal true | |
15 | .set html false | |
16 | .set texinfo false | |
17 | ||
18 | .if !set style | |
19 | .library "a4ps" | |
20 | .linelength ~~sys.linelength + 0.2in | |
21 | .set newlinelength ~~sys.linelength | |
22 | .emphasis ~~sys.linelength + 0.1in | |
23 | .pagedepth ~~sys.pagedepth - 0.2in | |
24 | .bindfont 51 "atl/Times-Bold" 9 | |
25 | .bindfont 52 "atl/Times-Roman" 9 | |
26 | .bindfont 53 "atl/Times-Roman" 7 | |
27 | .bindfont 54 "atl/Courier" 9 | |
28 | .bindfont 55 "atl/Courier-Bold" ~~maintypesize | |
29 | .bindfont 56 "atl/Times-Italic" 7 | |
30 | .bindfont 57 "atl/Times-Bold" 7 | |
31 | .bindfont 58 "atl/Symbol" 7 | |
32 | .set ssspaceb 1.50 | |
33 | ||
34 | .if ~~sgcal | |
35 | . Used for the "small print" incorporated code stuff. Only rm, it, bf, sp are | |
36 | . actually used at present. | |
37 | . rm it sl bf bi ss tt sp sc | |
38 | .fontgroup 9 = 53 56 0 57 0 0 0 58 0 | |
39 | .fi | |
40 | .fi | |
41 | ||
42 | .if !~~sys.fancy | |
43 | .fontgroup 9 = 0 0 0 0 0 0 0 0 0 | |
44 | .fi | |
45 | ||
46 | .include "markup.sg" | |
47 | ||
48 | .if ~~sys.fancy | |
49 | .flag $smc{ "$push$g0$f54" | |
50 | .flag $sm{ "$push$g0$f53" | |
51 | .flag $smi{ "$push$g0$f56" | |
52 | .flag $as{ "$push$g0$f52" | |
53 | .flag $ab{ "$push$g0$f51" | |
54 | .flag $cb{ "$push$g0$f55" | |
55 | . | |
56 | .else | |
57 | .flag $smc{ "$push" | |
58 | .flag $sm{ "$push" | |
59 | .flag $smi{ "$push" | |
60 | .flag $cb{ "$push" | |
61 | .fi | |
62 | ||
63 | .macro isunderscore "string" | |
64 | .set string "~~1" | |
65 | .set length length "~~1" | |
66 | .undrec 1 | |
67 | .endm | |
68 | ||
69 | .macro undrec "offset" | |
70 | .if ~~1 > ~~length | |
71 | .set underscore false | |
72 | .else | |
73 | .set sub "~~string"(1,~~1) | |
74 | .if "~~sub" == "_" | |
75 | .set underscore true | |
76 | .else | |
77 | .set next ~~1 + 1 | |
78 | .undrec ~~next | |
79 | .fi | |
80 | .fi | |
81 | .endm | |
82 | ||
83 | .macro testunderscore "string" | |
84 | .isunderscore "~~1" | |
85 | .newline | |
86 | .endm | |
87 | ||
88 | .macro tabs 6 | |
89 | .if ~~sys.fancy | |
90 | .tabset ~~1em | |
91 | .else | |
92 | .set temp (~~1 * 5)/4 | |
93 | .tabset ~~temp em | |
94 | .fi | |
95 | .endm | |
96 | ||
97 | .macro startoptions | |
98 | .newline | |
99 | .push | |
100 | .if ~~sys.fancy | |
101 | .indent 6em | |
102 | .else | |
103 | .indent 7em | |
104 | .fi | |
105 | .endm | |
106 | ||
107 | .macro endoptions | |
108 | .newline | |
109 | .pop | |
110 | .endm | |
111 | ||
112 | .macro option "option" "" | |
113 | .newpar | |
114 | .index \-~~1-\ option | |
115 | .tempindent 0 | |
116 | \-~~1-\~~2#$i | |
117 | .nosep | |
118 | .endm | |
119 | ||
120 | .macro startitems | |
121 | .newline | |
122 | .push | |
123 | .indent 3em | |
124 | .endm | |
125 | ||
126 | .macro enditems | |
127 | .newline | |
128 | .pop | |
129 | .endm | |
130 | ||
131 | .macro item "item" "6" | |
132 | .newpar | |
133 | .if ~~sys.leftonpage < ~~2ld | |
134 | .newpage | |
135 | .fi | |
136 | .tempindent 0 | |
137 | \**~~1**\ | |
138 | .blank | |
139 | .endm | |
140 | ||
d43194df PH |
141 | .macro startconf "" |
142 | .set confsection "~~1" | |
495ae4b0 PH |
143 | .newline |
144 | .push | |
145 | .if ~~sys.fancy | |
146 | .indent 2em | |
147 | .tabset 9em | |
148 | .else | |
149 | .indent 4em | |
150 | .tabset 13em | |
151 | .fi | |
152 | .endm | |
153 | ||
154 | .macro endconf | |
155 | .newline | |
156 | .pop | |
157 | .endm | |
158 | ||
159 | .macro conf "option" "type" "default" "6" | |
160 | .newpar | |
161 | .if ~~sys.leftonpage < ~~4ld | |
162 | .newpage | |
163 | .fi | |
164 | .testunderscore "~~1" | |
165 | .if ~~underscore | |
166 | .index \~~1\ | |
167 | .else | |
168 | .index \~~1\ option | |
169 | .fi | |
d43194df PH |
170 | .if "~~confsection" == "" |
171 | .set inssect "" | |
172 | .else | |
173 | .set inssect "$rm{Use:} $it{~~confsection}###" | |
174 | .fi | |
495ae4b0 | 175 | .tempindent 0 |
d43194df | 176 | \**~~1**\ $c ~~inssect$rm{Type:} $it{~~2} $e $rm{Default:} $it{~~3} |
495ae4b0 PH |
177 | .blank |
178 | .endm | |
179 | ||
180 | .set contents true | |
181 | .set figurenumber -1 | |
182 | .set displayindent 2em | |
183 | ||
184 | .index @$1, @$2, etc. $it{see numerical variables} | |
185 | .index address||rewriting $it{see rewriting} | |
186 | .index CR character $it{see carriage return} | |
187 | .index CRL $it{see certificate revocation list} | |
188 | .index delivery||failure report $it{see bounce message} | |
189 | .index dialup $it{see intermittently connected hosts} | |
4964e932 | 190 | .index exiscan $it{see content scanning} |
495ae4b0 PH |
191 | .index failover $it{see fallback} |
192 | .index fallover $it{see fallback} | |
193 | .index filter||Sieve $it{see Sieve filter} | |
194 | .index ident $it{see RFC 1413} | |
195 | .index LF character $it{see linefeed} | |
196 | .index maximum $it{see limit} | |
197 | .index NUL $it{see binary zero} | |
d43194df | 198 | .index passwd file $it{see \(/etc/passwd)\} |
495ae4b0 PH |
199 | .index process id $it{see pid} |
200 | .index RBL $it{see DNS list} | |
201 | .index redirection $it{see address redirection} | |
202 | .index return path||$it{see also envelope sender} | |
4964e932 | 203 | .index scanning $it{see content scanning} |
495ae4b0 PH |
204 | .index SSL $it{see TLS} |
205 | .index string||expansion $it{see expansion} | |
206 | .index top bit $it{see 8-bit characters} | |
207 | .index variables $it{see expansion, variables} | |
208 | .index zero, binary $it{see binary zero} | |
209 | ||
210 | . This is used for the printed index. See setting above for | |
211 | . the HTML index value. | |
212 | ||
213 | .set ACL "access control lists (ACLs)" | |
214 | ||
215 | . ====================================================== | |
216 | ||
217 | .push | |
218 | .disable filling | |
219 | .justify centre | |
220 | .nofoot | |
221 | .space 8ld | |
222 | $chead{University of Cambridge Computing Service} | |
223 | .space 2ld | |
224 | $chead{Specification of the Exim Mail Transfer Agent} | |
225 | .space 3ld | |
226 | by | |
227 | .space 1ld | |
228 | Philip Hazel | |
229 | .space ~~sys.leftonpage - 15*~~sys.linedepth | |
230 | .justify left | |
231 | University Computing Service | |
232 | New Museums Site | |
233 | Pembroke Street | |
234 | Cambridge CB2 3QH | |
235 | United Kingdom | |
236 | .blank | |
237 | .tabs 6 | |
238 | $it{phone:} $t +44 1223 334600 | |
239 | $it{fax:} $t +44 1223 334679 | |
240 | $it{email:} $t ph10 $it{at} cus.cam.ac.uk | |
241 | .blank | |
242 | Edition for Exim ~~version, ~~versionmonth ~~versionyear | |
243 | .space 2ld | |
244 | .if ~~sgcal | |
245 | .fontgroup 1 | |
246 | .fi | |
247 | $c$rm{Copyright (c) University of Cambridge ~~versionyear} | |
248 | ||
249 | ||
250 | .if ~~sgcal | |
251 | .fontgroup 0 | |
252 | .font 0 | |
253 | .fi | |
254 | ||
255 | .pop | |
256 | .newpage | |
257 | ||
258 | . Blank verso for title page | |
259 | .space 1ld | |
260 | .newpage | |
261 | ||
262 | ||
263 | . Set up for actual text pages | |
264 | .page 1 | |
265 | . The first one to prevent a warning from sgfr | |
266 | . set runningfoot "~~chapter" | |
267 | .set runningfoot "" | |
268 | ||
269 | .if ~~sys.fancy | |
270 | .footdepth 2ld | |
271 | .foot | |
272 | .if "~~runningfoot" == "" | |
273 | .set rhs "" | |
274 | .else | |
275 | .set rhs "~~runningfoot (~~chapter)" | |
276 | .fi | |
277 | .set lhs "Exim ~~version" | |
278 | .linelength ~~newlinelength | |
279 | $it{~~lhs}$c[~~sys.pagenumber]$e$it{~~rhs} | |
280 | .endfoot | |
281 | .fi | |
282 | ||
283 | ||
284 | ||
285 | ||
286 | . | |
287 | . | |
288 | . | |
289 | . | |
290 | . ============================================================================ | |
291 | .chapter Introduction | |
292 | .set runningfoot "introduction" | |
293 | ||
294 | .if ~~sys.fancy | |
295 | $c$bi{If I have seen further it is by standing on the shoulders of giants.}##(Isaac Newton) | |
296 | .elif !~~html | |
297 | $c"If I have seen further it is by standing on the shoulders of giants." | |
298 | .newline | |
299 | $e (Isaac Newton) | |
300 | .else | |
301 | \*If I have seen further it is by standing on the shoulders of giants.*\ | |
302 | (Isaac Newton). | |
303 | .fi | |
304 | .blank 4 | |
305 | ||
306 | Exim is a mail transfer agent (MTA) for hosts that are running Unix or | |
307 | Unix-like operating systems. It was designed on the assumption that it would be | |
308 | run on hosts that are permanently connected to the Internet. However, it can be | |
309 | used on intermittently connected hosts with suitable configuration adjustments. | |
310 | ||
311 | Configuration files currently exist for the following operating systems: AIX, | |
312 | BSD/OS (aka BSDI), Darwin (Mac OS X), DGUX, FreeBSD, GNU/Hurd, GNU/Linux, | |
313 | HI-OSF (Hitachi), HP-UX, IRIX, MIPS RISCOS, NetBSD, OpenBSD, QNX, SCO, SCO | |
314 | SVR4.2 (aka UNIX-SV), Solaris (aka SunOS5), SunOS4, Tru64-Unix (formerly | |
4964e932 PH |
315 | Digital UNIX, formerly DEC-OSF1), Ultrix, and Unixware. Some of these operating |
316 | systems are no longer current and cannot easily be tested, so the configuration | |
317 | files may no longer work in practice. | |
495ae4b0 PH |
318 | |
319 | There are also configuration files for compiling Exim in the Cygwin environment | |
320 | that can be installed on systems running Windows. However, this document does | |
321 | not contain any information about running Exim in the Cygwin environment. | |
322 | ||
323 | The terms and conditions for the use and distribution of Exim are contained in | |
324 | the file \(NOTICE)\. Exim is distributed under the terms of the GNU General | |
325 | Public Licence, a copy of which may be found in the file \(LICENCE)\. | |
326 | ||
327 | The use, supply or promotion of Exim for the purpose of sending bulk, | |
328 | unsolicited electronic mail is incompatible with the basic aims of the program, | |
329 | which revolve around the free provision of a service that enhances the quality | |
330 | of personal communications. The author of Exim regards indiscriminate | |
331 | mass-mailing as an antisocial, irresponsible abuse of the Internet. | |
332 | ||
333 | Exim owes a great deal to Smail 3 and its author, Ron Karr. Without the | |
334 | experience of running and working on the Smail 3 code, I could never have | |
335 | contemplated starting to write a new MTA. Many of the ideas and user interfaces | |
336 | were originally taken from Smail 3, though the actual code of Exim is entirely | |
337 | new, and has developed far beyond the initial concept. | |
338 | ||
339 | Many people, both in Cambridge and around the world, have contributed to the | |
340 | development and the testing of Exim, and to porting it to various operating | |
341 | systems. I am grateful to them all. The distribution now contains a file called | |
342 | \(ACKNOWLEDGMENTS)\, in which I have started recording the names of | |
343 | contributors. | |
344 | ||
d43194df | 345 | |
495ae4b0 PH |
346 | .section Exim documentation |
347 | .index documentation | |
d43194df | 348 | .em |
495ae4b0 PH |
349 | This edition of the Exim specification applies to version ~~version of Exim. |
350 | Substantive changes from the ~~previousversion edition are marked by bars in | |
351 | the right-hand margin in the PostScript, PDF, and plain text versions of the | |
352 | document, and by green text in the HTML version, as shown by this paragraph. | |
353 | Changes are not marked in the Texinfo version, because Texinfo doesn't support | |
354 | change bars. Minor corrections and rewordings are not marked. | |
d43194df | 355 | .nem |
495ae4b0 PH |
356 | |
357 | This document is very much a reference manual; it is not a tutorial. The reader | |
358 | is expected to have some familiarity with the SMTP mail transfer protocol and | |
359 | with general Unix system administration. Although there are some discussions | |
360 | and examples in places, the information is mostly organized in a way that makes | |
361 | it easy to look up, rather than in a natural order for sequential reading. | |
362 | Furthermore, the manual aims to cover every aspect of Exim in detail, including | |
363 | a number of rarely-used, special-purpose features that are unlikely to be of | |
364 | very wide interest. | |
365 | ||
366 | .index books about Exim | |
367 | An `easier' discussion of Exim which provides more in-depth explanatory, | |
368 | introductory, and tutorial material can be found in a book entitled | |
369 | .if ~~html | |
370 | [(A HREF="http://www.uit.co.uk/exim-book/")] | |
371 | $it{The Exim SMTP Mail Server}, | |
372 | [(/A)] | |
4964e932 | 373 | published by UIT Cambridge. |
495ae4b0 PH |
374 | .else |
375 | $it{The Exim SMTP Mail Server}, published by UIT Cambridge | |
376 | (\?http://www.uit.co.uk/exim-book/?\). | |
377 | .fi | |
378 | ||
379 | This book also contains a chapter that gives a general introduction to SMTP and | |
380 | Internet mail. Inevitably, however, the book is unlikely to be fully up-to-date | |
381 | with the latest release of Exim. (Note that the earlier book about Exim, | |
382 | published by O'Reilly, covers Exim 3, and many things have changed in Exim 4.) | |
383 | ||
384 | .index \(doc/NewStuff)\ | |
385 | .index \(doc/ChangeLog)\ | |
386 | .index change log | |
387 | As the program develops, there may be features in newer versions that have not | |
388 | yet made it into this document, which is updated only when the most significant | |
d43194df PH |
389 | digit of the fractional part of the version number changes. Specifications of |
390 | new features that are not yet in this manual are placed in the file | |
391 | \(doc/NewStuff)\ in the Exim distribution. | |
392 | ||
393 | .em | |
394 | Some features may be classified as `experimental'. These may change | |
395 | incompatibly while they are developing, or even be withdrawn. For this reason, | |
396 | they are not documented in this manual. Information about experimental features | |
397 | can be found in the file \(doc/experimental.txt)\. | |
398 | .nem | |
399 | ||
400 | All changes to the program (whether new features, bug fixes, or other kinds of | |
401 | change) are noted briefly in the file called \(doc/ChangeLog)\. | |
495ae4b0 PH |
402 | |
403 | .index \(doc/spec.txt)\ | |
404 | This specification itself is available as an ASCII file in \(doc/spec.txt)\ so | |
405 | that it can easily be searched with a text editor. Other files in the \(doc)\ | |
406 | directory are: | |
407 | .display rm | |
408 | .tabs 18 | |
409 | \(OptionLists.txt)\ $t $rm{list of all options in alphabetical order} | |
410 | \(dbm.discuss.txt)\ $t $rm{discussion about DBM libraries} | |
411 | \(exim.8)\ $t $rm{a man page of Exim's command line options} | |
d43194df PH |
412 | .newline |
413 | .em | |
414 | \(experimental.txt)\ $t $rm{documentation of experimental features} | |
415 | .nem | |
416 | .newline | |
495ae4b0 PH |
417 | \(filter.txt)\ $t $rm{specification of the filter language} |
418 | \(pcrepattern.txt)\ $t $rm{specification of PCRE regular expressions} | |
419 | \(pcretest.txt)\ $t $rm{specification of the PCRE testing program} | |
420 | \(Exim3.upgrade)\ $t $rm{upgrade notes from release 2 to release 3} | |
421 | \(Exim4.upgrade)\ $t $rm{upgrade notes from release 3 to release 4} | |
422 | .endd | |
423 | The main specification and the specification of the filtering language are also | |
424 | available in other formats (HTML, PostScript, PDF, and Texinfo). Section | |
425 | ~~SECTavail below tells you how to get hold of these. | |
426 | ||
427 | ||
d43194df | 428 | .section FTP and web sites |
495ae4b0 PH |
429 | .index web site |
430 | .index FTP site | |
d43194df PH |
431 | .em |
432 | The primary distribution site for Exim is currently the University of | |
433 | Cambridge's FTP site, whose contents are described in \*Where to find the Exim | |
434 | distribution*\ below. In addition, there is a | |
435 | .if ~~html | |
436 | [(A HREF="http://www.exim.org/")] | |
437 | .fi | |
438 | web site | |
439 | .if ~~html | |
440 | [(/A)] | |
441 | .fi | |
442 | and an | |
443 | .if ~~html | |
444 | [(A HREF="ftp://ftp.exim.org/")] | |
445 | .fi | |
446 | FTP site | |
447 | .if ~~html | |
448 | [(/A)] | |
449 | .fi | |
450 | at \exim.org\. These are now also hosted at the University of Cambridge. | |
451 | The \exim.org\ site was previously hosted for a number of years by Energis | |
452 | Squared, formerly Planet Online Ltd, whose support I gratefully acknowledge. | |
453 | ||
454 | As well as Exim distribution tar files, the Exim web site contains a number of | |
455 | differently formatted versions of the documentation, including the | |
495ae4b0 PH |
456 | .index FAQ |
457 | .if ~~html | |
458 | [(A HREF="FAQ.html")] | |
459 | .fi | |
460 | FAQ | |
461 | .if ~~html | |
462 | [(/A)] | |
463 | .fi | |
d43194df PH |
464 | in both text and HTML formats. The HTML version comes with a keyword-in-context |
465 | index. A recent addition to the online information is the | |
466 | .index wiki | |
467 | .if ~~html | |
468 | [(A HREF="http://www.exim.org/eximwiki/")] | |
469 | Exim wiki. | |
470 | [(/A)] | |
471 | .else | |
472 | Exim wiki (\?http://www.exim.org/eximwiki/?\). | |
473 | .fi | |
474 | We hope that this will make it easier for Exim users to contribute examples, | |
475 | tips, and know-how for the benefit of others. | |
476 | .nem | |
495ae4b0 | 477 | |
d43194df | 478 | .section Mailing lists |
495ae4b0 | 479 | .index mailing lists||for Exim users |
8e669ac1 PH |
480 | .em |
481 | The following are the three main Exim mailing lists: | |
495ae4b0 PH |
482 | .display rm |
483 | .tabs 28 | |
484 | $it{exim-users@@exim.org} $t general discussion list | |
8e669ac1 | 485 | $it{exim-dev@@exim.org} $t discussion of bugs, enhancements, etc. |
495ae4b0 PH |
486 | $it{exim-announce@@exim.org} $t moderated, low volume announcements list |
487 | .endd | |
8e669ac1 | 488 | .nem |
495ae4b0 PH |
489 | You can subscribe to these lists, change your existing subscriptions, and view |
490 | or search the archives via the | |
491 | .if ~~html | |
492 | [(A HREF="http://www.exim.org/maillist.html")] | |
493 | .fi | |
494 | mailing lists | |
495 | .if ~~html | |
496 | [(/A)] | |
497 | .fi | |
498 | link on the Exim home page. The $it{exim-users} mailing list is also forwarded | |
499 | to \?http://www.egroups.com/list/exim-users?\, an archiving system with | |
500 | searching capabilities. | |
501 | ||
502 | .section Exim training | |
503 | .index training courses | |
504 | From time to time (approximately annually at the time of writing), | |
505 | lecture-based training courses are run by the author of Exim in Cambridge, UK. | |
506 | Details can be found on the web site | |
507 | .if ~~html | |
508 | [(A HREF="http://www-tus.csx.cam.ac.uk/courses/exim/")] | |
509 | .fi | |
510 | \?http://www-tus@.csx@.cam@.ac.uk/courses/exim/?\. | |
511 | .if ~~html | |
512 | [(/A)] | |
513 | .fi | |
514 | ||
515 | .section Bug reports | |
516 | .index bug reports | |
517 | .index reporting bugs | |
518 | Reports of obvious bugs should be emailed to \*bugs@@exim.org*\. However, if | |
519 | you are unsure whether some behaviour is a bug or not, the best thing to do is | |
520 | to post a message to the $it{exim-users} mailing list and have it discussed. | |
521 | ||
522 | ||
d43194df | 523 | .em |
495ae4b0 PH |
524 | .section Where to find the Exim distribution |
525 | .rset SECTavail "~~chapter.~~section" | |
526 | .index FTP site | |
527 | .index distribution||ftp site | |
528 | The master ftp site for the Exim distribution is | |
529 | .display rm | |
530 | .if ! ~~sys.fancy | |
531 | .indent 0 | |
532 | .fi | |
533 | \?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim?\ | |
534 | .endd | |
d43194df | 535 | This is mirrored by |
495ae4b0 PH |
536 | .display rm |
537 | .if ! ~~sys.fancy | |
538 | .indent 0 | |
539 | .fi | |
d43194df | 540 | \?ftp://ftp.exim.org/pub/exim?\ |
495ae4b0 | 541 | .endd |
d43194df PH |
542 | The file references that follow are relative to the \(exim)\ directories at |
543 | these sites. | |
544 | ||
545 | There are now quite a number of independent mirror sites around the world. | |
546 | Those that I know about are listed in the file called \(Mirrors)\. | |
547 | ||
548 | Within the \(exim)\ directory there are subdirectories called \(exim3)\ (for | |
549 | previous Exim 3 distributions), \(exim4)\ (for the latest Exim 4 | |
550 | distributions), and \(Testing)\ for testing versions. In the \(exim4)\ | |
551 | subdirectory, the current release can always be found in files called | |
495ae4b0 PH |
552 | .display rm |
553 | \(exim-$it{n.nn}.tar.gz)\ | |
554 | \(exim-$it{n.nn}.tar.bz2)\ | |
555 | .endd | |
556 | where $it{n.nn} is the highest such version number in the directory. The two | |
557 | files contain identical data; the only difference is the type of compression. | |
558 | The \(.bz2)\ file is usually a lot smaller than the \(.gz)\ file. | |
559 | .index distribution||signing details | |
560 | .index distribution||public key | |
561 | .index public key for signed distribution | |
d43194df PH |
562 | The distributions are currently signed with Philip Hazel's GPG key. The |
563 | corresponding public key is available from a number of keyservers, and there is | |
564 | also a copy in the file \(Public-Key)\. The signatures for the tar bundles are | |
565 | in: | |
495ae4b0 PH |
566 | .display rm |
567 | \(exim-$it{n.nn}.tar.gz.sig)\ | |
568 | \(exim-$it{n.nn}.tar.bz2.sig)\ | |
569 | .endd | |
d43194df PH |
570 | For each released version, the log of changes is made separately available in a |
571 | separate file in the directory \(ChangeLogs)\ so that it is possible to | |
572 | find out what has changed without having to download the entire distribution. | |
495ae4b0 PH |
573 | |
574 | .index documentation||available formats | |
575 | The main distribution contains ASCII versions of this specification and other | |
576 | documentation; other formats of the documents are available in separate files | |
577 | inside the \(exim4)\ directory of the FTP site: | |
578 | .display rm | |
579 | \(exim-html-$it{n.nn}.tar.gz)\ | |
580 | \(exim-pdf-$it{n.nn}.tar.gz)\ | |
581 | \(exim-postscript-$it{n.nn}.tar.gz)\ | |
582 | \(exim-texinfo-$it{n.nn}.tar.gz)\ | |
583 | .endd | |
584 | These tar files contain only the \(doc)\ directory, not the complete | |
585 | distribution, and are also available in \(.bz2)\ as well as \(.gz)\ forms. | |
586 | ||
587 | .index FAQ | |
d43194df | 588 | The FAQ is available for downloading in two different formats in these files: |
495ae4b0 | 589 | .display rm |
d43194df PH |
590 | \(exim4/FAQ.txt.gz)\ |
591 | \(exim4/FAQ.html.tar.gz)\ | |
495ae4b0 PH |
592 | .endd |
593 | The first of these is a single ASCII file that can be searched with a text | |
594 | editor. The second is a directory of HTML files, normally accessed by starting | |
595 | at \(index.html)\. The HTML version of the FAQ (which is also included in the | |
596 | HTML documentation tarbundle) includes a keyword-in-context index, which is | |
597 | often the most convenient way of finding your way around. | |
598 | ||
599 | .section Wish list | |
600 | .index wish list | |
601 | A wish list is maintained, containing ideas for new features that have been | |
d43194df PH |
602 | submitted. From time to time the file is exported to the ftp site into the file |
603 | \(exim4/WishList)\. Items are removed from the list if they get implemented. | |
495ae4b0 PH |
604 | |
605 | ||
606 | .section Contributed material | |
607 | .index contributed material | |
d43194df PH |
608 | At the ftp site, there is a directory called \(Contrib)\ that contains |
609 | miscellaneous files contributed to the Exim community by Exim users. There is | |
610 | also a collection of contributed configuration examples in | |
611 | \(exim4/config.samples.tar.gz)\. These samples are referenced from the FAQ. | |
612 | .nem | |
495ae4b0 PH |
613 | |
614 | .section Limitations | |
615 | .index limitations of Exim | |
616 | .numberpars $. | |
617 | Exim is designed for use as an Internet MTA, and therefore handles addresses | |
618 | in RFC 2822 domain format only. | |
619 | .index bang paths||not handled by Exim | |
620 | It cannot handle UUCP `bang paths', though simple two-component bang paths can | |
621 | be converted by a straightforward rewriting configuration. This restriction | |
622 | does not prevent Exim from being interfaced to UUCP as a transport mechanism, | |
623 | provided that domain addresses are used. | |
624 | .nextp | |
625 | .index domainless addresses | |
626 | .index address||without domain | |
627 | Exim insists that every address it handles has a domain attached. For incoming | |
628 | local messages, domainless addresses are automatically qualified with a | |
629 | configured domain value. Configuration options specify from which remote | |
630 | systems unqualified addresses are acceptable. These are then qualified on | |
631 | arrival. | |
632 | .nextp | |
633 | .index transport||external | |
634 | .index external transports | |
635 | The only external transport currently implemented is an SMTP transport over a | |
636 | TCP/IP network (using sockets, including support for IPv6). However, a pipe | |
637 | transport is available, and there are facilities for writing messages to files | |
638 | and pipes, optionally in \*batched SMTP*\ format; these facilities can be used | |
639 | to send messages to some other transport mechanism such as UUCP, provided it | |
640 | can handle domain-style addresses. Batched SMTP input is also catered for. | |
641 | .nextp | |
642 | Exim is not designed for storing mail for dial-in hosts. When the volumes of | |
643 | such mail are large, it is better to get the messages `delivered' into files | |
644 | (that is, off Exim's queue) and subsequently passed on to the dial-in hosts by | |
645 | other means. | |
646 | .nextp | |
d43194df PH |
647 | .em |
648 | Although Exim does have basic facilities for scanning incoming messages, these | |
4964e932 | 649 | are not comprehensive enough to do full virus or spam scanning. Such operations |
d43194df PH |
650 | are best carried out using additional specialized software packages. If you |
651 | compile Exim with the content-scanning extension, straightforward interfaces to | |
652 | a number of common scanners are provided. | |
653 | .nem | |
495ae4b0 PH |
654 | .endp |
655 | ||
656 | ||
657 | ||
658 | .section Run time configuration | |
659 | Exim's run time configuration is held in a single text file that is divided | |
660 | into a number of sections. The entries in this file consist of keywords and | |
661 | values, in the style of Smail 3 configuration files. A default configuration | |
662 | file which is suitable for simple online installations is provided in the | |
663 | distribution, and is described in chapter ~~CHAPdefconfil below. | |
664 | ||
665 | ||
666 | .section Calling interface | |
667 | .index Sendmail compatibility||command line interface | |
668 | Like many MTAs, Exim has adopted the Sendmail command line interface so that it | |
669 | can be a straight replacement for \(/usr/lib/sendmail)\ or | |
670 | \(/usr/sbin/sendmail)\ when sending mail, but you do not need to know anything | |
671 | about Sendmail in order to run Exim. For actions other than sending messages, | |
672 | Sendmail-compatible options also exist, but those that produce output (for | |
673 | example, \-bp-\, which lists the messages on the queue) do so in Exim's own | |
674 | format. There are also some additional options that are compatible with Smail | |
675 | 3, and some further options that are new to Exim. Chapter ~~CHAPcommandline | |
676 | documents all Exim's command line options. This information is automatically | |
677 | made into the man page that forms part of the Exim distribution. | |
678 | ||
679 | Control of messages on the queue can be done via certain privileged command | |
680 | line options. There is also an optional monitor program called \*eximon*\, which | |
681 | displays current information in an X window, and which contains a menu | |
682 | interface to Exim's command line administration options. | |
683 | ||
684 | ||
685 | .section Terminology | |
686 | .index terminology definitions | |
687 | .index body of message||definition of | |
688 | The \*body*\ of a message is the actual data that the sender wants to transmit. | |
689 | It is the last part of a message, and is separated from the \*header*\ (see | |
690 | below) by a blank line. | |
691 | ||
692 | .index bounce message||definition of | |
693 | When a message cannot be delivered, it is normally returned to the sender in a | |
d43194df PH |
694 | delivery failure message or a `non-delivery report' (NDR). The term \*bounce*\ |
695 | is commonly used for this action, and the error reports are often called | |
696 | \*bounce messages*\. This is a convenient shorthand for `delivery failure error | |
697 | report'. Such messages have an empty sender address in the message's | |
698 | \*envelope*\ (see below) to ensure that they cannot themselves give rise to | |
699 | further bounce messages. | |
495ae4b0 PH |
700 | |
701 | The term \*default*\ appears frequently in this manual. It is used to qualify a | |
702 | value which is used in the absence of any setting in the configuration. It may | |
703 | also qualify an action which is taken unless a configuration setting specifies | |
704 | otherwise. | |
705 | ||
706 | The term \*defer*\ is used when the delivery of a message to a specific | |
707 | destination cannot immediately take place for some reason (a remote host may be | |
708 | down, or a user's local mailbox may be full). Such deliveries are \*deferred*\ | |
709 | until a later time. | |
710 | ||
711 | The word \*domain*\ is sometimes used to mean all but the first component of a | |
712 | host's name. It is $it{not} used in that sense here, where it normally | |
713 | refers to the part of an email address following the @@ sign. | |
714 | ||
715 | .index envelope, definition of | |
716 | .index sender||definition of | |
717 | A message in transit has an associated \*envelope*\, as well as a header and a | |
718 | body. The envelope contains a sender address (to which bounce messages should | |
719 | be delivered), and any number of recipient addresses. References to the | |
720 | sender or the recipients of a message usually mean the addresses in the | |
721 | envelope. An MTA uses these addresses for delivery, and for returning bounce | |
722 | messages, not the addresses that appear in the header lines. | |
723 | ||
724 | .index message||header, definition of | |
725 | .index header section||definition of | |
726 | The \*header*\ of a message is the first part of a message's text, consisting | |
727 | of a number of lines, each of which has a name such as ::From::, ::To::, | |
728 | ::Subject::, etc. Long header lines can be split over several text lines by | |
729 | indenting the continuations. The header is separated from the body by a blank | |
730 | line. | |
731 | ||
732 | .index local part||definition of | |
733 | .index domain||definition of | |
734 | The term \*local part*\, which is taken from RFC 2822, is used to refer to that | |
735 | part of an email address that precedes the @@ sign. The part that follows the | |
736 | @@ sign is called the \*domain*\ or \*mail domain*\. | |
737 | ||
738 | .index local delivery||definition of | |
739 | .index remote delivery, definition of | |
740 | The terms \*local delivery*\ and \*remote delivery*\ are used to distinguish | |
741 | delivery to a file or a pipe on the local host from delivery by SMTP over | |
742 | TCP/IP to a remote host. | |
743 | ||
744 | .index return path||definition of | |
745 | \*Return path*\ is another name that is used for the sender address in a | |
746 | message's envelope. | |
747 | ||
748 | .index queue||definition of | |
749 | The term \*queue*\ is used to refer to the set of messages awaiting delivery, | |
750 | because this term is in widespread use in the context of MTAs. However, in | |
751 | Exim's case the reality is more like a pool than a queue, because there is | |
752 | normally no ordering of waiting messages. | |
753 | ||
754 | .index queue runner||definition of | |
755 | The term \*queue runner*\ is used to describe a process that scans the queue | |
756 | and attempts to deliver those messages whose retry times have come. This term | |
757 | is used by other MTAs, and also relates to the command \runq\, but in Exim | |
758 | the waiting messages are normally processed in an unpredictable order. | |
759 | ||
760 | .index spool directory||definition of | |
761 | The term \*spool directory*\ is used for a directory in which Exim keeps the | |
762 | messages on its queue -- that is, those that it is in the process of | |
763 | delivering. This should not be confused with the directory in which local | |
764 | mailboxes are stored, which is called a `spool directory' by some people. In | |
765 | the Exim documentation, `spool' is always used in the first sense. | |
766 | ||
767 | ||
768 | ||
769 | . | |
770 | . | |
771 | . | |
772 | . | |
773 | . ============================================================================ | |
774 | .chapter Incorporated code | |
775 | .set runningfoot "incorporated code" | |
776 | .index incorporated code | |
777 | .index regular expressions||library | |
778 | .index PCRE | |
779 | A number of pieces of external code are included in the Exim distribution. | |
780 | .numberpars $. | |
781 | Regular expressions are supported in the main Exim program and in the Exim | |
d43194df PH |
782 | monitor using the freely-distributable PCRE library, copyright (c) University |
783 | of Cambridge. The source is distributed in the directory \(src/pcre)\. However, | |
784 | this is a cut-down version of PCRE. If you want to use the PCRE library in | |
785 | other programs, you should obtain and install the full version from | |
786 | \?ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre?\. | |
495ae4b0 PH |
787 | |
788 | .space 1ld | |
789 | .nextp | |
790 | .index cdb||acknowledgement | |
791 | Support for the cdb (Constant DataBase) lookup method is provided by code | |
d43194df PH |
792 | contributed by Nigel Metheringham of (at the time he contributed it) Planet |
793 | Online Ltd. which contains the following statements: | |
495ae4b0 PH |
794 | .rule |
795 | .push | |
796 | .if ~~sgcal | |
797 | .fontgroup 9 | |
798 | .font 0 | |
799 | .fi | |
800 | Copyright (c) 1998 Nigel Metheringham, Planet Online Ltd | |
801 | ||
802 | This program is free software; you can redistribute it and/or modify it under | |
803 | the terms of the GNU General Public License as published by the Free Software | |
804 | Foundation; either version 2 of the License, or (at your option) any later | |
805 | version. | |
806 | ||
807 | This code implements Dan Bernstein's Constant DataBase (cdb) spec. Information, | |
808 | the spec and sample code for cdb can be obtained from | |
809 | \?http://www.pobox.com/@~djb/cdb.html?\. This implementation borrows some code | |
810 | from Dan Bernstein's implementation (which has no license restrictions applied | |
811 | to it). | |
812 | .newline | |
813 | .pop | |
814 | .rule | |
815 | The implementation is completely contained within the code of Exim. | |
816 | It does not link against an external cdb library. | |
817 | .space 1ld | |
818 | .nextp | |
819 | .index SPA authentication | |
820 | .index Samba project | |
821 | .index Microsoft Secure Password Authentication | |
822 | Client support for Microsoft's \*Secure Password Authentication*\ is provided | |
4964e932 | 823 | by code contributed by Marc Prud'hommeaux. Server support was contributed by |
495ae4b0 PH |
824 | Tom Kistner. This includes code taken from the Samba project, which is released |
825 | under the Gnu GPL. | |
826 | ||
827 | .space 1ld | |
828 | .nextp | |
829 | .index Cyrus | |
830 | .index \*pwcheck*\ daemon | |
831 | .index \*pwauthd*\ daemon | |
832 | Support for calling the Cyrus \*pwcheck*\ and \*saslauthd*\ daemons is provided | |
833 | by code taken from the Cyrus-SASL library and adapted by Alexander S. | |
834 | Sabourenkov. The permission notice appears below, in accordance with the | |
835 | conditions expressed therein. | |
836 | ||
837 | .rule | |
838 | .push | |
839 | .if ~~sgcal | |
840 | .fontgroup 9 | |
841 | .font 0 | |
842 | .fi | |
843 | Copyright (c) 2001 Carnegie Mellon University. All rights reserved. | |
844 | ||
845 | Redistribution and use in source and binary forms, with or without | |
846 | modification, are permitted provided that the following conditions | |
847 | are met: | |
848 | ||
849 | .if ~~sgcal | |
850 | .cancelflag $npbracket | |
851 | .flag $npbracket "" "." | |
852 | .fi | |
853 | .numberpars | |
854 | Redistributions of source code must retain the above copyright | |
855 | notice, this list of conditions and the following disclaimer. | |
856 | .nextp | |
857 | Redistributions in binary form must reproduce the above copyright | |
858 | notice, this list of conditions and the following disclaimer in | |
859 | the documentation and/or other materials provided with the | |
860 | distribution. | |
861 | .nextp | |
862 | The name `Carnegie Mellon University' must not be used to | |
863 | endorse or promote products derived from this software without | |
864 | prior written permission. For permission or any other legal | |
865 | details, please contact | |
866 | .display rm | |
867 | Office of Technology Transfer | |
868 | Carnegie Mellon University | |
869 | 5000 Forbes Avenue | |
870 | Pittsburgh, PA 15213-3890 | |
871 | (412) 268-4387, fax: (412) 268-7395 | |
872 | tech-transfer@@andrew.cmu.edu | |
873 | .endd | |
874 | .nextp | |
875 | Redistributions of any form whatsoever must retain the following | |
876 | acknowledgment: | |
877 | .newline | |
878 | .push | |
879 | .indent ~~sys.indent + 3em | |
880 | .justify left | |
881 | $it{This product includes software developed by Computing Services | |
882 | at Carnegie Mellon University (\?http://www.cmu.edu/computing/?\).} | |
883 | .newline | |
884 | .pop | |
4964e932 | 885 | .endp |
495ae4b0 PH |
886 | .if ~~sgcal |
887 | .cancelflag $npbracket | |
888 | .flag $npbracket "(" ")" | |
889 | .fi | |
890 | ||
891 | CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO | |
892 | THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY | |
893 | AND FITNESS, IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY BE LIABLE | |
894 | FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | |
895 | WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN | |
896 | AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING | |
897 | OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | |
898 | .newline | |
899 | .pop | |
900 | .rule | |
901 | ||
902 | .space 1ld | |
903 | .nextp | |
904 | .index monitor | |
905 | .index X-windows | |
906 | .index Athena | |
907 | The Exim Monitor program, which is an X-Window application, includes | |
908 | modified versions of the Athena StripChart and TextPop widgets. | |
909 | This code is copyright by DEC and MIT, and their permission notice appears | |
910 | below, in accordance with the conditions expressed therein. | |
911 | ||
912 | .rule | |
913 | .push | |
914 | .if ~~sgcal | |
915 | .fontgroup 9 | |
916 | .font 0 | |
917 | .fi | |
918 | Copyright 1987, 1988 by Digital Equipment Corporation, Maynard, Massachusetts, | |
919 | and the Massachusetts Institute of Technology, Cambridge, Massachusetts. | |
920 | .blank | |
921 | $c All Rights Reserved | |
922 | .blank | |
923 | Permission to use, copy, modify, and distribute this software and its | |
924 | documentation for any purpose and without fee is hereby granted, | |
925 | provided that the above copyright notice appear in all copies and that | |
926 | both that copyright notice and this permission notice appear in | |
927 | supporting documentation, and that the names of Digital or MIT not be | |
928 | used in advertising or publicity pertaining to distribution of the | |
929 | software without specific, written prior permission. | |
930 | ||
931 | DIGITAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING | |
932 | ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL | |
933 | DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR | |
934 | ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, | |
935 | WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, | |
936 | ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS | |
937 | SOFTWARE. | |
938 | .newline | |
939 | .pop | |
940 | .rule | |
d43194df PH |
941 | .space 1ld |
942 | .nextp | |
943 | .em | |
944 | Many people have contributed code fragments, some large, some small, that were | |
945 | not covered by any specific licence requirements. It is assumed that the | |
946 | contributors are happy to see their code incoporated into Exim under the GPL. | |
947 | .nem | |
495ae4b0 PH |
948 | .endp |
949 | ||
950 | ||
951 | ||
952 | . | |
953 | . | |
954 | . | |
955 | . | |
956 | . ============================================================================ | |
957 | .chapter How Exim receives and delivers mail | |
958 | .set runningfoot "receiving & delivering mail" | |
959 | ||
960 | .section Overall philosophy | |
961 | .index design philosophy | |
962 | Exim is designed to work efficiently on systems that are permanently connected | |
963 | to the Internet and are handling a general mix of mail. In such circumstances, | |
964 | most messages can be delivered immediately. Consequently, Exim does not | |
965 | maintain independent queues of messages for specific domains or hosts, though | |
966 | it does try to send several messages in a single SMTP connection after a host | |
967 | has been down, and it also maintains per-host retry information. | |
968 | ||
969 | ||
970 | .section Policy control | |
971 | .index policy control||overview | |
972 | Policy controls are now an important feature of MTAs that are connected to the | |
973 | Internet. Perhaps their most important job is to stop MTAs being abused as | |
974 | `open relays' by misguided individuals who send out vast amounts of unsolicited | |
975 | junk, and want to disguise its source. Exim provides flexible facilities for | |
976 | specifying policy controls on incoming mail: | |
977 | .numberpars $. | |
978 | .index ~~ACL||introduction | |
979 | Exim 4 (unlike previous versions of Exim) implements policy controls on | |
d43194df | 980 | incoming mail by means of \*Access Control Lists*\ (ACLs). Each list is a |
495ae4b0 | 981 | series of statements that may either grant or deny access. ACLs can be used at |
d43194df PH |
982 | several places in the SMTP dialogue while receiving a message from a remote |
983 | host. However, the most common places are after each \\RCPT\\ command, and at | |
984 | the very end of the message. The sysadmin can specify conditions for accepting | |
985 | or rejecting individual recipients or the entire message, respectively, at | |
986 | these two points (see chapter ~~CHAPACL). Denial of access results in an SMTP | |
987 | error code. | |
495ae4b0 | 988 | .nextp |
4964e932 | 989 | An ACL is also available for locally generated, non-SMTP messages. In this |
495ae4b0 PH |
990 | case, the only available actions are to accept or deny the entire message. |
991 | .nextp | |
d43194df PH |
992 | .em |
993 | When Exim is compiled with the content-scanning extension, facilities are | |
994 | provided in the ACL mechanism for passing the message to external virus and/or | |
995 | spam scanning software. The result of such a scan is passed back to the ACL, | |
996 | which can then use it to decide what to do with the message. | |
997 | .nem | |
998 | .nextp | |
495ae4b0 PH |
999 | When a message has been received, either from a remote host or from the local |
1000 | host, but before the final acknowledgement has been sent, a locally supplied C | |
1001 | function called \*local@_scan()*\ can be run to inspect the message and decide | |
1002 | whether to accept it or not (see chapter ~~CHAPlocalscan). If the message is | |
1003 | accepted, the list of recipients can be modified by the function. | |
1004 | .nextp | |
d43194df PH |
1005 | .em |
1006 | Using the \*local@_scan()*\ mechanism is another way of calling external | |
1007 | scanner software. The \SA-Exim\ add-on package works this way. It does not | |
1008 | require Exim to be compiled with the content-scanning extension. | |
1009 | .nem | |
1010 | .nextp | |
495ae4b0 PH |
1011 | After a message has been accepted, a further checking mechanism is available in |
1012 | the form of the $it{system filter} (see chapter ~~CHAPsystemfilter). This runs | |
1013 | at the start of every delivery process. | |
1014 | .endp | |
1015 | ||
1016 | .section User filters | |
1017 | .index filter||introduction | |
1018 | .index Sieve filter | |
4964e932 PH |
1019 | In a conventional Exim configuration, users are able to run private filters by |
1020 | setting up appropriate \(.forward)\ files in their home directories. See | |
1021 | chapter ~~CHAPredirect (about the \%redirect%\ router) for the configuration | |
1022 | needed to support this, and the separate document entitled | |
495ae4b0 PH |
1023 | .if ~~html |
1024 | [(A HREF="filter_toc.html")] | |
1025 | .fi | |
1026 | \*Exim's interfaces to mail filtering*\ | |
1027 | .if ~~html | |
1028 | [(/A)] | |
1029 | .fi | |
1030 | for user details. Two different kinds of filtering are available: | |
1031 | .numberpars $. | |
4964e932 | 1032 | Sieve filters are written in the standard filtering language that is defined by |
495ae4b0 PH |
1033 | RFC 3028. |
1034 | .nextp | |
4964e932 | 1035 | Exim filters are written in a syntax that is unique to Exim, but which is more |
495ae4b0 PH |
1036 | powerful than Sieve, which it pre-dates. |
1037 | .endp | |
1038 | User filters are run as part of the routing process, described below. | |
1039 | ||
1040 | ||
1041 | .section Message identification | |
1042 | .rset SECTmessiden "~~chapter.~~section" | |
1043 | .index message||ids, details of format | |
1044 | .index format||of message id | |
1045 | .index id of message | |
1046 | .index base62 | |
1047 | .index base36 | |
1048 | .index Darwin | |
1049 | .index Cygwin | |
1050 | Every message handled by Exim is given a \*message id*\ which is sixteen | |
1051 | characters long. It is divided into three parts, separated by hyphens, for | |
1052 | example \"16VDhn-0001bo-D3"\. Each part is a sequence of letters and digits, | |
1053 | normally encoding numbers in base 62. However, in the Darwin operating | |
4964e932 PH |
1054 | system (Mac OS X) and when Exim is compiled to run under Cygwin, base 36 |
1055 | (avoiding the use of lower case letters) is used instead, because the message | |
495ae4b0 PH |
1056 | id is used to construct file names, and the names of files in those systems are |
1057 | not case-sensitive. | |
1058 | ||
1059 | .index pid (process id)||re-use of | |
1060 | The detail of the contents of the message id have changed as Exim has evolved. | |
1061 | Earlier versions relied on the operating system not re-using a process id (pid) | |
1062 | within one second. On modern operating systems, this assumption can no longer | |
4964e932 PH |
1063 | be made, so the algorithm had to be changed. To retain backward compatibility, |
1064 | the format of the message id was retained, which is why the following rules are | |
495ae4b0 PH |
1065 | somewhat eccentric: |
1066 | .numberpars $. | |
1067 | The first six characters of the message id are the time at which the message | |
1068 | started to be received, to a granularity of one second. That is, this field | |
1069 | contains the number of seconds since the start of the epoch (the normal Unix | |
1070 | way of representing the date and time of day). | |
1071 | .nextp | |
1072 | After the first hyphen, the next six characters are the id of the process that | |
1073 | received the message. | |
1074 | .nextp | |
1075 | There are two different possibilities for the final two characters: | |
1076 | .numberpars alpha | |
1077 | .index \localhost@_number\ | |
1078 | If \localhost@_number\ is not set, this value is the fractional part of the | |
1079 | time of reception, normally in units of 1/2000 of a second, but for systems | |
1080 | that must use base 36 instead of base 62 (because of case-insensitive file | |
1081 | systems), the units are 1/1000 of a second. | |
1082 | .nextp | |
1083 | If \localhost@_number\ is set, it is multiplied by 200 (100) and added to | |
1084 | the fractional part of the time, which in this case is in units of 1/200 | |
1085 | (1/100) of a second. | |
1086 | .endp | |
1087 | .endp | |
1088 | After a message has been received, Exim waits for the clock to tick at the | |
1089 | appropriate resolution before proceeding, so that if another message is | |
1090 | received by the same process, or by another process with the same (re-used) | |
1091 | pid, it is guaranteed that the time will be different. In most cases, the clock | |
1092 | will already have ticked while the message was being received. | |
1093 | ||
1094 | .section Receiving mail | |
1095 | .index receiving mail | |
1096 | .index message||reception | |
1097 | The only way Exim can receive mail from a remote host is using SMTP over | |
1098 | TCP/IP, in which case the sender and recipient addresses are tranferred using | |
1099 | SMTP commands. However, from a locally running process (such as a user's MUA), | |
1100 | there are several possibilities: | |
1101 | .numberpars $. | |
1102 | If the process runs Exim with the \-bm-\ option, the message is read | |
1103 | non-interactively (usually via a pipe), with the recipients taken from the | |
1104 | command line, or from the body of the message if \-t-\ is also used. | |
1105 | .nextp | |
1106 | If the process runs Exim with the \-bS-\ option, the message is also read | |
1107 | non-interactively, but in this case the recipients are listed at the start of | |
1108 | the message in a series of SMTP \\RCPT\\ commands, terminated by a \\DATA\\ | |
1109 | command. This is so-called `batch SMTP' format, | |
1110 | but it isn't really SMTP. The SMTP commands are just another way of passing | |
1111 | envelope addresses in a non-interactive submission. | |
1112 | .nextp | |
1113 | If the process runs Exim with the \-bs-\ option, the message is read | |
1114 | interactively, using the SMTP protocol. A two-way pipe is normally used for | |
1115 | passing data between the local process and the Exim process. | |
1116 | This is `real' SMTP and is handled in the same way as SMTP over TCP/IP. For | |
1117 | example, the ACLs for SMTP commands are used for this form of submission. | |
1118 | .nextp | |
1119 | A local process may also make a TCP/IP call to the host's loopback address | |
1120 | (127.0.0.1) or any other of its IP addresses. When receiving messages, Exim | |
1121 | does not treat the loopback address specially. It treats all such connections | |
1122 | in the same way as connections from other hosts. | |
1123 | .endp | |
1124 | ||
1125 | .index message||sender, constructed by Exim | |
1126 | .index sender||constructed by Exim | |
1127 | In the three cases that do not involve TCP/IP, the sender address is | |
1128 | constructed from the login name of the user that called Exim and a default | |
1129 | qualification domain (which can be set by the \qualify@_domain\ configuration | |
1130 | option). For local or batch SMTP, a sender address that is passed using the | |
1131 | SMTP \\MAIL\\ command is ignored. However, the system administrator may allow | |
1132 | certain users (`trusted users') to specify a different sender address | |
1133 | unconditionally, or all users to specify certain forms of different sender | |
1134 | address. The \-f-\ option or the SMTP \\MAIL\\ command is used to specify these | |
1135 | different addresses. See section ~~SECTtrustedadmin for details of trusted | |
1136 | users, and the \untrusted@_set@_sender\ option for a way of allowing untrusted | |
1137 | users to change sender addresses. | |
1138 | ||
4964e932 PH |
1139 | Messages received by either of the non-interactive mechanisms are subject to |
1140 | checking by the non-SMTP ACL, if one is defined. Messages received using SMTP | |
1141 | (either over TCP/IP, or interacting with a local process) can be checked by a | |
1142 | number of ACLs that operate at different times during the SMTP session. Either | |
1143 | individual recipients, or the entire message, can be rejected if local policy | |
495ae4b0 PH |
1144 | requirements are not met. The \*local@_scan()*\ function (see chapter |
1145 | ~~CHAPlocalscan) is run for all incoming messages. | |
1146 | ||
1147 | Exim can be configured not to start a delivery process when a message is | |
1148 | received; this can be unconditional, or depend on the number of incoming SMTP | |
1149 | connections or the system load. In these situations, new messages wait on the | |
1150 | queue until a queue runner process picks them up. However, in standard | |
1151 | configurations under normal conditions, delivery is started as soon as a | |
1152 | message is received. | |
1153 | ||
1154 | ||
1155 | ||
1156 | ||
1157 | .section Handling an incoming message | |
1158 | .index spool directory||files that hold a message | |
1159 | .index file||how a message is held | |
1160 | When Exim accepts a message, it writes two files in its spool directory. The | |
1161 | first contains the envelope information, the current status of the message, | |
1162 | and the header lines, and the second contains the body of the message. The | |
1163 | names of the two spool files consist of the message id, followed by $tt{-H} for | |
1164 | the file containing the envelope and header, and $tt{-D} for the data file. | |
1165 | ||
1166 | .index spool directory||\(input)\ sub-directory | |
1167 | By default all these message files are held in a single directory called | |
1168 | \(input)\ inside the general Exim spool directory. Some operating systems do | |
1169 | not perform very well if the number of files in a directory gets very large; to | |
1170 | improve performance in such cases, the \split@_spool@_directory\ option can be | |
1171 | used. This causes Exim to split up the input files into 62 sub-directories | |
1172 | whose names are single letters or digits. | |
1173 | ||
1174 | The envelope information consists of the address of the message's sender and | |
1175 | the addresses of the recipients. This information is entirely separate from | |
1176 | any addresses contained in the header lines. The status of the message includes | |
1177 | a list of recipients who have already received the message. The format of the | |
1178 | first spool file is described in chapter ~~CHAPspool. | |
1179 | ||
1180 | .index rewriting||addresses | |
1181 | Address rewriting that is specified in the rewrite section of the configuration | |
1182 | (see chapter ~~CHAPrewrite) is done once and for all on incoming addresses, | |
1183 | both in the header lines and the envelope, at the time the message is accepted. | |
1184 | If during the course of delivery additional addresses are generated (for | |
1185 | example, via aliasing), these new addresses are rewritten as soon as they are | |
1186 | generated. At the time a message is actually delivered (transported) further | |
1187 | rewriting can take place; because this is a transport option, it can be | |
1188 | different for different forms of delivery. It is also possible to specify the | |
1189 | addition or removal of certain header lines at the time the message is | |
1190 | delivered (see chapters ~~CHAProutergeneric and ~~CHAPtransportgeneric). | |
1191 | ||
1192 | ||
1193 | .section Life of a message | |
1194 | .index message||life of | |
1195 | .index message||frozen | |
1196 | A message remains in the spool directory until it is completely delivered to | |
1197 | its recipients or to an error address, or until it is deleted by an | |
1198 | administrator or by the user who originally created it. In cases when delivery | |
1199 | cannot proceed -- for example, when a message can neither be delivered to its | |
1200 | recipients nor returned to its sender, the message is marked `frozen' on the | |
1201 | spool, and no more deliveries are attempted. | |
1202 | ||
1203 | .index frozen messages||thawing | |
1204 | .index message||thawing frozen | |
1205 | An administrator can `thaw' such messages when the problem has been corrected, | |
1206 | and can also freeze individual messages by hand if necessary. In addition, an | |
1207 | administrator can force a delivery error, causing a bounce message to be sent. | |
1208 | ||
1209 | .index \auto@_thaw\ | |
1210 | There is an option called \auto@_thaw\, which can be used to cause Exim to | |
1211 | retry frozen messages after a certain time. When this is set, no message will | |
1212 | remain on the queue for ever, because the delivery timeout will eventually be | |
1213 | reached. Delivery failure reports (bounce messages) that reach this timeout are | |
1214 | discarded. | |
1215 | .index \timeout@_frozen@_after\ | |
1216 | There is also an option called \timeout@_frozen@_after\, which discards frozen | |
1217 | messages after a certain time. | |
1218 | ||
1219 | .index message||log file for | |
1220 | .index log||file for each message | |
1221 | While Exim is working on a message, it writes information about each delivery | |
1222 | attempt to the main log file. This includes successful, unsuccessful, and | |
1223 | delayed deliveries for each recipient (see chapter ~~CHAPlog). The log lines | |
1224 | are also written to a separate $it{message log} file for each message. These | |
1225 | logs are solely for the benefit of the administrator, and are normally deleted | |
1226 | along with the spool files when processing of a message is complete. | |
4964e932 | 1227 | The use of individual message logs can be disabled by setting |
495ae4b0 PH |
1228 | \no@_message@_logs\; this might give an improvement in performance on very |
1229 | busy systems. | |
1230 | ||
1231 | .index journal file | |
1232 | .index file||journal | |
1233 | All the information Exim itself needs to set up a delivery is kept in the first | |
1234 | spool file, along with the header lines. When a successful delivery occurs, the | |
1235 | address is immediately written at the end of a journal file, whose name is the | |
1236 | message id followed by $tt{-J}. At the end of a delivery run, if there are some | |
1237 | addresses left to be tried again later, the first spool file (the $tt{-H} file) | |
1238 | is updated to indicate which these are, and the journal file is then deleted. | |
1239 | Updating the spool file is done by writing a new file and renaming it, to | |
1240 | minimize the possibility of data loss. | |
1241 | ||
1242 | Should the system or the program crash after a successful delivery but before | |
1243 | the spool file has been updated, the journal is left lying around. The next | |
1244 | time Exim attempts to deliver the message, it reads the journal file and | |
1245 | updates the spool file before proceeding. This minimizes the chances of double | |
1246 | deliveries caused by crashes. | |
1247 | ||
1248 | ||
1249 | .section Processing an address for delivery | |
1250 | .rset SECTprocaddress "~~chapter.~~section" | |
1251 | .index drivers||definition of | |
1252 | .index router||definition of | |
1253 | .index transport||definition of | |
1254 | The main delivery processing elements of Exim are called $it{routers} and | |
1255 | $it{transports}, and collectively these are known as $it{drivers}. Code for a | |
1256 | number of them is provided in the source distribution, and compile-time options | |
1257 | specify which ones are included in the binary. Run time options specify which | |
1258 | ones are actually used for delivering messages. | |
1259 | ||
1260 | .index drivers||instance definition | |
4964e932 PH |
1261 | Each driver that is specified in the run time configuration is an \*instance*\ |
1262 | of that particular driver type. Multiple instances are allowed; for example, | |
1263 | you can set up several different \%smtp%\ transports, each with different | |
495ae4b0 PH |
1264 | option values that might specify different ports or different timeouts. Each |
1265 | instance has its own identifying name. In what follows we will normally use the | |
4964e932 | 1266 | instance name when discussing one particular instance (that is, one specific |
495ae4b0 PH |
1267 | configuration of the driver), and the generic driver name when discussing |
1268 | the driver's features in general. | |
1269 | ||
1270 | A $it{router} is a driver that operates on an address, either determining how | |
1271 | its delivery should happen, by routing it to a specific transport, or | |
1272 | converting the address into one or more new addresses (for example, via an | |
1273 | alias file). A router may also explicitly choose to fail an address, causing it | |
1274 | to be bounced. | |
1275 | ||
1276 | A $it{transport} is a driver that transmits a copy of the message from Exim's | |
1277 | spool to some destination. There are two kinds of transport: for a $it{local} | |
1278 | transport, the destination is a file or a pipe on the local host, whereas for a | |
1279 | $it{remote} transport the destination is some other host. A message is passed | |
1280 | to a specific transport as a result of successful routing. If a message has | |
1281 | several recipients, it may be passed to a number of different transports. | |
1282 | ||
1283 | .index preconditions||definition of | |
1284 | An address is processed by passing it to each configured router instance in | |
1285 | turn, subject to certain preconditions, until a router accepts the address or | |
1286 | specifies that it should be bounced. We will describe this process in more | |
1287 | detail shortly. As a simple example, the diagram below illustrates how each | |
1288 | recipient address in a message is processed in a small configuration of three | |
1289 | routers that are configured in various ways. | |
1290 | ||
1291 | .if ~~sys.fancy | |
1292 | .figure "Routing an address" rm | |
1293 | .indent 0 | |
4964e932 | 1294 | .call aspic -sgcal -nv |
495ae4b0 PH |
1295 | centre ~~sys.linelength; |
1296 | magnify 0.8; | |
1297 | boundingbox 30; | |
1298 | ibox depth 14 "address"; | |
1299 | B: arrow down 44; | |
1300 | textdepth 14; | |
1301 | A: box width 100 "first router" "conditions ok?"; | |
1302 | arrow right "yes"; | |
1303 | C: box width 100 "run" "first router"; | |
1304 | arrow down "fail"; | |
1305 | D: ibox depth 20 "address bounces"; | |
1306 | ||
1307 | arc clockwise from right of C "accept"; | |
1308 | arrow down 10; | |
1309 | ibox "queue for" "transport"; | |
1310 | ||
1311 | arrow down from A align bottom of D plus (0,-20) "no"(-6,20)/r; | |
1312 | E: box width 100 "second router" "conditions ok?"; | |
1313 | arrow right "yes"; | |
1314 | F: box width 100 "run" "second router"; | |
1315 | line right 100 "redirect"; | |
1316 | line up align middle of B; | |
1317 | arrow left to middle of B "new addresses"; | |
1318 | ||
1319 | line down 20 from bottom left of F plus (30,0); | |
1320 | arrow left align centre of E "decline"; | |
1321 | ||
1322 | line down 20 from bottom right of F plus (-30,0); | |
1323 | arrow right "fail"; | |
1324 | ibox width 64 "address" "bounces"; | |
1325 | ||
1326 | arrow down 64 from E "no"(-6,20)/r; | |
1327 | G: box width 100 "third router" "conditions ok?"; | |
1328 | arrow right "yes"; | |
1329 | H: box width 100 "run" "third router"; | |
1330 | arc clockwise from right of H "accept"; | |
1331 | arrow down 10; | |
1332 | ibox "queue for" "transport"; | |
1333 | ||
1334 | line down 20 from bottom of H; | |
1335 | arrow left align centre of G "decline"; | |
1336 | arrow down 64 from G "no"(-6,20)/r; | |
1337 | ||
1338 | ibox "no more routers" "address bounces"; | |
1339 | .endcall | |
1340 | .endfigure | |
1341 | .elif !~~html | |
1342 | .display asis | |
1343 | ||
1344 | address | |
1345 | | | |
1346 | |<------------- new addresses ----------------------------- | |
1347 | V | | |
1348 | ----------------- ----------------- | | |
1349 | | first router |----- yes ----->| run |--- accept | | |
1350 | | conditions ok?| | first router | | | | |
1351 | ----------------- ----------------- | | | |
1352 | | | V | | |
1353 | no | fail | queue for | | |
1354 | | V transport | | |
1355 | | address bounces | | |
1356 | | | | |
1357 | V | | |
1358 | ----------------- ----------------- | | |
1359 | | second router |----- yes ----->| run |----redirect ---- | |
1360 | | conditions ok?| | second router | | |
1361 | ----------------- ----------------- | |
1362 | | | | | |
1363 | no | | | | |
1364 | |<-------- decline ----------- --- fail ---> address | |
1365 | | bounces | |
1366 | V | |
1367 | ----------------- ----------------- | |
1368 | | third router |----- yes ----->| run |--- accept | |
1369 | | conditions ok?| | third router | | | |
1370 | ----------------- ----------------- | | |
1371 | | | V | |
1372 | no | | queue for | |
1373 | |<-------- decline --------------- transport | |
1374 | | | |
1375 | V | |
1376 | no more routers | |
1377 | address bounces | |
1378 | .endd | |
1379 | .else | |
1380 | [(img src="routing.gif" alt="Routing an address")][(br)] | |
1381 | .fi | |
1382 | To make this a more concrete example, we'll describe it in terms of some actual | |
1383 | routers, but remember, this is only an example. You can configure Exim's | |
1384 | routers in many different ways, and there may be any number of routers in a | |
1385 | configuration. | |
1386 | ||
1387 | The first router that is specified in a configuration is often one that handles | |
1388 | addresses in domains that are not recognized specially by the local host. These | |
1389 | are typically addresses for arbitrary domains on the Internet. A precondition | |
1390 | is set up which looks for the special domains known to the host (for example, | |
1391 | its own domain name), and the router is run for addresses that do $it{not} | |
1392 | match. Typically, this is a router that looks up domains in the DNS in order to | |
1393 | find the hosts to which this address routes. If it succeeds, the address is | |
1394 | queued for a suitable SMTP transport; if it does not succeed, the router is | |
1395 | configured to fail the address. | |
1396 | ||
1397 | The example pictured could be a configuration of this type. The second and | |
1398 | third routers can only be run for addresses for which the preconditions for | |
1399 | the first router are not met. If one of these preconditions checks the | |
1400 | domain, the second and third routers are run only for domains that are somehow | |
1401 | special to the local host. | |
1402 | ||
1403 | The second router does redirection -- also known as aliasing and forwarding. | |
1404 | When it generates one or more new addresses from the original, each of them is | |
1405 | routed independently from the start. Otherwise, the router may cause an address | |
4964e932 | 1406 | to fail, or it may simply decline to handle the address, in which case the |
495ae4b0 PH |
1407 | address is passed to the next router. |
1408 | ||
1409 | The final router in many configurations is one that checks to see if the | |
1410 | address belongs to a local mailbox. The precondition may involve a check to | |
1411 | see if the local part is the name of a login account, or it may look up the | |
1412 | local part in a file or a database. If its preconditions are not met, or if | |
1413 | the router declines, we have reached the end of the routers. When this happens, | |
1414 | the address is bounced. | |
1415 | ||
1416 | ||
1417 | .section Processing an address for verification | |
1418 | .index router||for verification | |
1419 | .index verifying||address, overview | |
4964e932 PH |
1420 | As well as being used to decide how to deliver to an address, Exim's routers |
1421 | are also used for \*address verification*\. Verification can be requested as | |
1422 | one of the checks to be performed in an ACL for incoming messages, on both | |
1423 | sender and recipient addresses, and it can be tested using the \-bv-\ and | |
495ae4b0 PH |
1424 | \-bvs-\ command line options. |
1425 | ||
4964e932 PH |
1426 | When an address is being verified, the routers are run in `verify mode'. This |
1427 | does not affect the way the routers work, but it is a state that can be | |
495ae4b0 PH |
1428 | detected. By this means, a router can be skipped or made to behave differently |
1429 | when verifying. A common example is a configuration in which the first router | |
1430 | sends all messages to a message-scanning program, unless they have been | |
1431 | previously scanned. Thus, the first router accepts all addresses without any | |
4964e932 | 1432 | checking, making it useless for verifying. Normally, the \no@_verify\ option |
495ae4b0 PH |
1433 | would be set for such a router, causing it to be skipped in verify mode. |
1434 | ||
1435 | ||
1436 | ||
1437 | .section Running an individual router | |
1438 | .rset SECTrunindrou "~~chapter.~~section" | |
1439 | .index router||running details | |
1440 | .index preconditions||checking | |
1441 | .index router||result of running | |
1442 | As explained in the example above, a number of preconditions are checked before | |
1443 | running a router. If any are not met, the router is skipped, and the address is | |
1444 | passed to the next router. When all the preconditions on a router $it{are} met, | |
1445 | the router is run. What happens next depends on the outcome, which is one of | |
1446 | the following: | |
1447 | .numberpars $. | |
1448 | \*accept*\: The router accepts the address, and either queues it for a | |
1449 | transport, or generates one or more `child' addresses. Processing the original | |
4964e932 | 1450 | address ceases, |
495ae4b0 PH |
1451 | .index \unseen\ option |
1452 | unless the \unseen\ option is set on the router. This option | |
1453 | can be used to set up multiple deliveries with different routing (for example, | |
1454 | for keeping archive copies of messages). When \unseen\ is set, the address is | |
1455 | passed to the next router. Normally, however, an \*accept*\ return marks the | |
1456 | end of routing. | |
1457 | ||
1458 | .index case of local parts | |
1459 | .index address||duplicate, discarding | |
1460 | If child addresses are generated, Exim checks to see whether they are | |
1461 | duplicates of any existing recipient addresses. During this check, local parts | |
1462 | are treated as case-sensitive. Duplicate addresses are discarded. Each of the | |
1463 | remaining child addresses is then processed independently, starting with the | |
1464 | first router by default. It is possible to change this by setting the | |
1465 | \redirect@_router\ option to specify which router to start at for child | |
1466 | addresses. Unlike \pass@_router\ (see below) the router specified by | |
1467 | \redirect@_router\ may be anywhere in the router configuration. | |
1468 | .nextp | |
1469 | \*pass*\: The router recognizes the address, but cannot handle it itself. It | |
1470 | requests that the address be passed to another router. By default the address | |
1471 | is passed to the next router, but this can be changed by setting the | |
1472 | \pass@_router\ option. However, (unlike \redirect@_router\) the named router | |
1473 | must be below the current router (to avoid loops). | |
1474 | .nextp | |
1475 | \*decline*\: The router declines to accept the address because it does not | |
1476 | recognize it at all. By default, the address is passed to the next router, but | |
1477 | this can be prevented by setting the \no@_more\ option. When \no@_more\ is set, | |
1478 | all the remaining routers are skipped. | |
1479 | .nextp | |
1480 | \*fail*\: The router determines that the address should fail, and queues it for | |
1481 | the generation of a bounce message. There is no further processing of the | |
1482 | original address unless \unseen\ is set on the router. | |
1483 | .nextp | |
1484 | \*defer*\: The router cannot handle the address at the present time. (A database | |
1485 | may be offline, or a DNS lookup may have timed out.) No further processing of | |
1486 | the address happens in this delivery attempt. It is tried again next time the | |
1487 | message is considered for delivery. | |
1488 | .nextp | |
1489 | \*error*\: There is some error in the router (for example, a syntax error in | |
1490 | its configuration). The action is as for defer. | |
1491 | .endp | |
1492 | If an address reaches the end of the routers without having been accepted by | |
1493 | any of them, it is bounced as unrouteable. | |
4964e932 PH |
1494 | The default error message in this situation is `unrouteable address', but you |
1495 | can set your own message by making use of the \cannot@_route@_message\ option. | |
1496 | This can be set for any router; the value from the last router that `saw' | |
495ae4b0 PH |
1497 | the address is used. |
1498 | ||
1499 | Sometimes while routing you want to fail a delivery when some conditions are | |
1500 | met but others are not, instead of passing the address on for further routing. | |
1501 | You can do this by having a second router that explicitly fails the delivery | |
4964e932 | 1502 | when the relevant conditions are met. The \%redirect%\ router has a `fail' |
495ae4b0 PH |
1503 | facility for this purpose. |
1504 | ||
1505 | ||
1506 | ||
1507 | .section Router preconditions | |
1508 | .rset SECTrouprecon "~~chapter.~~section" | |
1509 | .index router||preconditions, order of processing | |
1510 | .index preconditions||order of processing | |
1511 | The preconditions that are tested for each router are listed below, in the | |
1512 | order in which they are tested. The individual configuration options are | |
1513 | described in more detail in chapter ~~CHAProutergeneric. | |
1514 | .numberpars $. | |
1515 | The \local@_part@_prefix\ and \local@_part@_suffix\ options can specify that | |
1516 | the local parts handled by the router may or must have certain prefixes and/or | |
1517 | suffixes. If a mandatory affix (prefix or suffix) is not present, the router is | |
1518 | skipped. These conditions are tested first. When an affix is present, it is | |
1519 | removed from the local part before further processing, including the evaluation | |
1520 | of any other conditions. | |
1521 | .nextp | |
4964e932 PH |
1522 | Routers can be designated for use only when not verifying an address, that is, |
1523 | only when routing it for delivery (or testing its delivery routing). If the | |
1524 | \verify\ option is set false, the router is skipped when Exim is verifying an | |
495ae4b0 | 1525 | address. |
4964e932 PH |
1526 | Setting the \verify\ option actually sets two options, \verify@_sender\ and |
1527 | \verify@_recipient\, which independently control the use of the router for | |
1528 | sender and recipient verification. You can set these options directly if | |
495ae4b0 PH |
1529 | you want a router to be used for only one type of verification. |
1530 | .nextp | |
4964e932 PH |
1531 | If the \address@_test\ option is set false, the router is skipped when Exim is |
1532 | run with the \-bt-\ option to test an address routing. This can be helpful when | |
1533 | the first router sends all new messages to a scanner of some sort; it makes it | |
495ae4b0 PH |
1534 | possible to use \-bt-\ to test subsequent delivery routing without having to |
1535 | simulate the effect of the scanner. | |
1536 | .nextp | |
1537 | Routers can be designated for use only when verifying an address, as | |
1538 | opposed to routing it for delivery. The \verify@_only\ option controls this. | |
1539 | .nextp | |
1540 | Certain routers can be explicitly skipped when running the routers to check an | |
1541 | address given in the SMTP \\EXPN\\ command (see the \expn\ option). | |
1542 | .nextp | |
1543 | If the \domains\ option is set, the domain of the address must be in the set of | |
1544 | domains that it defines. | |
1545 | .nextp | |
1546 | If the \local@_parts\ option is set, the local part of the address must be in | |
1547 | the set of local parts that it defines. If \local@_part@_prefix\ or | |
1548 | \local@_part@_suffix\ is in use, the prefix or suffix is removed from the local | |
1549 | part before this check. If you want to do precondition tests on local parts | |
1550 | that include affixes, you can do so by using a \condition\ option (see below) | |
1551 | that uses the variables \$local@_part$\, \$local@_part@_prefix$\, and | |
1552 | \$local@_part@_suffix$\ as necessary. | |
1553 | .nextp | |
1554 | If the \check@_local@_user\ option is set, the local part must be the name of | |
1555 | an account on the local host. | |
4964e932 | 1556 | If this check succeeds, the uid and gid of the local user are placed in |
495ae4b0 PH |
1557 | \$local@_user@_uid$\ and \$local@_user@_gid$\; these values can be used in the |
1558 | remaining preconditions. | |
1559 | .nextp | |
1560 | If the \router@_home@_directory\ option is set, it is expanded at this point, | |
4964e932 PH |
1561 | because it overrides the value of \$home$\. If this expansion were left till |
1562 | later, the value of \$home$\ as set by \check@_local@_user\ would be used in | |
1563 | subsequent tests. Having two different values of \$home$\ in the same router | |
495ae4b0 PH |
1564 | could lead to confusion. |
1565 | .nextp | |
1566 | If the \senders\ option is set, the envelope sender address must be in the set | |
1567 | of addresses that it defines. | |
1568 | .nextp | |
1569 | If the \require@_files\ option is set, the existence or non-existence of | |
1570 | specified files is tested. | |
1571 | .nextp | |
1572 | .index customizing||precondition | |
1573 | If the \condition\ option is set, it is evaluated and tested. This option uses | |
1574 | an expanded string to allow you to set up your own custom preconditions. | |
1575 | Expanded strings are described in chapter ~~CHAPexpand. | |
1576 | .endp | |
1577 | ||
1578 | Note that \require@_files\ comes near the end of the list, so you cannot use it | |
1579 | to check for the existence of a file in which to lookup up a domain, local | |
1580 | part, or sender. However, as these options are all expanded, you can use the | |
1581 | \exists\ expansion condition to make such tests within each condition. The | |
1582 | \require@_files\ option is intended for checking files that the router may be | |
1583 | going to use internally, or which are needed by a specific transport (for | |
1584 | example, \(.procmailrc)\). | |
1585 | ||
1586 | ||
1587 | .section Delivery in detail | |
1588 | .index delivery||in detail | |
1589 | When a message is to be delivered, the sequence of events is as follows: | |
1590 | .numberpars $. | |
1591 | If a system-wide filter file is specified, the message is passed to it. The | |
1592 | filter may add recipients to the message, replace the recipients, discard the | |
1593 | message, cause a new message to be generated, or cause the message delivery to | |
1594 | fail. The format of the system filter file is the same as for Exim user filter | |
1595 | files, described in the separate document entitled | |
1596 | .if ~~html | |
1597 | [(A HREF="filter.html")] | |
1598 | .fi | |
1599 | \*Exim's interfaces to mail filtering*\. | |
1600 | .if ~~html | |
1601 | [(/A)] | |
1602 | .fi | |
1603 | .index Sieve filter||not available for system filter | |
1604 | (\**Note**\: Sieve cannot be used for system filter files.) | |
1605 | Some additional features are available in system filters -- see chapter | |
1606 | ~~CHAPsystemfilter for details. Note that a message is passed to the system | |
1607 | filter only once per delivery attempt, however many recipients it has. However, | |
1608 | if there are several delivery attempts because one or more addresses could not | |
1609 | be immediately delivered, the system filter is run each time. The filter | |
1610 | condition \first@_delivery\ can be used to detect the first run of the system | |
1611 | filter. | |
1612 | .nextp | |
1613 | Each recipient address is offered to each configured router in turn, subject to | |
1614 | its preconditions, until one is able to handle it. If no router can handle | |
1615 | the address, that is, if they all decline, the address is failed. Because | |
1616 | routers can be targeted at particular domains, several locally handled domains | |
1617 | can be processed entirely independently of each other. | |
1618 | .nextp | |
1619 | .index routing||loops in | |
1620 | .index loop||while routing | |
1621 | A router that accepts an address may set up a local or a remote transport for | |
1622 | it. However, the transport is not run at this time. Instead, the address is | |
1623 | placed on a list for the particular transport, to be run later. Alternatively, | |
1624 | the router may generate one or more new addresses (typically from alias, | |
1625 | forward, or filter files). New addresses are fed back into this process from | |
1626 | the top, but in order to avoid loops, a router ignores any address which has an | |
1627 | identically-named ancestor that was processed by itself. | |
1628 | .nextp | |
1629 | When all the routing has been done, addresses that have been successfully | |
1630 | handled are passed to their assigned transports. When local transports are | |
1631 | doing real local deliveries, they handle only one address at a time, but if a | |
1632 | local transport is being used as a pseudo-remote transport (for example, to | |
1633 | collect batched SMTP messages for transmission by some other means) multiple | |
1634 | addresses can be handled. Remote transports can always handle more than one | |
1635 | address at a time, but can be configured not to do so, or to restrict multiple | |
1636 | addresses to the same domain. | |
1637 | .nextp | |
1638 | Each local delivery to a file or a pipe runs in a separate process under a | |
1639 | non-privileged uid, and these deliveries are run one at a time. Remote | |
1640 | deliveries also run in separate processes, normally under a uid that is private | |
1641 | to Exim (`the Exim user'), but in this case, several remote deliveries can be | |
1642 | run in parallel. The maximum number of simultaneous remote deliveries for any | |
1643 | one message is set by the \remote@_max@_parallel\ option. | |
4964e932 | 1644 | The order in which deliveries are done is not defined, except that all local |
495ae4b0 | 1645 | deliveries happen before any remote deliveries. |
495ae4b0 PH |
1646 | .nextp |
1647 | .index queue runner | |
1648 | When it encounters a local delivery during a queue run, Exim checks its retry | |
1649 | database to see if there has been a previous temporary delivery failure for the | |
1650 | address before running the local transport. If there was a previous failure, | |
1651 | Exim does not attempt a new delivery until the retry time for the address is | |
1652 | reached. However, this happens only for delivery attempts that are part of a | |
1653 | queue run. Local deliveries are always attempted when delivery immediately | |
1654 | follows message reception, even if retry times are set for them. This makes for | |
1655 | better behaviour if one particular message is causing problems (for example, | |
1656 | causing quota overflow, or provoking an error in a filter file). | |
1657 | .nextp | |
1658 | .index delivery||retry in remote transports | |
1659 | Remote transports do their own retry handling, since an address may be | |
1660 | deliverable to one of a number of hosts, each of which may have a different | |
1661 | retry time. If there have been previous temporary failures and no host has | |
1662 | reached its retry time, no delivery is attempted, whether in a queue run or | |
1663 | not. See chapter ~~CHAPretry for details of retry strategies. | |
1664 | .nextp | |
1665 | If there were any permanent errors, a bounce message is returned to an | |
1666 | appropriate address (the sender in the common case), with details of the error | |
1667 | for each failing address. Exim can be configured to send copies of bounce | |
1668 | messages to other addresses. | |
1669 | .nextp | |
1670 | .index delivery||deferral | |
1671 | If one or more addresses suffered a temporary failure, the message is left on | |
1672 | the queue, to be tried again later. Delivery of these addresses is said to be | |
1673 | \*deferred*\. | |
1674 | .nextp | |
1675 | When all the recipient addresses have either been delivered or bounced, | |
1676 | handling of the message is complete. The spool files and message log are | |
1677 | deleted, though the message log can optionally be preserved if required. | |
1678 | .endp | |
1679 | ||
1680 | ||
1681 | .section Retry mechanism | |
1682 | .index delivery||retry mechanism | |
1683 | .index retry||description of mechanism | |
1684 | .index queue runner | |
1685 | Exim's mechanism for retrying messages that fail to get delivered at the first | |
1686 | attempt is the queue runner process. You must either run an Exim daemon that | |
1687 | uses the \-q-\ option with a time interval to start queue runners at regular | |
1688 | intervals, or use some other means (such as \*cron*\) to start them. If you do | |
1689 | not arrange for queue runners to be run, messages that fail temporarily at the | |
1690 | first attempt will remain on your queue for ever. A queue runner process works | |
1691 | it way through the queue, one message at a time, trying each delivery that has | |
1692 | passed its retry time. | |
1693 | You can run several queue runners at once. | |
1694 | ||
1695 | Exim uses a set of configured rules to determine when next to retry the failing | |
1696 | address (see chapter ~~CHAPretry). These rules also specify when Exim should | |
1697 | give up trying to deliver to the address, at which point it generates a bounce | |
1698 | message. If no retry rules are set for a particular host, address, and error | |
1699 | combination, no retries are attempted, and temporary errors are treated as | |
1700 | permanent. | |
1701 | ||
1702 | ||
1703 | .section Temporary delivery failure | |
1704 | .index delivery||temporary failure | |
1705 | There are many reasons why a message may not be immediately deliverable to a | |
1706 | particular address. Failure to connect to a remote machine (because it, or the | |
1707 | connection to it, is down) is one of the most common. Temporary failures may be | |
1708 | detected during routing as well as during the transport stage of delivery. | |
1709 | Local deliveries may be delayed if NFS files are unavailable, or if a mailbox | |
1710 | is on a file system where the user is over quota. Exim can be configured to | |
1711 | impose its own quotas on local mailboxes; where system quotas are set they will | |
1712 | also apply. | |
1713 | ||
1714 | If a host is unreachable for a period of time, a number of messages may be | |
1715 | waiting for it by the time it recovers, and sending them in a single SMTP | |
1716 | connection is clearly beneficial. Whenever a delivery to a remote host is | |
4964e932 | 1717 | deferred, |
495ae4b0 PH |
1718 | .index hints database |
1719 | Exim makes a note in its hints database, and whenever a successful | |
1720 | SMTP delivery has happened, it looks to see if any other messages are waiting | |
1721 | for the same host. If any are found, they are sent over the same SMTP | |
1722 | connection, subject to a configuration limit as to the maximum number in any | |
1723 | one connection. | |
1724 | ||
1725 | ||
1726 | ||
1727 | .section Permanent delivery failure | |
1728 | .index delivery||permanent failure | |
1729 | .index bounce message||when generated | |
1730 | When a message cannot be delivered to some or all of its intended recipients, a | |
1731 | bounce message is generated. Temporary delivery failures turn into permanent | |
1732 | errors when their timeout expires. All the addresses that fail in a given | |
1733 | delivery attempt are listed in a single message. If the original message has | |
1734 | many recipients, it is possible for some addresses to fail in one delivery | |
1735 | attempt and others to fail subsequently, giving rise to more than one bounce | |
1736 | message. The wording of bounce messages can be customized by the administrator. | |
1737 | See chapter ~~CHAPemsgcust for details. | |
1738 | ||
1739 | .index ::X-Failed-Recipients:: header line | |
1740 | Bounce messages contain an ::X-Failed-Recipients:: header line that lists the | |
1741 | failed addresses, for the benefit of programs that try to analyse such messages | |
1742 | automatically. | |
1743 | ||
1744 | .index bounce message||recipient of | |
1745 | A bounce message is normally sent to the sender of the original message, as | |
1746 | obtained from the message's envelope. For incoming SMTP messages, this is the | |
1747 | address given in the \\MAIL\\ command. However, when an address is | |
1748 | expanded via a forward or alias file, an alternative address can be specified | |
1749 | for delivery failures of the generated addresses. For a mailing list expansion | |
1750 | (see section ~~SECTmailinglists) it is common to direct bounce messages to the | |
1751 | manager of the list. | |
1752 | ||
1753 | ||
1754 | ||
1755 | .section Failures to deliver bounce messages | |
1756 | .index bounce message||failure to deliver | |
1757 | If a bounce message (either locally generated or received from a remote host) | |
1758 | itself suffers a permanent delivery failure, the message is left on the queue, | |
1759 | but it is frozen, awaiting the attention of an administrator. There are options | |
1760 | which can be used to make Exim discard such failed messages, or to keep them | |
1761 | for only a short time (see \timeout@_frozen@_after\ and | |
1762 | \ignore@_bounce@_errors@_after\). | |
1763 | ||
1764 | ||
1765 | ||
1766 | . | |
1767 | . | |
1768 | . | |
1769 | . | |
1770 | . ============================================================================ | |
1771 | .chapter Building and installing Exim | |
1772 | .set runningfoot "building/installing" | |
1773 | ||
1774 | .index building Exim | |
1775 | .section Unpacking | |
1776 | Exim is distributed as a gzipped or bzipped tar file which, when upacked, | |
1777 | creates a directory with the name of the current release (for example, | |
1778 | \(exim-~~version)\) into which the following files are placed: | |
1779 | .display rm | |
1780 | .if !~~sys.fancy && ~~sgcal | |
1781 | .tabs 16 | |
1782 | .else | |
4964e932 | 1783 | .tabs 22 |
495ae4b0 PH |
1784 | .fi |
1785 | \(ACKNOWLEDGMENTS)\ $t contains some acknowledgments | |
1786 | .newline | |
1787 | \(CHANGES)\ $t contains a reference to where changes are documented | |
1788 | \(LICENCE)\ $t the GNU General Public Licence | |
1789 | \(Makefile)\ $t top-level make file | |
1790 | \(NOTICE)\ $t conditions for the use of Exim | |
1791 | \(README)\ $t list of files, directories and simple build instructions | |
1792 | .endd | |
1793 | Other files whose names begin with \(README)\ may also be present. The | |
1794 | following subdirectories are created: | |
1795 | .display rm | |
1796 | .if !~~sys.fancy && ~~sgcal | |
1797 | .tabs 16 | |
1798 | .else | |
1799 | .tabs 22 | |
1800 | .fi | |
1801 | \(Local)\ $t an empty directory for local configuration files | |
1802 | \(OS)\ $t OS-specific files | |
1803 | \(doc)\ $t documentation files | |
1804 | \(exim@_monitor)\$t source files for the Exim monitor | |
1805 | \(scripts)\ $t scripts used in the build process | |
1806 | \(src)\ $t remaining source files | |
1807 | \(util)\ $t independent utilities | |
1808 | .endd | |
1809 | The main utility programs are contained in the \(src)\ directory, and are built | |
1810 | with the Exim binary. The \(util)\ directory contains a few optional scripts | |
1811 | that may be useful to some sites. | |
1812 | ||
1813 | .section Multiple machine architectures and operating systems | |
1814 | .index building Exim||multiple OS/architectures | |
1815 | The building process for Exim is arranged to make it easy to build binaries for | |
1816 | a number of different architectures and operating systems from the same set of | |
1817 | source files. Compilation does not take place in the \(src)\ directory. Instead, | |
1818 | a \*build directory*\ is created for each architecture and operating system. | |
1819 | .index symbolic link||to build directory | |
1820 | Symbolic links to the sources are installed in this directory, which is where | |
1821 | the actual building takes place. | |
1822 | ||
1823 | In most cases, Exim can discover the machine architecture and operating system | |
1824 | for itself, but the defaults can be overridden if necessary. | |
1825 | ||
1826 | .section DBM libraries | |
1827 | .rset SECTdb "~~chapter.~~section" | |
1828 | .index DBM||libraries, discussion of | |
1829 | .index hints database||DBM files used for | |
1830 | Even if you do not use any DBM files in your configuration, Exim still needs a | |
1831 | DBM library in order to operate, because it uses indexed files for its hints | |
1832 | databases. Unfortunately, there are a number of DBM libraries in existence, and | |
1833 | different operating systems often have different ones installed. | |
1834 | ||
1835 | .index Solaris||DBM library for | |
1836 | .index IRIX, DBM library for | |
1837 | .index BSD, DBM library for | |
1838 | .index Linux, DBM library for | |
1839 | If you are using Solaris, IRIX, one of the modern BSD systems, or a modern | |
1840 | Linux distribution, the DBM configuration should happen automatically, and you | |
1841 | may be able to ignore this section. Otherwise, you may have to learn more than | |
1842 | you would like about DBM libraries from what follows. | |
1843 | ||
1844 | .index \*ndbm*\ DBM library | |
1845 | Licensed versions of Unix normally contain a library of DBM functions operating | |
1846 | via the \*ndbm*\ interface, and this is what Exim expects by default. Free | |
1847 | versions of Unix seem to vary in what they contain as standard. In particular, | |
1848 | some early versions of Linux have no default DBM library, and different | |
1849 | distributors have chosen to bundle different libraries with their packaged | |
1850 | versions. However, the more recent releases seem to have standardised on the | |
1851 | Berkeley DB library. | |
1852 | ||
1853 | Different DBM libraries have different conventions for naming the files they | |
1854 | use. When a program opens a file called \(dbmfile)\, there are four | |
1855 | possibilities: | |
1856 | .numberpars | |
1857 | A traditional \*ndbm*\ implementation, such as that supplied as part of | |
1858 | Solaris, operates on two files called \(dbmfile.dir)\ and \(dbmfile.pag)\. | |
1859 | .nextp | |
1860 | .index \*gdbm*\ DBM library | |
1861 | The GNU library, \*gdbm*\, operates on a single file. If used via its \*ndbm*\ | |
1862 | compatibility interface it makes two different hard links to it with names | |
1863 | \(dbmfile.dir)\ and \(dbmfile.pag)\, but if used via its native interface, the | |
1864 | file name is used unmodified. | |
1865 | .nextp | |
1866 | .index Berkeley DB library | |
1867 | The Berkeley DB package, if called via its \*ndbm*\ compatibility interface, | |
1868 | operates on a single file called \(dbmfile.db)\, but otherwise looks to the | |
1869 | programmer exactly the same as the traditional \*ndbm*\ implementation. | |
1870 | .nextp | |
1871 | If the Berkeley package is used in its native mode, it operates on a single | |
1872 | file called \(dbmfile)\; the programmer's interface is somewhat different to | |
1873 | the traditional \*ndbm*\ interface. | |
1874 | .nextp | |
1875 | To complicate things further, there are several very different versions of the | |
1876 | Berkeley DB package. Version 1.85 was stable for a very long time, releases | |
1877 | 2.$it{x} and 3.$it{x} were current for a while, but the latest versions are now | |
1878 | numbered 4.$it{x}. Maintenance of some of the earlier releases has ceased. All | |
1879 | versions of Berkeley DB can be obtained from | |
1880 | .display rm | |
1881 | \?http://www.sleepycat.com/?\ | |
1882 | .endd | |
1883 | .nextp | |
1884 | .index \*tdb*\ DBM library | |
1885 | Yet another DBM library, called \*tdb*\, has become available from | |
1886 | .display rm | |
1887 | \?http://download.sourceforge.net/tdb?\ | |
1888 | .endd | |
1889 | It has its own interface, and also operates on a single file. | |
1890 | .endp | |
1891 | .index \\USE@_DB\\ | |
1892 | .index DBM||libraries, configuration for building | |
1893 | Exim and its utilities can be compiled to use any of these interfaces. In order | |
1894 | to use any version of the Berkeley DB package in native mode, you must set | |
1895 | \\USE@_DB\\ in an appropriate configuration file (typically | |
1896 | \(Local/Makefile)\). For example: | |
1897 | .display asis | |
1898 | USE_DB=yes | |
1899 | .endd | |
1900 | Similarly, for gdbm you set \\USE@_GDBM\\, and for tdb you set \\USE@_TDB\\. An | |
1901 | error is diagnosed if you set more than one of these. | |
1902 | ||
1903 | At the lowest level, the build-time configuration sets none of these options, | |
1904 | thereby assuming an interface of type (1). However, some operating system | |
1905 | configuration files (for example, those for the BSD operating systems and | |
1906 | Linux) assume type (4) by setting \\USE@_DB\\ as their default, and the | |
1907 | configuration files for Cygwin set \\USE@_GDBM\\. Anything you set in | |
1908 | \(Local/Makefile)\, however, overrides these system defaults. | |
1909 | ||
1910 | As well as setting \\USE@_DB\\, \\USE@_GDBM\\, or \\USE@_TDB\\, it may also be | |
1911 | necessary to set \\DBMLIB\\, to cause inclusion of the appropriate library, as | |
1912 | in one of these lines: | |
1913 | .display asis | |
1914 | DBMLIB = -ldb | |
1915 | DBMLIB = -ltdb | |
1916 | .endd | |
4964e932 | 1917 | Settings like that will work if the DBM library is installed in the standard |
495ae4b0 PH |
1918 | place. Sometimes it is not, and the library's header file may also not be in |
1919 | the default path. You may need to set \\INCLUDE\\ to specify where the header | |
4964e932 | 1920 | file is, and to specify the path to the library more fully in \\DBMLIB\\, as in |
495ae4b0 PH |
1921 | this example: |
1922 | .display asis | |
1923 | INCLUDE=-I/usr/local/include/db-4.1 | |
1924 | DBMLIB=/usr/local/lib/db-4.1/libdb.a | |
1925 | .endd | |
1926 | ||
1927 | There is further detailed discussion about the various DBM libraries in the | |
1928 | file \(doc/dbm.discuss.txt)\ in the Exim distribution. | |
1929 | ||
1930 | ||
1931 | .section Pre-building configuration | |
1932 | .index building Exim||pre-building configuration | |
1933 | .index configuration for building Exim | |
1934 | .index \(Local/Makefile)\ | |
1935 | .index \(src/EDITME)\ | |
1936 | Before building Exim, a local configuration file that specifies options | |
1937 | independent of any operating system has to be created with the name | |
1938 | \(Local/Makefile)\. A template for this file is supplied as the file | |
1939 | \(src/EDITME)\, and it contains full descriptions of all the option settings | |
1940 | therein. These descriptions are therefore not repeated here. If you are | |
1941 | building Exim for the first time, the simplest thing to do is to copy | |
1942 | \(src/EDITME)\ to \(Local/Makefile)\, then read it and edit it appropriately. | |
1943 | ||
1944 | There are three settings that you must supply, because Exim will not build | |
1945 | without them. They are the location of the run time configuration file | |
1946 | (\\CONFIGURE@_FILE\\), the directory in which Exim binaries will be installed | |
1947 | (\\BIN@_DIRECTORY\\), and the identity of the Exim user (\\EXIM@_USER\\ and | |
1948 | maybe \\EXIM@_GROUP\\ as well). The value of \\CONFIGURE@_FILE\\ can in fact be | |
1949 | a colon-separated list of file names; Exim uses the first of them that exists. | |
1950 | ||
1951 | There are a few other parameters that can be specified either at build time or | |
1952 | at run time, to enable the same binary to be used on a number of different | |
1953 | machines. However, if the locations of Exim's spool directory and log file | |
1954 | directory (if not within the spool directory) are fixed, it is recommended that | |
1955 | you specify them in \(Local/Makefile)\ instead of at run time, so that errors | |
1956 | detected early in Exim's execution (such as a malformed configuration file) can | |
1957 | be logged. | |
1958 | ||
d43194df PH |
1959 | .index content scanning||specifying at build time |
1960 | .em | |
1961 | Exim's interfaces for calling virus and spam scanning sofware directly from | |
1962 | access control lists are not compiled by default. If you want to include these | |
1963 | facilities, you need to set | |
1964 | .display asis | |
1965 | WITH_CONTENT_SCAN=yes | |
1966 | .endd | |
1967 | in your \(Local/Makefile)\. For details of the facilities themselves, see | |
1968 | chapter ~~CHAPexiscan. | |
1969 | .nem | |
1970 | ||
495ae4b0 PH |
1971 | .index \(Local/eximon.conf)\ |
1972 | .index \(exim@_monitor/EDITME)\ | |
1973 | If you are going to build the Exim monitor, a similar configuration process is | |
1974 | required. The file \(exim@_monitor/EDITME)\ must be edited appropriately for | |
1975 | your installation and saved under the name \(Local/eximon.conf)\. If you are | |
1976 | happy with the default settings described in \(exim@_monitor/EDITME)\, | |
1977 | \(Local/eximon.conf)\ can be empty, but it must exist. | |
1978 | ||
1979 | This is all the configuration that is needed in straightforward cases for known | |
1980 | operating systems. However, the building process is set up so that it is easy | |
1981 | to override options that are set by default or by operating-system-specific | |
1982 | configuration files, for example to change the name of the C compiler, which | |
1983 | defaults to \gcc\. See section ~~SECToverride below for details of how to do | |
1984 | this. | |
1985 | ||
1986 | ||
1987 | .section Support for iconv() | |
1988 | .index \*iconv()*\ support | |
4964e932 PH |
1989 | The contents of header lines in messages may be encoded according to the rules |
1990 | described RFC 2047. This makes it possible to transmit characters that are not | |
1991 | in the ASCII character set, and to label them as being in a particular | |
1992 | character set. When Exim is inspecting header lines by means of the \@$h@_\ | |
1993 | mechanism, it decodes them, and translates them into a specified character set | |
495ae4b0 PH |
1994 | (default ISO-8859-1). The translation is possible only if the operating system |
1995 | supports the \*iconv()*\ function. | |
1996 | ||
1997 | However, some of the operating systems that supply \*iconv()*\ do not support | |
1998 | very many conversions. The GNU \libiconv\ library (available from | |
1999 | \?http:/@/www.gnu.org/software/libiconv/?\) can be installed on such systems to | |
2000 | remedy this deficiency, as well as on systems that do not supply \*iconv()*\ at | |
4964e932 | 2001 | all. After installing \libiconv\, you should add |
495ae4b0 | 2002 | .display asis |
4964e932 PH |
2003 | HAVE_ICONV=yes |
2004 | .endd | |
495ae4b0 PH |
2005 | to your \(Local/Makefile)\ and rebuild Exim. |
2006 | ||
2007 | ||
2008 | .section Including TLS/SSL encryption support | |
2009 | .rset SECTinctlsssl "~~chapter.~~section" | |
2010 | .index TLS||including support for TLS | |
2011 | .index encryption||including support for | |
2012 | .index \\SUPPORT@_TLS\\ | |
2013 | .index OpenSSL||building Exim with | |
2014 | .index GnuTLS||building Exim with | |
2015 | Exim can be built to support encrypted SMTP connections, using the \\STARTTLS\\ | |
4964e932 PH |
2016 | command as per RFC 2487. It can also support legacy clients that expect to |
2017 | start a TLS session immediately on connection to a non-standard port (see the | |
d43194df PH |
2018 | \tls@_on@_connect@_ports\ runtime option and the \-tls-on-connect-\ command |
2019 | line option). | |
495ae4b0 | 2020 | |
4964e932 | 2021 | If you want to build Exim with TLS support, you must first install either the |
495ae4b0 PH |
2022 | OpenSSL or GnuTLS library. There is no cryptographic code in Exim itself for |
2023 | implementing SSL. | |
2024 | ||
2025 | If OpenSSL is installed, you should set | |
2026 | .display asis | |
2027 | SUPPORT_TLS=yes | |
2028 | TLS_LIBS=-lssl -lcrypto | |
2029 | .endd | |
2030 | in \(Local/Makefile)\. You may also need to specify the locations of the | |
2031 | OpenSSL library and include files. For example: | |
2032 | .display asis | |
2033 | SUPPORT_TLS=yes | |
2034 | TLS_LIBS=-L/usr/local/openssl/lib -lssl -lcrypto | |
2035 | TLS_INCLUDE=-I/usr/local/openssl/include/ | |
2036 | .endd | |
2037 | ||
2038 | If GnuTLS is installed, you should set | |
2039 | .index \\USE@_GNUTLS\\ | |
2040 | .display asis | |
2041 | SUPPORT_TLS=yes | |
2042 | USE_GNUTLS=yes | |
2043 | TLS_LIBS=-lgnutls -ltasn1 -lgcrypt | |
2044 | .endd | |
2045 | in \(Local/Makefile)\, and again you may need to specify the locations of the | |
2046 | library and include files. For example: | |
2047 | .display asis | |
2048 | SUPPORT_TLS=yes | |
4964e932 | 2049 | USE_GNUTLS=yes |
495ae4b0 PH |
2050 | TLS_LIBS=-L/usr/gnu/lib -lgnutls -ltasn1 -lgcrypt |
2051 | TLS_INCLUDE=-I/usr/gnu/include | |
2052 | .endd | |
2053 | You do not need to set \\TLS@_INCLUDE\\ if the relevant directory is already | |
4964e932 | 2054 | specified in \\INCLUDE\\. Details of how to configure Exim to make use of TLS |
495ae4b0 PH |
2055 | are given in chapter ~~CHAPTLS. |
2056 | ||
2057 | ||
2058 | ||
2059 | .section Use of tcpwrappers | |
2060 | .index tcpwrappers, building Exim to support | |
2061 | .index \\USE@_TCP@_WRAPPERS\\ | |
2062 | Exim can be linked with the \*tcpwrappers*\ library in order to check incoming | |
2063 | SMTP calls using the \*tcpwrappers*\ control files. This may be a convenient | |
2064 | alternative to Exim's own checking facilities for installations that are | |
2065 | already making use of \*tcpwrappers*\ for other purposes. To do this, you should | |
2066 | set \\USE@_TCP@_WRAPPERS\\ in \(Local/Makefile)\, arrange for the file | |
2067 | \(tcpd.h)\ to be available at compile time, and also ensure that the library | |
2068 | \(libwrap.a)\ is available at link time, typically by including \-lwrap-\ in | |
2069 | \\EXTRALIBS@_EXIM\\. For example, if \*tcpwrappers*\ is installed in | |
2070 | \(/usr/local)\, you might have | |
2071 | .display | |
2072 | USE@_TCP@_WRAPPERS=yes | |
2073 | CFLAGS=-O -I/usr/local/include | |
2074 | .newline | |
2075 | EXTRALIBS@_EXIM=-L/usr/local/lib -lwrap | |
2076 | .endd | |
2077 | in \(Local/Makefile)\. The name to use in the \*tcpwrappers*\ control files is | |
2078 | `exim'. For example, the line | |
2079 | .display | |
2080 | exim : LOCAL 192.168.1. .friendly.domain.example | |
2081 | .endd | |
2082 | in your \(/etc/hosts.allow)\ file allows connections from the local host, from | |
2083 | the subnet 192.168.1.0/24, and from all hosts in \*friendly.domain.example*\. | |
2084 | All other connections are denied. Consult the \*tcpwrappers*\ documentation for | |
2085 | further details. | |
2086 | ||
2087 | ||
2088 | .section Including support for IPv6 | |
2089 | .index IPv6||including support for | |
2090 | Exim contains code for use on systems that have IPv6 support. Setting | |
2091 | \\HAVE@_IPV6=YES\\ in \(Local/Makefile)\ causes the IPv6 code to be included; | |
2092 | it may also be necessary to set \\IPV6@_INCLUDE\\ and \\IPV6@_LIBS\\ on systems | |
2093 | where the IPv6 support is not fully integrated into the normal include and | |
2094 | library files. | |
2095 | ||
d43194df PH |
2096 | .em |
2097 | Two different types of DNS record for handling IPv6 addresses have been | |
2098 | defined. AAAA records (analagous to A records for IPv4) are in use, and are | |
2099 | currently seen as the mainstream. Another record type called A6 was proposed | |
2100 | as better than AAAA because it had more flexibility. However, it was felt to | |
2101 | be over-complex, and its status was reduced to `experimental'. It is not known | |
2102 | if anyone is actually using A6 records. Exim has support for A6 records, but | |
2103 | this is included only if you set \\SUPPORT@_A6=YES\\ in \(Local/Makefile)\. The | |
2104 | support has not been tested for some time. | |
2105 | .nem | |
495ae4b0 PH |
2106 | |
2107 | .section The building process | |
2108 | .index build directory | |
2109 | Once \(Local/Makefile)\ (and \(Local/eximon.conf)\, if required) have been | |
2110 | created, run \*make*\ at the top level. It determines the architecture and | |
2111 | operating system types, and creates a build directory if one does not exist. | |
2112 | For example, on a Sun system running Solaris 8, the directory | |
2113 | \(build-SunOS5-5.8-sparc)\ is created. | |
2114 | .index symbolic link||to source files | |
2115 | Symbolic links to relevant source files are installed in the build directory. | |
2116 | ||
4964e932 | 2117 | \**Warning**\: The \-j-\ (parallel) flag must not be used with \*make*\; the |
495ae4b0 | 2118 | building process fails if it is set. |
495ae4b0 PH |
2119 | |
2120 | If this is the first time \*make*\ has been run, it calls a script that builds | |
2121 | a make file inside the build directory, using the configuration files from the | |
2122 | \(Local)\ directory. The new make file is then passed to another instance of | |
2123 | \*make*\. This does the real work, building a number of utility scripts, and | |
2124 | then compiling and linking the binaries for the Exim monitor (if configured), a | |
2125 | number of utility programs, and finally Exim itself. The command \*make | |
2126 | makefile*\ can be used to force a rebuild of the make file in the build | |
2127 | directory, should this ever be necessary. | |
2128 | ||
2129 | If you have problems building Exim, check for any comments there may be in the | |
2130 | \(README)\ file concerning your operating system, and also take a look at the | |
2131 | .if ~~html | |
2132 | [(A HREF="FAQ.html")] | |
2133 | .fi | |
2134 | FAQ, | |
2135 | .if ~~html | |
2136 | [(/A)] | |
2137 | .fi | |
2138 | where some common problems are covered. | |
2139 | ||
2140 | ||
2141 | ||
2142 | .section Overriding build-time options for Exim | |
2143 | .index build-time options, overriding | |
2144 | .rset SECToverride "~~chapter.~~section" | |
2145 | The main make file that is created at the beginning of the building process | |
2146 | consists of the concatenation of a number of files which set configuration | |
2147 | values, followed by a fixed set of \*make*\ instructions. If a value is set | |
2148 | more than once, the last setting overrides any previous ones. This provides a | |
2149 | convenient way of overriding defaults. The files that are concatenated are, in | |
2150 | order: | |
2151 | .display rm | |
2152 | \(OS/Makefile-Default)\ | |
2153 | \(OS/Makefile-)\<<ostype>> | |
2154 | \(Local/Makefile)\ | |
2155 | \(Local/Makefile-)\<<ostype>> | |
2156 | \(Local/Makefile-)\<<archtype>> | |
2157 | \(Local/Makefile-)\<<ostype>>-<<archtype>> | |
2158 | \(OS/Makefile-Base)\ | |
2159 | .endd | |
2160 | .index \(Local/Makefile)\ | |
2161 | where <<ostype>> is the operating system type and <<archtype>> is the | |
2162 | .index building Exim||operating system type | |
2163 | .index building Exim||architecture type | |
2164 | architecture type. \(Local/Makefile)\ is required to exist, and the building | |
2165 | process fails if it is absent. The other three \(Local)\ files are optional, | |
2166 | and are often not needed. | |
2167 | ||
2168 | The values used for <<ostype>> and <<archtype>> are obtained from scripts | |
2169 | called \(scripts/os-type)\ and \(scripts/arch-type)\ respectively. If either of | |
2170 | the environment variables \\EXIM@_OSTYPE\\ or \\EXIM@_ARCHTYPE\\ is set, their | |
2171 | values are used, thereby providing a means of forcing particular settings. | |
2172 | Otherwise, the scripts try to get values from the \uname\ command. If this | |
2173 | fails, the shell variables \\OSTYPE\\ and \\ARCHTYPE\\ are inspected. A number | |
2174 | of $it{ad hoc} transformations are then applied, to produce the standard names | |
2175 | that Exim expects. You can run these scripts directly from the shell in order | |
2176 | to find out what values are being used on your system. | |
2177 | ||
2178 | ||
2179 | \(OS/Makefile-Default)\ contains comments about the variables that are set | |
2180 | therein. Some (but not all) are mentioned below. If there is something that | |
2181 | needs changing, review the contents of this file and the contents of the make | |
2182 | file for your operating system (\(OS/Makefile-<<ostype>>)\) to see what the | |
2183 | default values are. | |
2184 | ||
2185 | ||
2186 | .index building Exim||overriding default settings | |
2187 | If you need to change any of the values that are set in \(OS/Makefile-Default)\ | |
4964e932 | 2188 | or in \(OS/Makefile-<<ostype>>)\, or to add any new definitions, you do not |
495ae4b0 PH |
2189 | need to change the original files. Instead, you should make the changes by |
2190 | putting the new values in an appropriate \(Local)\ file. For example, | |
2191 | .index Tru64-Unix build-time settings | |
2192 | when building Exim in many releases of the Tru64-Unix (formerly Digital UNIX, | |
2193 | formerly DEC-OSF1) operating system, it is necessary to specify that the C | |
4964e932 | 2194 | compiler is called \*cc*\ rather than \*gcc*\. Also, the compiler must be |
495ae4b0 | 2195 | called with the option \-std1-\, to make it recognize some of the features of |
4964e932 | 2196 | Standard C that Exim uses. (Most other compilers recognize Standard C by |
495ae4b0 PH |
2197 | default.) To do this, you should create a file called \(Local/Makefile-OSF1)\ |
2198 | containing the lines | |
2199 | .display | |
2200 | CC=cc | |
2201 | CFLAGS=-std1 | |
2202 | .endd | |
4964e932 | 2203 | If you are compiling for just one operating system, it may be easier to put |
495ae4b0 PH |
2204 | these lines directly into \(Local/Makefile)\. |
2205 | ||
2206 | Keeping all your local configuration settings separate from the distributed | |
2207 | files makes it easy to transfer them to new versions of Exim simply by copying | |
2208 | the contents of the \(Local)\ directory. | |
2209 | ||
2210 | ||
2211 | .index NIS lookup type||including support for | |
2212 | .index NIS@+ lookup type||including support for | |
2213 | .index LDAP||including support for | |
2214 | .index lookup||inclusion in binary | |
2215 | Exim contains support for doing LDAP, NIS, NIS+, and other kinds of file | |
2216 | lookup, but not all systems have these components installed, so the default is | |
2217 | not to include the relevant code in the binary. All the different kinds of file | |
2218 | and database lookup that Exim supports are implemented as separate code modules | |
2219 | which are included only if the relevant compile-time options are set. In the | |
2220 | case of LDAP, NIS, and NIS+, the settings for \(Local/Makefile)\ are: | |
2221 | .display asis | |
2222 | LOOKUP_LDAP=yes | |
2223 | LOOKUP_NIS=yes | |
2224 | LOOKUP_NISPLUS=yes | |
2225 | .endd | |
2226 | and similar settings apply to the other lookup types. They are all listed in | |
2227 | \(src/EDITME)\. In most cases the relevant include files and interface | |
2228 | libraries need to be installed before compiling Exim. | |
2229 | .index cdb||including support for | |
2230 | However, in the case of cdb, which is included in the binary only if | |
2231 | .display asis | |
2232 | LOOKUP_CDB=yes | |
2233 | .endd | |
2234 | is set, the code is entirely contained within Exim, and no external include | |
2235 | files or libraries are required. When a lookup type is not included in the | |
2236 | binary, attempts to configure Exim to use it cause run time configuration | |
2237 | errors. | |
2238 | ||
2239 | .index Perl||including support for | |
2240 | Exim can be linked with an embedded Perl interpreter, allowing Perl | |
2241 | subroutines to be called during string expansion. To enable this facility, | |
2242 | .display asis | |
2243 | EXIM_PERL=perl.o | |
2244 | .endd | |
2245 | must be defined in \(Local/Makefile)\. Details of this facility are given in | |
2246 | chapter ~~CHAPperl. | |
2247 | ||
2248 | .index X11 libraries, location of | |
2249 | The location of the X11 libraries is something that varies a lot between | |
2250 | operating systems, and of course there are different versions of X11 to cope | |
2251 | with. Exim itself makes no use of X11, but if you are compiling the Exim | |
2252 | monitor, the X11 libraries must be available. | |
2253 | The following three variables are set in \(OS/Makefile-Default)\: | |
2254 | .display asis | |
2255 | X11=/usr/X11R6 | |
2256 | XINCLUDE=-I$(X11)/include | |
2257 | XLFLAGS=-L$(X11)/lib | |
2258 | .endd | |
2259 | These are overridden in some of the operating-system configuration files. For | |
2260 | example, in \(OS/Makefile-SunOS5)\ there is | |
2261 | .display asis | |
2262 | X11=/usr/openwin | |
2263 | XINCLUDE=-I$(X11)/include | |
2264 | XLFLAGS=-L$(X11)/lib -R$(X11)/lib | |
2265 | .endd | |
2266 | If you need to override the default setting for your operating system, place a | |
2267 | definition of all three of these variables into your | |
2268 | \(Local/Makefile-<<ostype>>)\ file. | |
2269 | ||
2270 | .index \\EXTRALIBS\\ | |
2271 | If you need to add any extra libraries to the link steps, these can be put in a | |
2272 | variable called \\EXTRALIBS\\, which appears in all the link commands, but by | |
2273 | default is not defined. In contrast, \\EXTRALIBS@_EXIM\\ is used only on the | |
2274 | command for linking the main Exim binary, and not for any associated utilities. | |
2275 | .index DBM||libraries, configuration for building | |
2276 | There is also \\DBMLIB\\, which appears in the link commands for binaries that | |
2277 | use DBM functions (see also section ~~SECTdb). Finally, there is | |
2278 | \\EXTRALIBS@_EXIMON\\, which appears only in the link step for the Exim monitor | |
2279 | binary, and which can be used, for example, to include additional X11 | |
2280 | libraries. | |
2281 | ||
2282 | .index configuration file||editing | |
2283 | The make file copes with rebuilding Exim correctly if any of the configuration | |
2284 | files are edited. However, if an optional configuration file is deleted, it is | |
2285 | necessary to touch the associated non-optional file (that is, \(Local/Makefile)\ | |
2286 | or \(Local/eximon.conf)\) before rebuilding. | |
2287 | ||
2288 | .section OS-specific header files | |
2289 | .index \(os.h)\ | |
2290 | .index building Exim||OS-specific C header files | |
2291 | The \(OS)\ directory contains a number of files with names of the form | |
2292 | \(os.h-<<ostype>>)\. These are system-specific C header files that should not | |
2293 | normally need to be changed. There is a list of macro settings that are | |
2294 | recognized in the file \(OS/os.configuring)\, which should be consulted if you | |
2295 | are porting Exim to a new operating system. | |
2296 | ||
2297 | ||
2298 | .section Overriding build-time options for the monitor | |
2299 | .index building Eximon||overriding default options | |
2300 | A similar process is used for overriding things when building the Exim monitor, | |
2301 | where the files that are involved are | |
2302 | .display rm | |
2303 | \(OS/eximon.conf-Default)\ | |
2304 | \(OS/eximon.conf-)\<<ostype>> | |
2305 | \(Local/eximon.conf)\ | |
2306 | \(Local/eximon.conf-)\<<ostype>> | |
2307 | \(Local/eximon.conf-)\<<archtype>> | |
2308 | \(Local/eximon.conf-)\<<ostype>>-<<archtype>> | |
2309 | .endd | |
2310 | .index \(Local/eximon.conf)\ | |
2311 | As with Exim itself, the final three files need not exist, and in this case the | |
2312 | \(OS/eximon.conf-<<ostype>>)\ file is also optional. The default values in | |
2313 | \(OS/eximon.conf-Default)\ can be overridden dynamically by setting environment | |
2314 | variables of the same name, preceded by \\EXIMON@_\\. For example, setting | |
2315 | \\EXIMON@_LOG@_DEPTH\\ in the environment overrides the value of | |
2316 | \\LOG@_DEPTH\\ at run time. | |
2317 | ||
2318 | ||
2319 | ||
2320 | .section Installing Exim binaries and scripts | |
2321 | .index installing Exim | |
2322 | .index \\BIN@_DIRECTORY\\ | |
2323 | The command \*make install*\ runs the \*exim@_install*\ script with no | |
2324 | arguments. The script copies binaries and utility scripts into the directory | |
2325 | whose name is specified by the \\BIN@_DIRECTORY\\ setting in | |
4964e932 | 2326 | \(Local/Makefile)\. |
495ae4b0 PH |
2327 | |
2328 | Exim's run time configuration file is named by the \\CONFIGURE@_FILE\\ setting | |
2329 | .index \\CONFIGURE@_FILE\\ | |
2330 | in \(Local/Makefile)\. If this names a single file, and the file does not | |
2331 | exist, the default configuration file \(src/configure.default)\ is copied there | |
2332 | by the installation script. If a run time configuration file already exists, it | |
2333 | is left alone. If \\CONFIGURE@_FILE\\ is a colon-separated list, naming several | |
2334 | alternative files, no default is installed. | |
2335 | ||
2336 | .index system aliases file | |
2337 | .index \(/etc/aliases)\ | |
2338 | One change is made to the default configuration file when it is installed: the | |
2339 | default configuration contains a router that references a system aliases file. | |
2340 | The path to this file is set to the value specified by | |
2341 | \\SYSTEM@_ALIASES@_FILE\\ in \(Local/Makefile)\ (\(/etc/aliases)\ by default). | |
2342 | If the system aliases file does not exist, the installation script creates it, | |
2343 | and outputs a comment to the user. | |
2344 | ||
2345 | The created file contains no aliases, but it does contain comments about the | |
2346 | aliases a site should normally have. Mail aliases have traditionally been | |
2347 | kept in \(/etc/aliases)\. However, some operating systems are now using | |
2348 | \(/etc/mail/aliases)\. You should check if yours is one of these, and change | |
2349 | Exim's configuration if necessary. | |
2350 | ||
2351 | The default configuration uses the local host's name as the only local domain, | |
2352 | and is set up to do local deliveries into the shared directory \(/var/mail)\, | |
2353 | running as the local user. System aliases and \(.forward)\ files in users' home | |
2354 | directories are supported, but no NIS or NIS+ support is configured. Domains | |
2355 | other than the name of the local host are routed using the DNS, with delivery | |
2356 | over SMTP. | |
2357 | ||
2358 | The install script copies files only if they are newer than the files they are | |
2359 | going to replace. The Exim binary is required to be owned by root and have the | |
2360 | \*setuid*\ bit set, | |
2361 | .index setuid||installing Exim with | |
2362 | for normal configurations. Therefore, you must run \*make install*\ as root so | |
2363 | that it can set up the Exim binary in this way. However, in some special | |
2364 | situations (for example, if a host is doing no local deliveries) it may be | |
2365 | possible to run Exim without making the binary setuid root (see chapter | |
2366 | ~~CHAPsecurity for details). | |
2367 | ||
2368 | It is possible to install Exim for special purposes (such as building a binary | |
2369 | distribution) in a private part of the file system. You can do this by a | |
2370 | command such as | |
2371 | .display asis | |
2372 | make DESTDIR=/some/directory/ install | |
2373 | .endd | |
4964e932 PH |
2374 | This has the effect of pre-pending the specified directory to all the file |
2375 | paths, except the name of the system aliases file that appears in the default | |
495ae4b0 | 2376 | configuration. (If a default alias file is created, its name \*is*\ modified.) |
4964e932 | 2377 | For backwards compatibility, \\ROOT\\ is used if \\DESTDIR\\ is not set, |
495ae4b0 PH |
2378 | but this usage is deprecated. |
2379 | ||
2380 | .index installing Exim||what is not installed | |
2381 | Running \*make install*\ does not copy the Exim 4 conversion script | |
2382 | \*convert4r4*\, or the \*pcretest*\ test program. You will probably run the | |
2383 | first of these only once (if you are upgrading from Exim 3), and the second | |
2384 | isn't really part of Exim. None of the documentation files in the \(doc)\ | |
2385 | directory are copied, except for the info files when you have set | |
2386 | \\INFO@_DIRECTORY\\, as described in section ~~SECTinsinfdoc below. | |
2387 | ||
2388 | For the utility programs, old versions are renamed by adding the suffix \(.O)\ | |
2389 | to their names. The Exim binary itself, however, is handled differently. It is | |
2390 | installed under a name that includes the version number and the compile number, | |
2391 | for example \(exim-~~version-1)\. The script then arranges for a symbolic link | |
2392 | called \(exim)\ to point to the binary. If you are updating a previous version | |
2393 | of Exim, the script takes care to ensure that the name \(exim)\ is never absent | |
2394 | from the directory (as seen by other processes). | |
2395 | ||
2396 | .index installing Exim||testing the script | |
2397 | If you want to see what the \*make install*\ will do before running it for | |
2398 | real, you can pass the \-n-\ option to the installation script by this command: | |
2399 | .display asis | |
2400 | make INSTALL_ARG=-n install | |
2401 | .endd | |
2402 | The contents of the variable \\INSTALL@_ARG\\ are passed to the installation | |
2403 | script. You do not need to be root to run this test. Alternatively, you can run | |
2404 | the installation script directly, but this must be from within the build | |
2405 | directory. For example, from the top-level Exim directory you could use this | |
2406 | command: | |
2407 | .display | |
2408 | (cd build-SunOS5-5.5.1-sparc; ../scripts/exim@_install -n) | |
2409 | .endd | |
2410 | ||
2411 | .index installing Exim||install script options | |
2412 | There are two other options that can be supplied to the installation script. | |
2413 | .numberpars $. | |
2414 | \-no@_chown-\ bypasses the call to change the owner of the installed binary | |
2415 | to root, and the call to make it a setuid binary. | |
2416 | .nextp | |
2417 | \-no@_symlink-\ bypasses the setting up of the symbolic link \(exim)\ to the | |
2418 | installed binary. | |
2419 | .endp | |
2420 | \\INSTALL@_ARG\\ can be used to pass these options to the script. For example: | |
2421 | .display asis | |
2422 | make INSTALL_ARG=-no_symlink install | |
2423 | .endd | |
2424 | ||
4964e932 PH |
2425 | The installation script can also be given arguments specifying which files are |
2426 | to be copied. For example, to install just the Exim binary, and nothing else, | |
495ae4b0 PH |
2427 | without creating the symbolic link, you could use: |
2428 | .display asis | |
2429 | make INSTALL_ARG='-no_symlink exim' install | |
2430 | .endd | |
2431 | ||
2432 | ||
2433 | .section Installing info documentation | |
2434 | .rset SECTinsinfdoc "~~chapter.~~section" | |
2435 | .index installing Exim||\*info*\ documentation | |
2436 | Not all systems use the GNU \*info*\ system for documentation, and for this | |
2437 | reason, the Texinfo source of Exim's documentation is not included in the main | |
2438 | distribution. Instead it is available separately from the ftp site (see section | |
2439 | ~~SECTavail). | |
2440 | ||
2441 | If you have defined \\INFO@_DIRECTORY\\ in \(Local/Makefile)\ and the Texinfo | |
2442 | source of the documentation is found in the source tree, running \*make | |
2443 | install*\ automatically builds the info files and installs them. | |
2444 | ||
2445 | ||
2446 | .section Setting up the spool directory | |
2447 | .index spool directory||creating | |
2448 | When it starts up, Exim tries to create its spool directory if it does not | |
2449 | exist. The Exim uid and gid are used for the owner and group of the spool | |
2450 | directory. Sub-directories are automatically created in the spool directory as | |
2451 | necessary. | |
2452 | ||
2453 | ||
2454 | ||
2455 | .section Testing | |
2456 | .index testing||installation | |
2457 | Having installed Exim, you can check that the run time configuration file is | |
2458 | syntactically valid by running the following command, which assumes that the | |
2459 | Exim binary directory is within your \\PATH\\ environment variable: | |
2460 | .display | |
2461 | exim -bV | |
2462 | .endd | |
2463 | If there are any errors in the configuration file, Exim outputs error messages. | |
2464 | Otherwise it outputs the version number and build date, | |
4964e932 | 2465 | the DBM library that is being used, and information about which drivers and |
495ae4b0 PH |
2466 | other optional code modules are included in the binary. |
2467 | Some simple routing tests can be done by using the address testing option. For | |
2468 | example, | |
2469 | .display | |
2470 | exim -bt <<local username>> | |
2471 | .endd | |
2472 | should verify that it recognizes a local mailbox, and | |
2473 | .display | |
2474 | exim -bt <<remote address>> | |
2475 | .endd | |
2476 | a remote one. Then try getting it to deliver mail, both locally and remotely. | |
2477 | This can be done by passing messages directly to Exim, without going through a | |
2478 | user agent. For example: | |
2479 | .display | |
2480 | exim -v postmaster@@your.domain.example | |
2481 | From: user@@your.domain.example | |
2482 | To: postmaster@@your.domain.example | |
2483 | Subject: Testing Exim | |
2484 | ||
2485 | This is a test message. | |
2486 | ^D | |
2487 | .endd | |
2488 | The \-v-\ option causes Exim to output some verification of what it is doing. | |
2489 | In this case you should see copies of three log lines, one for the message's | |
2490 | arrival, one for its delivery, and one containing `Completed'. | |
2491 | ||
2492 | .index delivery||problems with | |
2493 | If you encounter problems, look at Exim's log files (\*mainlog*\ and | |
2494 | \*paniclog*\) to see if there is any relevant information there. Another source | |
2495 | of information is running Exim with debugging turned on, by specifying the | |
2496 | \-d-\ option. If a message is stuck on Exim's spool, you can force a delivery | |
2497 | with debugging turned on by a command of the form | |
2498 | .display | |
2499 | exim -d -M <<message-id>> | |
2500 | .endd | |
2501 | You must be root or an `admin user' in order to do this. The \-d-\ option | |
2502 | produces rather a lot of output, but you can cut this down to specific areas. | |
2503 | For example, if you use \-d-all+route-\ only the debugging information relevant | |
2504 | to routing is included. (See the \-d-\ option in chapter ~~CHAPcommandline for | |
2505 | more details.) | |
2506 | ||
2507 | .index `sticky' bit | |
2508 | .index lock files | |
2509 | One specific problem that has shown up on some sites is the inability to do | |
2510 | local deliveries into a shared mailbox directory, because it does not have the | |
2511 | `sticky bit' set on it. By default, Exim tries to create a lock file before | |
2512 | writing to a mailbox file, and if it cannot create the lock file, the delivery | |
2513 | is deferred. You can get round this either by setting the `sticky bit' on the | |
2514 | directory, or by setting a specific group for local deliveries and allowing | |
2515 | that group to create files in the directory (see the comments above the | |
2516 | \%local@_delivery%\ transport in the default configuration file). Another | |
2517 | approach is to configure Exim not to use lock files, but just to rely on | |
2518 | \*fcntl()*\ locking instead. However, you should do this only if all user | |
2519 | agents also use \*fcntl()*\ locking. For further discussion of locking issues, | |
2520 | see chapter ~~CHAPappendfile. | |
2521 | ||
2522 | One thing that cannot be tested on a system that is already running an MTA is | |
2523 | the receipt of incoming SMTP mail on the standard SMTP port. However, the | |
2524 | \-oX-\ option can be used to run an Exim daemon that listens on some other | |
2525 | port, or \*inetd*\ can be used to do this. The \-bh-\ option and the | |
2526 | \*exim@_checkaccess*\ utility can be used to check out policy controls on | |
2527 | incoming SMTP mail. | |
2528 | ||
2529 | Testing a new version on a system that is already running Exim can most easily | |
2530 | be done by building a binary with a different \\CONFIGURE@_FILE\\ setting. From | |
2531 | within the run time configuration, all other file and directory names | |
2532 | that Exim uses can be altered, in order to keep it entirely clear of the | |
2533 | production version. | |
2534 | ||
2535 | .section Replacing another MTA with Exim | |
2536 | .index replacing another MTA | |
2537 | Building and installing Exim for the first time does not of itself put it in | |
2538 | general use. The name by which the system's MTA is called by mail user agents | |
2539 | is either \(/usr/sbin/sendmail)\, or \(/usr/lib/sendmail)\ (depending on the | |
2540 | operating system), and it is necessary to make this name point to the \*exim*\ | |
2541 | binary in order to get the user agents to pass messages to Exim. This is | |
2542 | normally done by renaming any existing file and making \(/usr/sbin/sendmail)\ | |
2543 | or \(/usr/lib/sendmail)\ | |
2544 | .index symbolic link||to \*exim*\ binary | |
2545 | a symbolic link to the \*exim*\ binary. It is a good idea to remove any setuid | |
2546 | privilege and executable status from the old MTA. It is then necessary to stop | |
2547 | and restart the mailer daemon, if one is running. | |
2548 | ||
2549 | .index FreeBSD, MTA indirection | |
2550 | .index \(/etc/mail/mailer.conf)\ | |
2551 | Some operating systems have introduced alternative ways of switching MTAs. For | |
2552 | example, if you are running FreeBSD, you need to edit the file | |
2553 | \(/etc/mail/mailer.conf)\ instead of setting up a symbolic link as just | |
2554 | described. A typical example of the contents of this file for running Exim is | |
2555 | as follows: | |
2556 | .display asis | |
2557 | sendmail /usr/exim/bin/exim | |
2558 | send-mail /usr/exim/bin/exim | |
2559 | mailq /usr/exim/bin/exim -bp | |
2560 | newaliases /usr/bin/true | |
2561 | .endd | |
2562 | ||
2563 | Once you have set up the symbolic link, or edited \(/etc/mail/mailer.conf)\, | |
2564 | your Exim installation is `live'. Check it by sending a message from your | |
2565 | favourite user agent. | |
2566 | ||
2567 | You should consider what to tell your users about the change of MTA. Exim may | |
2568 | have different capabilities to what was previously running, and there are | |
2569 | various operational differences such as the text of messages produced by | |
2570 | command line options and in bounce messages. If you allow your users to make | |
2571 | use of Exim's filtering capabilities, you should make the document entitled | |
2572 | .if ~~html | |
2573 | [(A HREF="filter.html")] | |
2574 | .fi | |
2575 | \*Exim's interface to mail filtering*\ | |
2576 | .if ~~html | |
2577 | [(/A)] | |
2578 | .fi | |
2579 | available to them. | |
2580 | ||
2581 | ||
2582 | .section Upgrading Exim | |
2583 | .index upgrading Exim | |
2584 | If you are already running Exim on your host, building and installing a new | |
2585 | version automatically makes it available to MUAs, or any other programs that | |
2586 | call the MTA directly. However, if you are running an Exim daemon, you do need | |
2587 | to send it a HUP signal, to make it re-exec itself, and thereby pick up the new | |
2588 | binary. You do not need to stop processing mail in order to install a new | |
2589 | version of Exim. | |
2590 | ||
2591 | ||
2592 | .section Stopping the Exim daemon on Solaris | |
2593 | .index Solaris||stopping Exim on | |
2594 | The standard command for stopping the mailer daemon on Solaris is | |
2595 | .display | |
2596 | /etc/init.d/sendmail stop | |
2597 | .endd | |
2598 | If \(/usr/lib/sendmail)\ has been turned into a symbolic link, this script | |
2599 | fails to stop Exim because it uses the command \*ps -e*\ and greps the output | |
2600 | for the text `sendmail'; this is not present because the actual program name | |
2601 | (that is, `exim') is given by the \*ps*\ command with these options. A solution | |
2602 | is to replace the line that finds the process id with something like | |
2603 | .display asis | |
2604 | pid=`cat /var/spool/exim/exim-daemon.pid` | |
2605 | .endd | |
2606 | to obtain the daemon's pid directly from the file that Exim saves it in. | |
2607 | ||
4964e932 PH |
2608 | Note, however, that stopping the daemon does not `stop Exim'. Messages can |
2609 | still be received from local processes, and if automatic delivery is configured | |
495ae4b0 PH |
2610 | (the normal case), deliveries will still occur. |
2611 | ||
2612 | ||
2613 | . | |
2614 | . | |
2615 | . | |
2616 | . | |
2617 | . ============================================================================ | |
2618 | .chapter The Exim command line | |
2619 | .set runningfoot "command line" | |
2620 | .rset CHAPcommandline ~~chapter | |
2621 | .index command line||options | |
2622 | .index options||command line | |
2623 | ||
2624 | Exim's command line takes the standard Unix form of a sequence of options, | |
2625 | each starting with a hyphen character, followed by a number of arguments. The | |
2626 | options are compatible with the main options of Sendmail, and there are also | |
2627 | some additional options, some of which are compatible with Smail 3. Certain | |
2628 | combinations of options do not make sense, and provoke an error if used. | |
2629 | The form of the arguments depends on which options are set. | |
2630 | ||
2631 | .section Setting options by program name | |
2632 | .index \*mailq*\ | |
2633 | If Exim is called under the name \*mailq*\, it behaves as if the option \-bp-\ | |
4964e932 PH |
2634 | were present before any other options. |
2635 | The \-bp-\ option requests a listing of the contents of the mail queue on the | |
495ae4b0 PH |
2636 | standard output. |
2637 | This feature is for compatibility with some systems that contain a command of | |
2638 | that name in one of the standard libraries, symbolically linked to | |
2639 | \(/usr/sbin/sendmail)\ or \(/usr/lib/sendmail)\. | |
2640 | ||
2641 | .index \*rsmtp*\ | |
2642 | If Exim is called under the name \*rsmtp*\ it behaves as if the option \-bS-\ | |
2643 | were present before any other options, for compatibility with Smail. The \-bS-\ | |
2644 | option is used for reading in a number of messages in batched SMTP format. | |
2645 | ||
2646 | .index \*rmail*\ | |
2647 | If Exim is called under the name \*rmail*\ it behaves as if the \-i-\ and | |
2648 | \-oee-\ options were present before any other options, for compatibility with | |
2649 | Smail. The name \*rmail*\ is used as an interface by some UUCP systems. | |
2650 | ||
2651 | .index \*runq*\ | |
2652 | .index queue runner | |
2653 | If Exim is called under the name \*runq*\ it behaves as if the option \-q-\ were | |
2654 | present before any other options, for compatibility with Smail. The \-q-\ | |
2655 | option causes a single queue runner process to be started. | |
2656 | ||
2657 | .index \*newaliases*\ | |
2658 | .index alias file||building | |
2659 | .index Sendmail compatibility||calling Exim as \*newaliases*\ | |
2660 | If Exim is called under the name \*newaliases*\ it behaves as if the option | |
2661 | \-bi-\ were present before any other options, for compatibility with Sendmail. | |
2662 | This option is used for rebuilding Sendmail's alias file. Exim does not have | |
2663 | the concept of a single alias file, but can be configured to run a given | |
2664 | command if called with the \-bi-\ option. | |
2665 | ||
2666 | .section Trusted and admin users | |
2667 | .rset SECTtrustedadmin "~~chapter.~~section" | |
2668 | Some Exim options are available only to \*trusted users*\ and others are | |
2669 | available only to \*admin users*\. In the description below, the phrases `Exim | |
2670 | user' and `Exim group' mean the user and group defined by \\EXIM@_USER\\ and | |
2671 | \\EXIM@_GROUP\\ in \(Local/Makefile)\ or set by the \exim@_user\ and | |
2672 | \exim@_group\ options. These do not necessarily have to use the name `exim'. | |
2673 | ||
2674 | .numberpars $. | |
2675 | .index trusted user||definition of | |
2676 | .index user||trusted, definition of | |
2677 | The trusted users are root, the Exim user, any user listed in the | |
2678 | \trusted@_users\ configuration option, and any user whose current group or any | |
2679 | supplementary group is one of those listed in the \trusted@_groups\ | |
2680 | configuration option. Note that the Exim group is not automatically trusted. | |
2681 | ||
2682 | .index `From' line | |
2683 | .index envelope sender | |
2684 | Trusted users are always permitted to use the \-f-\ option or a leading `From ' | |
2685 | line to specify the envelope sender of a message that is passed to Exim through | |
2686 | the local interface (see the \-bm-\ and \-f-\ options below). See the | |
2687 | \untrusted@_set@_sender\ option for a way of permitting non-trusted users to | |
2688 | set envelope senders. | |
2689 | .index ::From:: header line | |
2690 | .index ::Sender:: header line | |
2691 | For a trusted user, there is never any check on the contents of the ::From:: | |
2692 | header line, and a ::Sender:: line is never added. Furthermore, any existing | |
2693 | ::Sender:: line in incoming local (non-TCP/IP) messages is not removed. | |
2694 | ||
2695 | Trusted users may also specify a host name, host address, interface address, | |
2696 | protocol name, ident value, and authentication data when submitting a message | |
2697 | locally. Thus, they are able to insert messages into Exim's queue locally that | |
2698 | have the characteristics of messages received from a remote host. Untrusted | |
2699 | users may in some circumstances use \-f-\, but can never set the other values | |
2700 | that are available to trusted users. | |
2701 | .nextp | |
2702 | .index user||admin, definition of | |
2703 | .index admin user||definition of | |
2704 | The admin users are root, the Exim user, and any user that is a member of the | |
2705 | Exim group or of any group listed in the \admin@_groups\ configuration option. | |
2706 | The current group does not have to be one of these groups. | |
2707 | ||
2708 | Admin users are permitted to list the queue, and to carry out certain | |
2709 | operations on messages, for example, to force delivery failures. It is also | |
2710 | necessary to be an admin user in order to see the full information provided by | |
2711 | the Exim monitor, and full debugging output. | |
2712 | ||
2713 | By default, the use of the \-M-\, \-q-\, \-R-\, and \-S-\ options to cause Exim | |
2714 | to attempt delivery of messages on its queue is restricted to admin users. | |
2715 | However, this restriction can be relaxed by setting the \prod@_requires@_admin\ | |
2716 | option false (that is, specifying \no@_prod@_requires@_admin\). | |
2717 | ||
2718 | Similarly, the use of the \-bp-\ option to list all the messages in the queue | |
2719 | is restricted to admin users unless \queue@_list@_requires@_admin\ is set | |
2720 | false. | |
2721 | .endp | |
2722 | ||
4964e932 PH |
2723 | \**Warning**\: If you configure your system so that admin users are able to |
2724 | edit Exim's configuration file, you are giving those users an easy way of | |
2725 | getting root. There is further discussion of this issue at the start of chapter | |
495ae4b0 PH |
2726 | ~~CHAPconf. |
2727 | ||
2728 | ||
2729 | ||
2730 | .section Command line options | |
2731 | The command options are described in alphabetical order below. | |
2732 | ||
2733 | .startoptions | |
2734 | ||
2735 | .option @- | |
2736 | .index options||command line, terminating | |
2737 | This is a pseudo-option whose only purpose is to terminate the options and | |
2738 | therefore to cause subsequent command line items to be treated as arguments | |
2739 | rather than options, even if they begin with hyphens. | |
2740 | ||
2741 | .option -help | |
2742 | This option causes Exim to output a few sentences stating what it is. | |
4964e932 | 2743 | The same output is generated if the Exim binary is called with no options and |
495ae4b0 PH |
2744 | no arguments. |
2745 | ||
2746 | .option B <<type>> | |
2747 | .index 8-bit characters | |
2748 | .index Sendmail compatibility||8-bit characters | |
2749 | This is a Sendmail option for selecting 7 or 8 bit processing. Exim is 8-bit | |
2750 | clean; it ignores this option. | |
2751 | ||
2752 | .option bd | |
2753 | .index daemon | |
2754 | .index SMTP listener | |
2755 | .index queue runner | |
2756 | This option runs Exim as a daemon, awaiting incoming SMTP connections. Usually | |
2757 | the \-bd-\ option is combined with the \-q-\<<time>> option, to specify that | |
2758 | the daemon should also initiate periodic queue runs. | |
2759 | ||
2760 | The \-bd-\ option can be used only by an admin user. If either of the \-d-\ | |
2761 | (debugging) or \-v-\ (verifying) options are set, the daemon does not | |
2762 | disconnect from the controlling terminal. When running this way, it can be | |
2763 | stopped by pressing ctrl-C. | |
2764 | ||
2765 | By default, Exim listens for incoming connections to the standard SMTP port on | |
2766 | all the host's running interfaces. However, it is possible to listen on other | |
2767 | ports, on multiple ports, and only on specific interfaces. Chapter | |
2768 | ~~CHAPinterfaces contains a description of the options that control this. | |
2769 | ||
2770 | .index daemon||process id (pid) | |
2771 | .index pid (process id)||of daemon | |
2772 | When a listening daemon is started without the use of \-oX-\ (that is, without | |
2773 | overriding the normal configuration), it writes its process id to a file called | |
2774 | \(exim-daemon.pid)\ in Exim's spool directory. This location can be overridden | |
2775 | by setting \\PID@_FILE@_PATH\\ in \(Local/Makefile)\. The file is written while | |
2776 | Exim is still running as root. | |
2777 | ||
2778 | When \-oX-\ is used on the command line to start a listening daemon, the | |
2779 | process id is not written to the normal pid file path. However, \-oP-\ can be | |
2780 | used to specify a path on the command line if a pid file is required. | |
2781 | ||
2782 | .index \\SIGHUP\\ | |
2783 | The \\SIGHUP\\ signal can be used to cause the daemon to re-exec itself. This | |
2784 | should be done whenever Exim's configuration file, or any file that is | |
4964e932 | 2785 | incorporated into it by means of the \.include\ facility, is changed, and also |
495ae4b0 PH |
2786 | whenever a new version of Exim is installed. It is not necessary to do this |
2787 | when other files that are referenced from the configuration (for example, alias | |
2788 | files) are changed, because these are reread each time they are used. | |
2789 | ||
2790 | .option bdf | |
2791 | This option has the same effect as \-bd-\ except that it never disconnects from | |
2792 | the controlling terminal, even when no debugging is specified. | |
2793 | ||
2794 | .option be | |
2795 | .index testing||string expansion | |
2796 | .index expansion||testing | |
2797 | Run Exim in expansion testing mode. Exim discards its root privilege, to | |
2798 | prevent ordinary users from using this mode to read otherwise inaccessible | |
2799 | files. If no arguments are given, Exim runs interactively, prompting for lines | |
d43194df PH |
2800 | of data. |
2801 | .em | |
2802 | If Exim was built with \\USE@_READLINE\\=yes in \(Local/Makefile)\, it tries | |
2803 | to load the \libreadline\ library dynamically whenever the \-be-\ option is | |
2804 | used without command line arguments. If successful, it uses the \*readline()*\ | |
2805 | function, which provides extensive line-editing facilities, for reading the | |
2806 | test data. A line history is supported. | |
2807 | .nem | |
495ae4b0 | 2808 | |
d43194df PH |
2809 | Long expansion expressions can be split over several lines by using backslash |
2810 | continuations. As in Exim's run time configuration, whitespace at the start of | |
2811 | continuation lines is ignored. Each argument or data line is passed through the | |
2812 | string expansion mechanism, and the result is output. Variable values from the | |
2813 | configuration file (for example, \$qualify@_domain$\) are available, but no | |
2814 | message-specific values (such as \$domain$\) are set, because no message is | |
2815 | being processed. | |
495ae4b0 PH |
2816 | |
2817 | .option bF #<<filename>> | |
2818 | .index system filter||testing | |
2819 | .index testing||system filter | |
2820 | This option is the same as \-bf-\ except that it assumes that the filter being | |
2821 | tested is a system filter. The additional commands that are available only in | |
2822 | system filters are recognized. | |
2823 | ||
2824 | .option bf #<<filename>> | |
2825 | .index filter||testing | |
2826 | .index testing||filter file | |
2827 | .index forward file||testing | |
2828 | .index testing||forward file | |
2829 | .index Sieve filter||testing | |
d43194df PH |
2830 | This option runs Exim in user filter testing mode; the file is the filter file |
2831 | to be tested, and a test message must be supplied on the standard input. If | |
2832 | there are no message-dependent tests in the filter, an empty file can be | |
2833 | supplied. | |
2834 | .em | |
2835 | If you want to test a system filter file, use \-bF-\ instead of \-bf-\. You can | |
2836 | use both \-bF-\ and \-bf-\ on the same command, in order to | |
2837 | test a system filter and a user filter in the same run. For example: | |
2838 | .display asis | |
2839 | exim -bF /system/filter -bf /user/filter </test/message | |
2840 | .endd | |
2841 | This is helpful when the system filter adds header lines or sets filter | |
2842 | variables that are used by the user filter. | |
2843 | .nem | |
2844 | ||
2845 | If the test filter file does not begin with one of the special lines | |
495ae4b0 PH |
2846 | .display asis |
2847 | # Exim filter | |
2848 | # Sieve filter | |
2849 | .endd | |
2850 | it is taken to be a normal \(.forward)\ file, and is tested for validity under | |
4964e932 | 2851 | that interpretation. See sections ~~SECTitenonfilred to ~~SECTspecitredli for a |
495ae4b0 PH |
2852 | description of the possible contents of non-filter redirection lists. |
2853 | ||
2854 | The result of an Exim command that uses \-bf-\, provided no errors are | |
2855 | detected, is a list of the actions that Exim would try to take if presented | |
2856 | with the message for real. More details of filter testing are given in the | |
2857 | separate document entitled \*Exim's interfaces to mail filtering*\. | |
2858 | ||
2859 | .index `From' line | |
2860 | .index envelope sender | |
2861 | .index \-f-\ option||for filter testing | |
2862 | When testing a filter file, the envelope sender can be set by the \-f-\ option, | |
2863 | or by a `From ' line at the start of the test message. Various parameters that | |
2864 | would normally be taken from the envelope recipient address of the message can | |
d43194df PH |
2865 | be set by means of additional command line options (see the next four options). |
2866 | ||
2867 | .em | |
2868 | .option bfd #<<domain>> | |
2869 | This sets the domain of the recipient address when a filter file is being | |
2870 | tested by means of the \-bf-\ option. The default is the value of | |
2871 | \$qualify@_domain$\. | |
2872 | ||
2873 | .option bfl #<<local part>> | |
2874 | This sets the local part of the recipient address when a filter file is being | |
2875 | tested by means of the \-bf-\ option. The default is the username of the | |
2876 | process that calls Exim. A local part should be specified with any prefix or | |
495ae4b0 PH |
2877 | suffix stripped, because that is how it appears to the filter when a message is |
2878 | actually being delivered. | |
2879 | ||
d43194df PH |
2880 | .option bfp #<<prefix>> |
2881 | This sets the prefix of the local part of the recipient address when a filter | |
2882 | file is being tested by means of the \-bf-\ option. The default is an empty | |
2883 | prefix. | |
2884 | ||
2885 | .option bfp #<<suffix>> | |
2886 | This sets the suffix of the local part of the recipient address when a filter | |
2887 | file is being tested by means of the \-bf-\ option. The default is an empty | |
2888 | suffix. | |
2889 | .em | |
2890 | ||
2891 | ||
495ae4b0 PH |
2892 | .option bh #<<IP address>> |
2893 | .index testing||incoming SMTP | |
2894 | .index SMTP||testing incoming | |
2895 | .index testing||relay control | |
2896 | .index relaying||testing configuration | |
2897 | .index policy control||testing | |
2898 | .index debugging||\-bh-\ option | |
2899 | This option runs a fake SMTP session as if from the given IP address, using the | |
2900 | standard input and output. The IP address may include a port number at the end, | |
2901 | after a full stop. For example: | |
2902 | .display asis | |
2903 | exim -bh 10.9.8.7.1234 | |
2904 | exim -bh fe80::a00:20ff:fe86:a061.5678 | |
2905 | .endd | |
d43194df PH |
2906 | .em |
2907 | When an IPv6 address is given, it is converted into canonical form. In the case | |
2908 | of the second example above, the value of \$sender@_host@_address$\ after | |
2909 | conversion to the canonical form is \"fe80:0000:0000:0a00:20ff:fe86:a061.5678"\. | |
2910 | .nem | |
2911 | ||
495ae4b0 PH |
2912 | Comments as to what is going on are written to the standard error file. These |
2913 | include lines beginning with `LOG' for anything that would have been logged. | |
4964e932 PH |
2914 | This facility is provided for testing configuration options for incoming |
2915 | messages, to make sure they implement the required policy. For example, you can | |
495ae4b0 PH |
2916 | test your relay controls using \-bh-\. |
2917 | ||
2918 | .index RFC 1413 | |
2919 | \**Warning 1**\: You cannot test features of the configuration that rely on | |
2920 | ident (RFC 1413) callouts. These cannot be done when testing using | |
2921 | \-bh-\ because there is no incoming SMTP connection. | |
2922 | ||
2923 | \**Warning 2**\: Address verification callouts (see section ~~SECTcallver) are | |
4964e932 | 2924 | also skipped when testing using \-bh-\. If you want these callouts to occur, |
495ae4b0 PH |
2925 | use \-bhc-\ instead. |
2926 | ||
2927 | Messages supplied during the testing session are discarded, and nothing is | |
2928 | written to any of the real log files. There may be pauses when DNS (and other) | |
2929 | lookups are taking place, and of course these may time out. The \-oMi-\ option | |
2930 | can be used to specify a specific IP interface and port if this is important. | |
2931 | ||
2932 | The \*exim@_checkaccess*\ utility is a `packaged' version of \-bh-\ whose | |
2933 | output just states whether a given recipient address from a given host is | |
2934 | acceptable or not. See section ~~SECTcheckaccess. | |
2935 | ||
2936 | .option bhc #<<IP address>> | |
4964e932 PH |
2937 | This option operates in the same way as \-bh-\, except that address |
2938 | verification callouts are performed if required. This includes consulting and | |
2939 | updating the callout cache database. | |
495ae4b0 PH |
2940 | |
2941 | .option bi | |
2942 | .index alias file||building | |
2943 | .index building alias file | |
2944 | .index Sendmail compatibility||\-bi-\ option | |
2945 | Sendmail interprets the \-bi-\ option as a request to rebuild its alias file. | |
2946 | Exim does not have the concept of a single alias file, and so it cannot mimic | |
2947 | this behaviour. However, calls to \(/usr/lib/sendmail)\ with the \-bi-\ option | |
2948 | tend to appear in various scripts such as NIS make files, so the option must be | |
2949 | recognized. | |
2950 | ||
2951 | If \-bi-\ is encountered, the command specified by the \bi@_command\ | |
2952 | configuration option is run, under the uid and gid of the caller of Exim. If | |
2953 | the \-oA-\ option is used, its value is passed to the command as an argument. | |
2954 | The command set by \bi@_command\ may not contain arguments. The command can use | |
2955 | the \*exim@_dbmbuild*\ utility, or some other means, to rebuild alias files if | |
2956 | this is required. If the \bi@_command\ option is not set, calling Exim with | |
2957 | \-bi-\ is a no-op. | |
2958 | ||
2959 | .option bm | |
2960 | .index local message reception | |
2961 | This option runs an Exim receiving process that accepts an incoming, | |
2962 | locally-generated message on the current input. The recipients are given as the | |
2963 | command arguments (except when \-t-\ is also present -- see below). Each | |
2964 | argument can be a comma-separated list of RFC 2822 addresses. This is the | |
2965 | default option for selecting the overall action of an Exim call; it is assumed | |
2966 | if no other conflicting option is present. | |
2967 | ||
2968 | If any addresses in the message are unqualified (have no domain), they are | |
2969 | qualified by the values of the \qualify@_domain\ or \qualify@_recipient\ | |
2970 | options, as appropriate. The \-bnq-\ option (see below) provides a way of | |
2971 | suppressing this for special cases. | |
2972 | ||
4964e932 | 2973 | Policy checks on the contents of local messages can be enforced by means of the |
495ae4b0 PH |
2974 | non-SMTP ACL. See chapter ~~CHAPACL for details. |
2975 | .index return code||for \-bm-\ | |
2976 | The return code is zero if the message is successfully accepted. Otherwise, the | |
2977 | action is controlled by the \-oe$it{x}-\ option setting -- see below. | |
2978 | ||
2979 | .index message||format | |
2980 | .index format||message | |
2981 | .index `From' line | |
2982 | .index UUCP||`From' line | |
2983 | .index Sendmail compatibility||`From' line | |
2984 | The format of the message must be as defined in RFC 2822, except that, for | |
2985 | compatibility with Sendmail and Smail, a line in one of the forms | |
2986 | .display | |
2987 | From sender Fri Jan 5 12:55 GMT 1997 | |
2988 | From sender Fri, 5 Jan 97 12:55:01 | |
2989 | .endd | |
2990 | (with the weekday optional, and possibly with additional text after the date) | |
2991 | is permitted to appear at the start of the message. There appears to be no | |
2992 | authoritative specification of the format of this line. Exim recognizes it by | |
2993 | matching against the regular expression defined by the \uucp@_from@_pattern\ | |
4964e932 | 2994 | option, which can be changed if necessary. |
495ae4b0 PH |
2995 | .index \-f-\ option||overriding `From' line |
2996 | The specified sender is treated as if it were given as the argument to the | |
2997 | \-f-\ option, but if a \-f-\ option is also present, its argument is used in | |
2998 | preference to the address taken from the message. The caller of Exim must be a | |
2999 | trusted user for the sender of a message to be set in this way. | |
3000 | ||
3001 | .option bnq | |
3002 | .index address||qualification, suppressing | |
3003 | By default, Exim automatically qualifies unqualified addresses (those | |
3004 | without domains) that appear in messages that are submitted locally (that | |
3005 | is, not over TCP/IP). This qualification applies both to addresses in | |
4964e932 PH |
3006 | envelopes, and addresses in header lines. Sender addresses are qualified using |
3007 | \qualify@_domain\, and recipient addresses using \qualify@_recipient\ (which | |
495ae4b0 PH |
3008 | defaults to the value of \qualify@_domain\). |
3009 | ||
3010 | Sometimes, qualification is not wanted. For example, if \-bS-\ (batch SMTP) is | |
3011 | being used to re-submit messages that originally came from remote hosts after | |
3012 | content scanning, you probably do not want to qualify unqualified addresses in | |
3013 | header lines. (Such lines will be present only if you have not enabled a header | |
3014 | syntax check in the appropriate ACL.) | |
3015 | ||
3016 | The \-bnq-\ option suppresses all qualification of unqualified addresses in | |
3017 | messages that originate on the local host. When this is used, unqualified | |
3018 | addresses in the envelope provoke errors (causing message rejection) and | |
3019 | unqualified addresses in header lines are left alone. | |
3020 | ||
3021 | ||
3022 | .option bP | |
3023 | .index configuration options, extracting | |
3024 | .index options||configuration, extracting | |
3025 | If this option is given with no arguments, it causes the values of all Exim's | |
3026 | main configuration options to be written to the standard output. The values | |
3027 | of one or more specific options can be requested by giving their names as | |
3028 | arguments, for example: | |
3029 | .display | |
3030 | exim -bP qualify@_domain hold@_domains | |
3031 | .endd | |
3032 | However, any option setting that is preceded by the word `hide' in the | |
3033 | configuration file is not shown in full, except to an admin user. For other | |
3034 | users, the output is as in this example: | |
3035 | .display asis | |
3036 | mysql_servers = <value not displayable> | |
3037 | .endd | |
3038 | If \configure@_file\ is given as an argument, the name of the run time | |
3039 | configuration file is output. | |
4964e932 | 3040 | If a list of configuration files was supplied, the value that is output here |
495ae4b0 PH |
3041 | is the name of the file that was actually used. |
3042 | ||
3043 | .index daemon||process id (pid) | |
3044 | .index pid (process id)||of daemon | |
3045 | If \log__file__path\ or \pid@_file@_path\ are given, the names of the | |
3046 | directories where log files and daemon pid files are written are output, | |
3047 | respectively. If these values are unset, log files are written in a | |
3048 | sub-directory of the spool directory called \log\, and the pid file is written | |
3049 | directly into the spool directory. | |
3050 | ||
3051 | If \-bP-\ is followed by a name preceded by \"+"\, for example, | |
3052 | .display asis | |
3053 | exim -bP +local_domains | |
3054 | .endd | |
3055 | it searches for a matching named list of any type (domain, host, address, or | |
3056 | local part) and outputs what it finds. | |
3057 | ||
3058 | .index options||router, extracting | |
3059 | .index options||transport, extracting | |
3060 | If one of the words \router\, \transport\, or \authenticator\ is given, | |
3061 | followed by the name of an appropriate driver instance, the option settings for | |
3062 | that driver are output. For example: | |
3063 | .display | |
3064 | exim -bP transport local@_delivery | |
3065 | .endd | |
3066 | The generic driver options are output first, followed by the driver's private | |
3067 | options. A list of the names of drivers of a particular type can be obtained by | |
3068 | using one of the words \router@_list\, \transport@_list\, or | |
3069 | \authenticator@_list\, and a complete list of all drivers with their option | |
3070 | settings can be obtained by using \routers\, \transports\, or \authenticators\. | |
3071 | ||
3072 | ||
3073 | .option bp | |
3074 | .index queue||listing messages on | |
3075 | .index listing||messages on the queue | |
3076 | This option requests a listing of the contents of the mail queue on the | |
3077 | standard output. If the \-bp-\ option is followed by a list of message ids, | |
3078 | just those messages are listed. By default, this option can be used only by an | |
3079 | admin user. However, the \queue__list__requires__admin\ option can be set false | |
3080 | to allow any user to see the queue. | |
3081 | ||
3082 | Each message on the queue is displayed as in the following example: | |
3083 | .display | |
3084 | 25m 2.9K 0t5C6f-0000c8-00 <alice@@wonderland.fict.example> | |
3085 | red.king@@looking-glass.fict.example | |
3086 | <<other addresses>> | |
3087 | .endd | |
3088 | .index message||size in queue listing | |
3089 | .index size||of message | |
3090 | The first line contains the length of time the message has been on the queue | |
3091 | (in this case 25 minutes), the size of the message (2.9K), the unique local | |
3092 | identifier for the message, and the message sender, as contained in the | |
3093 | envelope. For bounce messages, the sender address is empty, and appears as | |
3094 | `<>'. If the message was submitted locally by an untrusted user who overrode | |
3095 | the default sender address, the user's login name is shown in parentheses | |
3096 | before the sender address. | |
3097 | .index frozen messages||in queue listing | |
3098 | If the message is frozen (attempts to deliver it are suspended) then the text | |
3099 | `$*$$*$$*$ frozen $*$$*$$*$' is displayed at the end of this line. | |
3100 | ||
3101 | The recipients of the message (taken from the envelope, not the headers) are | |
3102 | displayed on subsequent lines. Those addresses to which the message has already | |
3103 | been delivered are marked with the letter D. If an original address gets | |
3104 | expanded into several addresses via an alias or forward file, the original is | |
3105 | displayed with a D only when deliveries for all of its child addresses are | |
3106 | complete. | |
3107 | ||
3108 | ||
3109 | .option bpa | |
3110 | This option operates like \-bp-\, but in addition it shows delivered addresses | |
3111 | that were generated from the original top level address(es) in each message by | |
3112 | alias or forwarding operations. These addresses are flagged with `+D' instead | |
3113 | of just `D'. | |
3114 | ||
3115 | ||
3116 | .option bpc | |
3117 | .index queue||count of messages on | |
3118 | This option counts the number of messages on the queue, and writes the total | |
3119 | to the standard output. It is restricted to admin users, unless | |
3120 | \queue__list__requires__admin\ is set false. | |
3121 | ||
3122 | ||
3123 | .option bpr | |
3124 | This option operates like \-bp-\, but the output is not sorted into | |
3125 | chronological order of message arrival. This can speed it up when there are | |
3126 | lots of messages on the queue, and is particularly useful if the output is | |
3127 | going to be post-processed in a way that doesn't need the sorting. | |
3128 | ||
3129 | .option bpra | |
3130 | This option is a combination of \-bpr-\ and \-bpa-\. | |
3131 | ||
3132 | .option bpru | |
3133 | This option is a combination of \-bpr-\ and \-bpu-\. | |
3134 | ||
3135 | ||
3136 | .option bpu | |
3137 | This option operates like \-bp-\ but shows only undelivered top-level addresses | |
3138 | for each message displayed. Addresses generated by aliasing or forwarding are | |
3139 | not shown, unless the message was deferred after processing by a router with | |
3140 | the \one@_time\ option set. | |
3141 | ||
3142 | ||
3143 | .option brt | |
3144 | .index testing||retry configuration | |
3145 | .index retry||configuration testing | |
3146 | This option is for testing retry rules, and it must be followed by up to three | |
3147 | arguments. It causes Exim to look for a retry rule that matches the values | |
3148 | and to write it to the standard output. For example: | |
3149 | .display asis | |
3150 | exim -brt bach.comp.mus.example | |
3151 | Retry rule: *.comp.mus.example F,2h,15m; F,4d,30m; | |
3152 | .endd | |
3153 | See chapter ~~CHAPretry for a description of Exim's retry rules. The first | |
3154 | argument, which is required, can be a complete address in the form | |
3155 | \*local@_part@@domain*\, or it can be just a domain name. The second argument is | |
3156 | an optional second domain name; if no retry rule is found for the first | |
3157 | argument, the second is tried. This ties in with Exim's behaviour when looking | |
3158 | for retry rules for remote hosts -- if no rule is found that matches the host, | |
3159 | one that matches the mail domain is sought. The final argument is the name of a | |
3160 | specific delivery error, as used in setting up retry rules, for example | |
3161 | `quota@_3d'. | |
3162 | ||
3163 | .option brw | |
3164 | .index testing||rewriting | |
3165 | .index rewriting||testing | |
3166 | This option is for testing address rewriting rules, and it must be followed by | |
3167 | a single argument, consisting of either a local part without a domain, or a | |
3168 | complete address with a fully qualified domain. Exim outputs how this address | |
3169 | would be rewritten for each possible place it might appear. See chapter | |
3170 | ~~CHAPrewrite for further details. | |
3171 | ||
3172 | .option bS | |
3173 | .index SMTP||batched incoming | |
3174 | .index batched SMTP input | |
3175 | This option is used for batched SMTP input, which is an alternative interface | |
3176 | for non-interactive local message submission. A number of messages can be | |
3177 | submitted in a single run. However, despite its name, this is not really SMTP | |
3178 | input. Exim reads each message's envelope from SMTP commands on the standard | |
3179 | input, but generates no responses. If the caller is trusted, or | |
3180 | \untrusted@_set@_sender\ is set, the senders in the SMTP \\MAIL\\ commands are | |
3181 | believed; otherwise the sender is always the caller of Exim. | |
3182 | ||
3183 | The message itself is read from the standard input, in SMTP format (leading | |
3184 | dots doubled), terminated by a line containing just a single dot. An error is | |
3185 | provoked if the terminating dot is missing. A further message may then follow. | |
3186 | ||
3187 | As for other local message submissions, the contents of incoming batch SMTP | |
3188 | messages can be checked using the non-SMTP ACL (see chapter ~~CHAPACL). | |
3189 | Unqualified addresses are automatically qualified using \qualify@_domain\ and | |
3190 | \qualify@_recipient\, as appropriate, unless the \-bnq-\ option is used. | |
3191 | ||
3192 | Some other SMTP commands are recognized in the input. \\HELO\\ and \\EHLO\\ act | |
3193 | as \\RSET\\; \\VRFY\\, \\EXPN\\, \\ETRN\\, and \\HELP\\ act as \\NOOP\\; | |
3194 | \\QUIT\\ quits, ignoring the rest of the standard input. | |
3195 | ||
3196 | If any error is encountered, reports are written to the standard output and | |
3197 | error streams, and Exim gives up immediately. | |
3198 | .index return code||for \-bS-\ | |
3199 | The return code is 0 if no error was detected; it is 1 if one or more messages | |
3200 | were accepted before the error was detected; otherwise it is 2. | |
3201 | ||
3202 | More details of input using batched SMTP are given in section | |
3203 | ~~SECTincomingbatchedSMTP. | |
3204 | ||
3205 | .option bs | |
3206 | .index SMTP||local input | |
3207 | .index local SMTP input | |
3208 | This option causes Exim to accept one or more messages by reading SMTP commands | |
3209 | on the standard input, and producing SMTP replies on the standard output. SMTP | |
4964e932 | 3210 | policy controls, as defined in ACLs (see chapter ~~CHAPACL) are applied. |
495ae4b0 PH |
3211 | |
3212 | Some user agents use this interface as a way of passing locally-generated | |
3213 | messages to the MTA. | |
3214 | .index sender||source of | |
3215 | In this usage, if the caller of Exim is trusted, or \untrusted@_set@_sender\ is | |
3216 | set, the senders of messages are taken from the SMTP \\MAIL\\ commands. | |
3217 | Otherwise the content of these commands is ignored and the sender is set up as | |
3218 | the calling user. Unqualified addresses are automatically qualified using | |
3219 | \qualify@_domain\ and \qualify@_recipient\, as appropriate, unless the \-bnq-\ | |
3220 | option is used. | |
3221 | ||
3222 | .index inetd | |
3223 | The \-bs-\ option is also used to run Exim from \*inetd*\, as an alternative to | |
3224 | using a listening daemon. Exim can distinguish the two cases by checking | |
4964e932 PH |
3225 | whether the standard input is a TCP/IP socket. When Exim is called from |
3226 | \*inetd*\, the source of the mail is assumed to be remote, and the comments | |
3227 | above concerning senders and qualification do not apply. In this situation, | |
3228 | Exim behaves in exactly the same way as it does when receiving a message via | |
495ae4b0 PH |
3229 | the listening daemon. |
3230 | ||
3231 | .option bt | |
3232 | .index testing||addresses | |
3233 | .index address||testing | |
3234 | This option runs Exim in address testing mode, in which each argument is taken | |
3235 | as an address to be tested for deliverability. The results are written to the | |
d43194df PH |
3236 | standard output. If a test fails, and the caller is not an admin user, no |
3237 | details of the failure are output, because these might contain sensitive | |
3238 | information such as usernames and passwords for database lookups. | |
495ae4b0 PH |
3239 | |
3240 | If no arguments are given, Exim runs in an interactive manner, prompting with a | |
d43194df PH |
3241 | right angle bracket for addresses to be tested. |
3242 | .em | |
3243 | Unlike the \-be-\ test option, you cannot arrange for Exim to use the | |
3244 | \*readline()*\ function, because it is running as \*root*\ and there are | |
3245 | security issues. | |
3246 | .nem | |
3247 | ||
3248 | Each address is handled as if it were the recipient address of a message | |
3249 | (compare the \-bv-\ option). It is passed to the routers and the result is | |
3250 | written to the standard output. However, any router that has | |
3251 | \no@_address@_test\ set is bypassed. This can make \-bt-\ easier to use for | |
3252 | genuine routing tests if your first router passes everything to a scanner | |
3253 | program. | |
495ae4b0 PH |
3254 | |
3255 | .index return code||for \-bt-\ | |
3256 | The return code is 2 if any address failed outright; it is 1 if no address | |
3257 | failed outright but at least one could not be resolved for some reason. Return | |
3258 | code 0 is given only when all addresses succeed. | |
3259 | ||
3260 | \**Warning**\: \-bt-\ can only do relatively simple testing. If any of the | |
3261 | routers in the configuration makes any tests on the sender address of a | |
4964e932 | 3262 | message, |
495ae4b0 PH |
3263 | .index \-f-\ option||for address testing |
3264 | you can use the \-f-\ option to set an appropriate sender when running | |
3265 | \-bt-\ tests. Without it, the sender is assumed to be the calling user at the | |
3266 | default qualifying domain. However, if you have set up (for example) routers | |
3267 | whose behaviour depends on the contents of an incoming message, you cannot test | |
3268 | those conditions using \-bt-\. The \-N-\ option provides a possible way of | |
3269 | doing such tests. | |
3270 | ||
3271 | .option bV | |
3272 | .index version number of Exim, verifying | |
3273 | This option causes Exim to write the current version number, compilation | |
3274 | number, and compilation date of the \*exim*\ binary to the standard output. | |
3275 | It also lists the DBM library this is being used, the optional modules (such as | |
3276 | specific lookup types), the drivers that are included in the binary, and the | |
3277 | name of the run time configuration file that is in use. | |
3278 | ||
d43194df PH |
3279 | .em |
3280 | As part of its operation, \-bV-\ causes Exim to read and syntax check its | |
3281 | configuration file. However, this is a static check only. It cannot check | |
8408f763 PH |
3282 | values that are to be expanded. For example, although a misspelt ACL verb is |
3283 | detected, an error in the verb's arguments is not. You cannot rely on \-bV-\ | |
3284 | alone to discover (for example) all the typos in the configuration; some | |
3285 | realistic testing is needed. The \-bh-\ and \-N-\ options provide more dynamic | |
3286 | testing facilities. | |
d43194df PH |
3287 | .nem |
3288 | ||
3289 | ||
495ae4b0 PH |
3290 | .option bv |
3291 | .index verifying||address, using \-bv-\ | |
3292 | .index address||verification | |
3293 | This option runs Exim in address verification mode, in which each argument is | |
3294 | taken as an address to be verified. During normal operation, verification | |
3295 | happens mostly as a consequence processing a \verify\ condition in an ACL (see | |
3296 | chapter ~~CHAPACL). If you want to test an entire ACL, see the \-bh-\ option. | |
3297 | ||
3298 | If verification fails, and the caller is not an admin user, no details of the | |
3299 | failure are output, because these might contain sensitive information such as | |
3300 | usernames and passwords for database lookups. | |
3301 | ||
3302 | If no arguments are given, Exim runs in an interactive manner, prompting with a | |
d43194df PH |
3303 | right angle bracket for addresses to be verified. |
3304 | .em | |
3305 | Unlike the \-be-\ test option, you cannot arrange for Exim to use the | |
3306 | \*readline()*\ function, because it is running as \*exim*\ and there are | |
3307 | security issues. | |
3308 | .nem | |
3309 | ||
3310 | Verification differs from address testing (the \-bt-\ option) in that routers | |
3311 | that have \no@_verify\ set are skipped, and if the address is accepted by a | |
3312 | router that has \fail@_verify\ set, verification fails. The address is verified | |
3313 | as a recipient if \-bv-\ is used; to test verification for a sender address, | |
3314 | \-bvs-\ should be used. | |
495ae4b0 PH |
3315 | |
3316 | If the \-v-\ option is not set, the output consists of a single line for each | |
3317 | address, stating whether it was verified or not, and giving a reason in the | |
3318 | latter case. Otherwise, more details are given of how the address has been | |
3319 | handled, and in the case of address redirection, all the generated addresses | |
3320 | are also considered. Without \-v-\, generating more than one address by | |
3321 | redirection causes verification to end sucessfully. | |
3322 | ||
3323 | .index return code||for \-bv-\ | |
3324 | The return code is 2 if any address failed outright; it is 1 if no address | |
3325 | failed outright but at least one could not be resolved for some reason. Return | |
3326 | code 0 is given only when all addresses succeed. | |
3327 | ||
3328 | If any of the routers in the configuration makes any tests on the sender | |
3329 | address of a message, you should use the \-f-\ option to set an appropriate | |
3330 | sender when running \-bv-\ tests. Without it, the sender is assumed to be the | |
3331 | calling user at the default qualifying domain. | |
3332 | ||
3333 | .option bvs | |
3334 | This option acts like \-bv-\, but verifies the address as a sender rather | |
3335 | than a recipient address. This affects any rewriting and qualification that | |
3336 | might happen. | |
3337 | ||
3338 | .option C #<<filelist>> | |
3339 | .index configuration file||alternate | |
3340 | .index \\CONFIGURE@_FILE\\ | |
3341 | .index alternate configuration file | |
3342 | This option causes Exim to find the run time configuration file from the given | |
3343 | list instead of from the list specified by the \\CONFIGURE@_FILE\\ | |
3344 | compile-time setting. Usually, the list will consist of just a single file | |
3345 | name, but it can be a colon-separated list of names. In this case, the first | |
3346 | file that exists is used. Failure to open an existing file stops Exim from | |
3347 | proceeding any further along the list, and an error is generated. | |
3348 | ||
d43194df PH |
3349 | When this option is used by a caller other than root or the Exim user, and the |
3350 | list is different from the compiled-in list, Exim gives up its root privilege | |
3351 | immediately, and runs with the real and effective uid and gid set to those of | |
3352 | the caller. However, if \\ALT@_CONFIG@_ROOT@_ONLY\\ is defined in | |
3353 | \(Local/Makefile)\, root privilege is retained for \-C-\ only if the caller of | |
3354 | Exim is root. | |
3355 | .em | |
3356 | That is, the Exim user is no longer privileged in this regard. This build-time | |
3357 | option is not set by default in the Exim source distribution tarbundle. | |
3358 | However, if you are using a `packaged' version of Exim (source or binary), the | |
3359 | packagers might have enabled it. | |
3360 | .nem | |
495ae4b0 PH |
3361 | |
3362 | Setting \\ALT@_CONFIG@_ROOT@_ONLY\\ locks out the possibility of testing a | |
3363 | configuration using \-C-\ right through message reception and delivery, even if | |
3364 | the caller is root. The reception works, but by that time, Exim is running as | |
3365 | the Exim user, so when it re-execs to regain privilege for the delivery, the | |
3366 | use of \-C-\ causes privilege to be lost. However, root can test reception and | |
4964e932 | 3367 | delivery using two separate commands (one to put a message on the queue, using |
495ae4b0 PH |
3368 | \-odq-\, and another to do the delivery, using \-M-\). |
3369 | ||
3370 | If \\ALT@_CONFIG@_PREFIX\\ is defined \(in Local/Makefile)\, it specifies a | |
3371 | prefix string with which any file named in a \-C-\ command line option | |
3372 | must start. In addition, the file name must not contain the sequence \"/../"\. | |
3373 | However, if the value of the \-C-\ option is identical to the value of | |
3374 | \\CONFIGURE@_FILE\\ in \(Local/Makefile)\, Exim ignores \-C-\ and proceeds as | |
4964e932 | 3375 | usual. There is no default setting for \\ALT@_CONFIG@_PREFIX\\; when it is |
495ae4b0 PH |
3376 | unset, any file name can be used with \-C-\. |
3377 | ||
3378 | \\ALT@_CONFIG@_PREFIX\\ can be used to confine alternative configuration files | |
3379 | to a directory to which only root has access. This prevents someone who has | |
3380 | broken into the Exim account from running a privileged Exim with an arbitrary | |
3381 | configuration file. | |
3382 | ||
3383 | The \-C-\ facility is useful for ensuring that configuration files are | |
3384 | syntactically correct, but cannot be used for test deliveries, unless the | |
3385 | caller is privileged, or unless it is an exotic configuration that does not | |
3386 | require privilege. No check is made on the owner or group of the files | |
3387 | specified by this option. | |
3388 | ||
3389 | .option D <<macro>>=<<value>> | |
3390 | .index macro||setting on command line | |
3391 | This option can be used to override macro definitions in the configuration file | |
3392 | (see section ~~SECTmacrodefs). However, like \-C-\, if it is used by an | |
4964e932 | 3393 | unprivileged caller, it causes Exim to give up its root privilege. |
495ae4b0 PH |
3394 | If \\DISABLE@_D@_OPTION\\ is defined in \(Local/Makefile)\, the use of \-D-\ is |
3395 | completely disabled, and its use causes an immediate error exit. | |
3396 | ||
3397 | The entire option (including equals sign if present) must all be within one | |
4964e932 PH |
3398 | command line item. \-D-\ can be used to set the value of a macro to the empty |
3399 | string, in which case the equals sign is optional. These two commands are | |
495ae4b0 PH |
3400 | synonymous: |
3401 | .display asis | |
3402 | exim -DABC ... | |
3403 | exim -DABC= ... | |
3404 | .endd | |
4964e932 PH |
3405 | To include spaces in a macro definition item, quotes must be used. If you use |
3406 | quotes, spaces are permitted around the macro name and the equals sign. For | |
495ae4b0 PH |
3407 | example: |
3408 | .display asis | |
3409 | exim '-D ABC = something' ... | |
3410 | .endd | |
3411 | \-D-\ may be repeated up to 10 times on a command line. | |
3412 | ||
3413 | .option d <<debug options>> | |
3414 | .index debugging||list of selectors | |
3415 | .index debugging||\-d-\ option | |
3416 | This option causes debugging information to be written to the standard | |
3417 | error stream. It is restricted to admin users because debugging output may show | |
3418 | database queries that contain password information. Also, the details of users' | |
3419 | filter files should be protected. When \-d-\ is used, \-v-\ is assumed. If | |
3420 | \-d-\ is given on its own, a lot of standard debugging data is output. This can | |
3421 | be reduced, or increased to include some more rarely needed information, by | |
3422 | following \-d-\ with a string made up of names preceded by plus or minus | |
3423 | characters. These add or remove sets of debugging data, respectively. For | |
3424 | example, \-d+filter-\ adds filter debugging, whereas \-d-all+filter-\ selects | |
3425 | only filter debugging. The available debugging categories are: | |
3426 | .display flow | |
3427 | .tabs 21 | |
3428 | . | |
3429 | . The odd formatting of the lines below is deliberate. It does not affect the | |
3430 | . SGCAL output, but by putting in the space it keeps things aligned in the man | |
3431 | . page that is automatically generated from this text. | |
3432 | . | |
3433 | acl $t $rm{ACL interpretation} | |
3434 | auth $t $rm{authenticators} | |
3435 | deliver $t $rm{general delivery logic} | |
3436 | dns $t $rm{DNS lookups (see also resolver)} | |
3437 | dnsbl $t $rm{DNS black list (aka RBL) code} | |
3438 | exec $t $rm{arguments for \execv@(@)\ calls} | |
3439 | expand $t $rm{detailed debugging for string expansions} | |
3440 | filter $t $rm{filter handling} | |
3441 | hints@_lookup $t $rm{hints data lookups} | |
3442 | host@_lookup $t $rm{all types of name-to-IP address handling} | |
3443 | ident $t $rm{ident lookup} | |
3444 | interface $t $rm{lists of local interfaces} | |
3445 | lists $t $rm{matching things in lists} | |
3446 | load $t $rm{system load checks} | |
4964e932 | 3447 | local@_scan $t $rm{can be used by \*local@_scan()*\ (see chapter ~~CHAPlocalscan)} |
495ae4b0 PH |
3448 | lookup $t $rm{general lookup code and all lookups} |
3449 | memory $t $rm{memory handling} | |
3450 | pid $t $rm{add pid to debug output lines} | |
3451 | process@_info $t $rm{setting info for the process log} | |
3452 | queue@_run $t $rm{queue runs} | |
3453 | receive $t $rm{general message reception logic} | |
3454 | resolver $t $rm{turn on the DNS resolver's debugging output} | |
3455 | retry $t $rm{retry handling} | |
3456 | rewrite $t $rm{address rewriting} | |
3457 | route $t $rm{address routing} | |
3458 | timestamp $t $rm{add timestamp to debug output lines} | |
3459 | tls $t $rm{TLS logic} | |
3460 | transport $t $rm{transports} | |
3461 | uid $t $rm{changes of uid/gid and looking up uid/gid} | |
3462 | verify $t $rm{address verification logic} | |
3463 | ||
3464 | all $t $rm{all of the above, and also \-v-\} | |
3465 | .endd | |
495ae4b0 PH |
3466 | .index resolver, debugging output |
3467 | .index DNS||resolver, debugging output | |
4964e932 | 3468 | The \"resolver"\ option produces output only if the DNS resolver was compiled |
495ae4b0 PH |
3469 | with \\DEBUG\\ enabled. This is not the case in some operating systems. Also, |
3470 | unfortunately, debugging output from the DNS resolver is written to stdout | |
3471 | rather than stderr. | |
495ae4b0 PH |
3472 | |
3473 | The default (\-d-\ with no argument) omits \"expand"\, \"filter"\, | |
3474 | \"interface"\, \"load"\, \"memory"\, \"pid"\, \"resolver"\, and \"timestamp"\. | |
3475 | However, the \"pid"\ selector is forced when debugging is turned on for a | |
3476 | daemon, which then passes it on to any re-executed Exims. Exim also | |
3477 | automatically adds the pid to debug lines when several remote deliveries are | |
3478 | run in parallel. | |
3479 | ||
3480 | The \"timestamp"\ selector causes the current time to be inserted at the start | |
3481 | of all debug output lines. This can be useful when trying to track down delays | |
3482 | in processing. | |
3483 | ||
3484 | If the \debug@_print\ option is set in any driver, it produces output whenever | |
3485 | any debugging is selected, or if \-v-\ is used. | |
3486 | ||
d43194df PH |
3487 | .em |
3488 | .option dd <<debug options>> | |
3489 | This option behaves exactly like \-d-\ except when used on a command that | |
3490 | starts a daemon process. In that case, debugging is turned off for the | |
3491 | subprocesses that the daemon creates. Thus, it is useful for monitoring the | |
3492 | behaviour of the daemon without creating as much output as full debugging does. | |
3493 | .nem | |
3494 | ||
495ae4b0 | 3495 | .option dropcr |
4964e932 PH |
3496 | This is an obsolete option that is now a no-op. It used to affect the way Exim |
3497 | handled CR and LF characters in incoming messages. What happens now is | |
495ae4b0 PH |
3498 | described in section ~~SECTlineendings. |
3499 | ||
3500 | ||
3501 | .option E | |
3502 | .index bounce message||generating | |
3503 | This option specifies that an incoming message is a locally-generated delivery | |
3504 | failure report. It is used internally by Exim when handling delivery failures | |
3505 | and is not intended for external use. Its only effect is to stop Exim | |
3506 | generating certain messages to the postmaster, as otherwise message cascades | |
3507 | could occur in some situations. As part of the same option, a message id may | |
3508 | follow the characters \-E-\. If it does, the log entry for the receipt of the | |
3509 | new message contains the id, following `R=', as a cross-reference. | |
3510 | ||
3511 | .option e$it{x} | |
3512 | There are a number of Sendmail options starting with \-oe-\ which seem to be | |
3513 | called by various programs without the leading \o\ in the option. For example, | |
3514 | the \vacation\ program uses \-eq-\. Exim treats all options of the form | |
3515 | \-e$it{x}-\ as synonymous with the corresponding \-oe$it{x}-\ options. | |
3516 | ||
3517 | .option F #<<string>> | |
3518 | .index sender||name | |
3519 | .index name||of sender | |
3520 | This option sets the sender's full name for use when a locally-generated | |
3521 | message is being accepted. In the absence of this option, the user's \*gecos*\ | |
3522 | entry from the password data is used. As users are generally permitted to alter | |
3523 | their \*gecos*\ entries, no security considerations are involved. White space | |
3524 | between \-F-\ and the <<string>> is optional. | |
3525 | ||
3526 | .option f #<<address>> | |
3527 | .index sender||address | |
3528 | .index address||sender | |
3529 | .index trusted user | |
3530 | .index envelope sender | |
3531 | .index user||trusted | |
3532 | This option sets the address of the envelope sender of a locally-generated | |
3533 | message (also known as the return path). The option can normally be used only | |
3534 | by a trusted user, but \untrusted@_set@_sender\ can be set to allow untrusted | |
d43194df PH |
3535 | users to use it. |
3536 | .em | |
3537 | Processes running as root or the Exim user are always trusted. Other | |
3538 | trusted users are defined by the \trusted@_users\ or \trusted@_groups\ options. | |
3539 | ||
3540 | In the absence of \-f-\, or if the caller is not trusted, the sender of a local | |
3541 | message is set to the caller's login name at the default qualify domain. | |
495ae4b0 | 3542 | |
4964e932 | 3543 | There is one exception to the restriction on the use of \-f-\: an empty sender |
d43194df PH |
3544 | can be specified by any user, trusted or not, |
3545 | .nem | |
3546 | to create a message that can never provoke a bounce. An empty sender can be | |
3547 | specified either as an empty string, or as a pair of angle brackets with | |
3548 | nothing between them, as in these examples of shell commands: | |
495ae4b0 PH |
3549 | .display asis |
3550 | exim -f '<>' user@domain | |
3551 | exim -f "" user@domain | |
3552 | .endd | |
3553 | In addition, the use of \-f-\ is not restricted when testing a filter file with | |
3554 | \-bf-\ or when testing or verifying addresses using the \-bt-\ or \-bv-\ | |
3555 | options. | |
3556 | ||
3557 | Allowing untrusted users to change the sender address does not of itself make | |
3558 | it possible to send anonymous mail. Exim still checks that the ::From:: header | |
3559 | refers to the local user, and if it does not, it adds a ::Sender:: header, | |
3560 | though this can be overridden by setting \no@_local@_from@_check\. | |
3561 | ||
3562 | .index `From' line | |
3563 | White space between \-f-\ and the <<address>> is optional | |
3564 | (that is, they can be given as two arguments or one combined argument). | |
3565 | The sender of a locally-generated message can also be set (when permitted) by | |
3566 | an initial `From ' line in the message -- see the description of \-bm-\ above | |
3567 | -- but if \-f-\ is also present, it overrides `From'. | |
3568 | ||
3569 | .option G | |
3570 | .index Sendmail compatibility||\-G-\ option ignored | |
3571 | This is a Sendmail option which is ignored by Exim. | |
3572 | ||
3573 | .option h #<<number>> | |
3574 | .index Sendmail compatibility||\-h-\ option ignored | |
3575 | This option is accepted for compatibility with Sendmail, but has no effect. (In | |
3576 | Sendmail it overrides the `hop count' obtained by counting ::Received:: | |
3577 | headers.) | |
3578 | ||
3579 | .option i | |
3580 | .index Solaris||\*mail*\ command | |
3581 | .index dot||in incoming, non-SMTP message | |
3582 | This option, which has the same effect as \-oi-\, specifies that a dot on a | |
3583 | line by itself should not terminate an incoming, non-SMTP message. I can find | |
3584 | no documentation for this option in Solaris 2.4 Sendmail, but the \*mailx*\ | |
3585 | command in Solaris 2.4 uses it. See also \-ti-\. | |
3586 | ||
3587 | .option M #<<message id>>#<<message id>> ... | |
3588 | .index forcing delivery | |
3589 | .index delivery||forcing attempt | |
3590 | .index frozen messages||forcing delivery | |
3591 | This option requests Exim to run a delivery attempt on each message in turn. If | |
3592 | any of the messages are frozen, they are automatically thawed before the | |
3593 | delivery attempt. The settings of \queue@_domains\, \queue@_smtp@_domains\, and | |
4964e932 | 3594 | \hold@_domains\ are ignored. |
495ae4b0 PH |
3595 | .index hints database||overriding retry hints |
3596 | Retry hints for any of the addresses are | |
3597 | overridden -- Exim tries to deliver even if the normal retry time has not yet | |
3598 | been reached. This option requires the caller to be an admin user. However, | |
3599 | there is an option called \prod@_requires@_admin\ which can be set false to | |
3600 | relax this restriction (and also the same requirement for the \-q-\, \-R-\, and | |
3601 | \-S-\ options). | |
3602 | ||
3603 | ||
3604 | .option Mar #<<message id>>#<<address>>#<<address>> ... | |
3605 | .index message||adding recipients | |
3606 | .index recipient||adding | |
3607 | This option requests Exim to add the addresses to the list of recipients of the | |
3608 | message (`ar' for `add recipients'). The first argument must be a message id, | |
3609 | and the remaining ones must be email addresses. However, if the message is | |
3610 | active (in the middle of a delivery attempt), it is not altered. This option | |
3611 | can be used only by an admin user. | |
3612 | ||
3613 | .index SMTP||passed connection | |
3614 | .index SMTP||multiple deliveries | |
3615 | .index multiple SMTP deliveries | |
3616 | .option MC #<<transport>>#<<hostname>>#<<sequence number>>#<<message id>> | |
3617 | This option is not intended for use by external callers. It is used internally | |
3618 | by Exim to invoke another instance of itself to deliver a waiting message using | |
3619 | an existing SMTP connection, which is passed as the standard input. Details are | |
3620 | given in chapter ~~CHAPSMTP. This must be the final option, and the caller must | |
3621 | be root or the Exim user in order to use it. | |
3622 | ||
3623 | .option MCA | |
3624 | This option is not intended for use by external callers. It is used internally | |
3625 | by Exim in conjunction with the \-MC-\ option. It signifies that the connection | |
3626 | to the remote host has been authenticated. | |
3627 | ||
3628 | .option MCP | |
4964e932 PH |
3629 | This option is not intended for use by external callers. It is used internally |
3630 | by Exim in conjunction with the \-MC-\ option. It signifies that the server to | |
495ae4b0 PH |
3631 | which Exim is connected supports pipelining. |
3632 | ||
3633 | .option MCQ #<<process id>> <<pipe fd>> | |
3634 | This option is not intended for use by external callers. It is used internally | |
3635 | by Exim in conjunction with the \-MC-\ option when the original delivery was | |
3636 | started by a queue runner. It passes on the process id of the queue runner, | |
3637 | together with the file descriptor number of an open pipe. Closure of the pipe | |
3638 | signals the final completion of the sequence of processes that are passing | |
3639 | messages through the same SMTP connection. | |
3640 | ||
3641 | .option MCS | |
3642 | This option is not intended for use by external callers. It is used internally | |
3643 | by Exim in conjunction with the \-MC-\ option, and passes on the fact that the | |
3644 | SMTP \\SIZE\\ option should be used on messages delivered down the existing | |
3645 | connection. | |
3646 | ||
3647 | .option MCT | |
3648 | This option is not intended for use by external callers. It is used internally | |
3649 | by Exim in conjunction with the \-MC-\ option, and passes on the fact that the | |
3650 | host to which Exim is connected supports TLS encryption. | |
3651 | ||
3652 | .option Mc #<<message id>>#<<message id>> ... | |
3653 | .index hints database||not overridden by \-Mc-\ | |
3654 | .index delivery||manually started, not forced | |
3655 | This option requests Exim to run a delivery attempt on each message in turn, | |
3656 | but unlike the \-M-\ option, it does check for retry hints, and respects any | |
3657 | that are found. This option is not very useful to external callers. It is | |
3658 | provided mainly for internal use by Exim when it needs to re-invoke itself in | |
3659 | order to regain root privilege for a delivery (see chapter ~~CHAPsecurity). | |
3660 | However, \-Mc-\ can be useful when testing, in order to run a delivery that | |
3661 | respects retry times and other options such as \hold@_domains\ that are | |
3662 | overridden when \-M-\ is used. Such a delivery does not count as a queue run. | |
3663 | If you want to run a specific delivery as if in a queue run, you should use | |
3664 | \-q-\ with a message id argument. A distinction between queue run deliveries | |
3665 | and other deliveries is made in one or two places. | |
3666 | ||
3667 | .option Mes #<<message id>>#<<address>> | |
3668 | .index message||changing sender | |
3669 | .index sender||changing | |
3670 | This option requests Exim to change the sender address in the message to the | |
3671 | given address, which must be a fully qualified address or `<>' (`es' for `edit | |
3672 | sender'). There must be exactly two arguments. The first argument must be a | |
3673 | message id, and the second one an email address. However, if the message is | |
3674 | active (in the middle of a delivery attempt), its status is not altered. This | |
3675 | option can be used only by an admin user. | |
3676 | ||
3677 | .option Mf #<<message id>>#<<message id>> ... | |
3678 | .index freezing messages | |
3679 | .index message||manually freezing | |
3680 | This option requests Exim to mark each listed message as `frozen'. This | |
3681 | prevents any delivery attempts taking place until the message is `thawed', | |
3682 | either manually or as a result of the \auto@_thaw\ configuration option. | |
3683 | However, if any of the messages are active (in the middle of a delivery | |
3684 | attempt), their status is not altered. This option can be used only by an admin | |
3685 | user. | |
3686 | ||
3687 | .option Mg #<<message id>>#<<message id>> ... | |
3688 | .index giving up on messages | |
3689 | .index message||abandoning delivery attempts | |
3690 | .index delivery||abandoning further attempts | |
3691 | This option requests Exim to give up trying to deliver the listed messages, | |
3692 | including any that are frozen. However, if any of the messages are active, | |
4964e932 | 3693 | their status is not altered. |
495ae4b0 PH |
3694 | For non-bounce messages, a delivery error message is sent to the sender, |
3695 | containing the text `cancelled by administrator'. Bounce messages are just | |
3696 | discarded. | |
3697 | This option can be used only by an admin user. | |
3698 | ||
3699 | .option Mmad #<<message id>>#<<message id>> ... | |
3700 | .index delivery||cancelling all | |
3701 | This option requests Exim to mark all the recipient addresses in the messages | |
3702 | as already delivered (`mad' for `mark all delivered'). However, if any message | |
3703 | is active (in the middle of a delivery attempt), its status is not altered. | |
3704 | This option can be used only by an admin user. | |
3705 | ||
3706 | .option Mmd #<<message id>>#<<address>>#<<address>> ... | |
3707 | .index delivery||cancelling by address | |
3708 | .index recipient||removing | |
3709 | .index removing recipients | |
3710 | This option requests Exim to mark the given addresses as already delivered | |
3711 | (`md' for `mark delivered'). The first argument must be a message id, and the | |
3712 | remaining ones must be email addresses. These are matched to recipient | |
3713 | addresses in the message in a case-sensitive manner. If the message is active | |
3714 | (in the middle of a delivery attempt), its status is not altered. This option | |
3715 | can be used only by an admin user. | |
3716 | ||
3717 | .option Mrm #<<message id>>#<<message id>> ... | |
3718 | .index removing messages | |
3719 | .index abandoning mail | |
3720 | .index message||manually discarding | |
3721 | This option requests Exim to remove the given messages from the queue. No | |
3722 | bounce messages are sent; each message is simply forgotten. However, if any of | |
3723 | the messages are active, their status is not altered. This option can be used | |
3724 | only by an admin user or by the user who originally caused the message to be | |
3725 | placed on the queue. | |
3726 | ||
3727 | .option Mt #<<message id>>#<<message id>> ... | |
3728 | .index thawing messages | |
3729 | .index unfreezing messages | |
3730 | .index frozen messages||thawing | |
3731 | .index message||thawing frozen | |
3732 | This option requests Exim to `thaw' any of the listed messages that are | |
3733 | `frozen', so that delivery attempts can resume. However, if any of the messages | |
3734 | are active, their status is not altered. This option can be used only by an | |
3735 | admin user. | |
3736 | ||
3737 | .option Mvb #<<message id>> | |
3738 | .index listing||message body | |
3739 | .index message||listing body of | |
3740 | This option causes the contents of the message body (-D) spool file to be | |
3741 | written to the standard output. This option can be used only by an admin user. | |
3742 | ||
3743 | .option Mvh #<<message id>> | |
3744 | .index listing||message headers | |
3745 | .index header lines||listing | |
3746 | .index message||listing header lines | |
3747 | This option causes the contents of the message headers (-H) spool file to be | |
3748 | written to the standard output. This option can be used only by an admin user. | |
3749 | ||
3750 | .option Mvl #<<message id>> | |
3751 | .index listing||message log | |
3752 | .index message||listing message log | |
3753 | This option causes the contents of the message log spool file to be written to | |
3754 | the standard output. This option can be used only by an admin user. | |
3755 | ||
3756 | .option m | |
3757 | This is apparently a synonym for \-om-\ that is accepted by Sendmail, so Exim | |
3758 | treats it that way too. | |
3759 | ||
3760 | .option N | |
3761 | .index debugging||\-N-\ option | |
3762 | .index debugging||suppressing delivery | |
3763 | This is a debugging option that inhibits delivery of a message at the transport | |
3764 | level. It implies \-v-\. Exim goes through many of the motions of delivery -- | |
3765 | it just doesn't actually transport the message, but instead behaves as if it | |
3766 | had successfully done so. However, it does not make any updates to the retry | |
3767 | database, and the log entries for deliveries are flagged with `$*$>' rather | |
3768 | than `=>'. | |
3769 | ||
3770 | Because \-N-\ discards any message to which it applies, only root or the Exim | |
3771 | user are allowed to use it with \-bd-\, \-q-\, \-R-\ or \-M-\. In other words, | |
3772 | an ordinary user can use it only when supplying an incoming message to which it | |
3773 | will apply. Although transportation never fails when \-N-\ is set, an address | |
3774 | may be deferred because of a configuration problem on a transport, or a routing | |
3775 | problem. Once \-N-\ has been used for a delivery attempt, it sticks to the | |
3776 | message, and applies to any subsequent delivery attempts that may happen for | |
3777 | that message. | |
3778 | ||
3779 | .option n | |
3780 | .index Sendmail compatibility||\-n-\ option ignored | |
3781 | This option is interpreted by Sendmail to mean `no aliasing'. It is ignored by | |
3782 | Exim. | |
3783 | ||
3784 | .option O #<<data>> | |
4964e932 | 3785 | This option is interpreted by Sendmail to mean `set option`. It is ignored by |
495ae4b0 PH |
3786 | Exim. |
3787 | ||
3788 | .option oA #<<file name>> | |
3789 | .index Sendmail compatibility||\-oA-\ option | |
3790 | This option is used by Sendmail in conjunction with \-bi-\ to specify an | |
3791 | alternative alias file name. Exim handles \-bi-\ differently; see the | |
3792 | description above. | |
3793 | ||
3794 | .index SMTP||passed connection | |
3795 | .option oB #<<n>> | |
3796 | .index SMTP||multiple deliveries | |
3797 | .index multiple SMTP deliveries | |
3798 | This is a debugging option which limits the maximum number of messages that can | |
3799 | be delivered down one SMTP connection, overriding the value set in any \%smtp%\ | |
3800 | transport. If <<n>> is omitted, the limit is set to 1. | |
3801 | ||
3802 | .option odb | |
3803 | .index background delivery | |
3804 | .index delivery||in the background | |
3805 | This option applies to all modes in which Exim accepts incoming messages, | |
3806 | including the listening daemon. It requests `background' delivery of such | |
d43194df PH |
3807 | messages, which means that the accepting process automatically starts a |
3808 | delivery process for each message received, but does not wait for the delivery | |
3809 | processes to finish. | |
3810 | .em | |
3811 | When all the messages have been received, the reception process exits, leaving | |
3812 | the delivery processes to finish in their own time. The standard output and | |
3813 | error streams are closed at the start of each delivery process. | |
3814 | .nem | |
3815 | This is the default action if none of the \-od-\ options are present. | |
495ae4b0 PH |
3816 | |
3817 | If one of the queueing options in the configuration file | |
3818 | (\queue@_only\ or \queue@_only@_file\, for example) is in effect, \-odb-\ | |
3819 | overrides it if \queue@_only@_override\ is set true, which is the default | |
3820 | setting. If \queue@_only@_override\ is set false, \-odb-\ has no effect. | |
3821 | ||
3822 | .option odf | |
3823 | .index foreground delivery | |
3824 | .index delivery||in the foreground | |
3825 | This option requests `foreground' (synchronous) delivery when Exim has accepted | |
3826 | a locally-generated message. (For the daemon it is exactly the same as | |
3827 | \-odb-\.) A delivery process is automatically started to deliver the | |
3828 | message, and Exim waits for it to complete before proceeding. | |
d43194df PH |
3829 | .em |
3830 | The original Exim reception process does not finish until the delivery | |
3831 | process for the final message has ended. The standard error stream is left open | |
3832 | during deliveries. | |
3833 | .nem | |
4964e932 | 3834 | However, like \-odb-\, this option has no effect if \queue@_only@_override\ is |
495ae4b0 PH |
3835 | false and one of the queueing options in the configuration file is in effect. |
3836 | ||
d43194df PH |
3837 | .em |
3838 | If there is a temporary delivery error during foreground delivery, the message | |
3839 | is left on the queue for later delivery, and the original reception process | |
3840 | exists. See chapter ~~CHAPnonqueueing for a way of setting up a restricted | |
3841 | configuration that never queues messages. | |
3842 | .nem | |
3843 | ||
495ae4b0 PH |
3844 | .option odi |
3845 | This option is synonymous with \-odf-\. It is provided for compatibility with | |
3846 | Sendmail. | |
3847 | ||
3848 | .option odq | |
3849 | .index non-immediate delivery | |
3850 | .index delivery||suppressing immediate | |
3851 | .index queueing incoming messages | |
3852 | This option applies to all modes in which Exim accepts incoming messages, | |
3853 | including the listening daemon. It specifies that the accepting process should | |
3854 | not automatically start a delivery process for each message received. Messages | |
3855 | are placed on the queue, and remain there until a subsequent queue runner | |
3856 | process encounters them. | |
3857 | There are several configuration options (such as \queue@_only\) that can be | |
3858 | used to queue incoming messages under certain conditions. This option overrides | |
3859 | all of them and also \-odqs-\. It always forces queueing. | |
3860 | ||
3861 | .option odqs | |
3862 | .index SMTP||delaying delivery | |
4964e932 | 3863 | This option is a hybrid between \-odb-\/\-odi-\ and \-odq-\. |
495ae4b0 PH |
3864 | However, like \-odb-\ and \-odi-\, this option has no effect if |
3865 | \queue@_only@_override\ is false and one of the queueing options in the | |
3866 | configuration file is in effect. | |
3867 | ||
3868 | When \-odqs-\ does operate, a delivery process is started for each incoming | |
3869 | message, in the background by default, but in the foreground if \-odi-\ is also | |
3870 | present. | |
3871 | The recipient addresses are routed, and local deliveries are done in the normal | |
3872 | way. However, if any SMTP deliveries are required, they are not done at this | |
3873 | time, so the message remains on the queue until a subsequent queue runner | |
3874 | process encounters it. Because routing was done, Exim knows which messages are | |
3875 | waiting for which hosts, and so a number of messages for the same host can be | |
3876 | sent in a single SMTP connection. The \queue@_smtp@_domains\ configuration | |
3877 | option has the same effect for specific domains. See also the \-qq-\ option. | |
3878 | ||
3879 | .option oee | |
3880 | .index error||reporting | |
3881 | If an error is detected while a non-SMTP message is being received (for | |
3882 | example, a malformed address), the error is reported to the sender in a mail | |
3883 | message. | |
3884 | .index return code||for \-oee-\ | |
3885 | Provided this error message is successfully sent, the Exim receiving process | |
3886 | exits with a return code of zero. If not, the return code is 2 if the problem | |
3887 | is that the original message has no recipients, or 1 any other error. This is | |
3888 | the default \-oe$it{x}-\ option if Exim is called as \*rmail*\. | |
3889 | ||
3890 | .option oem | |
3891 | .index error||reporting | |
3892 | .index return code||for \-oem-\ | |
3893 | This is the same as \-oee-\, except that Exim always exits with a non-zero | |
3894 | return code, whether or not the error message was successfully sent. | |
3895 | This is the default \-oe$it{x}-\ option, unless Exim is called as \*rmail*\. | |
3896 | ||
3897 | .option oep | |
3898 | .index error||reporting | |
3899 | If an error is detected while a non-SMTP message is being received, the | |
3900 | error is reported by writing a message to the standard error file (stderr). | |
3901 | .index return code||for \-oep-\ | |
3902 | The return code is 1 for all errors. | |
3903 | ||
3904 | .option oeq | |
3905 | .index error||reporting | |
3906 | This option is supported for compatibility with Sendmail, but has the same | |
3907 | effect as \-oep-\. | |
3908 | ||
3909 | .option oew | |
3910 | .index error||reporting | |
3911 | This option is supported for compatibility with Sendmail, but has the same | |
3912 | effect as \-oem-\. | |
3913 | ||
3914 | .option oi | |
3915 | .index dot||in incoming, non-SMTP message | |
3916 | This option, which has the same effect as \-i-\, specifies that a dot on a line | |
3917 | by itself should not terminate an incoming, non-SMTP message. | |
4964e932 | 3918 | Otherwise, a single dot does terminate, though Exim does no special processing |
495ae4b0 | 3919 | for other lines that start with a dot. |
495ae4b0 PH |
3920 | This option is set by default if Exim is called as \*rmail*\. See also \-ti-\. |
3921 | ||
3922 | .option oitrue | |
3923 | This option is treated as synonymous with \-oi-\. | |
3924 | ||
3925 | .option oMa #<<host address>> | |
3926 | .index sender||host address, specifying for local message | |
3927 | A number of options starting with \-oM-\ can be used to set values associated | |
3928 | with remote hosts on locally-submitted messages (that is, messages not received | |
3929 | over TCP/IP). These options can be used by any caller in conjunction with the | |
4964e932 | 3930 | \-bh-\, |
495ae4b0 PH |
3931 | \-be-\, |
3932 | \-bf-\, \-bF-\, \-bt-\, or \-bv-\ testing options. In other circumstances, they | |
3933 | are ignored unless the caller is trusted. | |
3934 | ||
3935 | The \-oMa-\ option sets the sender host address. This may include a port number | |
3936 | at the end, after a full stop (period). For example: | |
3937 | .display asis | |
3938 | exim -bs -oMa 10.9.8.7.1234 | |
3939 | .endd | |
3940 | An alternative syntax is to enclose the IP address in square brackets, followed | |
3941 | by a colon and the port number: | |
3942 | .display asis | |
3943 | exim -bs -oMa [10.9.8.7]:1234 | |
3944 | .endd | |
3945 | The IP address is placed in the \$sender@_host@_address$\ variable, and the | |
3946 | port, if present, in \$sender@_host@_port$\. | |
3947 | ||
3948 | .option oMaa #<<name>> | |
3949 | .index authentication||name, specifying for local message | |
3950 | See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMaa-\ | |
3951 | option sets the value of \$sender@_host@_authenticated$\ (the authenticator | |
3952 | name). See chapter ~~CHAPSMTPAUTH for a discussion of SMTP authentication. | |
3953 | ||
3954 | .option oMai #<<string>> | |
3955 | .index authentication||id, specifying for local message | |
3956 | See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMai-\ | |
4964e932 | 3957 | option sets the |
495ae4b0 PH |
3958 | value of \$authenticated@_id$\ (the id that was authenticated). |
3959 | This overrides the default value (the caller's login id) for messages from | |
3960 | local sources. See chapter ~~CHAPSMTPAUTH for a discussion of authenticated | |
3961 | ids. | |
3962 | ||
3963 | .option oMas #<<address>> | |
3964 | .index authentication||sender, specifying for local message | |
3965 | See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMas-\ | |
3966 | option sets the authenticated sender value | |
4964e932 | 3967 | in \$authenticated@_sender$\. |
495ae4b0 PH |
3968 | It overrides the sender address that is created from the caller's login id for |
3969 | messages from local sources. See chapter ~~CHAPSMTPAUTH for a discussion of | |
3970 | authenticated senders. | |
3971 | ||
3972 | .option oMi #<<interface address>> | |
3973 | .index interface||address, specifying for local message | |
3974 | See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMi-\ | |
3975 | option sets the IP interface address value. A port number may be included, | |
3976 | using the same syntax as for \-oMa-\. | |
4964e932 | 3977 | The interface address is placed in \$interface@_address$\ and the port number, |
495ae4b0 PH |
3978 | if present, in \$interface@_port$\. |
3979 | ||
3980 | .option oMr #<<protocol name>> | |
3981 | .index protocol||incoming, specifying for local message | |
3982 | See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMr-\ | |
d43194df PH |
3983 | option sets the received protocol value that is stored in |
3984 | \$received@_protocol$\. However, this applies only when \-bs-\ is not used. For | |
3985 | interactive SMTP input (\-bs-\), the protocol is always | |
3986 | .em | |
3987 | `local-' followed by one of the standard SMTP protocol names (see the | |
3988 | description of \$received@_protocol$\ in section ~~SECTexpvar). | |
3989 | .nem | |
3990 | For \-bS-\ (batch SMTP) however, the protocol can be set by \-oMr-\. | |
495ae4b0 PH |
3991 | |
3992 | .option oMs #<<host name>> | |
3993 | .index sender||host name, specifying for local message | |
3994 | See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMs-\ | |
4964e932 PH |
3995 | option sets the sender host name |
3996 | in \$sender@_host@_name$\. When this option is present, Exim does not attempt | |
495ae4b0 PH |
3997 | to look up a host name from an IP address; it uses the name it is given. |
3998 | ||
3999 | .option oMt #<<ident string>> | |
4000 | .index sender||ident string, specifying for local message | |
4001 | See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMt-\ | |
4002 | option sets the sender ident value | |
4964e932 | 4003 | in \$sender@_ident$\. |
495ae4b0 PH |
4004 | The default setting for local callers is the login id of the calling process. |
4005 | ||
4006 | .option om | |
4007 | .index Sendmail compatibility||\-om-\ option ignored | |
4008 | In Sendmail, this option means `me too', indicating that the sender of a | |
4009 | message should receive a copy of the message if the sender appears in an alias | |
4010 | expansion. Exim always does this, so the option does nothing. | |
4011 | ||
4012 | .option oo | |
4013 | .index Sendmail compatibility||\-oo-\ option ignored | |
4014 | This option is ignored. In Sendmail it specifies `old style headers', whatever | |
4015 | that means. | |
4016 | ||
4017 | .option oP #<<path>> | |
4018 | .index pid (process id)||of daemon | |
4019 | .index daemon||process id (pid) | |
4964e932 | 4020 | This option is useful only in conjunction with \-bd-\ or \-q-\ with a time |
495ae4b0 PH |
4021 | value. The option specifies the file to which the process id of the daemon is |
4022 | written. When \-oX-\ is used with \-bd-\, or when \-q-\ with a time is used | |
4023 | without \-bd-\, this is the only way of causing Exim to write a pid file, | |
4024 | because in those cases, the normal pid file is not used. | |
4025 | ||
4026 | .option or #<<time>> | |
4027 | .index timeout||for non-SMTP input | |
4028 | This option sets a timeout value for incoming non-SMTP messages. If it is not | |
4029 | set, Exim will wait forever for the standard input. The value can also be set | |
4030 | by the \receive@_timeout\ option. The format used for specifying times is | |
4031 | described in section ~~SECTtimeformat. | |
4032 | ||
4033 | .option os #<<time>> | |
4034 | .index timeout||for SMTP input | |
4035 | .index SMTP||timeout, input | |
4036 | This option sets a timeout value for incoming SMTP messages. The timeout | |
4037 | applies to each SMTP command and block of data. The value can also be set by | |
4038 | the \smtp@_receive@_timeout\ option; it defaults to 5 minutes. The format used | |
4039 | for specifying times is described in section ~~SECTtimeformat. | |
4040 | ||
4041 | .option ov | |
4042 | This option has exactly the same effect as \-v-\. | |
4043 | ||
4044 | .option oX #<<number or string>> | |
4045 | .index TCP/IP||setting listening ports | |
4046 | .index TCP/IP||setting listening interfaces | |
4047 | .index port||receiving TCP/IP | |
4048 | This option is relevant only when the \-bd-\ (start listening daemon) option is | |
4049 | also given. It controls which ports and interfaces the daemon uses. Details of | |
4050 | the syntax, and how it interacts with configuration file options, are given in | |
4051 | chapter ~~CHAPinterfaces. When \-oX-\ is used to start a daemon, no pid file is | |
4052 | written unless \-oP-\ is also present to specify a pid file name. | |
4053 | ||
4054 | .option pd | |
4055 | .index Perl||starting the interpreter | |
4056 | This option applies when an embedded Perl interpreter is linked with Exim (see | |
4057 | chapter ~~CHAPperl). It overrides the setting of the \perl@_at@_start\ option, | |
4058 | forcing the starting of the interpreter to be delayed until it is needed. | |
4059 | ||
4060 | .option ps | |
4061 | .index Perl||starting the interpreter | |
4062 | This option applies when an embedded Perl interpreter is linked with Exim (see | |
4063 | chapter ~~CHAPperl). It overrides the setting of the \perl@_at@_start\ option, | |
4064 | forcing the starting of the interpreter to occur as soon as Exim is started. | |
4065 | ||
495ae4b0 PH |
4066 | .option p<<rval>>:<<sval>> |
4067 | For compatibility with Sendmail, this option | |
4068 | is equivalent to | |
4964e932 | 4069 | .display |
495ae4b0 PH |
4070 | -oMr <<rval>> -oMs <<sval>> |
4071 | .endd | |
4072 | It sets the incoming protocol and host name (for trusted callers). The | |
4073 | host name and its colon can be omitted when only the protocol is to be set. | |
4074 | Note the Exim already has two private options, \-pd-\ and \-ps-\, that refer to | |
4075 | embedded Perl. It is therefore impossible to set a protocol value of \"p"\ or | |
4076 | \"s"\ using this option (but that does not seem a real limitation). | |
495ae4b0 PH |
4077 | |
4078 | .option q | |
4079 | .index queue runner||starting manually | |
4080 | This option is normally restricted to admin users. However, there is a | |
4081 | configuration option called \prod@_requires@_admin\ which can be set false to | |
4082 | relax this restriction (and also the same requirement for the \-M-\, \-R-\, and | |
4083 | \-S-\ options). | |
4084 | ||
4085 | .index queue runner||description of operation | |
4086 | The \-q-\ option starts one queue runner process. This scans the queue of | |
4087 | waiting messages, and runs a delivery process for each one in turn. It waits | |
4088 | for each delivery process to finish before starting the next one. A delivery | |
4089 | process may not actually do any deliveries if the retry times for the addresses | |
4090 | have not been reached. Use \-qf-\ (see below) if you want to override this. | |
4091 | .index SMTP||passed connection | |
4092 | .index SMTP||multiple deliveries | |
4093 | .index multiple SMTP deliveries | |
4094 | If the delivery process spawns other processes to deliver other messages down | |
4095 | passed SMTP connections, the queue runner waits for these to finish before | |
4096 | proceeding. | |
4097 | ||
4098 | When all the queued messages have been considered, the original queue runner | |
4099 | process terminates. In other words, a single pass is made over the waiting | |
4100 | mail, one message at a time. Use \-q-\ with a time (see below) if you want this | |
4101 | to be repeated periodically. | |
4102 | ||
4103 | Exim processes the waiting messages in an unpredictable order. It isn't very | |
4104 | random, but it is likely to be different each time, which is all that matters. | |
4105 | If one particular message screws up a remote MTA, other messages to the same | |
4106 | MTA have a chance of getting through if they get tried first. | |
4107 | ||
4108 | It is possible to cause the messages to be processed in lexical message id | |
4109 | order, which is essentially the order in which they arrived, by setting the | |
4110 | \queue@_run@_in@_order\ option, but this is not recommended for normal use. | |
4111 | ||
4112 | .option q <<qflags>> | |
4113 | The \-q-\ option may be followed by one or more flag letters that change its | |
4114 | behaviour. They are all optional, but if more than one is present, they must | |
4115 | appear in the correct order. Each flag is described in a separate item below. | |
4116 | ||
4117 | .option qq... | |
4118 | .index queue||double scanning | |
4119 | .index queue||routing | |
4120 | .index routing||whole queue before delivery | |
4121 | An option starting with \-qq-\ requests a two-stage queue run. In the first | |
4122 | stage, the queue is scanned as if the \queue@_smtp@_domains\ option matched | |
4123 | every domain. Addresses are routed, local deliveries happen, but no remote | |
4964e932 | 4124 | transports are run. |
495ae4b0 PH |
4125 | .index hints database||remembering routing |
4126 | The hints database that remembers which messages are | |
4127 | waiting for specific hosts is updated, as if delivery to those hosts had been | |
4128 | deferred. After this is complete, a second, normal queue scan happens, with | |
4129 | routing and delivery taking place as normal. Messages that are routed to the | |
4130 | same host should mostly be delivered down a single SMTP | |
4131 | .index SMTP||passed connection | |
4132 | .index SMTP||multiple deliveries | |
4133 | .index multiple SMTP deliveries | |
4134 | connection because of the hints that were set up during the first queue scan. | |
4135 | This option may be useful for hosts that are connected to the Internet | |
4136 | intermittently. | |
4137 | ||
4138 | .option q[q]i... | |
4139 | .index queue||initial delivery | |
4140 | If the \*i*\ flag is present, the queue runner runs delivery processes only for | |
4141 | those messages that haven't previously been tried. (\*i*\ stands for `initial | |
4142 | delivery'.) This can be helpful if you are putting messages on the queue using | |
4143 | \-odq-\ and want a queue runner just to process the new messages. | |
4144 | ||
4145 | .option q[q][i]f... | |
4964e932 | 4146 | .index queue||forcing delivery |
495ae4b0 PH |
4147 | .index delivery||forcing in queue run |
4148 | If one \*f*\ flag is present, a delivery attempt is forced for each non-frozen | |
4149 | message, whereas without \f\ only those non-frozen addresses that have passed | |
4150 | their retry times are tried. | |
4151 | ||
4152 | .option q[q][i]ff... | |
4153 | .index frozen messages||forcing delivery | |
4154 | If \*ff*\ is present, a delivery attempt is forced for every message, whether | |
4155 | frozen or not. | |
4156 | ||
4157 | .option q[q][i][f[f]]l | |
4158 | .index queue||local deliveries only | |
4159 | The \*l*\ (the letter `ell') flag specifies that only local deliveries are to be | |
4160 | done. If a message requires any remote deliveries, it remains on the queue for | |
4161 | later delivery. | |
4162 | ||
4163 | .option q <<qflags>>#<<start id>>#<<end id>> | |
4164 | .index queue||delivering specific messages | |
4165 | When scanning the queue, Exim can be made to skip over messages whose ids are | |
4166 | lexically less than a given value by following the \-q-\ option with a starting | |
4167 | message id. For example: | |
4168 | .display | |
4169 | exim -q 0t5C6f-0000c8-00 | |
4170 | .endd | |
4171 | Messages that arrived earlier than \"0t5C6f-0000c8-00"\ are not inspected. If a | |
4172 | second message id is given, messages whose ids are lexically greater than it | |
4173 | are also skipped. If the same id is given twice, for example, | |
4174 | .display | |
4175 | exim -q 0t5C6f-0000c8-00 0t5C6f-0000c8-00 | |
4176 | .endd | |
4177 | just one delivery process is started, for that message. This differs from \-M-\ | |
4178 | in that retry data is respected, and it also differs from \-Mc-\ in that it | |
4179 | counts as a delivery from a queue run. Note that the selection mechanism does | |
4180 | not affect the order in which the messages are scanned. There are also other | |
4181 | ways of selecting specific sets of messages for delivery in a queue run -- see | |
4182 | \-R-\ and \-S-\. | |
4183 | ||
4184 | .option q <<qflags>><<time>> | |
4185 | .index queue runner||starting periodically | |
4186 | .index periodic queue running | |
4187 | When a time value is present, the \-q-\ option causes Exim to run as a daemon, | |
4188 | starting a queue runner process at intervals specified by the given time value | |
4189 | (whose format is described in section ~~SECTtimeformat). This form of the \-q-\ | |
4190 | option is commonly combined with the \-bd-\ option, in which case a single | |
4191 | daemon process handles both functions. A common way of starting up a combined | |
4192 | daemon at system boot time is to use a command such as | |
4193 | .display | |
4194 | /usr/exim/bin/exim -bd -q30m | |
4195 | .endd | |
4196 | Such a daemon listens for incoming SMTP calls, and also starts a queue runner | |
4197 | process every 30 minutes. | |
4198 | ||
4964e932 | 4199 | When a daemon is started by \-q-\ with a time value, but without \-bd-\, no pid |
495ae4b0 PH |
4200 | file is written unless one is explicitly requested by the \-oP-\ option. |
4201 | ||
4202 | .option qR <<rsflags>>#<<string>> | |
4203 | This option is synonymous with \-R-\. It is provided for Sendmail | |
4204 | compatibility. | |
4205 | ||
4206 | .option qS <<rsflags>>#<<string>> | |
4207 | This option is synonymous with \-S-\. | |
4208 | ||
4209 | .option R <<rsflags>>#<<string>> | |
4210 | .index queue runner||for specific recipients | |
4211 | .index delivery||to given domain | |
4212 | .index domain||delivery to | |
4213 | The <<rsflags>> may be empty, in which case the white space before the string | |
4214 | is optional, unless the string is \*f*\, \*ff*\, \*r*\, \*rf*\, or \*rff*\, | |
4215 | which are the possible values for <<rsflags>>. White space is required if | |
4216 | <<rsflags>> is not empty. | |
4217 | ||
4218 | This option is similar to \-q-\ with no time value, that is, it causes Exim to | |
4219 | perform a single queue run, except that, when scanning the messages on the | |
4220 | queue, Exim processes only those that have at least one undelivered recipient | |
4221 | address containing the given string, which is checked in a case-independent | |
4222 | way. If the <<rsflags>> start with \*r*\, <<string>> is interpreted as a regular | |
4223 | expression; otherwise it is a literal string. | |
4224 | ||
4225 | Once a message is selected, all its addresses are processed. For the first | |
4226 | selected message, Exim overrides any retry information and forces a delivery | |
4227 | attempt for each undelivered address. This means that if delivery of any | |
4228 | address in the first message is successful, any existing retry information is | |
4229 | deleted, and so delivery attempts for that address in subsequently selected | |
4230 | messages (which are processed without forcing) will run. However, if delivery | |
4231 | of any address does not succeed, the retry information is updated, and in | |
4232 | subsequently selected messages, the failing address will be skipped. | |
4233 | ||
4234 | If the <<rsflags>> contain \*f*\ or \*ff*\, the delivery forcing applies to all | |
4235 | selected messages, not just the first; | |
4236 | .index frozen messages||forcing delivery | |
4237 | frozen messages are included when \*ff*\ is present. | |
4238 | ||
4239 | The \-R-\ option makes it straightforward to initiate delivery of all messages | |
4240 | to a given domain after a host has been down for some time. When the SMTP | |
4241 | command \\ETRN\\ is accepted by its ACL (see chapter ~~CHAPACL), its default | |
4242 | effect is to run Exim with the \-R-\ option, but it can be configured to run an | |
4243 | arbitrary command instead. | |
4244 | ||
4245 | .option r | |
4246 | This is a documented (for Sendmail) obsolete alternative name for \-f-\. | |
4247 | ||
4248 | .index delivery||from given sender | |
4249 | .option S <<rsflags>>#<<string>> | |
4250 | .index queue runner||for specific senders | |
4251 | This option acts like \-R-\ except that it checks the string against each | |
4252 | message's sender instead of against the recipients. If \-R-\ is also set, both | |
4253 | conditions must be met for a message to be selected. If either of the options | |
4254 | has \*f*\ or \*ff*\ in its flags, the associated action is taken. | |
4255 | ||
495ae4b0 PH |
4256 | .option Tqt#<<times>> |
4257 | This an option that is exclusively for use by the Exim testing suite. | |
4258 | It is not recognized when Exim is run normally. It allows for the setting up | |
4964e932 PH |
4259 | of explicit `queue times' so that various warning/retry features can be |
4260 | tested. | |
495ae4b0 PH |
4261 | |
4262 | .option t | |
4263 | .index recipient||extracting from header lines | |
4264 | .index ::Bcc:: header line | |
4265 | .index ::Cc:: header line | |
4266 | .index ::To:: header line | |
4267 | When Exim is receiving a locally-generated, non-SMTP message on its standard | |
4268 | input, the \-t-\ option causes the recipients of the message to be obtained | |
4269 | from the ::To::, ::Cc::, and ::Bcc:: header lines in the message instead of from | |
4270 | the command arguments. The addresses are extracted before any rewriting takes | |
4271 | place. | |
4272 | ||
4273 | .index Sendmail compatibility||\-t-\ option | |
4274 | If the command has any arguments, they specify addresses to which the message | |
4275 | is $it{not} to be delivered. That is, the argument addresses are removed from | |
4276 | the recipients list obtained from the headers. This is compatible with Smail 3 | |
4277 | and in accordance with the documented behaviour of several versions of | |
4278 | Sendmail, as described in man pages on a number of operating systems (e.g. | |
4279 | Solaris 8, IRIX 6.5, HP-UX 11). However, some versions of Sendmail $it{add} | |
4280 | argument addresses to those obtained from the headers, and the O'Reilly | |
4281 | Sendmail book documents it that way. Exim can be made to add argument addresses | |
4282 | instead of subtracting them by setting the option | |
4283 | \extract__addresses__remove__arguments\ false. | |
4284 | ||
4285 | If a ::Bcc:: header line is present, it is removed from the message unless | |
4286 | there is no ::To:: or ::Cc::, in which case a ::Bcc:: line with no data is | |
4287 | created. This is necessary for conformity with the original RFC 822 standard; | |
4288 | the requirement has been removed in RFC 2822, but that is still very new. | |
4289 | ||
4290 | .index \Resent@-\ header lines||with \-t-\ | |
4964e932 | 4291 | If there are any \Resent@-\ header lines in the message, Exim extracts |
495ae4b0 | 4292 | recipients from all ::Resent-To::, ::Resent-Cc::, and ::Resent-Bcc:: header |
4964e932 PH |
4293 | lines instead of from ::To::, ::Cc::, and ::Bcc::. This is for compatibility |
4294 | with Sendmail and other MTAs. (Prior to release 4.20, Exim gave an error if | |
495ae4b0 PH |
4295 | \-t-\ was used in conjunction with \Resent@-\ header lines.) |
4296 | ||
4297 | RFC 2822 talks about different sets of \Resent@-\ header lines (for when a | |
4298 | message is resent several times). The RFC also specifies that they should be | |
4299 | added at the front of the message, and separated by ::Received:: lines. It is | |
4300 | not at all clear how \-t-\ should operate in the present of multiple sets, | |
4301 | nor indeed exactly what constitutes a `set'. | |
4302 | In practice, it seems that MUAs do not follow the RFC. The \Resent@-\ lines are | |
4303 | often added at the end of the header, and if a message is resent more than | |
4304 | once, it is common for the original set of \Resent@-\ headers to be renamed as | |
4305 | \X-Resent@-\ when a new set is added. This removes any possible ambiguity. | |
4306 | ||
4307 | .option ti | |
4964e932 | 4308 | This option is exactly equivalent to \-t-\ \-i-\. It is provided for |
495ae4b0 PH |
4309 | compatibility with Sendmail. |
4310 | ||
4311 | .option tls-on-connect | |
4312 | .index TLS||use without STARTTLS | |
4313 | .index TLS||automatic start | |
d43194df PH |
4314 | This option is available when Exim is compiled with TLS support. |
4315 | .em | |
4316 | It forces all incoming SMTP connections to behave as if the incoming port is | |
4317 | listed in the \tls@_on@_connect@_ports\ option. See section ~~SECTsupobssmt and | |
4318 | chapter ~~CHAPTLS for further details. | |
4319 | .nem | |
495ae4b0 PH |
4320 | |
4321 | .option U | |
4322 | .index Sendmail compatibility||\-U-\ option ignored | |
4323 | Sendmail uses this option for `initial message submission', and its | |
4324 | documentation states that in future releases, it may complain about | |
4325 | syntactically invalid messages rather than fixing them when this flag is not | |
4326 | set. Exim ignores this option. | |
4327 | ||
4328 | .option v | |
4329 | This option causes Exim to write information to the standard error stream, | |
4330 | describing what it is doing. In particular, it shows the log lines for | |
4331 | receiving and delivering a message, and if an SMTP connection is made, the SMTP | |
4332 | dialogue is shown. Some of the log lines shown may not actually be written to | |
4333 | the log if the setting of \log@_selector\ discards them. Any relevant selectors | |
4334 | are shown with each log line. If none are shown, the logging is unconditional. | |
4335 | ||
4336 | .option x | |
4337 | AIX uses \-x-\ for a private purpose (`mail from a local mail program has | |
4338 | National Language Support extended characters in the body of the mail item'). | |
4339 | It sets \-x-\ when calling the MTA from its \mail\ command. Exim ignores this | |
4340 | option. | |
4341 | ||
4342 | .endoptions | |
4343 | ||
4344 | ||
4345 | ||
4346 | . | |
4347 | . | |
4348 | . | |
4349 | . | |
4350 | . ============================================================================ | |
4351 | .chapter The Exim run time configuration file | |
4352 | .set runningfoot "configuration file" | |
4353 | .rset CHAPconf ~~chapter | |
4354 | ||
4355 | .index run time configuration | |
4356 | .index configuration file||general description | |
4357 | .index \\CONFIGURE@_FILE\\ | |
d43194df PH |
4358 | .index configuration file||errors in |
4359 | .index error||in configuration file | |
4360 | .index return code||for bad configuration | |
495ae4b0 PH |
4361 | Exim uses a single run time configuration file that is read whenever an Exim |
4362 | binary is executed. Note that in normal operation, this happens frequently, | |
4964e932 | 4363 | because Exim is designed to operate in a distributed manner, without central |
495ae4b0 PH |
4364 | control. |
4365 | ||
d43194df PH |
4366 | .em |
4367 | If a syntax error is detected while reading the configuration file, Exim | |
4368 | writes a message on the standard error, and exits with a non-zero return code. | |
4369 | The message is also written to the panic log. \**Note**\: only simple syntax | |
4370 | errors can be detected at this time. The values of any expanded options are | |
4371 | not checked until the expansion happens, even when the expansion does not | |
4372 | actually alter the string. | |
4373 | .nem | |
4374 | ||
4375 | ||
495ae4b0 PH |
4376 | The name of the configuration file is compiled into the binary for security |
4377 | reasons, and is specified by the \\CONFIGURE@_FILE\\ compilation option. In | |
4378 | most configurations, this specifies a single file. However, it is permitted to | |
4379 | give a colon-separated list of file names, in which case Exim uses the first | |
4380 | existing file in the list. | |
4381 | ||
4382 | .index \\EXIM@_USER\\ | |
4383 | .index \\EXIM@_GROUP\\ | |
d43194df PH |
4384 | .index \\CONFIGURE@_OWNER\\ |
4385 | .index \\CONFIGURE@_GROUP\\ | |
495ae4b0 PH |
4386 | .index configuration file||ownership |
4387 | .index ownership||configuration file | |
d43194df PH |
4388 | The run time configuration file must be owned by root or by the user that is |
4389 | specified at compile time by the \\EXIM@_USER\\ option, or by the user that is | |
4390 | specified at compile time by the \\CONFIGURE@_OWNER\\ option (if set). The | |
4391 | configuration file must not be world-writeable or group-writeable, unless its | |
4392 | group is the one specified at compile time by the \\EXIM@_GROUP\\ option | |
4393 | .em | |
4394 | or by the \\CONFIGURE@_GROUP\\ option. | |
4395 | .nem | |
495ae4b0 | 4396 | |
4964e932 PH |
4397 | \**Warning**\: In a conventional configuration, where the Exim binary is setuid |
4398 | to root, anybody who is able to edit the run time configuration file has an | |
4399 | easy way to run commands as root. If you make your mail administrators members | |
4400 | of the Exim group, but do not trust them with root, make sure that the run time | |
495ae4b0 PH |
4401 | configuration is not group writeable. |
4402 | ||
495ae4b0 | 4403 | A default configuration file, which will work correctly in simple situations, |
d43194df PH |
4404 | is provided in the file \(src/configure.default)\. If \\CONFIGURE@_FILE\\ |
4405 | defines just one file name, the installation process copies the default | |
4406 | configuration to a new file of that name if it did not previously exist. If | |
4407 | \\CONFIGURE@_FILE\\ is a list, no default is automatically installed. Chapter | |
4408 | ~~CHAPdefconfil is a `walk-through' discussion of the default configuration. | |
495ae4b0 PH |
4409 | |
4410 | ||
4411 | .section Using a different configuration file | |
4412 | .index configuration file||alternate | |
4413 | A one-off alternate configuration can be specified by the \-C-\ command line | |
4414 | option, which may specify a single file or a list of files. However, when \-C-\ | |
4415 | is used, Exim gives up its root privilege, unless called by root or the Exim | |
4964e932 | 4416 | user (or unless the argument for \-C-\ is identical to the built-in value from |
495ae4b0 PH |
4417 | \\CONFIGURE@_FILE\\). \-C-\ is useful mainly for checking the syntax of |
4418 | configuration files before installing them. No owner or group checks are done | |
4419 | on a configuration file specified by \-C-\. | |
4420 | ||
4421 | The privileged use of \-C-\ by the Exim user can be locked out by setting | |
4422 | \\ALT@_CONFIG@_ROOT@_ONLY\\ in \(Local/Makefile)\ when building Exim. However, | |
4423 | if you do this, you also lock out the possibility of testing a | |
4424 | configuration using \-C-\ right through message reception and delivery, even if | |
4425 | the caller is root. The reception works, but by that time, Exim is running as | |
4426 | the Exim user, so when it re-execs to regain privilege for the delivery, the | |
4427 | use of \-C-\ causes privilege to be lost. However, root can test reception and | |
4964e932 | 4428 | delivery using two separate commands (one to put a message on the queue, using |
495ae4b0 PH |
4429 | \-odq-\, and another to do the delivery, using \-M-\). |
4430 | ||
4431 | If \\ALT@_CONFIG@_PREFIX\\ is defined \(in Local/Makefile)\, it specifies a | |
4432 | prefix string with which any file named in a \-C-\ command line option must | |
4433 | start. In addition, the file name must not contain the sequence \"/../"\. There | |
4434 | is no default setting for \\ALT@_CONFIG@_PREFIX\\; when it is unset, any file | |
4435 | name can be used with \-C-\. | |
4436 | ||
4437 | One-off changes to a configuration can be specified by the \-D-\ command line | |
4964e932 | 4438 | option, which defines and overrides values for macros used inside the |
495ae4b0 PH |
4439 | configuration file. However, like \-C-\, the use of this option by a |
4440 | non-privileged user causes Exim to discard its root privilege. | |
4441 | If \\DISABLE@_D@_OPTION\\ is defined in \(Local/Makefile)\, the use of \-D-\ is | |
4442 | completely disabled, and its use causes an immediate error exit. | |
4443 | ||
4444 | Some sites may wish to use the same Exim binary on different machines that | |
4445 | share a file system, but to use different configuration files on each machine. | |
4446 | If \\CONFIGURE@_FILE@_USE@_NODE\\ is defined in \(Local/Makefile)\, Exim first | |
4447 | looks for a file whose name is the configuration file name followed by a dot | |
4448 | and the machine's node name, as obtained from the \*uname()*\ function. If this | |
4964e932 | 4449 | file does not exist, the standard name is tried. This processing occurs for |
495ae4b0 PH |
4450 | each file name in the list given by \\CONFIGURE@_FILE\\ or \-C-\. |
4451 | ||
4452 | In some esoteric situations different versions of Exim may be run under | |
4453 | different effective uids and the \\CONFIGURE@_FILE@_USE@_EUID\\ is defined to | |
4454 | help with this. See the comments in \(src/EDITME)\ for details. | |
4455 | ||
4456 | ||
4457 | .section Configuration file format | |
4458 | .rset SECTconffilfor "~~chapter.~~section" | |
4459 | .index configuration file||format of | |
4460 | .index format||configuration file | |
4461 | Exim's configuration file is divided into a number of different parts. General | |
4462 | option settings must always appear at the start of the file. The other parts | |
4463 | are all optional, and may appear in any order. Each part other than the first | |
4464 | is introduced by the word `begin' followed by the name of the part. The | |
4465 | optional parts are: | |
4466 | ||
4467 | .numberpars $. | |
4468 | \*ACL*\: Access control lists for controlling incoming SMTP mail. | |
4469 | .nextp | |
4470 | .index \\AUTH\\||configuration | |
4471 | \*authenticators*\: Configuration settings for the authenticator drivers. These | |
4472 | are concerned with the SMTP \\AUTH\\ command (see chapter ~~CHAPSMTPAUTH). | |
4473 | .nextp | |
4474 | \*routers*\: Configuration settings for the router drivers. Routers process | |
4475 | addresses and determine how the message is to be delivered. | |
4476 | .nextp | |
4477 | \*transports*\: Configuration settings for the transport drivers. Transports | |
4478 | define mechanisms for copying messages to destinations. | |
4479 | .nextp | |
4480 | \*retry*\: Retry rules, for use when a message cannot be immediately delivered. | |
4481 | .nextp | |
4482 | \*rewrite*\: Global address rewriting rules, for use when a message arrives and | |
4483 | when new addresses are generated during delivery. | |
4484 | .nextp | |
4485 | \*local@_scan*\: Private options for the \*local@_scan()*\ function. If you | |
4486 | want to use this feature, you must set | |
4487 | .display asis | |
4488 | LOCAL_SCAN_HAS_OPTIONS=yes | |
4489 | .endd | |
4964e932 | 4490 | in \(Local/Makefile)\ before building Exim. Full details of the |
495ae4b0 PH |
4491 | \*local@_scan()*\ facility are given in chapter ~~CHAPlocalscan. |
4492 | .endp | |
d43194df PH |
4493 | .index configuration file||leading whitespace in |
4494 | .index configuration file||trailing whitespace in | |
4495 | .index whitespace||in configuration file | |
4496 | .em | |
4497 | Leading and trailing whitespace in configuration lines is always ignored. | |
4498 | .nem | |
495ae4b0 PH |
4499 | Blank lines in the file, and lines starting with a @# character (ignoring |
4500 | leading white space) are treated as comments and are ignored. \**Note**\: a | |
4501 | @# character other than at the beginning of a line is not treated specially, | |
4502 | and does not introduce a comment. | |
4503 | ||
d43194df PH |
4504 | Any non-comment line can be continued by ending it with a backslash. |
4505 | .em | |
4506 | Note that the general rule for whitespace means that trailing white space after | |
4507 | the backslash is ignored, and leading white space at the start of continuation | |
4508 | lines is also ignored. | |
4509 | .nem | |
495ae4b0 PH |
4510 | Comment lines beginning with @# (but not empty lines) may appear in the middle |
4511 | of a sequence of continuation lines. | |
4512 | ||
4513 | A convenient way to create a configuration file is to start from the | |
4514 | default, which is supplied in \(src/configure.default)\, and add, delete, or | |
4515 | change settings as required. | |
4516 | ||
4517 | The ACLs, retry rules, and rewriting rules have their own syntax which is | |
4518 | described in chapters ~~CHAPACL, ~~CHAPretry, and ~~CHAPrewrite, respectively. | |
4519 | The other parts of the configuration file have some syntactic items in common, | |
4520 | and these are described below, from section ~~SECTcos onwards. Before that, the | |
4521 | inclusion, macro, and conditional facilities are described. | |
4522 | ||
4523 | ||
4524 | .section File inclusions in the configuration file | |
4525 | .index inclusions in configuration file | |
4526 | .index configuration file||including other files | |
4527 | .index .include in configuration file | |
4528 | .index .include@_if@_exists in configuration file | |
4529 | You can include other files inside Exim's run time configuration file by | |
4530 | using this syntax: | |
4531 | .display | |
4532 | @.include <<file name>> | |
4533 | .endd | |
4534 | or | |
4535 | .display | |
4536 | @.include@_if@_exists <<file name>> | |
4537 | .endd | |
4964e932 PH |
4538 | on a line by itself. Double quotes round the file name are optional. If you use |
4539 | the first form, a configuration error occurs if the file does not exist; the | |
495ae4b0 PH |
4540 | second form does nothing for non-existent files. |
4541 | ||
4542 | Includes may be nested to any depth, but remember that Exim reads its | |
4543 | configuration file often, so it is a good idea to keep them to a minimum. | |
4544 | If you change the contents of an included file, you must HUP the daemon, | |
4545 | because an included file is read only when the configuration itself is read. | |
4546 | ||
4547 | The processing of inclusions happens early, at a physical line level, so, like | |
4548 | comment lines, an inclusion can be used in the middle of an option setting, | |
4549 | for example: | |
4550 | .display asis | |
4551 | hosts_lookup = a.b.c \ | |
4552 | .include /some/file | |
4553 | .endd | |
4964e932 PH |
4554 | Include processing happens |
4555 | after | |
495ae4b0 PH |
4556 | macro processing (see below). Its effect is to process the lines of the file as |
4557 | if they occurred inline where the inclusion appears. | |
4558 | ||
4559 | ||
4560 | .section Macros in the configuration file | |
4561 | .rset SECTmacrodefs "~~chapter.~~section" | |
4562 | .index macro||description of | |
4563 | .index configuration file||macros | |
4564 | If a line in the main part of the configuration (that is, before the first | |
4565 | `begin' line) begins with an upper case letter, it is taken as a macro | |
4566 | definition, and must be of the form | |
4567 | .display | |
4568 | <<name>> = <<rest of line>> | |
4569 | .endd | |
4570 | The name must consist of letters, digits, and underscores, and need not all be | |
4571 | in upper case, though that is recommended. The rest of the line, including any | |
4572 | continuations, is the replacement text, and has leading and trailing white | |
4573 | space removed. Quotes are not removed. The replacement text can never end with | |
4574 | a backslash character, but this doesn't seem to be a serious limitation. | |
4575 | ||
4576 | Once a macro is defined, all subsequent lines in the file (and any included | |
4577 | files) are scanned for the macro name; if there are several macros, the line is | |
4578 | scanned for each in turn, in the order in which they are defined. The | |
4579 | replacement text is not re-scanned for the current macro, though it is scanned | |
4580 | for subsequently defined macros. For this reason, a macro name may not contain | |
4581 | the name of a previously defined macro as a substring. You could, for example, | |
4582 | define | |
4583 | .display asis | |
4584 | ABCD_XYZ = <<something>> | |
4585 | ABCD = <<something else>> | |
4586 | .endd | |
4587 | but putting the definitions in the opposite order would provoke a configuration | |
4588 | error. | |
4589 | ||
4590 | Macro expansion is applied to individual lines from the file, before checking | |
4591 | for line continuation or file inclusion (see below). If a line consists solely | |
4592 | of a macro name, and the expansion of the macro is empty, the line is ignored. | |
4593 | A macro at the start of a line may turn the line into a comment line or a | |
4594 | \".include"\ line. | |
4595 | ||
4596 | As an example of macro usage, consider a configuration where aliases are looked | |
4597 | up in a MySQL database. It helps to keep the file less cluttered if long | |
4598 | strings such as SQL statements are defined separately as macros, for example: | |
4599 | .display asis | |
4600 | ALIAS_QUERY = select mailbox from user where \ | |
4601 | login=${quote_mysql:$local_part}; | |
4602 | .endd | |
4603 | This can then be used in a \%redirect%\ router setting like this: | |
4604 | .display asis | |
4605 | data = ${lookup mysql{ALIAS_QUERY}} | |
4606 | .endd | |
4607 | In earlier versions of Exim macros were sometimes used for domain, host, or | |
4608 | address lists. In Exim 4 these are handled better by named lists -- see section | |
4609 | ~~SECTnamedlists. | |
4610 | ||
4611 | Macros in the configuration file can be overridden by the \-D-\ command line | |
4612 | option, but Exim gives up its root privilege when \-D-\ is used, unless called | |
4613 | by root or the Exim user. | |
4614 | ||
4615 | ||
4616 | .section Conditional skips in the configuration file | |
4617 | .index configuration file||conditional skips | |
4618 | .index .ifdef | |
4619 | You can use the directives \".ifdef"\, \".ifndef"\, \".elifdef"\, | |
4964e932 PH |
4620 | \".elifndef"\, \".else"\, and \".endif"\ to dynamically include or exclude |
4621 | portions of the configuration file. The processing happens whenever the file is | |
4622 | read (that is, when an Exim binary starts to run). | |
495ae4b0 PH |
4623 | |
4624 | The implementation is very simple. Instances of the first four directives must | |
4625 | be followed by text that includes the names of one or macros. The condition | |
4626 | that is tested is whether or not any macro substitution has taken place in the | |
4627 | line. Thus: | |
4628 | .display | |
4629 | @.ifdef AAA | |
4630 | message@_size@_limit = 50M | |
4631 | @.else | |
4632 | message@_size@_limit = 100M | |
4633 | @.endif | |
4634 | .endd | |
4635 | sets a message size limit of 50M if the macro \"AAA"\ is defined, and 100M | |
4636 | otherwise. If there is more than one macro named on the line, the condition | |
4637 | is true if any of them are defined. That is, it is an `or' condition. To | |
4638 | obtain an `and' condition, you need to use nested \".ifdef"\s. | |
4639 | ||
4640 | Although you can use a macro expansion to generate one of these directives, | |
4641 | it is not very useful, because the condition `there was a macro substitution | |
4642 | in this line' will always be true. | |
4643 | ||
4644 | Text following \".else"\ and \".endif"\ is ignored, and can be used as comment | |
4645 | to clarify complicated nestings. | |
4646 | ||
4647 | ||
4648 | .section Common option syntax | |
4649 | .rset SECTcos "~~chapter.~~section" | |
4650 | .index common option syntax | |
4651 | .index syntax of common options | |
4652 | .index configuration file||common option syntax | |
4653 | For the main set of options, driver options, and \*local@_scan()*\ options, | |
4654 | each setting is on a line by itself, and starts with a name consisting of | |
4655 | lower-case letters and underscores. Many options require a data value, and in | |
4656 | these cases the name must be followed by an equals sign (with optional white | |
4657 | space) and then the value. For example: | |
4658 | .display asis | |
4659 | qualify_domain = mydomain.example.com | |
4660 | .endd | |
4661 | Some option settings may contain sensitive data, for example, passwords for | |
4662 | accessing databases. To stop non-admin users from using the \-bP-\ command line | |
4663 | option to read these values, you can precede the option settings with the word | |
4664 | `hide'. For example: | |
4665 | .display asis | |
4666 | hide mysql_servers = localhost/users/admin/secret-password | |
4667 | .endd | |
4668 | For non-admin users, such options are displayed like this: | |
4669 | .display asis | |
4670 | mysql_servers = <value not displayable> | |
4671 | .endd | |
4672 | If `hide' is used on a driver option, it hides the value of that option on all | |
4673 | instances of the same driver. | |
4674 | ||
4675 | The following sections describe the syntax used for the different data types | |
4676 | that are found in option settings. | |
4677 | ||
4678 | .section Boolean options | |
4679 | .index format||boolean | |
4680 | .index boolean configuration values | |
4681 | Options whose type is given as boolean are on/off switches. There are two | |
4682 | different ways of specifying such options: with and without a data value. If | |
4683 | the option name is specified on its own without data, the switch is turned on; | |
4684 | if it is preceded by `no@_' or `not@_' the switch is turned off. However, | |
4685 | boolean options may optionally be followed by an equals sign and one of the | |
4686 | words `true', `false', `yes', or `no', as an alternative syntax. For example, | |
4687 | the following two settings have exactly the same effect: | |
4688 | .display asis | |
4689 | queue_only | |
4690 | queue_only = true | |
4691 | .endd | |
4692 | The following two lines also have the same (opposite) effect: | |
4693 | .display asis | |
4694 | no_queue_only | |
4695 | queue_only = false | |
4696 | .endd | |
4697 | You can use whichever syntax you prefer. | |
4698 | ||
4699 | ||
4700 | ||
4701 | .section Integer values | |
4702 | .index integer configuration values | |
4703 | .index format||integer | |
4704 | If an integer data item starts with the characters `0x', the remainder of it | |
4705 | is interpreted as a hexadecimal number. Otherwise, it is treated as octal if it | |
4706 | starts with the digit 0, and decimal if not. If an integer value is followed by | |
4707 | the letter K, it is multiplied by 1024; if it is followed by the letter M, it | |
4708 | is multiplied by 1024x1024. | |
4709 | ||
4710 | When the values of integer option settings are output, values which are an | |
4964e932 | 4711 | exact multiple of 1024 or 1024x1024 are |
495ae4b0 PH |
4712 | sometimes, but not always, |
4713 | printed using the letters K and M. The printing style is independent of the | |
4714 | actual input format that was used. | |
4715 | ||
4716 | .section Octal integer values | |
4717 | .index integer format | |
4718 | .index format||octal integer | |
4719 | The value of an option specified as an octal integer is always interpreted in | |
4720 | octal, whether or not it starts with the digit zero. Such options are always | |
4721 | output in octal. | |
4722 | ||
4723 | ||
4724 | .section Fixed point number values | |
4725 | .index fixed point configuration values | |
4726 | .index format||fixed point | |
4727 | A fixed point number consists of a decimal integer, optionally followed by a | |
4728 | decimal point and up to three further digits. | |
4729 | ||
4730 | ||
4731 | .section Time interval values | |
4732 | .index time interval||specifying in configuration | |
4733 | .index format||time interval | |
4734 | .rset SECTtimeformat "~~chapter.~~section" | |
4735 | A time interval is specified as a sequence of numbers, each followed by one of | |
4736 | the following letters, with no intervening white space: | |
4737 | .display rm | |
4738 | .tabs 5 | |
4739 | \s\ $t seconds | |
4740 | \m\ $t minutes | |
4741 | \h\ $t hours | |
4742 | \d\ $t days | |
4743 | \w\ $t weeks | |
4744 | .endd | |
4745 | For example, `3h50m' specifies 3 hours and 50 minutes. The values of time | |
4746 | intervals are output in the same format. | |
4964e932 | 4747 | Exim does not restrict the values; it is perfectly acceptable, for example, to |
495ae4b0 PH |
4748 | specify `90m' instead of `1h30m'. |
4749 | ||
4750 | ||
4751 | .section String values | |
4752 | .index string||format of configuration values | |
4753 | .index format||string | |
4754 | .rset SECTstrings "~~chapter.~~section" | |
4755 | If a string data item does not start with a double-quote character, it is taken | |
4756 | as consisting of the remainder of the line plus any continuation lines, | |
4757 | starting at the first character after any leading white space, with trailing | |
4758 | white space characters removed, and with no interpretation of the characters in | |
4759 | the string. Because Exim removes comment lines (those beginning with @#) at an | |
4760 | early stage, they can appear in the middle of a multi-line string. The | |
4761 | following settings are therefore equivalent: | |
4762 | .display asis | |
4763 | trusted_users = uucp:mail | |
4764 | ||
4765 | trusted_users = uucp:\ | |
4766 | # This comment line is ignored | |
4767 | ||
4768 | .endd | |
4769 | .index string||quoted | |
4770 | .index escape characters in quoted strings | |
4771 | If a string does start with a double-quote, it must end with a closing | |
4772 | double-quote, and any backslash characters other than those used for line | |
4773 | continuation are interpreted as escape characters, as follows: | |
4774 | .display | |
4775 | .tabs 15 | |
4776 | @\@\ $t $rm{single backslash} | |
4777 | @\n $t $rm{newline} | |
4778 | @\r $t $rm{carriage return} | |
4779 | @\t $t $rm{tab} | |
4780 | @\<<octal digits>> $t $rm{up to 3 octal digits specify one character} | |
4781 | @\x<<hex digits>> $t $rm{up to 2 hexadecimal digits specify one character} | |
4782 | .endd | |
4783 | If a backslash is followed by some other character, including a double-quote | |
4784 | character, that character replaces the pair. | |
4785 | ||
4786 | Quoting is necessary only if you want to make use of the backslash escapes to | |
4787 | insert special characters, or if you need to specify a value with leading or | |
4788 | trailing spaces. These cases are rare, so quoting is almost never needed in | |
4789 | current versions of Exim. In versions of Exim before 3.14, quoting was required | |
4790 | in order to continue lines, so you may come across older configuration files | |
4791 | and examples that apparently quote unnecessarily. | |
4792 | ||
4793 | .section Expanded strings | |
4794 | .index string||expansion, definition of | |
4795 | .index expansion||definition of | |
4796 | Some strings in the configuration file are subjected to \*string expansion*\, | |
4797 | by which means various parts of the string may be changed according to the | |
4798 | circumstances (see chapter ~~CHAPexpand). The input syntax for such strings is | |
4799 | as just described; in particular, the handling of backslashes in quoted strings | |
4800 | is done as part of the input process, before expansion takes place. However, | |
4801 | backslash is also an escape character for the expander, so any backslashes that | |
4802 | are required for that reason must be doubled if they are within a quoted | |
4803 | configuration string. | |
4804 | ||
4805 | .section User and group names | |
4806 | .index user name||format of | |
4807 | .index format||user name | |
4808 | .index group||name format | |
4809 | .index format||group name | |
4810 | User and group names are specified as strings, using the syntax described | |
4811 | above, but the strings are interpreted specially. A user or group name must | |
4812 | either consist entirely of digits, or be a name that can be looked up using the | |
4813 | \*getpwnam()*\ or \*getgrnam()*\ function, as appropriate. | |
4814 | ||
4815 | .section List construction | |
4816 | .index list||syntax of in configuration | |
4817 | .index format||list item in configuration | |
4818 | .index string list, definition | |
4819 | .rset SECTlistconstruct "~~chapter.~~section" | |
d43194df PH |
4820 | The data for some configuration options is a list of items, with colon as the |
4821 | default separator. Many of these options are shown with type `string list' in | |
4822 | the descriptions later in this document. Others are listed as `domain list', | |
4823 | `host list', `address list', or `local part list'. Syntactically, they are all | |
4824 | the same; however, those other than `string list' are subject to particular | |
4825 | kinds of interpretation, as described in chapter ~~CHAPdomhosaddlists. | |
495ae4b0 PH |
4826 | |
4827 | In all these cases, the entire list is treated as a single string as far as the | |
4828 | input syntax is concerned. The \trusted@_users\ setting in section | |
4829 | ~~SECTstrings above is an example. If a colon is actually needed in an item in | |
4830 | a list, it must be entered as two colons. Leading and trailing white space on | |
4831 | each item in a list is ignored. This makes it possible to include items that | |
4832 | start with a colon, and in particular, certain forms of IPv6 address. For | |
4833 | example, the list | |
4834 | .display asis | |
4835 | local_interfaces = 127.0.0.1 : ::::1 | |
4836 | .endd | |
4837 | contains two IP addresses, the IPv4 address 127.0.0.1 and the IPv6 address | |
d43194df | 4838 | @:@:1. |
495ae4b0 PH |
4839 | .index list||separator, changing |
4840 | .index IPv6||addresses in lists | |
d43194df PH |
4841 | Doubling colons in IPv6 addresses is an unwelcome chore, so a mechanism was |
4842 | introduced to allow the separator character to be changed. If a list begins | |
4843 | with a left angle bracket, followed by any punctuation character, that | |
4844 | character is used instead of colon as the list separator. For example, the list | |
4845 | above can be rewritten to use a semicolon separator like this: | |
495ae4b0 PH |
4846 | .display asis |
4847 | local_interfaces = <; 127.0.0.1 ; ::1 | |
4848 | .endd | |
4849 | This facility applies to all lists, with the exception of the list in | |
4850 | \log@_file@_path\. It is recommended that the use of non-colon separators be | |
4851 | confined to circumstances where they really are needed. | |
4852 | ||
4853 | ||
d43194df PH |
4854 | .em |
4855 | .section Empty items in lists | |
4856 | .rset SECTempitelis "~~chapter.~~section" | |
4857 | .index list||empty item in | |
4858 | An empty item at the end of a list is always ignored. In other words, trailing | |
4859 | separator characters are ignored. Thus, the list in | |
4860 | .display asis | |
4861 | senders = user@domain : | |
4862 | .endd | |
4863 | contains only a single item. If you want to include an empty string as one item | |
4864 | in a list, it must not be the last item. For example, this list contains three | |
4865 | items, the second of which is empty: | |
4866 | .display asis | |
4867 | senders = user1@domain : : user2@domain | |
4868 | .endd | |
4869 | \**Note**\: there must be whitespace between the two colons, as otherwise they | |
4870 | are interpreted as representing a single colon data character (and the list | |
4871 | would then contain just one item). If you want to specify a list that contains | |
4872 | just one, empty item, you can do it as in this example: | |
4873 | .display asis | |
4874 | senders = : | |
4875 | .endd | |
4876 | In this case, the first item is empty, and the second is discarded because it | |
4877 | is at the end of the list. | |
4878 | .nem | |
4879 | ||
4880 | ||
495ae4b0 PH |
4881 | .section Format of driver configurations |
4882 | .rset SECTfordricon "~~chapter.~~section" | |
4883 | .index drivers||configuration format | |
4884 | There are separate parts in the configuration for defining routers, transports, | |
4885 | and authenticators. In each part, you are defining a number of driver | |
4886 | instances, each with its own set of options. Each driver instance is defined by | |
4887 | a sequence of lines like this: | |
4888 | .display | |
4889 | <<instance name>>: | |
4890 | <<option>> | |
4891 | ... | |
4892 | <<option>> | |
4893 | .endd | |
4894 | In the following example, the instance name is \%localuser%\, and it is | |
4895 | followed by three options settings: | |
4896 | .display asis | |
4897 | localuser: | |
4898 | driver = accept | |
4899 | check_local_user | |
4900 | transport = local_delivery | |
4901 | .endd | |
4964e932 | 4902 | For each driver instance, you specify which Exim code module it uses -- by the |
495ae4b0 PH |
4903 | setting of the \driver\ option -- and (optionally) some configuration settings. |
4904 | For example, in the case of transports, if you want a transport to deliver with | |
4905 | SMTP you would use the \%smtp%\ driver; if you want to deliver to a local file | |
4906 | you would use the \%appendfile%\ driver. Each of the drivers is described in | |
4907 | detail in its own separate chapter later in this manual. | |
4908 | ||
4909 | You can have several routers, transports, or authenticators that are based on | |
4910 | the same underlying driver (each must have a different name). | |
4911 | ||
4912 | The order in which routers are defined is important, because addresses are | |
4913 | passed to individual routers one by one, in order. The order in which | |
4914 | transports are defined does not matter at all. The order in which | |
4915 | authenticators are defined is used only when Exim, as a client, is searching | |
4916 | them to find one that matches an authentication mechanism offered by the | |
4917 | server. | |
4918 | ||
4919 | .index generic options | |
4920 | .index options||generic, definition of | |
4921 | Within a driver instance definition, there are two kinds of option: | |
4922 | $it{generic} and $it{private}. The generic options are those that apply to all | |
4923 | drivers of the same type (that is, all routers, all transports or all | |
4924 | authenticators). | |
4925 | The \driver\ option is a generic option that must appear in every definition. | |
4926 | .index private options | |
4927 | The private options are special for each driver, and none need appear, because | |
4928 | they all have default values. | |
4929 | ||
4930 | The options may appear in any order, except that the \driver\ option must | |
4931 | precede any private options, since these depend on the particular driver. For | |
4932 | this reason, it is recommended that \driver\ always be the first option. | |
4933 | ||
4934 | Driver instance names, which are used for reference in log entries and | |
4935 | elsewhere, can be any sequence of letters, digits, and underscores (starting | |
4936 | with a letter) and must be unique among drivers of the same type. A router and | |
4937 | a transport (for example) can each have the same name, but no two router | |
4938 | instances can have the same name. The name of a driver instance should not be | |
4939 | confused with the name of the underlying driver module. For example, the | |
4940 | configuration lines: | |
4941 | .display asis | |
4942 | remote_smtp: | |
4943 | driver = smtp | |
4944 | .endd | |
4945 | create an instance of the \%smtp%\ transport driver whose name is | |
4946 | \%remote@_smtp%\. The same driver code can be used more than once, with | |
4947 | different instance names and different option settings each time. A second | |
4948 | instance of the \%smtp%\ transport, with different options, might be defined | |
4949 | thus: | |
4950 | .display asis | |
4951 | special_smtp: | |
4952 | driver = smtp | |
4953 | port = 1234 | |
4954 | command_timeout = 10s | |
4955 | .endd | |
4956 | The names \%remote@_smtp%\ and \%special@_smtp%\ would be used to reference | |
4957 | these transport instances from routers, and these names would appear in log | |
4958 | lines. | |
4959 | ||
4960 | Comment lines may be present in the middle of driver specifications. The full | |
4961 | list of option settings for any particular driver instance, including all the | |
4962 | defaulted values, can be extracted by making use of the \-bP-\ command line | |
4963 | option. | |
4964 | ||
4965 | ||
4966 | ||
4967 | ||
4968 | ||
4969 | ||
4970 | . | |
4971 | . | |
4972 | . | |
4973 | . | |
4974 | . ============================================================================ | |
4975 | .chapter The default configuration file | |
4976 | .set runningfoot "default configuration" | |
4977 | .rset CHAPdefconfil "~~chapter" | |
4978 | .index configuration file||default, `walk through' | |
4979 | .index default||configuration file `walk through' | |
4980 | The default configuration file supplied with Exim as \(src/configure.default)\ | |
4981 | is sufficient for a host with simple mail requirements. As an introduction to | |
4982 | the way Exim is configured, this chapter `walks through' the default | |
4983 | configuration, giving brief explanations of the settings. Detailed descriptions | |
4984 | of the options are given in subsequent chapters. The default configuration file | |
4985 | itself contains extensive comments about ways you might want to modify the | |
4986 | initial settings. However, note that there are many options that are not | |
4987 | mentioned at all in the default configuration. | |
4988 | ||
4989 | ||
4990 | .section Main configuration settings | |
4991 | The main (global) configuration option settings must always come first in the | |
4992 | file. The first thing you'll see in the file, after some initial comments, is | |
4993 | the line | |
4994 | .display asis | |
4995 | # primary_hostname = | |
4996 | .endd | |
4997 | This is a commented-out setting of the \primary@_hostname\ option. Exim needs | |
4998 | to know the official, fully qualified name of your host, and this is where you | |
4999 | can specify it. However, in most cases you do not need to set this option. When | |
5000 | it is unset, Exim uses the \*uname()*\ system function to obtain the host name. | |
5001 | ||
5002 | The first three non-comment configuration lines are as follows: | |
5003 | .display asis | |
5004 | domainlist local_domains = @ | |
5005 | domainlist relay_to_domains = | |
5006 | hostlist relay_from_hosts = 127.0.0.1 | |
5007 | .endd | |
5008 | These are not, in fact, option settings. They are definitions of two named | |
5009 | domain lists and one named host list. Exim allows you to give names to lists of | |
5010 | domains, hosts, and email addresses, in order to make it easier to manage the | |
5011 | configuration file (see section ~~SECTnamedlists). | |
5012 | ||
5013 | The first line defines a domain list called \*local@_domains*\; this is used | |
5014 | later in the configuration to identify domains that are to be delivered | |
4964e932 | 5015 | on the local host. |
495ae4b0 PH |
5016 | .index @@ in a domain list |
5017 | There is just one item in this list, the string `@@'. This is a special form of | |
5018 | entry which means `the name of the local host'. Thus, if the local host is | |
5019 | called \*a.host.example*\, mail to \*any.user@@a.host.example*\ is expected to | |
5020 | be delivered locally. Because the local host's name is referenced indirectly, | |
5021 | the same configuration file can be used on different hosts. | |
5022 | ||
5023 | The second line defines a domain list called \*relay@_to@_domains*\, but the | |
5024 | list itself is empty. Later in the configuration we will come to the part that | |
5025 | controls mail relaying through the local host; it allows relaying to any | |
5026 | domains in this list. By default, therefore, no relaying on the basis of a mail | |
5027 | domain is permitted. | |
5028 | ||
5029 | The third line defines a host list called \*relay@_from@_hosts*\. This list is | |
5030 | used later in the configuration to permit relaying from any host or IP address | |
5031 | that matches the list. The default contains just the IP address of the IPv4 | |
5032 | loopback interface, which means that processes on the local host are able to | |
5033 | submit mail for relaying by sending it over TCP/IP to that interface. No other | |
5034 | hosts are permitted to submit messages for relaying. | |
5035 | ||
5036 | Just to be sure there's no misunderstanding: at this point in the configuration | |
5037 | we aren't actually setting up any controls. We are just defining some domains | |
5038 | and hosts that will be used in the controls that are specified later. | |
5039 | ||
5040 | The next configuration line is a genuine option setting: | |
5041 | .display asis | |
5042 | acl_smtp_rcpt = acl_check_rcpt | |
5043 | .endd | |
5044 | This option specifies an \*Access Control List*\ (ACL) which is to be used | |
4964e932 | 5045 | during an incoming SMTP session for every recipient of a message (every |
495ae4b0 PH |
5046 | \\RCPT\\ command). The name of the list is \*acl@_check@_rcpt*\, and we will |
5047 | come to its definition below, in the ACL section of the configuration. ACLs | |
5048 | control which recipients are accepted for an incoming message -- if a | |
5049 | configuration does not provide an ACL to check recipients, no SMTP mail can be | |
5050 | accepted. | |
5051 | ||
5052 | Two commented-out options settings are next: | |
5053 | .display asis | |
5054 | # qualify_domain = | |
5055 | # qualify_recipient = | |
5056 | .endd | |
5057 | The first of these specifies a domain that Exim uses when it constructs a | |
5058 | complete email address from a local login name. This is often needed when Exim | |
5059 | receives a message from a local process. If you do not set \qualify@_domain\, | |
5060 | the value of \primary@_hostname\ is used. If you set both of these options, you | |
5061 | can have different qualification domains for sender and recipient addresses. If | |
5062 | you set only the first one, its value is used in both cases. | |
5063 | ||
5064 | .index domain literal||recognizing format | |
5065 | The following line must be uncommented if you want Exim to recognize | |
5066 | addresses of the form \*user@@[10.11.12.13]*\ that is, with a `domain literal' | |
5067 | (an IP address) instead of a named domain. | |
5068 | .display asis | |
5069 | # allow_domain_literals | |
5070 | .endd | |
495ae4b0 PH |
5071 | The RFCs still require this form, but many people think that in the modern |
5072 | Internet it makes little sense to permit mail to be sent to specific hosts by | |
5073 | quoting their IP addresses. This ancient format has been used by people who | |
5074 | try to abuse hosts by using them for unwanted relaying. However, some | |
4964e932 | 5075 | people believe there are circumstances (for example, messages addressed to |
495ae4b0 | 5076 | \*postmaster*\) where domain literals are still useful. |
495ae4b0 PH |
5077 | |
5078 | The next configuration line is a kind of trigger guard: | |
5079 | .display asis | |
5080 | never_users = root | |
5081 | .endd | |
5082 | It specifies that no delivery must ever be run as the root user. The normal | |
5083 | convention is to set up \*root*\ as an alias for the system administrator. This | |
5084 | setting is a guard against slips in the configuration. | |
5085 | The list of users specified by \never@_users\ is not, however, the complete | |
5086 | list; the build-time configuration in \(Local/Makefile)\ has an option called | |
5087 | \\FIXED@_NEVER@_USERS\\ specifying a list that cannot be overridden. The | |
4964e932 | 5088 | contents of \never@_users\ are added to this list. By default |
495ae4b0 PH |
5089 | \\FIXED@_NEVER@_USERS\\ also specifies root. |
5090 | ||
5091 | When a remote host connects to Exim in order to send mail, the only information | |
5092 | Exim has about the host's identity is its IP address. The next configuration | |
5093 | line, | |
5094 | .display asis | |
5095 | host_lookup = * | |
5096 | .endd | |
5097 | specifies that Exim should do a reverse DNS lookup on all incoming connections, | |
5098 | in order to get a host name. This improves the quality of the logging | |
5099 | information, but if you feel it is too expensive, you can remove it entirely, | |
5100 | or restrict the lookup to hosts on `nearby' networks. | |
4964e932 | 5101 | Note that it is not always possible to find a host name from an IP address, |
495ae4b0 PH |
5102 | because not all DNS reverse zones are maintained, and sometimes DNS servers are |
5103 | unreachable. | |
5104 | ||
5105 | The next two lines are concerned with \*ident*\ callbacks, as defined by RFC | |
5106 | 1413 (hence their names): | |
5107 | .display asis | |
5108 | rfc1413_hosts = * | |
5109 | rfc1413_query_timeout = 30s | |
5110 | .endd | |
5111 | These settings cause Exim to make ident callbacks for all incoming SMTP calls. | |
5112 | You can limit the hosts to which these calls are made, or change the timeout | |
5113 | that is used. If you set the timeout to zero, all ident calls are disabled. | |
5114 | Although they are cheap and can provide useful information for tracing problem | |
5115 | messages, some hosts and firewalls have problems with ident calls. This can | |
5116 | result in a timeout instead of an immediate refused connection, leading to | |
5117 | delays on starting up an incoming SMTP session. | |
5118 | ||
5119 | When Exim receives messages over SMTP connections, it expects all addresses to | |
5120 | be fully qualified with a domain, as required by the SMTP definition. However, | |
5121 | if you are running a server to which simple clients submit messages, you may | |
5122 | find that they send unqualified addresses. The two commented-out options: | |
5123 | .display asis | |
5124 | # sender_unqualified_hosts = | |
5125 | # recipient_unqualified_hosts = | |
5126 | .endd | |
5127 | show how you can specify hosts that are permitted to send unqualified sender | |
5128 | and recipient addresses, respectively. | |
5129 | ||
5130 | The \percent@_hack@_domains\ option is also commented out: | |
5131 | .display asis | |
5132 | # percent_hack_domains = | |
5133 | .endd | |
5134 | It provides a list of domains for which the `percent hack' is to operate. This | |
5135 | is an almost obsolete form of explicit email routing. If you do not know | |
5136 | anything about it, you can safely ignore this topic. | |
5137 | ||
5138 | The last two settings in the main part of the default configuration are | |
5139 | concerned with messages that have been `frozen' on Exim's queue. When a message | |
5140 | is frozen, Exim no longer continues to try to deliver it. Freezing occurs when | |
5141 | a bounce message encounters a permanent failure because the sender address of | |
5142 | the original message that caused the bounce is invalid, so the bounce cannot be | |
5143 | delivered. This is probably the most common case, but there are also other | |
5144 | conditions that cause freezing, and frozen messages are not always bounce | |
5145 | messages. | |
5146 | .display asis | |
5147 | ignore_bounce_errors_after = 2d | |
5148 | timeout_frozen_after = 7d | |
5149 | .endd | |
5150 | The first of these options specifies that failing bounce messages are to be | |
5151 | discarded after 2 days on the queue. The second specifies that any frozen | |
5152 | message (whether a bounce message or not) is to be timed out (and discarded) | |
5153 | after a week. In this configuration, the first setting ensures that no failing | |
5154 | bounce message ever lasts a week. | |
5155 | ||
5156 | ||
5157 | .section ACL configuration | |
5158 | .index default||ACLs | |
5159 | .index ~~ACL||default configuration | |
5160 | In the default configuration, the ACL section follows the main configuration. | |
5161 | It starts with the line | |
5162 | .display asis | |
5163 | begin acl | |
5164 | .endd | |
5165 | and it contains the definition of one ACL called \*acl@_check@_rcpt*\ that was | |
5166 | referenced in the setting of \acl@_smtp@_rcpt\ above. | |
5167 | .index \\RCPT\\||ACL for | |
5168 | This ACL is used for every \\RCPT\\ command in an incoming SMTP message. Each | |
5169 | \\RCPT\\ command specifies one of the message's recipients. The ACL statements | |
5170 | are considered in order, until the recipient address is either accepted or | |
5171 | rejected. The \\RCPT\\ command is then accepted or rejected, according to the | |
5172 | result of the ACL processing. | |
5173 | .display asis | |
5174 | acl_check_rcpt: | |
5175 | .endd | |
5176 | This line, consisting of a name terminated by a colon, marks the start of the | |
5177 | ACL, and names it. | |
5178 | .display asis | |
5179 | accept hosts = : | |
5180 | .endd | |
5181 | This ACL statement accepts the recipient if the sending host matches the list. | |
5182 | But what does that strange list mean? It doesn't actually contain any host | |
5183 | names or IP addresses. The presence of the colon puts an empty item in the | |
5184 | list; Exim matches this only if the incoming message didn't come from a remote | |
5185 | host. The colon is important. Without it, the list itself is empty, and can | |
5186 | never match anything. | |
5187 | ||
5188 | What this statement is doing is to accept unconditionally all recipients in | |
5189 | messages that are submitted by SMTP from local processes using the standard | |
5190 | input and output (that is, not using TCP/IP). A number of MUAs operate in this | |
5191 | manner. | |
5192 | .display asis | |
5193 | deny domains = +local_domains | |
5194 | local_parts = ^[.] : ^.*[@%!/|] | |
5195 | ||
5196 | deny domains = !+local_domains | |
5197 | local_parts = ^[./|] : ^.*[@%!] : ^.*/\\.\\./ | |
4964e932 PH |
5198 | .endd |
5199 | These statements are concerned with local parts that contain any of the | |
495ae4b0 PH |
5200 | characters `@@', `%', `!', `/', `|', or dots in unusual places. Although these |
5201 | characters are entirely legal in local parts (in the case of `@@' and leading | |
5202 | dots, only if correctly quoted), they do not commonly occur in Internet mail | |
5203 | addresses. | |
5204 | ||
5205 | The first three have in the past been associated with explicitly routed | |
5206 | addresses (percent is still sometimes used -- see the \percent@_hack@_domains\ | |
5207 | option). Addresses containing these characters are regularly tried by spammers | |
5208 | in an attempt to bypass relaying restrictions, and also by open relay testing | |
5209 | programs. Unless you really need them it is safest to reject these characters | |
5210 | at this early stage. This configuration is heavy-handed in rejecting these | |
5211 | characters for all messages it accepts from remote hosts. This is a deliberate | |
5212 | policy of being as safe as possible. | |
5213 | ||
5214 | The first rule above is stricter, and is applied to messages that are addressed | |
5215 | to one of the local domains handled by this host. This is implemented by the | |
5216 | first condition, which restricts it to domains that are listed in the | |
5217 | \*local@_domains*\ domain list. The `+' character is used to indicate a | |
5218 | reference to a named list. In this configuration, there is just one domain in | |
5219 | \*local@_domains*\, but in general there may be many. | |
5220 | ||
5221 | The second condition on the first statement uses two regular expressions to | |
5222 | block local parts that begin with a dot or contain `@@', `%', `!', `/', or `|'. | |
5223 | If you have local accounts that include these characters, you will have to | |
5224 | modify this rule. | |
5225 | ||
5226 | Empty components (two dots in a row) are not valid in RFC 2822, but Exim | |
5227 | allows them because they have been encountered in practice. (Consider local | |
5228 | parts constructed as `first-initial.second-initial.family-name' when applied to | |
5229 | someone like the author of Exim, who has no second initial.) However, a local | |
5230 | part starting with a dot or containing `/../' can cause trouble if it is used | |
5231 | as part of a file name (for example, for a mailing list). This is also true for | |
5232 | local parts that contain slashes. A pipe symbol can also be troublesome if the | |
5233 | local part is incorporated unthinkingly into a shell command line. | |
5234 | ||
5235 | The second rule above applies to all other domains, and is less strict. This | |
5236 | allows your own users to send outgoing messages to sites that use slashes | |
5237 | and vertical bars in their local parts. It blocks local parts that begin | |
5238 | with a dot, slash, or vertical bar, but allows these characters within the | |
5239 | local part. However, the sequence `/../' is barred. The use of `@@', `%', and | |
5240 | `!' is blocked, as before. The motivation here is to prevent your users (or | |
5241 | your users' viruses) from mounting certain kinds of attack on remote sites. | |
5242 | ||
5243 | .display asis | |
5244 | accept local_parts = postmaster | |
5245 | domains = +local_domains | |
5246 | .endd | |
5247 | This statement, which has two conditions, accepts an incoming address if the | |
5248 | local part is \*postmaster*\ and the domain is one of those listed in the | |
5249 | \*local@_domains*\ domain list. The `+' character is used to indicate a | |
5250 | reference to a named list. In this configuration, there is just one domain in | |
5251 | \*local@_domains*\, but in general there may be many. | |
5252 | ||
5253 | The presence of this statement means that mail to postmaster is never blocked | |
5254 | by any of the subsequent tests. This can be helpful while sorting out problems | |
5255 | in cases where the subsequent tests are incorrectly denying access. | |
5256 | .display asis | |
5257 | require verify = sender | |
5258 | .endd | |
5259 | This statement requires the sender address to be verified before any subsequent | |
5260 | ACL statement can be used. If verification fails, the incoming recipient | |
5261 | address is refused. Verification consists of trying to route the address, to | |
4964e932 PH |
5262 | see if a |
5263 | bounce | |
495ae4b0 PH |
5264 | message could be delivered to it. In the case of remote addresses, basic |
5265 | verification checks only the domain, but \*callouts*\ can be used for more | |
5266 | verification if required. Section ~~SECTaddressverification discusses the | |
5267 | details of address verification. | |
5268 | ||
5269 | .display asis | |
5270 | # deny message = rejected because $sender_host_address is \ | |
5271 | # in a black list at $dnslist_domain\n\ | |
5272 | # $dnslist_text | |
5273 | # dnslists = black.list.example | |
5274 | # | |
5275 | # warn message = X-Warning: $sender_host_address is \ | |
5276 | # in a black list at $dnslist_domain | |
5277 | # log_message = found in $dnslist_domain | |
5278 | # dnslists = black.list.example | |
5279 | .endd | |
5280 | These commented-out lines are examples of how you could configure Exim to check | |
5281 | sending hosts against a DNS black list. The first statement rejects messages | |
5282 | from blacklisted hosts, whereas the second merely inserts a warning header | |
5283 | line. | |
5284 | ||
5285 | .display asis | |
5286 | accept domains = +local_domains | |
5287 | endpass | |
5288 | message = unknown user | |
5289 | verify = recipient | |
5290 | .endd | |
5291 | This statement accepts the incoming recipient address if its domain is one of | |
5292 | the local domains, but only if the address can be verified. Verification of | |
5293 | local addresses normally checks both the local part and the domain. The | |
5294 | \endpass\ line needs some explanation: if the condition above \endpass\ fails, | |
5295 | that is, if the address is not in a local domain, control is passed to the next | |
5296 | ACL statement. However, if the condition below \endpass\ fails, that is, if a | |
5297 | recipient in a local domain cannot be verified, access is denied and the | |
5298 | recipient is rejected. | |
5299 | .index customizing||ACL failure message | |
5300 | The \message\ modifier provides a customized error message for the failure. | |
5301 | .display asis | |
5302 | accept domains = +relay_to_domains | |
5303 | endpass | |
5304 | message = unrouteable address | |
5305 | verify = recipient | |
5306 | .endd | |
5307 | This statement accepts the incoming recipient address if its domain is one of | |
5308 | the domains for which this host is a relay, but again, only if the address can | |
5309 | be verified. | |
5310 | .display asis | |
5311 | accept hosts = +relay_from_hosts | |
5312 | .endd | |
5313 | Control reaches this statement only if the recipient's domain is neither a | |
5314 | local domain, nor a relay domain. The statement accepts the address if the | |
5315 | message is coming from one of the hosts that are defined as being allowed to | |
5316 | relay through this host. Recipient verification is omitted here, because in | |
5317 | many cases the clients are dumb MUAs that do not cope well with SMTP error | |
5318 | responses. If you are actually relaying out from MTAs, you should probably add | |
5319 | recipient verification here. | |
5320 | .display asis | |
5321 | accept authenticated = * | |
5322 | .endd | |
5323 | Control reaches here for attempts to relay to arbitrary domains from arbitrary | |
5324 | hosts. The statement accepts the address only if the client host has | |
5325 | authenticated itself. The default configuration does not define any | |
5326 | authenticators, which means that no client can in fact authenticate. You will | |
5327 | need to add authenticator definitions if you want to make use of this ACL | |
5328 | statement. | |
5329 | .display asis | |
5330 | deny message = relay not permitted | |
5331 | .endd | |
5332 | The final statement denies access, giving a specific error message. Reaching | |
5333 | the end of the ACL also causes access to be denied, but with the generic | |
5334 | message `administrative prohibition'. | |
5335 | ||
5336 | ||
5337 | .section Router configuration | |
5338 | .index default||routers | |
5339 | .index routers||default | |
5340 | The router configuration comes next in the default configuration, introduced | |
5341 | by the line | |
5342 | .display asis | |
5343 | begin routers | |
5344 | .endd | |
5345 | Routers are the modules in Exim that make decisions about where to send | |
5346 | messages. An address is passed to each router in turn, until it is either | |
5347 | accepted, or failed. This means that the order in which you define the routers | |
5348 | matters. Each router is fully described in its own chapter later in this | |
5349 | manual. Here we give only brief overviews. | |
5350 | ||
5351 | .index domain literal||default router | |
5352 | .display asis | |
5353 | # domain_literal: | |
5354 | # driver = ipliteral | |
5355 | # domains = !+local_domains | |
5356 | # transport = remote_smtp | |
5357 | .endd | |
5358 | This router is commented out because the majority of sites do not want to | |
5359 | support domain literal addresses (those of the form \*user@@[10.9.8.7]*\). If | |
5360 | you uncomment this router, you also need to uncomment the setting of | |
5361 | \allow@_domain@_literals\ in the main part of the configuration. | |
5362 | ||
5363 | .display asis | |
5364 | dnslookup: | |
5365 | driver = dnslookup | |
5366 | domains = ! +local_domains | |
5367 | transport = remote_smtp | |
5368 | .newline | |
5369 | ignore_target_hosts = 0.0.0.0 : 127.0.0.0/8 | |
5370 | .newline | |
5371 | no_more | |
5372 | .endd | |
5373 | The first uncommented router handles addresses that do not involve any local | |
5374 | domains. This is specified by the line | |
5375 | .display asis | |
5376 | domains = ! +local_domains | |
5377 | .endd | |
5378 | The \domains\ option lists the domains to which this router applies, but the | |
5379 | exclamation mark is a negation sign, so the router is used only for domains | |
5380 | that are not in the domain list called \*local@_domains*\ (which was defined at | |
5381 | the start of the configuration). The plus sign before \*local@_domains*\ | |
5382 | indicates that it is referring to a named list. Addresses in other domains are | |
5383 | passed on to the following routers. | |
5384 | ||
5385 | The name of the router driver is \%dnslookup%\, | |
5386 | and is specified by the \driver\ option. Do not be confused by the fact that | |
4964e932 PH |
5387 | the name of this router instance is the same as the name of the driver. The |
5388 | instance name is arbitrary, but the name set in the \driver\ option must be one | |
495ae4b0 PH |
5389 | of the driver modules that is in the Exim binary. |
5390 | ||
5391 | The \%dnslookup%\ router routes addresses by looking up their domains in the | |
5392 | DNS in order to obtain a list of hosts to which the address is routed. If the | |
5393 | router succeeds, the address is queued for the \%remote@_smtp%\ transport, as | |
5394 | specified by the \transport\ option. If the router does not find the domain in | |
5395 | the DNS, no further routers are tried because of the \no@_more\ setting, so the | |
5396 | address fails and is bounced. | |
5397 | ||
5398 | The \ignore@_target@_hosts\ option specifies a list of IP addresses that are to | |
5399 | be entirely ignored. This option is present because a number of cases have been | |
4964e932 | 5400 | encountered where MX records in the DNS point to host names |
495ae4b0 PH |
5401 | whose IP addresses are 0.0.0.0 or are in the 127 subnet (typically 127.0.0.1). |
5402 | Completely ignoring these IP addresses causes Exim to fail to route the | |
5403 | email address, so it bounces. Otherwise, Exim would log a routing problem, and | |
5404 | continue to try to deliver the message periodically until the address timed | |
5405 | out. | |
5406 | .display asis | |
5407 | system_aliases: | |
5408 | driver = redirect | |
5409 | allow_fail | |
5410 | allow_defer | |
5411 | data = ${lookup{$local_part}lsearch{/etc/aliases}} | |
5412 | # user = exim | |
5413 | file_transport = address_file | |
5414 | pipe_transport = address_pipe | |
5415 | .endd | |
5416 | Control reaches this and subsequent routers only for addresses in the local | |
5417 | domains. This router checks to see whether the local part is defined as an | |
5418 | alias in the \(/etc/aliases)\ file, and if so, redirects it according to the | |
5419 | data that it looks up from that file. If no data is found for the local part, | |
5420 | the value of the \data\ option is empty, causing the address to be passed to | |
5421 | the next router. | |
5422 | ||
4964e932 PH |
5423 | \(/etc/aliases)\ is a conventional name for the system aliases file that is |
5424 | often used. That is why it is referenced by from the default configuration | |
495ae4b0 PH |
5425 | file. However, you can change this by setting \\SYSTEM@_ALIASES@_FILE\\ in |
5426 | \(Local/Makefile)\ before building Exim. | |
5427 | ||
5428 | .display asis | |
5429 | userforward: | |
5430 | driver = redirect | |
5431 | check_local_user | |
5432 | file = $home/.forward | |
5433 | no_verify | |
5434 | no_expn | |
5435 | check_ancestor | |
5436 | # allow_filter | |
5437 | file_transport = address_file | |
5438 | pipe_transport = address_pipe | |
5439 | reply_transport = address_reply | |
5440 | .endd | |
5441 | This is the most complicated router in the default configuration. It is another | |
5442 | redirection router, but this time it is looking for forwarding data set up by | |
5443 | individual users. The \check@_local@_user\ setting means that the first thing it | |
5444 | does is to check that the local part of the address is the login name of a | |
5445 | local user. If it is not, the router is skipped. When a local user is found, | |
5446 | the file called \(.forward)\ in the user's home directory is consulted. If it | |
5447 | does not exist, or is empty, the router declines. Otherwise, the contents of | |
4964e932 | 5448 | \(.forward)\ are interpreted as redirection data (see chapter ~~CHAPredirect |
495ae4b0 PH |
5449 | for more details). |
5450 | ||
5451 | .index Sieve filter||enabling in default router | |
5452 | Traditional \(.forward)\ files contain just a list of addresses, pipes, or | |
5453 | files. Exim supports this by default. However, if \allow@_filter\ is set (it is | |
5454 | commented out by default), the contents of the file are interpreted as a set of | |
5455 | Exim or Sieve filtering instructions, provided the file begins with `@#Exim | |
5456 | filter' or `@#Sieve filter', respectively. User filtering is discussed in the | |
5457 | separate document entitled \*Exim's interfaces to mail filtering*\. | |
5458 | ||
5459 | The \no@_verify\ and \no@_expn\ options mean that this router is skipped when | |
5460 | verifying addresses, or when running as a consequence of an SMTP \\EXPN\\ | |
4964e932 | 5461 | command. |
495ae4b0 PH |
5462 | There are two reasons for doing this: |
5463 | .numberpars | |
4964e932 | 5464 | Whether or not a local user has a \(.forward)\ file is not really relevant when |
495ae4b0 PH |
5465 | checking an address for validity; it makes sense not to waste resources doing |
5466 | unnecessary work. | |
5467 | .nextp | |
4964e932 PH |
5468 | More importantly, when Exim is verifying addresses or handling an \\EXPN\\ |
5469 | command during an SMTP session, it is running as the Exim user, not as root. | |
495ae4b0 PH |
5470 | The group is the Exim group, and no additional groups are set up. |
5471 | It may therefore not be possible for Exim to read users' \(.forward)\ files at | |
5472 | this time. | |
5473 | .endp | |
5474 | ||
5475 | The setting of \check@_ancestor\ prevents the router from generating a new | |
5476 | address that is the same as any previous address that was redirected. (This | |
5477 | works round a problem concerning a bad interaction between aliasing and | |
5478 | forwarding -- see section ~~SECTredlocmai). | |
5479 | ||
5480 | The final three option settings specify the transports that are to be used when | |
5481 | forwarding generates a direct delivery to a file, or to a pipe, or sets up an | |
5482 | auto-reply, respectively. For example, if a \(.forward)\ file contains | |
5483 | .display asis | |
5484 | a.nother@elsewhere.example, /home/spqr/archive | |
5485 | .endd | |
5486 | the delivery to \(/home/spqr/archive)\ is done by running the \address@_file\ | |
5487 | transport. | |
5488 | .display asis | |
5489 | localuser: | |
5490 | driver = accept | |
5491 | check_local_user | |
5492 | transport = local_delivery | |
5493 | .endd | |
5494 | The final router sets up delivery into local mailboxes, provided that the local | |
5495 | part is the name of a local login, by accepting the address and queuing it for | |
5496 | the \%local@_delivery%\ transport. Otherwise, we have reached the end of the | |
5497 | routers, so the address is bounced. | |
5498 | ||
5499 | ||
5500 | .section Transport configuration | |
5501 | .index default||transports | |
5502 | .index transports||default | |
5503 | Transports define mechanisms for actually delivering messages. They operate | |
5504 | only when referenced from routers, so the order in which they are defined does | |
5505 | not matter. The transports section of the configuration starts with | |
5506 | .display asis | |
5507 | begin transports | |
5508 | .endd | |
5509 | One remote transport and four local transports are defined. | |
5510 | .display asis | |
5511 | remote_smtp: | |
5512 | driver = smtp | |
5513 | .endd | |
5514 | This transport is used for delivering messages over SMTP connections. All its | |
5515 | options are defaulted. The list of remote hosts comes from the router. | |
5516 | .display asis | |
5517 | local_delivery: | |
5518 | driver = appendfile | |
5519 | file = /var/mail/$local_part | |
5520 | delivery_date_add | |
5521 | envelope_to_add | |
5522 | return_path_add | |
5523 | # group = mail | |
5524 | # mode = 0660 | |
5525 | .endd | |
5526 | This \%appendfile%\ transport is used for local delivery to user mailboxes in | |
5527 | traditional BSD mailbox format. By default it runs under the uid and gid of the | |
5528 | local user, which requires the sticky bit to be set on the \(/var/mail)\ | |
5529 | directory. Some systems use the alternative approach of running mail deliveries | |
5530 | under a particular group instead of using the sticky bit. The commented options | |
5531 | show how this can be done. | |
5532 | ||
5533 | Exim adds three headers to the message as it delivers it: ::Delivery-date::, | |
5534 | ::Envelope-to:: and ::Return-path::. This action is requested by the three | |
5535 | similarly-named options above. | |
5536 | .display asis | |
5537 | address_pipe: | |
5538 | driver = pipe | |
5539 | return_output | |
5540 | .endd | |
5541 | This transport is used for handling deliveries to pipes that are generated by | |
5542 | redirection (aliasing or users' \(.forward)\ files). The \return@_output\ | |
5543 | option specifies that any output generated by the pipe is to be returned to the | |
5544 | sender. | |
5545 | .display asis | |
5546 | address_file: | |
5547 | driver = appendfile | |
5548 | delivery_date_add | |
5549 | envelope_to_add | |
5550 | return_path_add | |
5551 | .endd | |
5552 | This transport is used for handling deliveries to files that are generated by | |
5553 | redirection. The name of the file is not specified in this instance of | |
5554 | \%appendfile%\, because it comes from the \%redirect%\ router. | |
5555 | .display asis | |
5556 | address_reply: | |
5557 | driver = autoreply | |
5558 | .endd | |
5559 | This transport is used for handling automatic replies generated by users' | |
5560 | filter files. | |
5561 | ||
5562 | ||
5563 | .section Default retry rule | |
5564 | .index retry||default rule | |
5565 | .index default||retry rule | |
5566 | The retry section of the configuration file contains rules which affect the way | |
5567 | Exim retries deliveries that cannot be completed at the first attempt. It is | |
5568 | introduced by the line | |
5569 | .display asis | |
5570 | begin retry | |
5571 | .endd | |
5572 | In the default configuration, there is just one rule, which applies to all | |
5573 | errors: | |
5574 | .display asis | |
5575 | * * F,2h,15m; G,16h,1h,1.5; F,4d,6h | |
5576 | .endd | |
5577 | This causes any temporarily failing address to be retried every 15 minutes for | |
5578 | 2 hours, then at intervals starting at one hour and increasing by a factor of | |
5579 | 1.5 until 16 hours have passed, then every 6 hours up to 4 days. If an address | |
5580 | is not delivered after 4 days of failure, it is bounced. | |
5581 | ||
5582 | ||
5583 | .section Rewriting configuration | |
5584 | The rewriting section of the configuration, introduced by | |
5585 | .display asis | |
5586 | begin rewrite | |
5587 | .endd | |
5588 | contains rules for rewriting addresses in messages as they arrive. There are no | |
5589 | rewriting rules in the default configuration file. | |
5590 | ||
5591 | ||
5592 | .section Authenticators configuration | |
5593 | .index \\AUTH\\||configuration | |
5594 | The authenticators section of the configuration, introduced by | |
5595 | .display asis | |
5596 | begin authenticators | |
5597 | .endd | |
5598 | defines mechanisms for the use of the SMTP \\AUTH\\ command. No authenticators | |
5599 | are specified in the default configuration file. | |
5600 | ||
5601 | ||
5602 | ||
5603 | . | |
5604 | . | |
5605 | . | |
5606 | . | |
5607 | . ============================================================================ | |
5608 | .chapter Regular expressions | |
5609 | .set runningfoot "regular expressions" | |
5610 | .rset CHAPregexp ~~chapter | |
5611 | ||
5612 | .index regular expressions||library | |
5613 | .index PCRE | |
5614 | Exim supports the use of regular expressions in many of its options. It | |
5615 | uses the PCRE regular expression library; this provides regular expression | |
5616 | matching that is compatible with Perl 5. The syntax and semantics of | |
5617 | regular expressions is discussed in many Perl reference books, and also in | |
5618 | Jeffrey Friedl's | |
5619 | .if ~~html | |
5620 | [(A HREF="http://www.oreilly.com/catalog/regex/")] | |
5621 | .fi | |
5622 | $it{Mastering Regular Expressions} | |
5623 | .if ~~html | |
5624 | [(/A)] | |
5625 | .fi | |
5626 | (O'Reilly, ISBN 0-596-00289-0). | |
5627 | ||
4964e932 | 5628 | The documentation for the syntax and semantics of the regular expressions that |
495ae4b0 PH |
5629 | are supported by PCRE is included in plain text in the file |
5630 | \(doc/pcrepattern.txt)\ in the Exim distribution, and also in the HTML | |
5631 | tarbundle of Exim documentation, and as an appendix to the | |
5632 | .if ~~html | |
5633 | [(A HREF="http://www.uit.co.uk/exim-book/")] | |
5634 | .fi | |
5635 | Exim book. | |
5636 | .if ~~html | |
5637 | [(/A)] | |
5638 | .fi | |
5639 | It describes in detail the features of the regular expressions that PCRE | |
5640 | supports, so no further description is included here. The PCRE functions are | |
5641 | called from Exim using the default option settings (that is, with no PCRE | |
5642 | options set), except that the \\PCRE@_CASELESS\\ option is set when the | |
5643 | matching is required to be case-insensitive. | |
5644 | ||
4964e932 PH |
5645 | In most cases, when a regular expression is required in an Exim configuration, |
5646 | it has to start with a circumflex, in order to distinguish it from plain text | |
495ae4b0 PH |
5647 | or an `ends with' wildcard. In this example of a configuration setting, the |
5648 | second item in the colon-separated list is a regular expression. | |
5649 | .display asis | |
5650 | domains = a.b.c : ^\\d{3} : *.y.z : ... | |
5651 | .endd | |
5652 | The doubling of the backslash is required because of string expansion that | |
5653 | precedes interpretation -- see section ~~SECTlittext for more discussion of | |
5654 | this issue, and a way of avoiding the need for doubling backslashes. The | |
5655 | regular expression that is eventually used in this example contains just one | |
5656 | backslash. The circumflex is included in the regular expression, and has the | |
5657 | normal effect of `anchoring' it to the start of the string that is being | |
5658 | matched. | |
5659 | ||
4964e932 | 5660 | There are, however, two cases where a circumflex is not required for the |
495ae4b0 PH |
5661 | recognition of a regular expression: these are the \match\ condition in a |
5662 | string expansion, and the \matches\ condition in an Exim filter file. In these | |
5663 | cases, the relevant string is always treated as a regular expression; if it | |
5664 | does not start with a circumflex, the expression is not anchored, and can match | |
5665 | anywhere in the subject string. | |
5666 | ||
4964e932 | 5667 | In all cases, if you want a regular expression to match at the end of a string, |
495ae4b0 PH |
5668 | you must code the @$ metacharacter to indicate this. For example: |
5669 | .display asis | |
5670 | domains = ^\\d{3}\\.example | |
5671 | .endd | |
4964e932 | 5672 | matches the domain \*123.example*\, but it also matches \*123.example.com*\. |
495ae4b0 PH |
5673 | You need to use: |
5674 | .display asis | |
5675 | domains = ^\\d{3}\\.example\$ | |
5676 | .endd | |
5677 | if you want \*example*\ to be the top-level domain. (The backslash before the | |
5678 | @$ is another artefact of string expansion.) | |
495ae4b0 PH |
5679 | |
5680 | ||
5681 | .section Testing regular expressions | |
5682 | .index testing||regular expressions | |
5683 | .index regular expressions||testing | |
5684 | .index \*pcretest*\ | |
5685 | A program called \*pcretest*\ forms part of the PCRE distribution and is built | |
5686 | with PCRE during the process of building Exim. It is primarily intended for | |
5687 | testing PCRE itself, but it can also be used for experimenting with regular | |
5688 | expressions. After building Exim, the binary can be found in the build | |
5689 | directory (it is not installed anywhere automatically). There is documentation | |
5690 | of various options in \(doc/pcretest.txt)\, but for simple testing, none are | |
5691 | needed. This is the output of a sample run of \*pcretest*\: | |
5692 | .display | |
5693 | re> $cb{/^([^@@]+)@@.+@\.(ac|edu)@\.(?!kr)[a-z]@{2@}@$/} | |
5694 | data> $cb{x@@y.ac.uk} | |
5695 | 0: x@@y.ac.uk | |
5696 | 1: x | |
5697 | 2: ac | |
5698 | data> $cb{x@@y.ac.kr} | |
5699 | No match | |
5700 | data> $cb{x@@y.edu.com} | |
5701 | No match | |
5702 | data> $cb{x@@y.edu.co} | |
5703 | 0: x@@y.edu.co | |
5704 | 1: x | |
5705 | 2: edu | |
5706 | .endd | |
5707 | .if ~~sys.fancy | |
5708 | Input typed by the user is shown in bold face. | |
5709 | .fi | |
5710 | After the `re>' prompt, a regular expression enclosed in delimiters is | |
5711 | expected. If this compiles without error, `data>' prompts are given for strings | |
5712 | against which the expression is matched. An empty data line causes a new | |
5713 | regular expression to be read. If the match is successful, the captured | |
5714 | substring values (that is, what would be in the variables \$0$\, \$1$\, \$2$\, | |
5715 | etc.) are shown. The above example tests for an email address whose domain ends | |
5716 | with either `ac' or `edu' followed by a two-character top-level domain that is | |
5717 | not `kr'. The local part is captured in \$1$\ and the `ac' or `edu' in \$2$\. | |
5718 | ||
5719 | ||
5720 | ||
5721 | ||
5722 | ||
5723 | ||
5724 | . | |
5725 | . | |
5726 | . | |
5727 | . | |
5728 | . ============================================================================ | |
5729 | .chapter File and database lookups | |
5730 | .set runningfoot "file/database lookups" | |
5731 | .rset CHAPfdlookup "~~chapter" | |
5732 | .index file||lookup | |
5733 | .index database lookups | |
5734 | .index lookup||description of | |
5735 | Exim can be configured to look up data in files or databases as it processes | |
5736 | messages. Two different kinds of syntax are used: | |
5737 | .numberpars | |
5738 | A string that is to be expanded may contain explicit lookup requests. These | |
4964e932 PH |
5739 | cause parts of the string to be replaced by data that is obtained from the |
5740 | lookup. | |
495ae4b0 PH |
5741 | .nextp |
5742 | Lists of domains, hosts, and email addresses can contain lookup requests as a | |
5743 | way of avoiding excessively long linear lists. In this case, the data that is | |
5744 | returned by the lookup is often (but not always) discarded; whether the lookup | |
5745 | succeeds or fails is what really counts. These kinds of list are described in | |
5746 | chapter ~~CHAPdomhosaddlists. | |
5747 | .endp | |
5748 | It is easy to confuse the two different kinds of lookup, especially as the | |
5749 | lists that may contain the second kind are always expanded before being | |
4964e932 | 5750 | processed as lists. Therefore, they may also contain lookups of the first kind. |
495ae4b0 PH |
5751 | Be careful to distinguish between the following two examples: |
5752 | .display asis | |
5753 | domains = ${lookup{$sender_host_address}lsearch{/some/file}} | |
5754 | domains = lsearch;/some/file | |
5755 | .endd | |
5756 | The first uses a string expansion, the result of which must be a domain list. | |
5757 | String expansions are described in detail in chapter ~~CHAPexpand. The | |
5758 | expansion takes place first, and the file that is searched could contain lines | |
5759 | like this: | |
5760 | .display asis | |
5761 | 192.168.3.4: domain1 : domain2 : ... | |
5762 | 192.168.1.9: domain3 : domain4 : ... | |
5763 | .endd | |
4964e932 | 5764 | Thus, the result of the expansion is a list of domains (and possibly other |
495ae4b0 PH |
5765 | types of item that are allowed in domain lists). |
5766 | ||
4964e932 | 5767 | In the second case, the lookup is a single item in a domain list. It causes |
495ae4b0 PH |
5768 | Exim to use a lookup to see if the domain that is being processed can be found |
5769 | in the file. The file could contains lines like this: | |
5770 | .display asis | |
4964e932 | 5771 | domain1: |
495ae4b0 PH |
5772 | domain2: |
5773 | .endd | |
4964e932 | 5774 | Any data that follows the keys is not relevant when checking that the domain |
495ae4b0 PH |
5775 | matches the list item. |
5776 | ||
4964e932 | 5777 | It is possible to use both kinds of lookup at once. Consider a file containing |
495ae4b0 PH |
5778 | lines like this: |
5779 | .display asis | |
5780 | 192.168.5.6: lsearch;/another/file | |
5781 | .endd | |
4964e932 PH |
5782 | If the value of \$sender@_host@_address$\ is 192.168.5.6, expansion of the |
5783 | first \domains\ setting above generates the second setting, which therefore | |
495ae4b0 PH |
5784 | causes a second lookup to occur. |
5785 | ||
5786 | The rest of this chapter describes the different lookup types that are | |
5787 | available. Any of them can be used in either of the circumstances described | |
4964e932 | 5788 | above. The syntax requirements for the two cases are described in chapters |
495ae4b0 PH |
5789 | ~~CHAPexpand and ~~CHAPdomhosaddlists, respectively. |
5790 | ||
5791 | .section Lookup types | |
5792 | .index lookup||types of | |
5793 | .index single-key lookup||definition of | |
5794 | Two different styles of data lookup are implemented: | |
5795 | .numberpars $. | |
5796 | The \*single-key*\ style requires the specification of a file in which to look, | |
d43194df PH |
5797 | and a single key to search for. |
5798 | .em | |
5799 | The key must be a non-empty string for the lookup to succeed. | |
5800 | .nem | |
5801 | The lookup type determines how the file is searched. | |
495ae4b0 PH |
5802 | .nextp |
5803 | .index query-style lookup||definition of | |
5804 | The \*query*\ style accepts a generalized database query. | |
5805 | No particular key value is assumed by Exim for query-style lookups. You can | |
5806 | use whichever Exim variable(s) you need to construct the database query. | |
5807 | .endp | |
5808 | The code for each lookup type is in a separate source file that is included in | |
5809 | the binary of Exim only if the corresponding compile-time option is set. The | |
5810 | default settings in \(src/EDITME)\ are: | |
5811 | .display asis | |
5812 | LOOKUP_DBM=yes | |
5813 | LOOKUP_LSEARCH=yes | |
5814 | .endd | |
5815 | which means that only linear searching and DBM lookups are included by default. | |
5816 | For some types of lookup (e.g. SQL databases), you need to install appropriate | |
5817 | libraries and header files before building Exim. | |
5818 | ||
5819 | ||
5820 | ||
5821 | .section Single-key lookup types | |
5822 | .rset SECTsinglekeylookups "~~chapter.~~section" | |
5823 | .index lookup||single-key types | |
5824 | .index single-key lookup||list of types | |
5825 | The following single-key lookup types are implemented: | |
5826 | .numberpars $. | |
5827 | .index cdb||description of | |
5828 | .index lookup||cdb | |
5829 | .index binary zero||in lookup key | |
5830 | \%cdb%\: The given file is searched as a Constant DataBase file, using the key | |
5831 | string without a terminating binary zero. The cdb format is designed for | |
5832 | indexed files that are read frequently and never updated, except by total | |
5833 | re-creation. As such, it is particulary suitable for large files containing | |
5834 | aliases or other indexed data referenced by an MTA. Information about cdb can | |
5835 | be found in several places: | |
5836 | .display rm | |
5837 | \?http://www.pobox.com/@~djb/cdb.html?\ | |
5838 | \?ftp://ftp.corpit.ru/pub/tinycdb/?\ | |
5839 | \?http://packages.debian.org/stable/utils/freecdb.html?\ | |
5840 | .endd | |
5841 | A cdb distribution is not needed in order to build Exim with cdb support, | |
5842 | because the code for reading cdb files is included directly in Exim itself. | |
5843 | However, no means of building or testing cdb files is provided with Exim, so | |
5844 | you need to obtain a cdb distribution in order to do this. | |
5845 | .nextp | |
5846 | .index DBM||lookup type | |
5847 | .index lookup||dbm | |
5848 | .index binary zero||in lookup key | |
5849 | \%dbm%\: Calls to DBM library functions are used to extract data from the given | |
5850 | DBM file by looking up the record with the given key. A terminating binary | |
5851 | zero is included in the key that is passed to the DBM library. See section | |
5852 | ~~SECTdb for a discussion of DBM libraries. | |
5853 | .index Berkeley DB library||file format | |
4964e932 PH |
5854 | For all versions of Berkeley DB, Exim uses the \\DB@_HASH\\ style of database |
5855 | when building DBM files using the \exim@_dbmbuild\ utility. However, when using | |
495ae4b0 PH |
5856 | Berkeley DB versions 3 or 4, it opens existing databases for reading with the |
5857 | \\DB@_UNKNOWN\\ option. This enables it to handle any of the types of database | |
4964e932 | 5858 | that the library supports, and can be useful for accessing DBM files created by |
495ae4b0 PH |
5859 | other applications. (For earlier DB versions, \\DB@_HASH\\ is always used.) |
5860 | ||
5861 | .nextp | |
5862 | .index lookup||dbmnz | |
5863 | .index lookup||dbm, terminating zero | |
5864 | .index binary zero||in lookup key | |
5865 | .index Courier | |
5866 | .index \(/etc/userdbshadow.dat)\ | |
5867 | .index dmbnz lookup type | |
5868 | \%dbmnz%\: This is the same as \%dbm%\, except that a terminating binary zero | |
5869 | is not included in the key that is passed to the DBM library. You may need this | |
5870 | if you want to look up data in files that are created by or shared with some | |
5871 | other application that does not use terminating zeros. For example, you need to | |
5872 | use \%dbmnz%\ rather than \%dbm%\ if you want to authenticate incoming SMTP | |
5873 | calls using the passwords from Courier's \(/etc/userdbshadow.dat)\ file. Exim's | |
5874 | utility program for creating DBM files (\*exim@_dbmbuild*\) includes the zeros | |
5875 | by default, but has an option to omit them (see section ~~SECTdbmbuild). | |
5876 | .nextp | |
5877 | .index lookup||dsearch | |
5878 | .index dsearch lookup type | |
5879 | \%dsearch%\: The given file must be a directory; this is searched for a file | |
5880 | whose name is the key. The key may not contain any forward slash characters. | |
5881 | The result of a successful lookup is the name of the file. An example of how | |
5882 | this lookup can be used to support virtual domains is given in section | |
5883 | ~~SECTvirtualdomains. | |
5884 | .nextp | |
5885 | .index lookup||iplsearch | |
5886 | .index iplsearch lookup type | |
495ae4b0 PH |
5887 | \%iplsearch%\: The given file is a text file containing keys and data. A key is |
5888 | terminated by a colon or white space or the end of the line. The keys in the | |
5889 | file must be IP addresses, or IP addresses with CIDR masks. Keys that involve | |
5890 | IPv6 addresses must be enclosed in quotes to prevent the first internal colon | |
5891 | being interpreted as a key terminator. For example: | |
5892 | .display asis | |
5893 | 1.2.3.4: data for 1.2.3.4 | |
5894 | 192.168.0.0/16 data for 192.168.0.0/16 | |
5895 | "abcd::cdab": data for abcd::cdab | |
5896 | "abcd:abcd::/32" data for abcd:abcd::/32 | |
5897 | .endd | |
5898 | The key for an \%iplsearch%\ lookup must be an IP address (without a mask). The | |
5899 | file is searched linearly, using the CIDR masks where present, until a matching | |
5900 | key is found. The first key that matches is used; there is no attempt to find a | |
4964e932 | 5901 | `best' match. Apart from the way the keys are matched, the processing for |
495ae4b0 PH |
5902 | \%iplsearch%\ is the same as for \%lsearch%\. |
5903 | ||
5904 | \**Warning 1**\: Unlike most other single-key lookup types, a file of data for | |
5905 | \%iplsearch%\ can \*not*\ be turned into a DBM or cdb file, because those | |
5906 | lookup types support only literal keys. | |
5907 | ||
4964e932 | 5908 | \**Warning 2**\: In a host list, you must always use \%net-iplsearch%\ so that |
495ae4b0 PH |
5909 | the implicit key is the host's IP address rather than its name (see section |
5910 | ~~SECThoslispatsikey). | |
495ae4b0 PH |
5911 | |
5912 | .nextp | |
5913 | .index linear search | |
5914 | .index lookup||lsearch | |
5915 | .index lsearch lookup type | |
5916 | \%lsearch%\: The given file is a text file that is searched linearly for a | |
5917 | line beginning with the search key, terminated by a colon or white space or the | |
5918 | end of the line. The first occurrence that is found in the file is used. White | |
5919 | space between the key and the colon is permitted. The remainder of the line, | |
5920 | with leading and trailing white space removed, is the data. This can be | |
5921 | continued onto subsequent lines by starting them with any amount of white | |
5922 | space, but only a single space character is included in the data at such a | |
5923 | junction. If the data begins with a colon, the key must be terminated by a | |
5924 | colon, for example: | |
5925 | .display | |
5926 | baduser: :fail: | |
5927 | .endd | |
5928 | Empty lines and lines beginning with @# are ignored, even if they occur in the | |
5929 | middle of an item. This is the traditional textual format of alias files. Note | |
5930 | that the keys in an \%lsearch%\ file are literal strings. There is no | |
5931 | wildcarding of any kind. | |
5932 | ||
5933 | .index lookup||lsearch, colons in keys | |
d43194df PH |
5934 | .index whitespace||in lsearch key |
5935 | In most \%lsearch%\ files, keys are not required to contain colons or @# | |
5936 | characters, or whitespace. However, if you need this feature, it is available. | |
5937 | If a key begins with a doublequote character, it is terminated only by a | |
5938 | matching quote (or end of line), and the normal escaping rules apply to its | |
5939 | contents (see section ~~SECTstrings). An optional colon is permitted after | |
5940 | quoted keys (exactly as for unquoted keys). There is no special handling of | |
5941 | quotes for the data part of an \%lsearch%\ line. | |
495ae4b0 PH |
5942 | .nextp |
5943 | .index NIS lookup type | |
5944 | .index lookup||NIS | |
5945 | .index binary zero||in lookup key | |
5946 | \%nis%\: The given file is the name of a NIS map, and a NIS lookup is done with | |
5947 | the given key, without a terminating binary zero. There is a variant called | |
5948 | \%nis0%\ which does include the terminating binary zero in the key. This is | |
5949 | reportedly needed for Sun-style alias files. Exim does not recognize NIS | |
5950 | aliases; the full map names must be used. | |
5951 | .nextp | |
5952 | .index wildlsearch lookup type | |
5953 | .index lookup||wildlsearch | |
5954 | .index nwildlsearch lookup type | |
5955 | .index lookup||nwildlsearch | |
5956 | \%wildlsearch%\ or \%nwildlsearch%\: These search a file linearly, like | |
5957 | \%lsearch%\, but instead of being interpreted as a literal string, each key may | |
5958 | be wildcarded. The difference between these two lookup types is that for | |
4964e932 | 5959 | \%wildlsearch%\, each key in the file is string-expanded before being used, |
495ae4b0 PH |
5960 | whereas for \%nwildlsearch%\, no expansion takes place. |
5961 | ||
5962 | Like \%lsearch%\, the testing is done case-insensitively. The following forms | |
5963 | of wildcard are recognized: | |
5964 | .numberpars "$*$" | |
8408f763 | 5965 | The string may begin with an asterisk to mean `ends with'. For example: |
495ae4b0 PH |
5966 | .display asis |
5967 | *.a.b.c data for anything.a.b.c | |
5968 | *fish data for anythingfish | |
5969 | .endd | |
5970 | .nextp | |
5971 | The string may begin with a circumflex to indicate a regular expression. For | |
5972 | example, for \%wildlsearch%\: | |
5973 | .display asis | |
5974 | ^\N\d+\.a\.b\N data for <digits>.a.b | |
5975 | .endd | |
4964e932 PH |
5976 | Note the use of \"@\N"\ to disable expansion of the contents of the regular |
5977 | expression. If you are using \%nwildlsearch%\, where the keys are not | |
495ae4b0 PH |
5978 | string-expanded, the equivalent entry is: |
5979 | .display asis | |
5980 | ^\d+\.a\.b data for <digits>.a.b | |
5981 | .endd | |
5982 | ||
5983 | If the regular expression contains white space or colon characters, you must | |
5984 | either quote it (see \%lsearch%\ above), or represent these characters in other | |
5985 | ways. For example, \"@\s"\ can be used for white space and \"@\x3A"\ for a | |
5986 | colon. This may be easier than quoting, because if you quote, you have to | |
5987 | escape all the backslashes inside the quotes. | |
5988 | .nextp | |
5989 | Although I cannot see it being of much use, the general matching function | |
4964e932 PH |
5990 | that is used to implement |
5991 | \%(n)wildlsearch%\ | |
495ae4b0 PH |
5992 | means that the string may begin with a lookup name terminated by a semicolon, |
5993 | and followed by lookup data. For example: | |
5994 | .display asis | |
5995 | cdb;/some/file data for keys that match the file | |
5996 | .endd | |
5997 | The data that is obtained from the nested lookup is discarded. | |
5998 | .endp | |
5999 | Keys that do not match any of these patterns are interpreted literally. The | |
6000 | continuation rules for the data are the same as for \%lsearch%\, and keys may | |
6001 | be followed by optional colons. | |
6002 | ||
6003 | \**Warning**\: Unlike most other single-key lookup types, a file of data for | |
6004 | \%(n)wildlsearch%\ can \*not*\ be turned into a DBM or cdb file, because those | |
6005 | lookup types support only literal keys. | |
6006 | .endp | |
6007 | ||
6008 | .section Query-style lookup types | |
6009 | .index lookup||query-style types | |
6010 | .index query-style lookup||list of types | |
4964e932 | 6011 | The supported query-style lookup types are listed below. Further details about |
495ae4b0 PH |
6012 | many of them are given in later sections. |
6013 | .numberpars $. | |
6014 | .index DNS||as a lookup type | |
6015 | .index lookup||DNS | |
d43194df PH |
6016 | \%dnsdb%\: This does a DNS search for |
6017 | .em | |
6018 | one or more records whose domain names are given in the supplied query. The | |
6019 | resulting data is the contents of the records. | |
6020 | .nem | |
6021 | See section ~~SECTdnsdb. | |
495ae4b0 PH |
6022 | .nextp |
6023 | .index Interbase lookup type | |
6024 | .index lookup||Interbase | |
6025 | \%ibase%\: This does a lookup in an Interbase database. | |
6026 | .nextp | |
6027 | .index LDAP||lookup type | |
6028 | .index lookup||LDAP | |
6029 | \%ldap%\: This does an LDAP lookup using a query in the form of a URL, and | |
6030 | returns attributes from a single entry. There is a variant called \%ldapm%\ | |
6031 | that permits values from multiple entries to be returned. A third variant | |
6032 | called \%ldapdn%\ returns the Distinguished Name of a single entry instead of | |
6033 | any attribute values. See section ~~SECTldap. | |
6034 | .nextp | |
6035 | .index MySQL||lookup type | |
6036 | .index lookup||MySQL | |
6037 | \%mysql%\: The format of the query is an SQL statement that is passed to a MySQL | |
6038 | database. See section ~~SECTsql. | |
6039 | .nextp | |
6040 | .index NIS@+ lookup type | |
6041 | .index lookup||NIS+ | |
6042 | \%nisplus%\: This does a NIS+ lookup using a query that can specify the name of | |
6043 | the field to be returned. See section ~~SECTnisplus. | |
6044 | .nextp | |
6045 | .index Oracle||lookup type | |
6046 | .index lookup||Oracle | |
6047 | \%oracle%\: The format of the query is an SQL statement that is passed to an | |
6048 | Oracle database. See section ~~SECTsql. | |
6049 | .nextp | |
6050 | .index lookup||passwd | |
6051 | .index passwd lookup type | |
d43194df | 6052 | .index \(/etc/passwd)\ |
495ae4b0 PH |
6053 | \%passwd%\ is a query-style lookup with queries that are just user names. The |
6054 | lookup calls \*getpwnam()*\ to interrogate the system password data, and on | |
6055 | success, the result string is the same as you would get from an \%lsearch%\ | |
6056 | lookup on a traditional \(/etc/passwd file)\, though with \"*"\ for the | |
6057 | password value. For example: | |
6058 | .display asis | |
6059 | *:42:42:King Rat:/home/kr:/bin/bash | |
6060 | .endd | |
6061 | .nextp | |
6062 | .index PostgreSQL lookup type | |
6063 | .index lookup||PostgreSQL | |
6064 | \%pgsql%\: The format of the query is an SQL statement that is passed to a | |
6065 | PostgreSQL database. See section ~~SECTsql. | |
6066 | .nextp | |
6067 | \%testdb%\: This is a lookup type that is used for testing Exim. It is | |
6068 | not likely to be useful in normal operation. | |
6069 | .nextp | |
6070 | .index whoson lookup type | |
6071 | .index lookup||whoson | |
6072 | \%whoson%\: \*Whoson*\ (\?http://whoson.sourceforge.net?\) is a proposed | |
6073 | Internet protocol that allows Internet server programs to check whether a | |
6074 | particular (dynamically allocated) IP address is currently allocated to a known | |
6075 | (trusted) user and, optionally, to obtain the identity of the said user. In | |
6076 | Exim, this can be used to implement `POP before SMTP' checking using ACL | |
6077 | statements such as | |
6078 | .display asis | |
6079 | require condition = \ | |
6080 | ${lookup whoson {$sender_host_address}{yes}{no}} | |
6081 | .endd | |
6082 | The query consists of a single IP address. The value returned is the name of | |
6083 | the authenticated user. | |
6084 | .endp | |
6085 | ||
6086 | .section Temporary errors in lookups | |
6087 | .index lookup||temporary error in | |
6088 | Lookup functions can return temporary error codes if the lookup cannot be | |
6089 | completed. For example, a NIS or LDAP database might be unavailable. For this | |
6090 | reason, it is not advisable to use a lookup that might do this for critical | |
6091 | options such as a list of local domains. | |
6092 | ||
6093 | When a lookup cannot be completed in a router or transport, delivery | |
6094 | of the message (to the relevant address) is deferred, as for any other | |
6095 | temporary error. In other circumstances Exim may assume the lookup has failed, | |
6096 | or may give up altogether. | |
6097 | ||
6098 | ||
6099 | .section Default values in single-key lookups | |
6100 | .rset SECTdefaultvaluelookups "~~chapter.~~section" | |
6101 | .index wildcard lookups | |
6102 | .index lookup||default values | |
6103 | .index lookup||wildcard | |
6104 | .index lookup||$*$ added to type | |
6105 | .index default||in single-key lookups | |
6106 | In this context, a `default value' is a value specified by the administrator | |
6107 | that is to be used if a lookup fails. | |
6108 | ||
6109 | If `$*$' is added to a single-key lookup type (for example, \lsearch$*$\) and | |
6110 | the initial lookup fails, the key `$*$' is looked up in the file to provide | |
6111 | a default value. See also the section on partial matching below. | |
6112 | ||
6113 | .index @*@@ with single-key lookup | |
6114 | .index lookup||$*$@@ added to type | |
6115 | .index alias file||per-domain default | |
6116 | Alternatively, if `$*$@@' is added to a single-key lookup type (for example | |
6117 | \dbm$*$@@\) then, if the initial lookup fails and the key contains an @@ | |
6118 | character, a second lookup is done with everything before the last @@ replaced | |
6119 | by $*$. This makes it possible to provide per-domain defaults in alias files | |
6120 | that include the domains in the keys. If the second lookup fails (or doesn't | |
6121 | take place because there is no @@ in the key), `$*$' is looked up. | |
6122 | For example, a \%redirect%\ router might contain: | |
6123 | .display asis | |
6124 | data = ${lookup{$local_part@$domain}lsearch*@{/etc/mixed-aliases}} | |
6125 | .endd | |
4964e932 | 6126 | Suppose the address that is being processed is \*jane@@eyre.example*\. Exim |
495ae4b0 PH |
6127 | looks up these keys, in this order: |
6128 | .display asis | |
6129 | jane@eyre.example | |
6130 | *@eyre.example | |
6131 | * | |
6132 | .endd | |
4964e932 PH |
6133 | The data is taken from whichever key it finds first. \**Note**\: in an |
6134 | \%lsearch%\ file, this does not mean the first of these keys in the file. A | |
6135 | complete scan is done for each key, and only if it is not found at all does | |
495ae4b0 PH |
6136 | Exim move on to try the next key. |
6137 | ||
6138 | ||
6139 | .section Partial matching in single-key lookups | |
6140 | .rset SECTpartiallookup "~~chapter.~~section" | |
6141 | .index partial matching | |
6142 | .index wildcard lookups | |
6143 | .index lookup||partial matching | |
6144 | .index lookup||wildcard | |
6145 | .index asterisk||in search type | |
6146 | The normal operation of a single-key lookup is to search the file for an exact | |
6147 | match with the given key. However, in a number of situations where domains are | |
6148 | being looked up, it is useful to be able to do partial matching. In this case, | |
6149 | information in the file that has a key starting with `$*$.' is matched by any | |
6150 | domain that ends with the components that follow the full stop. For example, if | |
6151 | a key in a DBM file is | |
6152 | .display | |
6153 | *.dates.fict.example | |
6154 | .endd | |
6155 | then when partial matching is enabled this is matched by (amongst others) | |
6156 | \*2001.dates.fict.example*\ and \*1984.dates.fict.example*\. It is also matched | |
6157 | by \*dates.fict.example*\, if that does not appear as a separate key in the | |
6158 | file. | |
6159 | ||
4964e932 | 6160 | \**Note**\: Partial matching is not available for query-style lookups. It is |
495ae4b0 PH |
6161 | also not available for any lookup items in address lists (see section |
6162 | ~~SECTaddresslist). | |
6163 | ||
6164 | Partial matching is implemented by doing a series of separate lookups using | |
6165 | keys constructed by modifying the original subject key. This means that it can | |
6166 | be used with any of the single-key lookup types, provided that | |
4964e932 | 6167 | partial matching keys |
495ae4b0 PH |
6168 | beginning with a special prefix (default `$*$.') are included in the data file. |
6169 | Keys in the file that do not begin with the prefix are matched only by | |
6170 | unmodified subject keys when partial matching is in use. | |
6171 | ||
6172 | Partial matching is requested by adding the string `partial-' to the front of | |
6173 | the name of a single-key lookup type, for example, \partial-dbm\. When this is | |
6174 | done, the subject key is first looked up unmodified; if that fails, `$*$.' | |
6175 | is added at the start of the subject key, and it is looked up again. If that | |
6176 | fails, further lookups are tried with dot-separated components removed | |
6177 | from the start of the subject key, one-by-one, and `$*$.' added on the front of | |
6178 | what remains. | |
6179 | ||
6180 | A minimum number of two non-$*$ components are required. This can be adjusted | |
6181 | by including a number before the hyphen in the search type. For example, | |
6182 | \partial3-lsearch\ specifies a minimum of three non-$*$ components in the | |
6183 | modified keys. Omitting the number is equivalent to `partial2-'. If the subject | |
6184 | key is \*2250.dates.fict.example*\ then the following keys are looked up when | |
6185 | the minimum number of non-$*$ components is two: | |
6186 | .display asis | |
6187 | 2250.dates.fict.example | |
6188 | *.2250.dates.fict.example | |
6189 | *.dates.fict.example | |
6190 | *.fict.example | |
6191 | .endd | |
6192 | As soon as one key in the sequence is successfully looked up, the lookup | |
4964e932 | 6193 | finishes. |
495ae4b0 PH |
6194 | |
6195 | .index lookup||partial matching, changing prefix | |
6196 | .index prefix||for partial matching | |
4964e932 | 6197 | The use of `$*$.' as the partial matching prefix is a default that can be |
495ae4b0 PH |
6198 | changed. The motivation for this feature is to allow Exim to operate with file |
6199 | formats that are used by other MTAs. A different prefix can be supplied in | |
6200 | parentheses instead of the hyphen after `partial'. For example: | |
6201 | .display asis | |
6202 | domains = partial(.)lsearch;/some/file | |
6203 | .endd | |
6204 | In this example, if the domain is \*a.b.c*\, the sequence of lookups is | |
4964e932 | 6205 | \"a.b.c"\, \".a.b.c"\, and \".b.c"\ (the default minimum of 2 non-wild |
495ae4b0 PH |
6206 | components is unchanged). The prefix may consist of any punctuation characters |
6207 | other than a closing parenthesis. It may be empty, for example: | |
6208 | .display asis | |
6209 | domains = partial1()cdb;/some/file | |
6210 | .endd | |
6211 | For this example, if the domain is \*a.b.c*\, the sequence of lookups is | |
6212 | \"a.b.c"\, \"b.c"\, and \"c"\. | |
6213 | ||
6214 | If `partial0' is specified, what happens at the end (when the lookup with just | |
6215 | one non-wild component has failed, and the original key is shortened right down | |
6216 | to the null string) depends on the prefix: | |
6217 | .numberpars $. | |
6218 | If the prefix has zero length, the whole lookup fails. | |
6219 | .nextp | |
6220 | If the prefix has length 1, a lookup for just the prefix is done. For | |
6221 | example, the final lookup for `partial0(.)' is for \"."\ alone. | |
6222 | .nextp | |
6223 | Otherwise, if the prefix ends in a dot, the dot is removed, and the | |
4964e932 | 6224 | remainder is looked up. With the default prefix, therefore, the final lookup is |
495ae4b0 PH |
6225 | for `$*$' on its own. |
6226 | .nextp | |
6227 | Otherwise, the whole prefix is looked up. | |
6228 | .endp | |
6229 | ||
6230 | If the search type ends in `$*$' or `$*$@@' (see section | |
6231 | ~~SECTdefaultvaluelookups above), the search for an ultimate default that this | |
6232 | implies happens after all partial lookups have failed. If `partial0' is | |
6233 | specified, adding `$*$' to the search type has no effect with the default | |
6234 | prefix, because the `$*$' key is already included in the sequence of partial | |
6235 | lookups. However, there might be a use for lookup types such as | |
6236 | `partial0(.)lsearch$*$'. | |
6237 | ||
6238 | The use of `$*$' in lookup partial matching differs from its use as a wildcard | |
6239 | in domain lists and the like. Partial matching works only in terms of | |
6240 | dot-separated components; a key such as \"*fict.example"\ | |
6241 | in a database file is useless, because the asterisk in a partial matching | |
6242 | subject key is always followed by a dot. | |
6243 | ||
6244 | ||
6245 | ||
6246 | .section Lookup caching | |
4964e932 | 6247 | .index lookup||caching |
495ae4b0 | 6248 | .index caching||lookup data |
d43194df PH |
6249 | .em |
6250 | Exim caches all lookup results in order to avoid needless repetition of | |
6251 | lookups. However, because (apart from the daemon) Exim operates as a collection | |
6252 | of independent, short-lived processes, this caching applies only within a | |
6253 | single Exim process. There is no inter-process caching facility. | |
6254 | ||
6255 | For single-key lookups, Exim keeps the relevant files open in case there is | |
6256 | another lookup that needs them. In some types of configuration this can lead to | |
6257 | many files being kept open for messages with many recipients. To avoid hitting | |
6258 | the operating system limit on the number of simultaneously open files, Exim | |
6259 | closes the least recently used file when it needs to open more files than its | |
6260 | own internal limit, which can be changed via the \lookup@_open@_max\ option. | |
6261 | ||
6262 | The single-key lookup files are closed and the lookup caches are flushed at | |
6263 | strategic points during delivery -- for example, after all routing is complete. | |
6264 | .nem | |
495ae4b0 PH |
6265 | |
6266 | ||
6267 | .section Quoting lookup data | |
6268 | .index lookup||quoting | |
6269 | .index quoting||in lookups | |
6270 | When data from an incoming message is included in a query-style lookup, there | |
6271 | is the possibility of special characters in the data messing up the syntax of | |
6272 | the query. For example, a NIS+ query that contains | |
6273 | .display asis | |
6274 | [name=$local_part] | |
6275 | .endd | |
6276 | will be broken if the local part happens to contain a closing square bracket. | |
6277 | For NIS+, data can be enclosed in double quotes like this: | |
6278 | .display asis | |
6279 | [name="$local_part"] | |
6280 | .endd | |
6281 | but this still leaves the problem of a double quote in the data. The rule for | |
6282 | NIS+ is that double quotes must be doubled. Other lookup types have different | |
6283 | rules, and to cope with the differing requirements, an expansion operator | |
6284 | of the following form is provided: | |
6285 | .display | |
6286 | @$@{quote@_<<lookup-type>>:<<string>>@} | |
6287 | .endd | |
6288 | For example, the safest way to write the NIS+ query is | |
6289 | .display asis | |
6290 | [name="${quote_nisplus:$local_part}"] | |
6291 | .endd | |
6292 | See chapter ~~CHAPexpand for full coverage of string expansions. The quote | |
6293 | operator can be used for all lookup types, but has no effect for single-key | |
6294 | lookups, since no quoting is ever needed in their key strings. | |
6295 | ||
6296 | ||
6297 | ||
6298 | .section More about dnsdb | |
6299 | .rset SECTdnsdb "~~chapter.~~section" | |
6300 | .index dnsdb lookup | |
6301 | .index lookup||dnsdb | |
6302 | .index DNS||as a lookup type | |
d43194df PH |
6303 | The \%dnsdb%\ lookup type uses the DNS as its database. A simple query consists |
6304 | of a record type and a domain name, separated by an equals sign. For example, | |
6305 | an expansion string could contain: | |
495ae4b0 PH |
6306 | .display asis |
6307 | ${lookup dnsdb{mx=a.b.example}{$value}fail} | |
6308 | .endd | |
d43194df PH |
6309 | The supported DNS record types are A, CNAME, MX, NS, PTR, SRV, and TXT, and, |
6310 | when Exim is compiled with IPv6 support, AAAA (and A6 if that is also | |
6311 | configured). If no type is given, TXT is assumed. When the type is PTR, | |
6312 | .em | |
6313 | the data can be an IP address, written as normal; inversion and the addition of | |
6314 | \in-addr.arpa\ or \ip6.arpa\ happens automatically. For example: | |
495ae4b0 PH |
6315 | .display asis |
6316 | ${lookup dnsdb{ptr=192.168.4.5}{$value}fail} | |
6317 | .endd | |
d43194df PH |
6318 | If the data for a PTR record is not a syntactically valid IP address, it is not |
6319 | altered and nothing is added. | |
6320 | ||
6321 | For any record type, if multiple records are found (or, for A6 lookups, if a | |
6322 | single record leads to multiple addresses), the data is returned as a | |
6323 | concatenation, with newline as the default separator. The order, of course, | |
6324 | depends on the DNS resolver. You can specify a different separator character | |
6325 | between multiple records by putting a right angle-bracket followed immediately | |
6326 | by the new separator at the start of the query. For example: | |
6327 | .display asis | |
6328 | ${lookup dnsdb{>: a=host1.example}} | |
6329 | .endd | |
6330 | It is permitted to specify a space as the separator character. Further | |
6331 | whitespace is ignored. | |
495ae4b0 | 6332 | |
495ae4b0 | 6333 | .index SRV record||in \%dnsdb%\ lookup |
d43194df PH |
6334 | For SRV records, the priority, weight, port, and host name are returned for |
6335 | each record, separated by spaces. | |
6336 | ||
6337 | .index MX record||in \%dnsdb%\ lookup | |
6338 | For MX records, both the preference value and the host name are returned for | |
6339 | each record, separated by a space. However, if you want only host names, you | |
6340 | can use the pseudo-type MXH: | |
6341 | .display asis | |
6342 | ${lookup dnsdb{mxh=a.b.example}} | |
6343 | .endd | |
6344 | In this case, the preference values are omitted. | |
495ae4b0 | 6345 | |
d43194df PH |
6346 | .index name server||for enclosing domain |
6347 | Another pseudo-type is ZNS (for `zone NS'). It performs a lookup for NS | |
6348 | records on the given domain, but if none are found, it removes the first | |
6349 | component of the domain name, and tries again. This process continues until NS | |
6350 | records are found or there are no more components left (or there is a DNS | |
6351 | error). In other words, it may return the name servers for a top-level domain, | |
6352 | but it never returns the root name servers. If there are no NS records for the | |
6353 | top-level domain, the lookup fails. Consider these examples: | |
6354 | .display asis | |
6355 | ${lookup dnsdb{zns=xxx.quercite.com}} | |
6356 | ${lookup dnsdb{zns=xxx.edu}} | |
6357 | .endd | |
6358 | Assuming that in each case there are no NS records for the full domain name, | |
6359 | the first returns the name servers for \quercite.com\, and the second returns | |
6360 | the name servers for \edu\. | |
6361 | ||
6362 | You should be careful about how you use this lookup because, unless the | |
6363 | top-level domain does not exist, the lookup always returns some host names. The | |
6364 | sort of use to which this might be put is for seeing if the name servers for a | |
6365 | given domain are on a blacklist. You can probably assume that the name servers | |
6366 | for the high-level domains such as \com\ or \co.uk\ are not going to be on such | |
6367 | a list. | |
6368 | ||
6369 | .nem | |
495ae4b0 | 6370 | |
d43194df PH |
6371 | .em |
6372 | .section Multiple dnsdb lookups | |
6373 | In the previous section, \%dnsdb%\ lookups for a single domain are described. | |
6374 | However, you can specify a list of domains or IP addresses in a single | |
6375 | \%dnsdb%\ lookup. The list is specified in the normal Exim way, with colon as | |
6376 | the default separator, but with the ability to change this. For example: | |
6377 | .display asis | |
6378 | ${lookup dnsdb{one.domain.com:two.domain.com}} | |
6379 | ${lookup dnsdb{a=one.host.com:two.host.com}} | |
6380 | ${lookup dnsdb{ptr = <; 1.2.3.4 ; 4.5.6.8}} | |
6381 | .endd | |
6382 | In order to retain backwards compatibility, there is one special case: if | |
6383 | the lookup type is PTR and no change of separator is specified, Exim looks | |
6384 | to see if the rest of the string is precisely one IPv6 address. In this | |
6385 | case, it does not treat it as a list. | |
6386 | ||
6387 | The data from each lookup is concatenated, with newline separators by default, | |
6388 | in the same way that multiple DNS records for a single item are handled. A | |
6389 | different separator can be specified, as described above. | |
6390 | ||
6391 | The \%dnsdb%\ lookup fails only if all the DNS lookups fail. If there is a | |
6392 | temporary DNS error for any of them, the behaviour is controlled by | |
6393 | an optional keyword followed by a comma that may appear before the record | |
6394 | type. The possible keywords are `defer@_strict', `defer@_never', and | |
6395 | `defer@_lax'. With `strict' behaviour, any temporary DNS error causes the | |
6396 | whole lookup to defer. With `never' behaviour, a temporary DNS error is | |
6397 | ignored, and the behaviour is as if the DNS lookup failed to find anything. | |
6398 | With `lax' behaviour, all the queries are attempted, but a temporary DNS | |
6399 | error causes the whole lookup to defer only if none of the other lookups | |
6400 | succeed. The default is `lax', so the following lookups are equivalent: | |
6401 | .display asis | |
6402 | ${lookup dnsdb{defer_lax,a=one.host.com:two.host.com}} | |
6403 | ${lookup dnsdb{a=one.host.com:two.host.com}} | |
6404 | .endd | |
6405 | Thus, in the default case, as long as at least one of the DNS lookups | |
6406 | yields some data, the lookup succeeds. | |
6407 | .nem | |
495ae4b0 PH |
6408 | |
6409 | ||
6410 | .section More about LDAP | |
6411 | .rset SECTldap "~~chapter.~~section" | |
6412 | .index LDAP lookup | |
6413 | .index lookup||LDAP | |
6414 | .index Solaris||LDAP | |
6415 | The original LDAP implementation came from the University of Michigan; this has | |
6416 | become `Open LDAP', and there are now two different releases. Another | |
6417 | implementation comes from Netscape, and Solaris 7 and subsequent releases | |
6418 | contain inbuilt LDAP support. Unfortunately, though these are all compatible at | |
6419 | the lookup function level, their error handling is different. For this reason | |
6420 | it is necessary to set a compile-time variable when building Exim with LDAP, to | |
6421 | indicate which LDAP library is in use. One of the following should appear in | |
6422 | your \(Local/Makefile)\: | |
6423 | .display asis | |
6424 | LDAP_LIB_TYPE=UMICHIGAN | |
6425 | LDAP_LIB_TYPE=OPENLDAP1 | |
6426 | LDAP_LIB_TYPE=OPENLDAP2 | |
6427 | LDAP_LIB_TYPE=NETSCAPE | |
6428 | LDAP_LIB_TYPE=SOLARIS | |
6429 | .endd | |
6430 | If \\LDAP@_LIB@_TYPE\\ is not set, Exim assumes \"OPENLDAP1"\, which has the | |
6431 | same interface as the University of Michigan version. | |
6432 | ||
6433 | There are three LDAP lookup types in Exim. These behave slightly differently in | |
6434 | the way they handle the results of a query: | |
6435 | .numberpars $. | |
6436 | \%ldap%\ requires the result to contain just one entry; if there are more, it | |
6437 | gives an error. | |
6438 | .nextp | |
6439 | \%ldapdn%\ also requires the result to contain just one entry, but it is the | |
6440 | Distinguished Name that is returned rather than any attribute values. | |
6441 | .nextp | |
6442 | \%ldapm%\ permits the result to contain more than one entry; the attributes from | |
6443 | all of them are returned. | |
6444 | .endp | |
6445 | ||
6446 | For \%ldap%\ and \%ldapm%\, if a query finds only entries with no attributes, | |
6447 | Exim behaves as if the entry did not exist, and the lookup fails. The format of | |
6448 | the data returned by a successful lookup is described in the next section. | |
6449 | First we explain how LDAP queries are coded. | |
6450 | ||
6451 | .section Format of LDAP queries | |
6452 | .rset SECTforldaque "~~chapter.~~section" | |
6453 | .index LDAP||query format | |
6454 | An LDAP query takes the form of a URL as defined in RFC 2255. For example, in | |
6455 | the configuration of a \%redirect%\ router one might have this setting: | |
6456 | .display asis | |
6457 | data = ${lookup ldap \ | |
6458 | {ldap:///cn=$local_part,o=University%20of%20Cambridge,\ | |
6459 | c=UK?mailbox?base?}} | |
6460 | .endd | |
6461 | .index LDAP||with TLS | |
6462 | The URL may begin with \"ldap"\ or \"ldaps"\ if your LDAP library supports | |
6463 | secure (encrypted) LDAP connections. The second of these ensures that an | |
6464 | encrypted TLS connection is used. | |
6465 | ||
6466 | .section LDAP quoting | |
6467 | .index LDAP||quoting | |
6468 | Two levels of quoting are required in LDAP queries, the first for LDAP itself | |
6469 | and the second because the LDAP query is represented as a URL. Furthermore, | |
4964e932 | 6470 | within an LDAP query, two different kinds of quoting are required. For this |
495ae4b0 PH |
6471 | reason, there are two different LDAP-specific quoting operators. |
6472 | ||
6473 | The \quote@_ldap\ operator is designed for use on strings that are part of | |
6474 | filter specifications. Conceptually, it first does the following conversions on | |
6475 | the string: | |
6476 | .display asis | |
6477 | * => \2A | |
6478 | ( => \28 | |
6479 | ) => \29 | |
6480 | \ => \5C | |
6481 | .endd | |
6482 | in accordance with RFC 2254. The resulting string is then quoted according | |
6483 | to the rules for URLs, that is, all characters except | |
6484 | .display asis | |
6485 | ! $ ' - . _ ( ) * + | |
6486 | .endd | |
6487 | are converted to their hex values, preceded by a percent sign. For example: | |
6488 | .display asis | |
6489 | ${quote_ldap: a(bc)*, a<yz>; } | |
6490 | .endd | |
6491 | yields | |
6492 | .display asis | |
6493 | %20a%5C28bc%5C29%5C2A%2C%20a%3Cyz%3E%3B%20 | |
6494 | .endd | |
6495 | Removing the URL quoting, this is (with a leading and a trailing space): | |
6496 | .display asis | |
6497 | a\28bc\29\2A, a<yz>; | |
6498 | .endd | |
6499 | ||
6500 | The \quote@_ldap@_dn\ operator is designed for use on strings that are part of | |
6501 | base DN specifications in queries. Conceptually, it first converts the string | |
6502 | by inserting a backslash in front of any of the following characters: | |
6503 | .display asis | |
6504 | , + " \ < > ; | |
6505 | .endd | |
6506 | It also inserts a backslash before any leading spaces or @# characters, and | |
6507 | before any trailing spaces. (These rules are in RFC 2253.) The resulting string | |
6508 | is then quoted according to the rules for URLs. For example: | |
6509 | .display asis | |
4964e932 | 6510 | ${quote_ldap_dn: a(bc)*, a<yz>; } |
495ae4b0 PH |
6511 | .endd |
6512 | yields | |
6513 | .display asis | |
6514 | %5C%20a(bc)*%5C%2C%20a%5C%3Cyz%5C%3E%5C%3B%5C%20 | |
6515 | .endd | |
6516 | Removing the URL quoting, this is (with a trailing space): | |
6517 | .display asis | |
6518 | \ a(bc)*\, a\<yz\>\;\ | |
6519 | .endd | |
4964e932 | 6520 | There are some further comments about quoting in the section on LDAP |
495ae4b0 PH |
6521 | authentication below. |
6522 | ||
6523 | .section LDAP connections | |
6524 | .index LDAP||connections | |
6525 | The connection to an LDAP server may either be over TCP/IP, or, when OpenLDAP | |
6526 | is in use, via a Unix domain socket. The example given above does not specify | |
6527 | an LDAP server. A server that is reached by TCP/IP can be specified in a query | |
6528 | by starting it with | |
6529 | .display | |
6530 | ldap://<<hostname>>:<<port>>/... | |
6531 | .endd | |
6532 | If the port (and preceding colon) are omitted, the standard LDAP port (389) is | |
6533 | used. When no server is specified in a query, a list of default servers is | |
6534 | taken from the \ldap@_default@_servers\ configuration option. This supplies a | |
6535 | colon-separated list of servers which are tried in turn until one successfully | |
6536 | handles a query, or there is a serious error. Successful handling either | |
6537 | returns the requested data, or indicates that it does not exist. Serious errors | |
6538 | are syntactical, or multiple values when only a single value is expected. | |
6539 | Errors which cause the next server to be tried are connection failures, bind | |
6540 | failures, and timeouts. | |
6541 | ||
6542 | For each server name in the list, a port number can be given. The standard way | |
6543 | of specifing a host and port is to use a colon separator (RFC 1738). Because | |
6544 | \ldap@_default@_servers\ is a colon-separated list, such colons have to be | |
6545 | doubled. For example | |
6546 | .display asis | |
6547 | ldap_default_servers = ldap1.example.com::145:ldap2.example.com | |
6548 | .endd | |
6549 | If \ldap@_default@_servers\ is unset, a URL with no server name is passed | |
6550 | to the LDAP library with no server name, and the library's default (normally | |
6551 | the local host) is used. | |
6552 | ||
6553 | If you are using the OpenLDAP library, you can connect to an LDAP server using | |
6554 | a Unix domain socket instead of a TCP/IP connection. This is specified by using | |
6555 | \"ldapi"\ instead of \"ldap"\ in LDAP queries. What follows here applies only | |
6556 | to OpenLDAP. If Exim is compiled with a different LDAP library, this feature is | |
6557 | not available. | |
6558 | ||
6559 | For this type of connection, instead of a host name for the server, a pathname | |
6560 | for the socket is required, and the port number is not relevant. The pathname | |
6561 | can be specified either as an item in \ldap@_default@_servers\, or inline in | |
6562 | the query. In the former case, you can have settings such as | |
6563 | .display asis | |
6564 | ldap_default_servers = /tmp/ldap.sock : backup.ldap.your.domain | |
6565 | .endd | |
6566 | When the pathname is given in the query, you have to escape the slashes as | |
6567 | \"%2F"\ to fit in with the LDAP URL syntax. For example: | |
6568 | .display asis | |
6569 | ${lookup ldap {ldapi://%2Ftmp%2Fldap.sock/o=... | |
6570 | .endd | |
6571 | When Exim processes an LDAP lookup and finds that the `hostname' is really | |
6572 | a pathname, it uses the Unix domain socket code, even if the query actually | |
6573 | specifies \"ldap"\ or \"ldaps"\. In particular, no encryption is used for a | |
6574 | socket connection. This behaviour means that you can use a setting of | |
6575 | \ldap@_default@_servers\ such as in the example above with traditional \"ldap"\ | |
6576 | or \"ldaps"\ queries, and it will work. First, Exim tries a connection via | |
6577 | the Unix domain socket; if that fails, it tries a TCP/IP connection to the | |
6578 | backup host. | |
6579 | ||
6580 | If an explicit \"ldapi"\ type is given in a query when a host name is | |
6581 | specified, an error is diagnosed. However, if there are more items in | |
6582 | \ldap@_default@_servers\, they are tried. In other words: | |
6583 | .numberpars $. | |
6584 | Using a pathname with \"ldap"\ or \"ldaps"\ forces the use of the Unix domain | |
6585 | interface. | |
6586 | .nextp | |
4964e932 | 6587 | Using \"ldapi"\ with a host name causes an error. |
495ae4b0 PH |
6588 | .endp |
6589 | ||
6590 | Using \"ldapi"\ with no host or path in the query, and no setting of | |
6591 | \ldap@_default@_servers\, does whatever the library does by default. | |
6592 | ||
6593 | ||
6594 | .section LDAP authentication and control information | |
6595 | .index LDAP||authentication | |
6596 | The LDAP URL syntax provides no way of passing authentication and other control | |
6597 | information to the server. To make this possible, the URL in an LDAP query may | |
6598 | be preceded by any number of `<<name>>=<<value>>' settings, separated by | |
6599 | spaces. If a value contains spaces it must be enclosed in double quotes, and | |
6600 | when double quotes are used, backslash is interpreted in the usual way inside | |
d43194df | 6601 | them. The following names are recognized: |
495ae4b0 | 6602 | .display |
495ae4b0 | 6603 | DEREFERENCE $rm{set the dereferencing parameter} |
d43194df PH |
6604 | .newline |
6605 | .em | |
6606 | NETTIME $rm{set a timeout for a network operation} | |
6607 | .nem | |
6608 | .newline | |
495ae4b0 PH |
6609 | USER $rm{set the DN, for authenticating the LDAP bind} |
6610 | PASS $rm{set the password, likewise} | |
6611 | SIZE $rm{set the limit for the number of entries returned} | |
6612 | TIME $rm{set the maximum waiting time for a query} | |
6613 | .endd | |
4964e932 | 6614 | The value of the \\DEREFERENCE\\ parameter must be one of the words `never', |
495ae4b0 PH |
6615 | `searching', `finding', or `always'. |
6616 | ||
d43194df PH |
6617 | .em |
6618 | The name \\CONNECT\\ is an obsolete name for \\NETTIME\\, retained for | |
6619 | backwards compatibility. This timeout (specified as a number of seconds) is | |
6620 | enforced from the client end for operations that can be carried out over a | |
6621 | network. Specifically, it applies to network connections and calls to the | |
6622 | \*ldap@_result()*\ function. If the value is greater than zero, it is used if | |
6623 | \\LDAP@_OPT@_NETWORK@_TIMEOUT\\ is defined in the LDAP headers (OpenLDAP), or | |
6624 | if \\LDAP@_X@_OPT@_CONNECT@_TIMEOUT\\ is defined in the LDAP headers (Netscape | |
6625 | SDK 4.1). A value of zero forces an explicit setting of `no timeout' for | |
6626 | Netscape SDK; for OpenLDAP no action is taken. | |
6627 | ||
6628 | The \\TIME\\ parameter (also a number of seconds) is passed to the server to | |
6629 | set a server-side limit on the time taken to complete a search. | |
6630 | .nem | |
6631 | ||
495ae4b0 PH |
6632 | Here is an example of an LDAP query in an Exim lookup that uses some of these |
6633 | values. This is a single line, folded for ease of reading: | |
6634 | .display asis | |
6635 | .indent 0 | |
6636 | ${lookup ldap | |
6637 | {user="cn=manager,o=University of Cambridge,c=UK" pass=secret | |
6638 | ldap:///o=University%20of%20Cambridge,c=UK?sn?sub?(cn=foo)} | |
6639 | {$value}fail} | |
6640 | .endd | |
6641 | The encoding of spaces as %20 is a URL thing which should not be done for any | |
6642 | of the auxiliary data. Exim configuration settings that include lookups which | |
6643 | contain password information should be preceded by `hide' to prevent non-admin | |
6644 | users from using the \-bP-\ option to see their values. | |
6645 | ||
6646 | The auxiliary data items may be given in any order. The default is no | |
6647 | connection timeout (the system timeout is used), no user or password, no limit | |
6648 | on the number of entries returned, and no time limit on queries. | |
6649 | ||
495ae4b0 PH |
6650 | When a DN is quoted in the \\USER=\\ setting for LDAP authentication, Exim |
6651 | removes any URL quoting that it may contain before passing it LDAP. Apparently | |
6652 | some libraries do this for themselves, but some do not. Removing the URL | |
6653 | quoting has two advantages: | |
6654 | .numberpars $. | |
6655 | It makes it possible to use the same \quote@_ldap@_dn\ expansion for \\USER=\\ | |
6656 | DNs as with DNs inside actual queries. | |
6657 | .nextp | |
4964e932 | 6658 | It permits spaces inside \\USER=\\ DNs. |
495ae4b0 PH |
6659 | .endp |
6660 | For example, a setting such as | |
6661 | .display asis | |
6662 | USER=cn=${quote_ldap_dn:$1} | |
6663 | .endd | |
6664 | should work even if \$1$\ contains spaces. | |
6665 | ||
4964e932 PH |
6666 | Expanded data for the \\PASS=\\ value should be quoted using the \quote\ |
6667 | expansion operator, rather than the LDAP quote operators. The only reason this | |
6668 | field needs quoting is to ensure that it conforms to the Exim syntax, which | |
495ae4b0 PH |
6669 | does not allow unquoted spaces. For example: |
6670 | .display asis | |
6671 | PASS=${quote:$3} | |
6672 | .endd | |
6673 | ||
6674 | The LDAP authentication mechanism can be used to check passwords as part of | |
6675 | SMTP authentication. See the \ldapauth\ expansion string condition in chapter | |
6676 | ~~CHAPexpand. | |
6677 | ||
6678 | ||
6679 | .section Format of data returned by LDAP | |
6680 | .index LDAP||returned data formats | |
6681 | The \%ldapdn%\ lookup type returns the Distinguished Name from a single entry as | |
6682 | a sequence of values, for example | |
6683 | .display asis | |
6684 | cn=manager, o=University of Cambridge, c=UK | |
6685 | .endd | |
6686 | ||
6687 | The \%ldap%\ lookup type generates an error if more than one entry matches the | |
d43194df PH |
6688 | search filter, whereas \%ldapm%\ permits this case, and inserts a newline in |
6689 | the result between the data from different entries. It is possible for multiple | |
6690 | values to be returned for both \%ldap%\ and \%ldapm%\, but in the former case | |
6691 | you know that whatever values are returned all came from a single entry in the | |
495ae4b0 PH |
6692 | directory. |
6693 | ||
6694 | In the common case where you specify a single attribute in your LDAP query, the | |
6695 | result is not quoted, and does not contain the attribute name. If the attribute | |
6696 | has multiple values, they are separated by commas. | |
6697 | ||
6698 | If you specify multiple attributes, the result contains space-separated, quoted | |
6699 | strings, each preceded by the attribute name and an equals sign. Within the | |
6700 | quotes, the quote character, backslash, and newline are escaped with | |
6701 | backslashes, and commas are used to separate multiple values for the attribute. | |
6702 | Apart from the escaping, the string within quotes takes the same form as the | |
6703 | output when a single attribute is requested. Specifying no attributes is the | |
6704 | same as specifying all of an entry's attributes. | |
6705 | ||
6706 | Here are some examples of the output format. The first line of each pair is an | |
6707 | LDAP query, and the second is the data that is returned. The attribute called | |
6708 | \attr1\ has two values, whereas \attr2\ has only one value: | |
6709 | .display asis | |
6710 | ldap:///o=base?attr1?sub?(uid=fred) | |
6711 | value1.1, value1.2 | |
6712 | ||
6713 | ldap:///o=base?attr2?sub?(uid=fred) | |
6714 | value two | |
6715 | ||
6716 | ldap:///o=base?attr1,attr2?sub?(uid=fred) | |
6717 | attr1="value1.1, value1.2" attr2="value two" | |
6718 | ||
6719 | ldap:///o=base??sub?(uid=fred) | |
6720 | objectClass="top" attr1="value1.1, value1.2" attr2="value two" | |
6721 | .endd | |
6722 | The \extract\ operator in string expansions can be used to pick out individual | |
6723 | fields from data that consists of $it{key}=$it{value} pairs. You can make use | |
6724 | of Exim's \-be-\ option to run expansion tests and thereby check the results of | |
6725 | LDAP lookups. | |
6726 | ||
6727 | ||
6728 | ||
6729 | .section More about NIS+ | |
6730 | .rset SECTnisplus "~~chapter.~~section" | |
6731 | .index NIS@+ lookup type | |
6732 | .index lookup||NIS+ | |
6733 | NIS+ queries consist of a NIS+ \*indexed name*\ followed by an optional colon | |
6734 | and field name. If this is given, the result of a successful query is the | |
6735 | contents of the named field; otherwise the result consists of a concatenation | |
6736 | of \*field-name=field-value*\ pairs, separated by spaces. Empty values and | |
6737 | values containing spaces are quoted. For example, the query | |
6738 | .display asis | |
6739 | [name=mg1456],passwd.org_dir | |
6740 | .endd | |
6741 | might return the string | |
6742 | .display asis | |
6743 | name=mg1456 passwd="" uid=999 gid=999 gcos="Martin Guerre" | |
6744 | home=/home/mg1456 shell=/bin/bash shadow="" | |
6745 | .endd | |
6746 | (split over two lines here to fit on the page), whereas | |
6747 | .display asis | |
6748 | [name=mg1456],passwd.org_dir:gcos | |
6749 | .endd | |
6750 | would just return | |
6751 | .display asis | |
6752 | Martin Guerre | |
6753 | .endd | |
6754 | with no quotes. A NIS+ lookup fails if NIS+ returns more than one table entry | |
6755 | for the given indexed key. The effect of the \quote@_nisplus\ expansion | |
6756 | operator is to double any quote characters within the text. | |
6757 | ||
6758 | ||
6759 | .section More about MySQL, PostgreSQL, Oracle, and Interbase | |
6760 | .rset SECTsql "~~chapter.~~section" | |
6761 | .index MySQL||lookup type | |
6762 | .index PostgreSQL lookup type | |
6763 | .index lookup||MySQL | |
6764 | .index lookup||PostgreSQL | |
6765 | .index Oracle||lookup type | |
6766 | .index lookup||Oracle | |
6767 | .index Interbase lookup type | |
6768 | .index lookup||Interbase | |
6769 | If any MySQL, PostgreSQL, Oracle, or Interbase lookups are used, the | |
6770 | \mysql@_servers\, \pgsql@_servers\, \oracle@_servers\, or \ibase@_servers\ | |
6771 | option (as appropriate) must be set to a colon-separated list of server | |
6772 | information. Each item in the list is a slash-separated list of four items: | |
6773 | host name, database name, user name, and password. In the case of Oracle, the | |
6774 | host name field is used for the `service name', and the database name field is | |
6775 | not used and should be empty. For example: | |
6776 | .display asis | |
6777 | hide oracle_servers = oracle.plc.example//ph10/abcdwxyz | |
6778 | .endd | |
6779 | Because password data is sensitive, you should always precede the setting with | |
6780 | `hide', to prevent non-admin users from obtaining the setting via the \-bP-\ | |
6781 | option. Here is an example where two MySQL servers are listed: | |
6782 | .display asis | |
6783 | hide mysql_servers = localhost/users/root/secret:\ | |
6784 | otherhost/users/root/othersecret | |
6785 | .endd | |
6786 | For MySQL and PostgreSQL, a host may be specified as <<name>>:<<port>> but | |
6787 | because this is a colon-separated list, the colon has to be doubled. | |
6788 | ||
6789 | For each query, these parameter groups are tried in order until a connection | |
6790 | and a query succeeds. Queries for these databases are SQL statements, so an | |
6791 | example might be | |
6792 | .display asis | |
6793 | .indent 0 | |
6794 | ${lookup mysql{select mailbox from users where id='ph10'}{$value}fail} | |
6795 | .endd | |
6796 | If the result of the query contains more than one field, the data for | |
6797 | each field in the row is returned, preceded by its name, so the result | |
6798 | of | |
6799 | .display asis | |
6800 | .indent 0 | |
6801 | ${lookup pgsql{select home,name from users where id='ph10'}{$value}} | |
6802 | .endd | |
6803 | might be | |
6804 | .display asis | |
6805 | home=/home/ph10 name="Philip Hazel" | |
6806 | .endd | |
6807 | Values containing spaces and empty values are double quoted, with embedded | |
6808 | quotes escaped by a backslash. | |
6809 | ||
6810 | If the result of the query contains just one field, the value is passed back | |
6811 | verbatim, without a field name, for example: | |
6812 | .display asis | |
6813 | Philip Hazel | |
6814 | .endd | |
6815 | If the result of the query yields more than one row, it is all concatenated, | |
6816 | with a newline between the data for each row. | |
6817 | ||
6818 | The \quote@_mysql\, \quote@_pgsql\, and \quote@_oracle\ expansion operators | |
6819 | convert newline, tab, carriage return, and backspace to @\n, @\t, @\r, and @\b | |
6820 | respectively, and the characters single-quote, double-quote, and backslash | |
6821 | itself are escaped with backslashes. The \quote@_pgsql\ expansion operator, in | |
6822 | addition, escapes the percent and underscore characters. This cannot be done | |
6823 | for MySQL because these escapes are not recognized in contexts where these | |
6824 | characters are not special. | |
6825 | ||
6826 | ||
6827 | .section Special MySQL features | |
6828 | For MySQL, an empty host name or the use of `localhost' in \mysql@_servers\ | |
6829 | causes a connection to the server on the local host by means of a Unix domain | |
6830 | socket. An alternate socket can be specified in parentheses. The full syntax of | |
6831 | each item in \mysql@_servers\ is: | |
6832 | .display | |
6833 | <<hostname>>@:@:<<port>>(<<socket name>>)/<<database>>/<<user>>/<<password>> | |
6834 | .endd | |
6835 | Any of the three sub-parts of the first field can be omitted. For normal use on | |
6836 | the local host it can be left blank or set to just `localhost'. | |
6837 | ||
6838 | No database need be supplied -- but if it is absent here, it must be given in | |
6839 | the queries. | |
6840 | ||
6841 | If a MySQL query is issued that does not request any data (an insert, update, | |
6842 | or delete command), the result of the lookup is the number of rows affected. | |
d43194df PH |
6843 | .em |
6844 | \**Warning**\: this can be misleading. If an update does not actually change | |
6845 | anything (for example, setting a field to the value it already has), the result | |
6846 | is zero because no rows are affected. | |
6847 | .nem | |
495ae4b0 PH |
6848 | |
6849 | ||
6850 | .section Special PostgreSQL features | |
6851 | PostgreSQL lookups can also use Unix domain socket connections to the database. | |
6852 | This is usually faster and costs less CPU time than a TCP/IP connection. | |
6853 | However it can be used only if the mail server runs on the same machine as the | |
6854 | database server. A configuration line for PostgreSQL via Unix domain sockets | |
6855 | looks like this: | |
6856 | .display asis | |
6857 | hide pgsql_servers = (/tmp/.s.PGSQL.5432)/db/user/password : ... | |
6858 | .endd | |
6859 | In other words, instead of supplying a host name, a path to the socket is | |
6860 | given. The path name is enclosed in parentheses so that its slashes aren't | |
6861 | visually confused with the delimiters for the other server parameters. | |
6862 | ||
6863 | If a PostgreSQL query is issued that does not request any data (an insert, | |
6864 | update, or delete command), the result of the lookup is the number of rows | |
6865 | affected. | |
6866 | ||
6867 | ||
6868 | ||
6869 | ||
6870 | . | |
6871 | . | |
6872 | . | |
6873 | . | |
6874 | . ============================================================================ | |
6875 | .chapter Domain, host, address, and local part lists | |
6876 | .set runningfoot "domain, host, and address lists" | |
6877 | .rset CHAPdomhosaddlists "~~chapter" | |
6878 | .index list||of domains, hosts, etc. | |
6879 | A number of Exim configuration options contain lists of domains, hosts, | |
6880 | email addresses, or local parts. For example, the \hold@_domains\ option | |
6881 | contains a list of domains whose delivery is currently suspended. These lists | |
6882 | are also used as data in ACL statements (see chapter ~~CHAPACL). | |
6883 | ||
6884 | Each item in one of these lists is a pattern to be matched against a domain, | |
6885 | host, email address, or local part, respectively. In the sections below, the | |
6886 | different types of pattern for each case are described, but first we cover some | |
6887 | general facilities that apply to all four kinds of list. | |
6888 | ||
6889 | ||
6890 | .section Expansion of lists | |
6891 | .index expansion||of lists | |
d43194df PH |
6892 | .em |
6893 | Each list is expanded as a single string before it is used. The result of | |
6894 | expansion must be a list, possibly containing empty items, which is split up | |
6895 | into separate items for matching. By default, colon is the separator character, | |
6896 | but this can be varied if necessary. See sections ~~SECTlistconstruct and | |
6897 | ~~SECTempitelis for details of the list syntax; the second of these discusses | |
6898 | the way you specify empty list items. | |
6899 | .nem | |
6900 | ||
6901 | If the string expansion is forced to fail, Exim behaves as if the item it is | |
6902 | testing (domain, host, address, or local part) is not in the list. Other | |
6903 | expansion failures cause temporary errors. | |
495ae4b0 PH |
6904 | |
6905 | If an item in a list is a regular expression, backslashes, dollars and possibly | |
6906 | other special characters in the expression must be protected against | |
6907 | misinterpretation by the string expander. The easiest way to do this is to use | |
6908 | the \"@\N"\ expansion feature to indicate that the contents of the regular | |
6909 | expression should not be expanded. For example, in an ACL you might have: | |
6910 | .display asis | |
6911 | deny senders = \N^\d{8}\w@.*\.baddomain\.example$\N : | |
6912 | ${lookup{$domain}lsearch{/badsenders/bydomain}} | |
6913 | .endd | |
6914 | The first item is a regular expression that is protected from expansion by | |
6915 | \"@\N"\, whereas the second uses the expansion to obtain a list of unwanted | |
6916 | senders based on the receiving domain. | |
6917 | ||
495ae4b0 PH |
6918 | |
6919 | ||
6920 | .section Negated items in lists | |
6921 | .index list||negation | |
6922 | .index negation in lists | |
6923 | Items in a list may be positive or negative. Negative items are indicated by a | |
6924 | leading exclamation mark, which may be followed by optional white space. A list | |
6925 | defines a set of items (domains, etc). When Exim processes one of these lists, | |
6926 | it is trying to find out whether a domain, host, address, or local part | |
6927 | (respectively) is in the set that is defined by the list. It works like this: | |
6928 | ||
6929 | The list is scanned from left to right. If a positive item is matched, the | |
6930 | subject that is being checked is in the set; if a negative item is matched, the | |
6931 | subject is not in the set. If the end of the list is reached without the | |
6932 | subject having matched any of the patterns, it is in the set if the last item | |
6933 | was a negative one, but not if it was a positive one. For example, the list in | |
6934 | .display asis | |
6935 | domainlist relay_domains = !a.b.c : *.b.c | |
6936 | .endd | |
6937 | matches any domain ending in \*.b.c*\ except for \*a.b.c*\. Domains that match | |
6938 | neither \*a.b.c*\ nor \*@*.b.c*\ do not match, because the last item in the | |
6939 | list is positive. However, if the setting were | |
6940 | .display asis | |
6941 | domainlist relay_domains = !a.b.c | |
6942 | .endd | |
6943 | then all domains other than \*a.b.c*\ would match because the last item in the | |
6944 | list is negative. In other words, a list that ends with a negative item behaves | |
6945 | as if it had an extra item \":*"\ on the end. | |
6946 | ||
4964e932 PH |
6947 | Another way of thinking about positive and negative items in lists is to read |
6948 | the connector as `or' after a positive item and as `and' after a negative | |
6949 | item. | |
495ae4b0 PH |
6950 | |
6951 | ||
6952 | .section File names in lists | |
6953 | .rset SECTfilnamlis "~~chapter.~~section" | |
6954 | .index list||file name in | |
6955 | If an item in a domain, host, address, or local part list is an absolute file | |
6956 | name (beginning with a slash character), each line of the file is read and | |
6957 | processed as if it were an independent item in the list, except that further | |
6958 | file names are not allowed, | |
6959 | and no expansion of the data from the file takes place. | |
6960 | Empty lines in the file are ignored, and the file may also contain comment | |
6961 | lines: | |
6962 | .numberpars $. | |
6963 | For domain and host lists, if a @# character appears anywhere in a line of the | |
6964 | file, it and all following characters are ignored. | |
6965 | .nextp | |
6966 | Because local parts may legitimately contain @# characters, a comment in an | |
6967 | address list or local part list file is recognized only if @# is preceded by | |
6968 | white space or the start of the line. For example: | |
6969 | .display asis | |
6970 | not#comment@x.y.z # but this is a comment | |
6971 | .endd | |
6972 | .endp | |
6973 | Putting a file name in a list has the same effect as inserting each line of the | |
6974 | file as an item in the list (blank lines and comments excepted). However, there | |
6975 | is one important difference: the file is read each time the list is processed, | |
6976 | so if its contents vary over time, Exim's behaviour changes. | |
6977 | ||
6978 | If a file name is preceded by an exclamation mark, the sense of any match | |
6979 | within the file is inverted. For example, if | |
6980 | .display asis | |
6981 | hold_domains = !/etc/nohold-domains | |
6982 | .endd | |
6983 | and the file contains the lines | |
6984 | .display asis | |
6985 | !a.b.c | |
6986 | *.b.c | |
6987 | .endd | |
6988 | then \*a.b.c*\ is in the set of domains defined by \hold@_domains\, whereas any | |
6989 | domain matching \"*.b.c"\ is not. | |
6990 | ||
6991 | ||
6992 | .section An lsearch file is not an out-of-line list | |
6993 | As will be described in the sections that follow, lookups can be used in lists | |
6994 | to provide indexed methods of checking list membership. There has been some | |
6995 | confusion about the way \%lsearch%\ lookups work in lists. Because | |
6996 | an \%lsearch%\ file contains plain text and is scanned sequentially, it is | |
6997 | sometimes thought that it is allowed to contain wild cards and other kinds of | |
6998 | non-constant pattern. This is not the case. The keys in an \%lsearch%\ file are | |
6999 | always fixed strings, just as for any other single-key lookup type. | |
7000 | ||
4964e932 | 7001 | If you want to use a file to contain wild-card patterns that form part of a |
495ae4b0 PH |
7002 | list, just give the file name on its own, without a search type, as described |
7003 | in the previous section. | |
7004 | ||
7005 | ||
7006 | ||
7007 | .section Named lists | |
7008 | .rset SECTnamedlists "~~chapter.~~section" | |
7009 | .index named lists | |
7010 | .index list||named | |
7011 | A list of domains, hosts, email addresses, or local parts can be given a name | |
7012 | which is then used to refer to the list elsewhere in the configuration. This is | |
7013 | particularly convenient if the same list is required in several different | |
7014 | places. It also allows lists to be given meaningful names, which can improve | |
7015 | the readability of the configuration. For example, it is conventional to define | |
7016 | a domain list called \*local@_domains*\ for all the domains that are handled | |
7017 | locally on a host, using a configuration line such as | |
7018 | .display asis | |
7019 | domainlist local_domains = localhost:my.dom.example | |
7020 | .endd | |
7021 | Named lists are referenced by giving their name preceded by a plus sign, so, | |
7022 | for example, a router that is intended to handle local domains would be | |
7023 | configured with the line | |
7024 | .display asis | |
7025 | domains = +local_domains | |
7026 | .endd | |
7027 | The first router in a configuration is often one that handles all domains | |
7028 | except the local ones, using a configuration with a negated item like this: | |
7029 | .display asis | |
7030 | dnslookup: | |
7031 | driver = dnslookup | |
7032 | domains = ! +local_domains | |
7033 | transport = remote_smtp | |
7034 | no_more | |
7035 | .endd | |
7036 | The four kinds of named list are created by configuration lines starting with | |
7037 | the words \domainlist\, \hostlist\, \addresslist\, or \localpartlist\, | |
7038 | respectively. Then there follows the name that you are defining, followed by an | |
7039 | equals sign and the list itself. For example: | |
7040 | .display asis | |
7041 | hostlist relay_hosts = 192.168.23.0/24 : my.friend.example | |
7042 | addresslist bad_senders = cdb;/etc/badsenders | |
7043 | .endd | |
7044 | A named list may refer to other named lists: | |
7045 | .display asis | |
7046 | domainlist dom1 = first.example : second.example | |
7047 | domainlist dom2 = +dom1 : third.example | |
7048 | domainlist dom3 = fourth.example : +dom2 : fifth.example | |
7049 | .endd | |
7050 | ||
7051 | \**Warning**\: If the last item in a referenced list is a negative one, the | |
7052 | effect may not be what you intended, because the negation does not propagate | |
7053 | out to the higher level. For example, consider: | |
7054 | .display asis | |
7055 | domainlist dom1 = !a.b | |
7056 | domainlist dom2 = +dom1 : *.b | |
7057 | .endd | |
7058 | The second list specifies `either in the \dom1\ list or \*@*.b*\'. The first | |
7059 | list specifies just `not \*a.b*\', so the domain \*x.y*\ matches it. That means | |
7060 | it matches the second list as well. The effect is not the same as | |
7061 | .display asis | |
7062 | domainlist dom2 = !a.b : *.b | |
7063 | .endd | |
4964e932 | 7064 | where \*x.y*\ does not match. It's best to avoid negation altogether in |
495ae4b0 PH |
7065 | referenced lists if you can. |
7066 | ||
7067 | Named lists may have a performance advantage. When Exim is routing an | |
7068 | address or checking an incoming message, it caches the result of tests on named | |
7069 | lists. So, if you have a setting such as | |
7070 | .display asis | |
7071 | domains = +local_domains | |
7072 | .endd | |
7073 | on several of your routers | |
4964e932 | 7074 | or in several ACL statements, |
495ae4b0 PH |
7075 | the actual test is done only for the first one. However, the caching works only |
7076 | if there are no expansions within the list itself or any sublists that it | |
7077 | references. In other words, caching happens only for lists that are known to be | |
7078 | the same each time they are referenced. | |
7079 | ||
7080 | By default, there may be up to 16 named lists of each type. This limit can be | |
7081 | extended by changing a compile-time variable. The use of domain and host lists | |
7082 | is recommended for concepts such as local domains, relay domains, and relay | |
7083 | hosts. The default configuration is set up like this. | |
7084 | ||
7085 | ||
7086 | .section Named lists compared with macros | |
7087 | .index list||named compared with macro | |
7088 | .index macro||compared with named list | |
7089 | At first sight, named lists might seem to be no different from macros in the | |
7090 | configuration file. However, macros are just textual substitutions. If you | |
7091 | write | |
7092 | .display asis | |
7093 | ALIST = host1 : host2 | |
7094 | auth_advertise_hosts = !ALIST | |
7095 | .endd | |
7096 | it probably won't do what you want, because that is exactly the same as | |
7097 | .display asis | |
7098 | auth_advertise_hosts = !host1 : host2 | |
7099 | .endd | |
7100 | Notice that the second host name is not negated. However, if you use a host | |
7101 | list, and write | |
7102 | .display asis | |
7103 | hostlist alist = host1 : host2 | |
7104 | auth_advertise_hosts = ! +alist | |
7105 | .endd | |
7106 | the negation applies to the whole list, and so that is equivalent to | |
7107 | .display asis | |
7108 | auth_advertise_hosts = !host1 : !host2 | |
7109 | .endd | |
7110 | ||
7111 | ||
495ae4b0 PH |
7112 | .section Named list caching |
7113 | .index list||caching of named | |
7114 | .index caching||named lists | |
7115 | While processing a message, Exim caches the result of checking a named list if | |
7116 | it is sure that the list is the same each time. In practice, this means that | |
7117 | the cache operates only if the list contains no @$ characters, which guarantees | |
7118 | that it will not change when it is expanded. Sometimes, however, you may have | |
7119 | an expanded list that you know will be the same each time within a given | |
7120 | message. For example: | |
7121 | .display asis | |
7122 | domainlist special_domains = \ | |
7123 | ${lookup{$sender_host_address}cdb{/some/file}} | |
7124 | .endd | |
7125 | This provides a list of domains that depends only on the sending host's IP | |
7126 | address. If this domain list is referenced a number of times (for example, | |
7127 | in several ACL lines, or in several routers) the result of the check is not | |
7128 | cached by default, because Exim does not know that it is going to be the | |
7129 | same list each time. | |
7130 | ||
7131 | By appending \"@_cache"\ to \"domainlist"\ you can tell Exim to go ahead and | |
7132 | cache the result anyway. For example: | |
7133 | .display asis | |
7134 | domainlist_cache special_domains = ${lookup{... | |
7135 | .endd | |
7136 | If you do this, you should be absolutely sure that caching is going to do | |
7137 | the right thing in all cases. When in doubt, leave it out. | |
495ae4b0 PH |
7138 | |
7139 | ||
7140 | .section Domain lists | |
7141 | .rset SECTdomainlist "~~chapter.~~section" | |
7142 | .index domain list||patterns for | |
7143 | .index list||domain list | |
7144 | Domain lists contain patterns that are to be matched against a mail domain. | |
7145 | The following types of item may appear in domain lists: | |
7146 | .numberpars $. | |
7147 | .index primary host name | |
4964e932 | 7148 | .index host||name, matched in domain list |
495ae4b0 PH |
7149 | .index \primary@_hostname\ |
7150 | .index domain list||matching primary host name | |
7151 | .index @@ in a domain list | |
7152 | If a pattern consists of a single @@ character, it matches the local host name, | |
7153 | as set by the \primary@_hostname\ option (or defaulted). This makes it possible | |
7154 | to use the same configuration file on several different hosts that differ only | |
7155 | in their names. | |
7156 | .nextp | |
7157 | .index @@[] in a domain list | |
7158 | .index domain list||matching local IP interfaces | |
7159 | .index domain literal | |
7160 | If a pattern consists of the string \"@@[]"\ it matches any local IP interface | |
7161 | address, enclosed in square brackets, as in an email address that contains a | |
4964e932 | 7162 | domain literal. |
495ae4b0 | 7163 | In today's Internet, the use of domain literals is controversial. |
495ae4b0 PH |
7164 | .nextp |
7165 | .index @@mx@_any | |
7166 | .index @@mx@_primary | |
7167 | .index @@mx@_secondary | |
7168 | .index domain list||matching MX pointers to local host | |
7169 | If a pattern consists of the string \"@@mx@_any"\ it matches any domain that | |
7170 | has an MX record pointing to the local host or to any host that is listed in | |
7171 | .index \hosts@_treat@_as@_local\ | |
7172 | \hosts@_treat@_as@_local\. The items \"@@mx@_primary"\ and \"@@mx@_secondary"\ | |
7173 | are similar, except that the first matches only when a primary MX target is the | |
7174 | local host, and the second only when no primary MX target is the local host, | |
7175 | but a secondary MX target is. `Primary' means an MX record with the lowest | |
7176 | preference value -- there may of course be more than one of them. | |
7177 | ||
4964e932 PH |
7178 | The MX lookup that takes place when matching a pattern of this type is |
7179 | performed with the resolver options for widening names turned off. Thus, for | |
7180 | example, a single-component domain will \*not*\ be expanded by adding the | |
7181 | resolver's default domain. See the \qualify@_single\ and \search@_parents\ | |
495ae4b0 PH |
7182 | options of the \%dnslookup%\ router for a discussion of domain widening. |
7183 | ||
7184 | Sometimes you may want to ignore certain IP addresses when using one of these | |
7185 | patterns. You can specify this by following the pattern with \"/ignore=<<ip | |
7186 | list>>"\, where <<ip list>> is a list of IP addresses. These addresses are | |
4964e932 | 7187 | ignored when processing the pattern (compare the \ignore@_target@_hosts\ option |
495ae4b0 PH |
7188 | on a router). For example: |
7189 | .display asis | |
7190 | domains = @mx_any/ignore=127.0.0.1 | |
7191 | .endd | |
7192 | This example matches any domain that has an MX record pointing to one of | |
7193 | the local host's IP addresses other than 127.0.0.1. | |
7194 | ||
4964e932 PH |
7195 | The list of IP addresses is in fact processed by the same code that processes |
7196 | host lists, so it may contain CIDR-coded network specifications and it may also | |
495ae4b0 PH |
7197 | contain negative items. |
7198 | ||
7199 | Because the list of IP addresses is a sublist within a domain list, you have to | |
7200 | be careful about delimiters if there is more than one address. Like any other | |
7201 | list, the default delimiter can be changed. Thus, you might have: | |
7202 | .display asis | |
7203 | domains = @mx_any/ignore=<;127.0.0.1;0.0.0.0 : \ | |
7204 | an.other.domain : ... | |
7205 | .endd | |
7206 | so that the sublist uses semicolons for delimiters. When IPv6 addresses are | |
7207 | involved, it is easiest to change the delimiter for the main list as well: | |
7208 | .display asis | |
7209 | domains = <? @mx_any/ignore=<;127.0.0.1;::1 ? \ | |
7210 | an.other.domain ? ... | |
7211 | .endd | |
495ae4b0 PH |
7212 | |
7213 | .nextp | |
7214 | .index asterisk||in domain list | |
7215 | .index domain list||asterisk in | |
7216 | .index domain list||matching `ends with' | |
7217 | If a pattern starts with an asterisk, the remaining characters of the pattern | |
7218 | are compared with the terminating characters of the domain. The use of `$*$' in | |
7219 | domain lists differs from its use in partial matching lookups. In a domain | |
7220 | list, the character following the asterisk need not be a dot, whereas partial | |
7221 | matching works only in terms of dot-separated components. For example, a domain | |
7222 | list item such as \"*key.ex"\ matches \*donkey.ex*\ as well as | |
7223 | \*cipher.key.ex*\. | |
7224 | .nextp | |
7225 | .index regular expressions||in domain list | |
7226 | .index domain list||matching regular expression | |
7227 | If a pattern starts with a circumflex character, it is treated as a regular | |
7228 | expression, and matched against the domain using a regular expression matching | |
7229 | function. The circumflex is treated as part of the regular expression. | |
7230 | References to descriptions of the syntax of regular expressions are given in | |
7231 | chapter ~~CHAPregexp. | |
7232 | ||
7233 | \**Warning**\: Because domain lists are expanded before being processed, you | |
7234 | must escape any backslash and dollar characters in the regular expression, or | |
7235 | use the special \"@\N"\ sequence (see chapter ~~CHAPexpand) to specify that it | |
7236 | is not to be expanded (unless you really do want to build a regular expression | |
7237 | by expansion, of course). | |
7238 | .nextp | |
7239 | .index lookup||in domain list | |
7240 | .index domain list||matching by lookup | |
7241 | If a pattern starts with the name of a single-key lookup type followed by a | |
7242 | semicolon (for example, `dbm;' or `lsearch;'), the remainder of the pattern | |
7243 | must be a file name in a suitable format for the lookup type. For example, for | |
7244 | `cdb;' it must be an absolute path: | |
7245 | .display asis | |
7246 | domains = cdb;/etc/mail/local_domains.cdb | |
7247 | .endd | |
7248 | The appropriate type of lookup is done on the file using the domain name as the | |
7249 | key. In most cases, the data that is looked up is not used; Exim is interested | |
7250 | only in whether or not the key is present in the file. However, when a lookup | |
7251 | is used for the \domains\ option on a router | |
7252 | or a \domains\ condition in an ACL statement, the data is preserved in the | |
7253 | \$domain@_data$\ variable and can be referred to in other router options or | |
7254 | other statements in the same ACL. | |
7255 | .nextp | |
7256 | Any of the single-key lookup type names may be preceded by `partial<<n>>-', | |
7257 | where the <<n>> is optional, for example, | |
7258 | .display asis | |
7259 | domains = partial-dbm;/partial/domains | |
7260 | .endd | |
7261 | This causes partial matching logic to be invoked; a description of how this | |
7262 | works is given in section ~~SECTpartiallookup. | |
7263 | .nextp | |
7264 | .index asterisk||in lookup type | |
7265 | Any of the single-key lookup types may be followed by an asterisk. This causes | |
7266 | a default lookup for a key consisting of a single asterisk to be done if the | |
7267 | original lookup fails. This is not a useful feature when using a domain list to | |
7268 | select particular domains (because any domain would match), but it might have | |
7269 | value if the result of the lookup is being used via the \$domain@_data$\ | |
7270 | expansion variable. | |
7271 | .nextp | |
7272 | If the pattern starts with the name of a query-style lookup type followed by a | |
7273 | semicolon (for example, `nisplus;' or `ldap;'), the remainder of the pattern | |
7274 | must be an appropriate query for the lookup type, as described in chapter | |
7275 | ~~CHAPfdlookup. For example: | |
7276 | .display asis | |
7277 | hold_domains = mysql;select domain from holdlist \ | |
7278 | where domain = '$domain'; | |
7279 | .endd | |
7280 | In most cases, the data that is looked up is not used (so for an SQL query, for | |
7281 | example, it doesn't matter what field you select). Exim is interested only in | |
7282 | whether or not the query succeeds. However, when a lookup is used for the | |
7283 | \domains\ option on a router, the data is preserved in the \$domain@_data$\ | |
7284 | variable and can be referred to in other options. | |
7285 | .nextp | |
7286 | .index domain list||matching literal domain name | |
7287 | If none of the above cases apply, a caseless textual comparison is made between | |
7288 | the pattern and the domain. | |
7289 | .endp | |
7290 | ||
7291 | Here is an example that uses several different kinds of pattern: | |
7292 | .display asis | |
7293 | domainlist funny_domains = \ | |
7294 | @ : \ | |
7295 | lib.unseen.edu : \ | |
7296 | *.foundation.fict.example : \ | |
7297 | \N^[1-2]\d{3}\.fict\.example$\N : \ | |
7298 | partial-dbm;/opt/data/penguin/book : \ | |
7299 | nis;domains.byname : \ | |
7300 | nisplus;[name=$domain,status=local],domains.org_dir | |
7301 | .endd | |
7302 | There are obvious processing trade-offs among the various matching modes. Using | |
7303 | an asterisk is faster than a regular expression, and listing a few names | |
7304 | explicitly probably is too. The use of a file or database lookup is expensive, | |
7305 | but may be the only option if hundreds of names are required. Because the | |
7306 | patterns are tested in order, it makes sense to put the most commonly matched | |
7307 | patterns earlier. | |
7308 | ||
7309 | ||
7310 | .section Host lists | |
7311 | .rset SECThostlist "~~chapter.~~section" | |
7312 | .index host list||patterns in | |
7313 | .index list||host list | |
7314 | Host lists are used to control what remote hosts are allowed to do. For | |
7315 | example, some hosts may be allowed to use the local host as a relay, and some | |
7316 | may be permitted to use the SMTP \\ETRN\\ command. Hosts can be identified in | |
7317 | two different ways, by name or by IP address. In a host list, some types of | |
7318 | pattern are matched to a host name, and some are matched to an IP address. | |
7319 | You need to be particularly careful with this when single-key lookups are | |
7320 | involved, to ensure that the right value is being used as the key. | |
7321 | ||
7322 | .section Special host list patterns | |
7323 | .index empty item in hosts list | |
7324 | .index host list||empty string in | |
7325 | If a host list item is the empty string, it matches only when no remote host is | |
7326 | involved. This is the case when a message is being received from a local | |
7327 | process using SMTP on the standard input, that is, when a TCP/IP connection is | |
7328 | not used. | |
7329 | ||
7330 | .index asterisk||in host list | |
7331 | The special pattern `$*$' in a host list matches any host or no host. Neither | |
7332 | the IP address nor the name is actually inspected. | |
7333 | ||
7334 | ||
7335 | .section Host list patterns that match by IP address | |
7336 | .rset SECThoslispatip "~~chapter.~~section" | |
7337 | .index host list||matching IP addresses | |
7338 | If an IPv4 host calls an IPv6 host and the call is accepted on an IPv6 socket, | |
7339 | the incoming address actually appears in the IPv6 host as | |
7340 | `@:@:$tt{ffff}:<<v4address>>'. When such an address is tested against a host | |
7341 | list, it is converted into a traditional IPv4 address first. (Not all operating | |
7342 | systems accept IPv4 calls on IPv6 sockets, as there have been some security | |
7343 | concerns.) | |
7344 | ||
7345 | The following types of pattern in a host list check the remote host by | |
7346 | inspecting its IP address: | |
7347 | .numberpars $. | |
7348 | If the pattern is a plain domain name (not a regular expression, not starting | |
7349 | with $*$, not a lookup of any kind), Exim calls the operating system function | |
7350 | to find the associated IP address(es). Exim uses the newer | |
7351 | \*getipnodebyname()*\ function when available, otherwise \*gethostbyname()*\. | |
7352 | This typically causes a forward DNS lookup of the name. The result is compared | |
7353 | with the IP address of the subject host. | |
7354 | ||
495ae4b0 | 7355 | If there is a temporary problem (such as a DNS timeout) with the host name |
4964e932 | 7356 | lookup, a temporary error occurs. For example, if the list is being used in an |
495ae4b0 PH |
7357 | ACL condition, the ACL gives a `defer' response, usually leading to a temporary |
7358 | SMTP error code. If no IP address can be found for the host name, what happens | |
7359 | is described in section ~~SECTbehipnot below. | |
495ae4b0 PH |
7360 | |
7361 | .nextp | |
7362 | .index @@ in a host list | |
7363 | If the pattern is `@@', the primary host name is substituted and used as a | |
7364 | domain name, as just described. | |
7365 | .nextp | |
7366 | If the pattern is an IP address, it is matched against the IP address of the | |
7367 | subject host. IPv4 addresses are given in the normal `dotted-quad' notation. | |
7368 | IPv6 addresses can be given in colon-separated format, but the colons have to | |
7369 | be doubled so as not to be taken as item separators when the default list | |
7370 | separator is used. IPv6 addresses are recognized even when Exim is compiled | |
7371 | without IPv6 support. This means that if they appear in a host list on an | |
7372 | IPv4-only host, Exim will not treat them as host names. They are just addresses | |
7373 | that can never match a client host. | |
7374 | .nextp | |
7375 | .index @@[] in a host list | |
7376 | If the pattern is `@@[]', it matches the IP address of any IP interface on | |
7377 | the local host. For example, if the local host is an IPv4 host with one | |
7378 | interface address 10.45.23.56, these two ACL statements have the same effect: | |
7379 | .display asis | |
7380 | accept hosts = 127.0.0.1 : 10.45.23.56 | |
7381 | accept hosts = @[] | |
7382 | .endd | |
7383 | .nextp | |
7384 | If the pattern is an IP address followed by a slash and a mask length (for | |
7385 | example 10.11.42.0/24), it is matched against the IP address of the subject | |
7386 | host under the given mask. | |
7387 | This allows, an entire network of hosts to be included (or excluded) by a | |
7388 | single item. | |
4964e932 | 7389 | .index CIDR notation |
495ae4b0 PH |
7390 | The mask uses CIDR notation; it specifies the number of address bits that must |
7391 | match, starting from the most significant end of the address. | |
7392 | ||
7393 | \**Note**\: the mask is \*not*\ a count of addresses, nor is it the high number | |
7394 | of a range of addresses. It is the number of bits in the network portion of the | |
7395 | address. The above example specifies a 24-bit netmask, so it matches all 256 | |
7396 | addresses in the 10.11.42.0 network. An item such as | |
7397 | .display asis | |
7398 | 192.168.23.236/31 | |
7399 | .endd | |
4964e932 PH |
7400 | matches just two addresses, 192.168.23.236 and 192.168.23.237. A mask value of |
7401 | 32 for an IPv4 address is the same as no mask at all; just a single address | |
495ae4b0 PH |
7402 | matches. |
7403 | ||
7404 | Here is another example which shows an IPv4 and an IPv6 network: | |
7405 | .display asis | |
7406 | recipient_unqualified_hosts = 192.168.0.0/16: \ | |
7407 | 3ffe::ffff::836f::::/48 | |
7408 | .endd | |
7409 | The doubling of list separator characters applies only when these items | |
7410 | appear inline in a host list. It is not required when indirecting via a file. | |
7411 | For example, | |
7412 | .display asis | |
7413 | recipient_unqualified_hosts = /opt/exim/unqualnets | |
7414 | .endd | |
7415 | could make use of a file containing | |
7416 | .display asis | |
7417 | 172.16.0.0/12 | |
7418 | 3ffe:ffff:836f::/48 | |
7419 | .endd | |
7420 | to have exactly the same effect as the previous example. When listing IPv6 | |
7421 | addresses inline, it is usually more convenient to use the facility for | |
7422 | changing separator characters. This list contains the same two networks: | |
7423 | .display asis | |
7424 | recipient_unqualified_hosts = <; 172.16.0.0/12; \ | |
7425 | 3ffe:ffff:836f::/48 | |
7426 | .endd | |
7427 | The separator is changed to semicolon by the leading `<;' at the start of the | |
7428 | list. | |
7429 | .endp | |
7430 | ||
7431 | ||
7432 | .section Host list patterns for single-key lookups by host address | |
7433 | .rset SECThoslispatsikey "~~chapter.~~section" | |
7434 | .index host list||lookup of IP address | |
7435 | When a host is to be identified by a single-key lookup of its complete IP | |
7436 | address, the pattern takes this form: | |
7437 | .display | |
7438 | net-<<single-key-search-type>>;<<search-data>> | |
7439 | .endd | |
7440 | For example: | |
7441 | .display asis | |
7442 | hosts_lookup = net-cdb;/hosts-by-ip.db | |
7443 | .endd | |
7444 | The text form of the IP address of the subject host is used as the lookup key. | |
7445 | IPv6 addresses are converted to an unabbreviated form, using lower case | |
7446 | letters, with dots as separators because colon is the key terminator in | |
7447 | \%lsearch%\ files. [Colons can in fact be used in keys in \%lsearch%\ files by | |
7448 | quoting the keys, but this is a facility that was added later.] The data | |
7449 | returned by the lookup is not used. | |
7450 | ||
7451 | .index IP address||masking | |
7452 | .index host list||masked IP address | |
7453 | Single-key lookups can also be performed using masked IP addresses, using | |
7454 | patterns of this form: | |
7455 | .display | |
7456 | net<<number>>-<<single-key-search-type>>;<<search-data>> | |
7457 | .endd | |
7458 | For example: | |
7459 | .display asis | |
7460 | net24-dbm;/networks.db | |
7461 | .endd | |
7462 | The IP address of the subject host is masked using <<number>> as the mask | |
7463 | length. A textual string is constructed from the masked value, followed by the | |
7464 | mask, and this is used as the lookup key. For example, if the host's IP address | |
7465 | is 192.168.34.6, the key that is looked up for the above example is | |
7466 | `192.168.34.0/24'. IPv6 addresses are converted to a text value using lower | |
7467 | case letters and dots as separators instead of the more usual colon, because | |
7468 | colon is the key terminator in \%lsearch%\ files. Full, unabbreviated IPv6 | |
7469 | addresses are always used. | |
7470 | ||
7471 | \**Warning**\: Specifing \net32@-\ (for an IPv4 address) or \net128@-\ (for an | |
7472 | IPv6 address) is not the same as specifing just \net@-\ without a number. In | |
7473 | the former case the key strings include the mask value, whereas in the latter | |
7474 | case the IP address is used on its own. | |
7475 | ||
7476 | ||
7477 | .section Host list patterns that match by host name | |
7478 | .rset SECThoslispatnam "~~chapter.~~section" | |
7479 | .index host||lookup failures | |
7480 | .index unknown host name | |
4964e932 | 7481 | .index host list||matching host name |
495ae4b0 PH |
7482 | There are several types of pattern that require Exim to know the name of the |
7483 | remote host. These are either wildcard patterns or lookups by name. (If a | |
7484 | complete hostname is given without any wildcarding, it is used to find an IP | |
7485 | address to match against, as described in the section ~~SECThoslispatip above.) | |
7486 | ||
7487 | If the remote host name is not already known when Exim encounters one of these | |
4964e932 | 7488 | patterns, it has to be found from the IP address. |
495ae4b0 PH |
7489 | Although many sites on the Internet are conscientious about maintaining reverse |
7490 | DNS data for their hosts, there are also many that do not do this. | |
7491 | Consequently, a name cannot always be found, and this may lead to unwanted | |
7492 | effects. Take care when configuring host lists with wildcarded name patterns. | |
7493 | Consider what will happen if a name cannot be found. | |
7494 | ||
7495 | Because of the problems of determining host names from IP addresses, matching | |
7496 | against host names is not as common as matching against IP addresses. | |
7497 | ||
7498 | By default, in order to find a host name, Exim first does a reverse DNS lookup; | |
7499 | if no name is found in the DNS, the system function (\*gethostbyaddr()*\ or | |
7500 | \*getipnodebyaddr()*\ if available) is tried. The order in which these lookups | |
7501 | are done can be changed by setting the \host@_lookup@_order\ option. | |
7502 | ||
7503 | There are some options that control what happens if a host name cannot be | |
7504 | found. These are described in section ~~SECTbehipnot below. | |
495ae4b0 PH |
7505 | |
7506 | ||
7507 | .index host||alias for | |
7508 | .index alias for host | |
7509 | As a result of aliasing, hosts may have more than one name. When processing any | |
7510 | of the following types of pattern, all the host's names are checked: | |
7511 | .numberpars $. | |
7512 | .index asterisk||in host list | |
7513 | If a pattern starts with `$*$' the remainder of the item must match the end of | |
7514 | the host name. For example, \"*.b.c"\ matches all hosts whose names end in | |
7515 | \*.b.c*\. This special simple form is provided because this is a very common | |
7516 | requirement. Other kinds of wildcarding require the use of a regular | |
7517 | expression. | |
7518 | .nextp | |
7519 | .index regular expressions||in host list | |
7520 | .index host list||regular expression in | |
7521 | If the item starts with `@^' it is taken to be a regular expression which is | |
7522 | matched against the host name. For example, | |
7523 | .display asis | |
7524 | ^(a|b)\.c\.d$ | |
7525 | .endd | |
7526 | is a regular expression that matches either of the two hosts \*a.c.d*\ or | |
7527 | \*b.c.d*\. When a regular expression is used in a host list, you must take care | |
7528 | that backslash and dollar characters are not misinterpreted as part of the | |
7529 | string expansion. The simplest way to do this is to use \"@\N"\ to mark that | |
7530 | part of the string as non-expandable. For example: | |
7531 | .display asis | |
7532 | sender_unqualified_hosts = \N^(a|b)\.c\.d$\N : .... | |
7533 | .endd | |
4964e932 PH |
7534 | \**Warning**\: If you want to match a complete host name, you must include the |
7535 | \"@$"\ terminating metacharacter in the regular expression, as in the above | |
7536 | example. Without it, a match at the start of the host name is all that is | |
495ae4b0 | 7537 | required. |
495ae4b0 PH |
7538 | .endp |
7539 | ||
7540 | ||
495ae4b0 PH |
7541 | .section Behaviour when an IP address or name cannot be found |
7542 | .rset SECTbehipnot "~~chapter.~~section" | |
7543 | .index host||lookup failures | |
4964e932 PH |
7544 | While processing a host list, Exim may need to look up an IP address from a |
7545 | name (see section ~~SECThoslispatip), or it may need to look up a host name | |
7546 | from an IP address (see section ~~SECThoslispatnam). In either case, the | |
495ae4b0 PH |
7547 | behaviour when it fails to find the information it is seeking is the same. |
7548 | ||
7549 | .index \"+include@_unknown"\ | |
7550 | .index \"+ignore@_unknown"\ | |
7551 | By default, Exim behaves as if the host does not match the list. This may not | |
7552 | always be what you want to happen. To change Exim's behaviour, the special | |
7553 | items \"+include@_unknown"\ or \"+ignore@_unknown"\ may appear in the list (at | |
7554 | top level -- they are not recognized in an indirected file). | |
7555 | .numberpars $. | |
7556 | If any item that follows \"+include@_unknown"\ requires information that | |
7557 | cannot found, Exim behaves as if the host does match the list. For example, | |
7558 | .display asis | |
7559 | host_reject_connection = +include_unknown:*.enemy.ex | |
7560 | .endd | |
7561 | rejects connections from any host whose name matches \"*.enemy.ex"\, and also | |
7562 | any hosts whose name it cannot find. | |
7563 | .nextp | |
4964e932 PH |
7564 | If any item that follows \"+ignore@_unknown"\ requires information that cannot |
7565 | be found, Exim ignores that item and proceeds to the rest of the list. For | |
495ae4b0 PH |
7566 | example: |
7567 | .display asis | |
7568 | accept hosts = +ignore_unknown : friend.example : \ | |
7569 | 192.168.4.5 | |
7570 | .endd | |
4964e932 PH |
7571 | accepts from any host whose name is \*friend.example*\ and from 192.168.4.5, |
7572 | whether or not its host name can be found. Without \"+ignore@_unknown"\, if no | |
495ae4b0 PH |
7573 | name can be found for 192.168.4.5, it is rejected. |
7574 | .endp | |
7575 | Both \"+include@_unknown"\ and \"+ignore@_unknown"\ may appear in the same | |
4964e932 | 7576 | list. The effect of each one lasts until the next, or until the end of the |
495ae4b0 PH |
7577 | list. |
7578 | ||
7579 | \**Note**\: This section applies to permanent lookup failures. It does \*not*\ | |
7580 | apply to temporary DNS errors. They always cause a defer action. | |
495ae4b0 PH |
7581 | |
7582 | ||
7583 | .section Host list patterns for single-key lookups by host name | |
7584 | .rset SECThoslispatnamsk "~~chapter.~~section" | |
7585 | .index host||lookup failures | |
7586 | .index unknown host name | |
7587 | .index host list||matching host name | |
7588 | If a pattern is of the form | |
7589 | .display | |
7590 | <<single-key-search-type>>;<<search-data>> | |
7591 | .endd | |
7592 | for example | |
7593 | .display asis | |
7594 | dbm;/host/accept/list | |
7595 | .endd | |
7596 | a single-key lookup is performend, using the host name as its key. If the | |
7597 | lookup succeeds, the host matches the item. The actual data that is looked up | |
7598 | is not used. | |
7599 | ||
7600 | \**Reminder**\: With this kind of pattern, you must have host $it{names} as | |
7601 | keys in the file, not IP addresses. If you want to do lookups based on IP | |
7602 | addresses, you must precede the search type with `net-' (see section | |
7603 | ~~SECThoslispatsikey). There is, however, no reason why you could not use two | |
7604 | items in the same list, one doing an address lookup and one doing a name | |
7605 | lookup, both using the same file. | |
7606 | ||
7607 | ||
7608 | .section Host list patterns for query-style lookups | |
7609 | If a pattern is of the form | |
7610 | .display | |
7611 | <<query-style-search-type>>;<<query>> | |
7612 | .endd | |
7613 | the query is obeyed, and if it succeeds, the host matches the item. The actual | |
7614 | data that is looked up is not used. The variables \$sender@_host@_address$\ and | |
7615 | \$sender@_host@_name$\ can be used in the query. For example: | |
7616 | .display asis | |
7617 | hosts_lookup = pgsql;\ | |
7618 | select ip from hostlist where ip='$sender_host_address' | |
7619 | .endd | |
d43194df PH |
7620 | The value of \$sender@_host@_address$\ for an IPv6 address contains colons. You |
7621 | can use the \sg\ expansion item to change this if you need to. If you want to | |
7622 | use masked IP addresses in database queries, you can use the \mask\ expansion | |
7623 | operator. | |
495ae4b0 | 7624 | |
4964e932 | 7625 | If the query contains a reference to \$sender@_host@_name$\, Exim automatically |
495ae4b0 PH |
7626 | looks up the host name if has not already done so. (See section |
7627 | ~~SECThoslispatnam for comments on finding host names.) | |
7628 | ||
4964e932 | 7629 | Historical note: prior to release 4.30, Exim would always attempt to find a |
495ae4b0 | 7630 | host name before running the query, unless the search type was preceded by |
4964e932 | 7631 | \"net-"\. This is no longer the case. For backwards compatibility, \"net-"\ is |
495ae4b0 | 7632 | still recognized for query-style lookups, but its presence or absence has no |
d43194df PH |
7633 | effect. (Of course, for single-key lookups, \"net-"\ $it{is} important. |
7634 | See section ~~SECThoslispatsikey.) | |
495ae4b0 PH |
7635 | |
7636 | ||
7637 | .section Mixing wildcarded host names and addresses in host lists | |
7638 | .rset SECTmixwilhos "~~chapter.~~section" | |
7639 | .index host list||mixing names and addresses in | |
7640 | If you have name lookups or wildcarded host names and IP addresses in the same | |
7641 | host list, you should normally put the IP addresses first. For example, in an | |
7642 | ACL you could have: | |
7643 | .display asis | |
7644 | accept hosts = 10.9.8.7 : *.friend.example | |
7645 | .endd | |
7646 | The reason for this lies in the left-to-right way that Exim processes lists. | |
7647 | It can test IP addresses without doing any DNS lookups, but when it reaches an | |
7648 | item that requires a host name, it fails if it cannot find a host name to | |
7649 | compare with the pattern. If the above list is given in the opposite order, the | |
7650 | \accept\ statement fails for a host whose name cannot be found, even if its | |
7651 | IP address is 10.9.8.7. | |
7652 | ||
7653 | If you really do want to do the name check first, and still recognize the IP | |
7654 | address, you can rewrite the ACL like this: | |
7655 | .display asis | |
7656 | accept hosts = *.friend.example | |
7657 | accept hosts = 10.9.8.7 | |
7658 | .endd | |
7659 | If the first \accept\ fails, Exim goes on to try the second one. See chapter | |
7660 | ~~CHAPACL for details of ACLs. | |
7661 | ||
7662 | ||
7663 | ||
7664 | ||
7665 | .section Address lists | |
7666 | .index list||address list | |
7667 | .index address list||empty item | |
7668 | .index address list||patterns | |
7669 | .rset SECTaddresslist "~~chapter.~~section" | |
7670 | Address lists contain patterns that are matched against mail addresses. There | |
7671 | is one special case to be considered: the sender address of a bounce message is | |
7672 | always empty. You can test for this by providing an empty item in an address | |
7673 | list. For example, you can set up a router to process bounce messages by | |
7674 | using this option setting: | |
7675 | .display asis | |
7676 | senders = : | |
7677 | .endd | |
7678 | The presence of the colon creates an empty item. If you do not provide any | |
7679 | data, the list is empty and matches nothing. The empty sender can also be | |
d43194df PH |
7680 | detected by a regular expression that matches an empty string, |
7681 | .em | |
7682 | and by a query-style lookup that succeeds when \$sender@_address$\ is empty. | |
495ae4b0 | 7683 | |
d43194df PH |
7684 | The following kinds of address list pattern can match any address, including |
7685 | the empty address that is characteristic of bounce message senders: | |
7686 | .nem | |
495ae4b0 | 7687 | .numberpars $. |
d43194df PH |
7688 | .em |
7689 | As explained above, if a pattern item is empty, it matches the empty address | |
7690 | (and no others). | |
7691 | .nem | |
7692 | .nextp | |
495ae4b0 PH |
7693 | .index regular expressions||in address list |
7694 | .index address list||regular expression in | |
7695 | If (after expansion) a pattern starts with `@^', a regular expression match is | |
7696 | done against the complete address, with the pattern as the regular expression. | |
7697 | You must take care that backslash and dollar characters are not misinterpreted | |
7698 | as part of the string expansion. The simplest way to do this is to use \"@\N"\ | |
7699 | to mark that part of the string as non-expandable. For example: | |
7700 | .display asis | |
7701 | deny senders = \N^\d{8}.+@spamhaus.example$\N : ... | |
7702 | .endd | |
7703 | The \"@\N"\ sequences are removed by the expansion, so the item does start | |
7704 | with `@^' by the time it is being interpreted as an address pattern. | |
7705 | .nextp | |
d43194df PH |
7706 | .index address list||lookup for complete address |
7707 | Complete addresses can be looked up by using a pattern that starts with a | |
7708 | lookup type terminated by a semicolon, followed by the data for the lookup. For | |
7709 | example: | |
495ae4b0 | 7710 | .display asis |
d43194df PH |
7711 | deny senders = cdb;/etc/blocked.senders : \ |
7712 | mysql;select address from blocked where \ | |
7713 | address='${quote_mysql:$sender_address}' | |
495ae4b0 | 7714 | .endd |
d43194df PH |
7715 | .em |
7716 | Both query-style and single-key lookup types can be used. For a single-key | |
7717 | lookup type, Exim uses the complete address as the key. However, empty keys are | |
7718 | not supported for single-key lookups, so a match against the empty address | |
7719 | always fails. This restriction does not apply to query-style lookups. | |
7720 | ||
7721 | .nem | |
7722 | Partial matching for single-key lookups (section ~~SECTpartiallookup) cannot be | |
7723 | used, and is ignored if specified, with an entry being written to the panic | |
7724 | log. | |
7725 | .index @*@@ with single-key lookup | |
7726 | However, you can configure lookup defaults, as described in section | |
7727 | ~~SECTdefaultvaluelookups, but this is useful only for the `$*$@@' type of | |
7728 | default. For example, with this lookup: | |
495ae4b0 | 7729 | .display asis |
d43194df | 7730 | accept senders = lsearch*@;/some/file |
495ae4b0 | 7731 | .endd |
d43194df | 7732 | the file could contains lines like this: |
495ae4b0 | 7733 | .display asis |
d43194df PH |
7734 | user1@domain1.example |
7735 | *@domain2.example | |
495ae4b0 | 7736 | .endd |
d43194df PH |
7737 | and for the sender address \*nimrod@@jaeger.example*\, the sequence of keys |
7738 | that are tried is: | |
7739 | .display asis | |
7740 | nimrod@jaeger.example | |
7741 | *@jaeger.example | |
7742 | * | |
7743 | .endd | |
7744 | \**Warning 1**\: Do not include a line keyed by `$*$' in the file, because that | |
7745 | would mean that every address matches, thus rendering the test useless. | |
7746 | ||
7747 | \**Warning 2**\: Do not confuse these two kinds of item: | |
7748 | .display asis | |
7749 | deny recipients = dbm*@;/some/file | |
7750 | deny recipients = *@dbm;/some/file | |
7751 | .endd | |
7752 | The first does a whole address lookup, with defaulting, as just described, | |
7753 | because it starts with a lookup type. The second matches the local part and | |
7754 | domain independently, as described in a bullet point below. | |
7755 | .endp | |
7756 | ||
7757 | ||
7758 | .em | |
7759 | The following kinds of address list pattern can match only non-empty addresses. | |
7760 | If the subject address is empty, a match against any of these pattern types | |
7761 | always fails. | |
7762 | .nem | |
7763 | ||
7764 | .numberpars $. | |
7765 | .index @@@@ with single-key lookup | |
7766 | .index address list||@@@@ lookup type | |
7767 | .index address list||split local part and domain | |
7768 | If a pattern starts with `@@@@' followed by a single-key lookup item | |
7769 | (for example, \"@@@@lsearch;/some/file"\), the address that is being checked is | |
7770 | split into a local part and a domain. The domain is looked up in the file. If | |
7771 | it is not found, there is no match. If it is found, the data that is looked up | |
7772 | from the file is treated as a colon-separated list of local part patterns, each | |
7773 | of which is matched against the subject local part in turn. | |
7774 | ||
7775 | .index asterisk||in address list | |
7776 | The lookup may be a partial one, and/or one involving a search for a default | |
7777 | keyed by `$*$' (see section ~~SECTdefaultvaluelookups). The local part patterns | |
7778 | that are looked up can be regular expressions or begin with `$*$', or even be | |
7779 | further lookups. They may also be independently negated. For example, with | |
7780 | .display asis | |
7781 | deny senders = @@dbm;/etc/reject-by-domain | |
7782 | .endd | |
7783 | the data from which the DBM file is built could contain lines like | |
7784 | .display asis | |
7785 | baddomain.com: !postmaster : * | |
7786 | .endd | |
7787 | to reject all senders except \postmaster\ from that domain. | |
7788 | .index local part||starting with ! | |
7789 | If a local part that actually begins with an exclamation mark is required, it | |
7790 | has to be specified using a regular expression. In \%lsearch%\ files, an entry | |
7791 | may be split over several lines by indenting the second and subsequent lines, | |
7792 | but the separating colon must still be included at line breaks. White space | |
7793 | surrounding the colons is ignored. For example: | |
7794 | .display asis | |
7795 | aol.com: spammer1 : spammer2 : ^[0-9]+$ : | |
7796 | spammer3 : spammer4 | |
7797 | .endd | |
7798 | As in all colon-separated lists in Exim, a colon can be included in an item by | |
7799 | doubling. | |
495ae4b0 PH |
7800 | |
7801 | If the last item in the list starts with a right angle-bracket, the remainder | |
7802 | of the item is taken as a new key to look up in order to obtain a continuation | |
7803 | list of local parts. The new key can be any sequence of characters. Thus one | |
7804 | might have entries like | |
7805 | .display asis | |
7806 | aol.com: spammer1 : spammer 2 : >* | |
7807 | xyz.com: spammer3 : >* | |
7808 | *: ^\d{8}$ | |
7809 | .endd | |
7810 | in a file that was searched with \@@@@dbm$*$\, to specify a match for 8-digit | |
7811 | local parts for all domains, in addition to the specific local parts listed for | |
7812 | each domain. Of course, using this feature costs another lookup each time a | |
7813 | chain is followed, but the effort needed to maintain the data is reduced. | |
7814 | .index loop||in lookups | |
7815 | It is possible to construct loops using this facility, and in order to catch | |
7816 | them, the chains may be no more than fifty items long. | |
7817 | .nextp | |
4964e932 PH |
7818 | The @@@@<<lookup>> style of item can also be used with a query-style |
7819 | lookup, but in this case, the chaining facility is not available. The lookup | |
495ae4b0 PH |
7820 | can only return a single list of local parts. |
7821 | .nextp | |
d43194df PH |
7822 | If a pattern contains an @@ character, but is not a regular expression and does |
7823 | not begin with a lookup type as described above, the local part of the subject | |
7824 | address is compared with the local part of the pattern, which may start with an | |
7825 | asterisk. If the local parts match, the domain is checked in exactly the same | |
7826 | way as for a pattern in a domain list. For example, the domain can be | |
7827 | wildcarded, refer to a named list, or be a lookup: | |
495ae4b0 PH |
7828 | .display asis |
7829 | deny senders = *@*.spamming.site:\ | |
7830 | *@+hostile_domains:\ | |
7831 | bozo@partial-lsearch;/list/of/dodgy/sites:\ | |
7832 | .newline | |
7833 | *@dbm;/bad/domains.db | |
7834 | .endd | |
7835 | .index local part||starting with ! | |
7836 | .index address list||local part starting with ! | |
7837 | If a local part that begins with an exclamation mark is required, it has to be | |
7838 | specified using a regular expression, because otherwise the exclamation mark is | |
7839 | treated as a sign of negation. | |
7840 | .nextp | |
d43194df PH |
7841 | If a pattern is not one of the above syntax forms, that is, if a |
7842 | .em | |
7843 | non-empty | |
7844 | .nem | |
7845 | pattern that is not a regular expression or a lookup does not contain an @@ | |
7846 | character, it is matched against the domain part of the subject address. The | |
7847 | only two formats that are recognized this way are a literal domain, or a domain | |
7848 | pattern that starts with $*$. In both these cases, the effect is the same as if | |
7849 | \"*@@"\ preceded the pattern. | |
495ae4b0 PH |
7850 | .endp |
7851 | ||
7852 | \**Warning**\: there is an important difference between the address list items | |
7853 | in these two examples: | |
7854 | .display asis | |
7855 | senders = +my_list | |
7856 | senders = *@+my_list | |
7857 | .endd | |
7858 | In the first one, \"my@_list"\ is a named address list, whereas in the second | |
7859 | example it is a named domain list. | |
7860 | ||
7861 | ||
7862 | ||
7863 | .section Case of letters in address lists | |
7864 | .rset SECTcasletadd "~~chapter.~~section" | |
7865 | .index case of local parts | |
7866 | .index address list||case forcing | |
7867 | .index case forcing in address lists | |
7868 | Domains in email addresses are always handled caselessly, but for local parts | |
7869 | case may be significant on some systems (see \caseful@_local@_part\ for how | |
7870 | Exim deals with this when routing addresses). However, RFC 2505 ($it{Anti-Spam | |
7871 | Recommendations for SMTP MTAs}) suggests that matching of addresses to blocking | |
7872 | lists should be done in a case-independent manner. Since most address lists in | |
7873 | Exim are used for this kind of control, Exim attempts to do this by default. | |
7874 | ||
7875 | The domain portion of an address is always lowercased before matching it to an | |
7876 | address list. The local part is lowercased by default, and any string | |
7877 | comparisons that take place are done caselessly. This means that the data in | |
7878 | the address list itself, in files included as plain file names, and in any file | |
7879 | that is looked up using the `@@@@' mechanism, can be in any case. However, the | |
7880 | keys in files that are looked up by a search type other than \%lsearch%\ (which | |
7881 | works caselessly) must be in lower case, because these lookups are not | |
7882 | case-independent. | |
7883 | ||
7884 | .index \"+caseful"\ | |
7885 | To allow for the possibility of caseful address list matching, if an item in | |
7886 | an address list is the string `+caseful', the original case of the local | |
7887 | part is restored for any comparisons that follow, and string comparisons are no | |
7888 | longer case-independent. This does not affect the domain, which remains in | |
7889 | lower case. However, although independent matches on the domain alone are still | |
7890 | performed caselessly, regular expressions that match against an entire address | |
7891 | become case-sensitive after `+caseful' has been seen. | |
7892 | ||
7893 | ||
7894 | .section Local part lists | |
7895 | .rset SECTlocparlis "~~chapter.~~section" | |
7896 | .index list||local part list | |
7897 | .index local part||list | |
7898 | Case-sensitivity in local part lists is handled in the same way as for address | |
7899 | lists, as just described. The `+caseful' item can be used if required. In a | |
7900 | setting of the \local@_parts\ option in a router with \caseful@_local@_part\ | |
7901 | set false, the subject is lowercased and the matching is initially | |
7902 | case-insensitive. In this case, `+caseful' will restore case-sensitive matching | |
7903 | in the local part list, but not elsewhere in the router. If | |
7904 | \caseful@_local@_part\ is set true in a router, matching in the \local@_parts\ | |
7905 | option is case-sensitive from the start. | |
7906 | ||
7907 | If a local part list is indirected to a file (see section ~~SECTfilnamlis), | |
7908 | comments are handled in the same way as address lists -- they are recognized | |
7909 | only if the @# is preceded by white space or the start of the line. | |
7910 | Otherwise, local part lists are matched in the same way as domain lists, except | |
7911 | that the special items that refer to the local host (\"@@"\, \"@@[]"\, | |
7912 | \"@@mx@_any"\, \"@@mx@_primary"\, and \"@@mx@_secondary"\) are not recognized. | |
7913 | Refer to section ~~SECTdomainlist for details of the other available item | |
7914 | types. | |
7915 | ||
7916 | ||
7917 | ||
7918 | . | |
7919 | . | |
7920 | . | |
7921 | . | |
7922 | . ============================================================================ | |
7923 | .chapter String expansions | |
7924 | .set runningfoot "string expansions" | |
7925 | .rset CHAPexpand ~~chapter | |
7926 | .index expansion||of strings | |
7927 | Many strings in Exim's run time configuration are expanded before use. Some of | |
7928 | them are expanded every time they are used; others are expanded only once. | |
7929 | ||
7930 | When a string is being expanded it is copied verbatim from left to right except | |
7931 | when a dollar or backslash character is encountered. A dollar specifies the | |
7932 | start of a portion of the string which is interpreted and replaced as described | |
4964e932 | 7933 | below in section ~~SECTexpansionitems onwards. Backslash is used as an escape |
495ae4b0 PH |
7934 | character, as described in the following section. |
7935 | ||
7936 | ||
7937 | .section Literal text in expanded strings | |
7938 | .rset SECTlittext "~~chapter.~~section" | |
7939 | .index expansion||including literal text | |
7940 | An uninterpreted dollar can be included in an expanded string by putting a | |
7941 | backslash in front of it. A backslash can be used to prevent any special | |
7942 | character being treated specially in an expansion, including itself. If the | |
7943 | string appears in quotes in the configuration file, two backslashes are | |
7944 | required because the quotes themselves cause interpretation of backslashes when | |
7945 | the string is read in (see section ~~SECTstrings). | |
7946 | ||
7947 | .index expansion||non-expandable substrings | |
7948 | A portion of the string can specified as non-expandable by placing it between | |
7949 | two occurrences of \"@\N"\. This is particularly useful for protecting regular | |
7950 | expressions, which often contain backslashes and dollar signs. For example: | |
7951 | .display asis | |
7952 | deny senders = \N^\d{8}[a-z]@some\.site\.example$\N | |
7953 | .endd | |
7954 | On encountering the first \"@\N"\, the expander copies subsequent characters | |
7955 | without interpretation until it reaches the next \"@\N"\ or the end of the | |
7956 | string. | |
7957 | ||
7958 | ||
7959 | .section Character escape sequences in expanded strings | |
7960 | .index expansion||escape sequences | |
7961 | A backslash followed by one of the letters `n', `r', or `t' in an expanded | |
7962 | string is recognized as an escape sequence for the character newline, carriage | |
7963 | return, or tab, respectively. A backslash followed by up to three octal digits | |
7964 | is recognized as an octal encoding for a single character, and a backslash | |
7965 | followed by `x' and up to two hexadecimal digits is a hexadecimal encoding. | |
7966 | ||
7967 | These escape sequences are also recognized in quoted strings when they are read | |
7968 | in. Their interpretation in expansions as well is useful for unquoted strings, | |
7969 | and for other cases such as looked-up strings that are then expanded. | |
7970 | ||
7971 | .section Testing string expansions | |
7972 | .index expansion||testing | |
7973 | .index testing||string expansion | |
7974 | .index \-be-\ option | |
7975 | Many expansions can be tested by calling Exim with the \-be-\ option. This takes | |
7976 | the command arguments, or lines from the standard input if there are no | |
7977 | arguments, runs them through the string expansion code, and writes the results | |
7978 | to the standard output. Variables based on configuration values are set up, but | |
7979 | since no message is being processed, variables such as \$local@_part$\ have no | |
7980 | value. Nevertheless the \-be-\ option can be useful for checking out file and | |
7981 | database lookups, and the use of expansion operators such as \sg\, \substr\ and | |
7982 | \nhash\. | |
7983 | ||
7984 | Exim gives up its root privilege when it is called with the \-be-\ option, and | |
7985 | instead runs under the uid and gid it was called with, to prevent users from | |
7986 | using \-be-\ for reading files to which they do not have access. | |
7987 | ||
7988 | ||
d43194df PH |
7989 | .em |
7990 | .section Forced expansion failure | |
7991 | .rset SECTforexpfai "~~chapter.~~section" | |
7992 | .index expansion||forced failure | |
7993 | A number of expansions that are described in the following section have | |
7994 | alternative `true' and `false' substrings, enclosed in curly brackets. Which | |
7995 | one is used depends on some condition that is evaluated as part of the | |
7996 | expansion. If, instead of a `false' substring, the word `fail' is used (not in | |
7997 | curly brackets), the entire string expansion fails in a way that can be | |
7998 | detected by the code that requested the expansion. This is called `forced | |
7999 | expansion failure', and its consequences depend on the circumstances. In some | |
8000 | cases it is no different from any other expansion failure, but in others a | |
8001 | different action may be taken. Such variations are mentioned in the | |
8002 | documentation of the option that is being expanded. | |
8003 | .nem | |
8004 | ||
8005 | ||
495ae4b0 PH |
8006 | .section Expansion items |
8007 | .rset SECTexpansionitems "~~chapter.~~section" | |
8008 | The following items are recognized in expanded strings. White space may be used | |
8009 | between sub-items that are keywords or substrings enclosed in braces inside an | |
8010 | outer set of braces, to improve readability. \**Warning**\: Within braces, | |
8011 | white space is significant. | |
8012 | ||
8013 | .startitems | |
8014 | ||
8015 | .item "@$<<variable name>>#$rm{or}#@$@{<<variable name>>@}" | |
8016 | .index expansion||variables | |
8017 | Substitute the contents of the named variable, for example | |
8018 | .display asis | |
8019 | $local_part | |
8020 | ${domain} | |
8021 | .endd | |
8022 | The second form can be used to separate the name from subsequent alphanumeric | |
8023 | characters. This form (using curly brackets) is available only for variables; | |
8024 | it does $it{not} apply to message headers. The names of the variables are given | |
8025 | in section ~~SECTexpvar below. If the name of a non-existent variable is given, | |
8026 | the expansion fails. | |
8027 | ||
8028 | .item "@$@{<<op>>:<<string>>@}" | |
8029 | .index expansion||operators | |
8030 | The string is first itself expanded, and then the operation specified by <<op>> | |
8031 | is applied to it. For example, | |
8032 | .display asis | |
8033 | ${lc:$local_part} | |
8034 | .endd | |
8035 | The string starts with the first character after the colon, which may be | |
8036 | leading white space. A list of operators is given in section ~~SECTexpop below. | |
8037 | The operator notation is used for simple expansion items that have just one | |
8038 | argument, because it reduces the number of braces and therefore makes the | |
8039 | string easier to understand. | |
8040 | ||
8041 | .item "@$@{extract@{<<key>>@}@{<<string1>>@}@{<<string2>>@}@{<<string3>>@}@}" | |
8042 | .index expansion||extracting substrings by key | |
4964e932 PH |
8043 | The key and <<string1>> are first expanded separately. |
8044 | Leading and trailing whitespace is removed from the key (but not from any of | |
495ae4b0 PH |
8045 | the strings). |
8046 | The key must not consist entirely of digits. The expanded <<string1>> must be | |
8047 | of the form: | |
8048 | .display | |
8049 | <<key1>> = <<value1>> <<key2>> = <<value2>> ... | |
8050 | .endd | |
8051 | where the equals signs and spaces (but not both) are optional. If any of the | |
8052 | values contain white space, they must be enclosed in double quotes, and any | |
8053 | values that are enclosed in double quotes are subject to escape processing as | |
8054 | described in section ~~SECTstrings. The expanded <<string1>> is searched for | |
8055 | the value that corresponds to the key. The search is case-insensitive. If the | |
8056 | key is found, <<string2>> is expanded, and replaces the whole item; otherwise | |
8057 | <<string3>> is used. During the expansion of <<string2>> the variable \$value$\ | |
8058 | contains the value that has been extracted. Afterwards, it is restored to any | |
8059 | previous value it might have had. | |
8060 | ||
8061 | If @{<<string3>>@} is omitted, the item is replaced by an empty string if the | |
8062 | key is not found. If @{<<string2>>@} is also omitted, the value that was | |
8063 | extracted is used. Thus, for example, these two expansions are identical, and | |
8064 | yield `2001': | |
8065 | .display | |
8066 | @$@{extract@{gid@}{uid=1984 gid=2001@}@} | |
8067 | @$@{extract@{gid@}{uid=1984 gid=2001@}@{@$value@}@} | |
8068 | .endd | |
8069 | Instead of @{<<string3>>@} the word `fail' (not in curly brackets) can appear, | |
8070 | for example: | |
8071 | .display | |
8072 | @$@{extract@{Z@}@{A=... B=...@}@{@$value@} fail @} | |
8073 | .endd | |
d43194df PH |
8074 | This forces an expansion failure (see section ~~SECTforexpfai); @{<<string2>>@} |
8075 | must be present for `fail' to be recognized. | |
495ae4b0 PH |
8076 | |
8077 | ||
8078 | .item "@$@{extract@{<<number>>@}@{<<separators>>@}@{<<string1>>@}@{<<string2>>@}@{<<string3>>@}@}" | |
8079 | .index expansion||extracting substrings by number | |
8080 | The <<number>> argument must consist entirely of decimal digits, | |
4964e932 | 8081 | apart from leading and trailing whitespace, which is ignored. |
495ae4b0 PH |
8082 | This is what distinguishes this form of \extract\ from the previous kind. It |
8083 | behaves in the same way, except that, instead of extracting a named field, it | |
8084 | extracts from <<string1>> the field whose number is given as the first | |
8085 | argument. You can use \$value$\ in <<string2>> or \"fail"\ instead of | |
8086 | <<string3>> as before. | |
8087 | ||
8088 | The fields in the string are separated by any one of the characters in the | |
8089 | separator string. These may include space or tab characters. | |
8090 | The first field is numbered one. If the number is negative, the fields are | |
8091 | counted from the end of the string, with the rightmost one numbered -1. If the | |
8092 | number given is zero, the entire string is returned. If the modulus of the | |
8093 | number is greater than the number of fields in the string, the result is the | |
8094 | expansion of <<string3>>, or the empty string if <<string3>> is not provided. | |
8095 | For example: | |
8096 | .display asis | |
8097 | ${extract{2}{:}{x:42:99:& Mailer::/bin/bash}} | |
8098 | .endd | |
8099 | yields `42', and | |
8100 | .display asis | |
8101 | ${extract{-4}{:}{x:42:99:& Mailer::/bin/bash}} | |
8102 | .endd | |
8103 | yields `99'. Two successive separators mean that the field between them is | |
8104 | empty (for example, the fifth field above). | |
8105 | ||
8106 | ||
8107 | .item "@$@{hash@{<<string1>>@}@{<<string2>>@}@{<<string3>>@}@}" | |
8108 | .index hash function||textual | |
8109 | .index expansion||textual hash | |
4964e932 PH |
8110 | This is a textual hashing function, and was the first to be implemented in |
8111 | early versions of Exim. In current releases, there are other hashing functions | |
495ae4b0 PH |
8112 | (numeric, MD5, and SHA-1), which are described below. |
8113 | ||
4964e932 PH |
8114 | The first two strings, after expansion, must be numbers. Call them <<m>> and |
8115 | <<n>>. If you are using fixed values for these numbers, that is, if <<string1>> | |
495ae4b0 PH |
8116 | and <<string2>> do not change when they are expanded, you can use the |
8117 | simpler operator notation that avoids some of the braces: | |
8118 | .display | |
8119 | @$@{hash@_<<n>>@_<<m>>:<<string>>@} | |
8120 | .endd | |
8121 | The second number is optional (in both notations). | |
8122 | ||
4964e932 | 8123 | If <<n>> is greater than or equal to the length of the string, the expansion |
495ae4b0 PH |
8124 | item returns the string. Otherwise it computes a new string of length <<n>> by |
8125 | applying a hashing function to the string. The new string consists of | |
8126 | characters taken from the first <<m>> characters of the string | |
8127 | .display asis | |
8128 | abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQWRSTUVWXYZ0123456789 | |
8129 | .endd | |
8130 | If <<m>> is not present the value 26 is used, so that only lower case | |
8131 | letters appear. For example: | |
8132 | .display | |
4964e932 PH |
8133 | @$@{hash@{3@}@{monty@}@} $rm{yields} \"jmg"\ |
8134 | @$@{hash@{5@}@{monty@}@} $rm{yields} \"monty"\ | |
8135 | @$@{hash@{4@}@{62@}@{monty python@}@} $rm{yields} \"fbWx"\ | |
495ae4b0 PH |
8136 | .endd |
8137 | ||
8138 | ||
8139 | .item "@$header@_<<header name>>:#$rm{or}#@$h@_<<header name>>:" | |
8140 | .item "@$bheader@_<<header name>>:#$rm{or}#@$bh@_<<header name>>:" | |
8141 | .item "@$rheader@_<<header name>>:#$rm{or}#@$rh@_<<header name>>:" | |
8142 | .index expansion||header insertion | |
8143 | .index \$header@_$\ | |
8144 | .index \$bheader@_$\ | |
8145 | .index \$rheader@_$\ | |
8146 | .index header lines||in expansion strings | |
8147 | .index header lines||character sets | |
8148 | .index header lines||decoding | |
8149 | Substitute the contents of the named message header line, for example | |
8150 | .display asis | |
8151 | $header_reply-to: | |
8152 | .endd | |
8153 | The newline that terminates a header line is not included in the expansion, but | |
8154 | internal newlines (caused by splitting the header line over several physical | |
4964e932 | 8155 | lines) may be present. |
495ae4b0 | 8156 | |
4964e932 PH |
8157 | The difference between \rheader\, \bheader\, and \header\ is in the way the |
8158 | data in the header line is interpreted. | |
495ae4b0 | 8159 | .numberpars $. |
d43194df | 8160 | .index whitespace||in header lines |
495ae4b0 PH |
8161 | \rheader\ gives the original `raw' content of the header line, with no |
8162 | processing at all, and without the removal of leading and trailing whitespace. | |
8163 | .nextp | |
8164 | .index base64 encoding||in header lines | |
8165 | \bheader\ removes leading and trailing whitespace, and then decodes base64 or | |
8166 | quoted-printable MIME `words' within the header text, but does no character | |
8167 | set translation. If decoding of what looks superficially like a MIME `word' | |
4964e932 | 8168 | fails, the raw string is returned. |
495ae4b0 PH |
8169 | .index binary zero||in header line |
8170 | If decoding produces a binary zero character, it is replaced by a question mark | |
8171 | -- this is what Exim does for binary zeros that are actually received in header | |
8172 | lines. | |
8173 | .nextp | |
8174 | \header\ tries to translate the string as decoded by \bheader\ to a standard | |
8175 | character set. This is an attempt to produce the same string as would be | |
8176 | displayed on a user's MUA. If translation fails, the \bheader\ string is | |
8177 | returned. Translation is attempted only on operating systems that support the | |
8178 | \*iconv()*\ function. This is indicated by the compile-time macro | |
8179 | \\HAVE@_ICONV\\ in a system Makefile or in \(Local/Makefile)\. | |
8180 | .endp | |
8181 | ||
8182 | In a filter file, the target character set for \header\ can be specified by a | |
8183 | command of the following form: | |
8184 | .display asis | |
8185 | headers charset "UTF-8" | |
8186 | .endd | |
8187 | This command affects all references to \$h@_$\ (or \$header@_$\) expansions in | |
8188 | subsequently obeyed filter commands. In the absence of this command, the target | |
8189 | character set in a filter is taken from the setting of the \headers@_charset\ | |
8190 | option in the runtime configuration. The value of this option defaults to the | |
8191 | value of \\HEADERS@_CHARSET\\ in \(Local/Makefile)\. The ultimate default is | |
8192 | ISO-8859-1. | |
8193 | ||
8194 | Header names follow the syntax of RFC 2822, which states that they may contain | |
8195 | any printing characters except space and colon. Consequently, curly brackets | |
8196 | $it{do not} terminate header names, and should not be used to enclose them as | |
8197 | if they were variables. Attempting to do so causes a syntax error. | |
8198 | ||
8199 | Only header lines that are common to all copies of a message are visible to | |
8200 | this mechanism. These are the original header lines that are received with the | |
4964e932 | 8201 | message, and any that are added by |
495ae4b0 PH |
8202 | an ACL \warn\ statement or by |
8203 | a system filter. Header lines that are added to a particular copy of a message | |
8204 | by a router or transport are not accessible. | |
8205 | ||
8206 | For incoming SMTP messages, no header lines are visible in ACLs that are obeyed | |
8207 | before the \\DATA\\ ACL, because the header structure is not set up until the | |
8208 | message is received. Header lines that are added by \warn\ statements in a | |
8209 | \\RCPT\\ ACL (for example) are saved until the message's incoming header lines | |
8210 | are available, at which point they are added. When a \\DATA\\ ACL is running, | |
8211 | however, header lines added by earlier ACLs are visible. | |
8212 | ||
8213 | Upper case and lower case letters are synonymous in header names. If the | |
8214 | following character is white space, the terminating colon may be omitted, but | |
8215 | this is not recommended, because you may then forget it when it is needed. When | |
8216 | white space terminates the header name, it is included in the expanded string. | |
8217 | If the message does not contain the given header, the expansion item is | |
8218 | replaced by an empty string. (See the \def\ condition in section ~~SECTexpcond | |
4964e932 | 8219 | for a means of testing for the existence of a header.) |
495ae4b0 PH |
8220 | |
8221 | If there is more than one header with the same name, they are all concatenated | |
8222 | to form the substitution string, up to a maximum length of 64K. A newline | |
8223 | character is inserted between each line. | |
8224 | For the \header\ expansion, for those headers that contain lists of addresses, | |
8225 | a comma is also inserted at the junctions between lines. This does not happen | |
8226 | for the \rheader\ expansion. | |
8227 | ||
8228 | ||
8229 | ||
8230 | .item "@$@{hmac@{<<hashname>>@}@{<<secret>>@}@{<<string>>@}@}" | |
8231 | .index expansion||hmac hashing | |
8232 | This function uses cryptographic hashing (either MD5 or SHA-1) to convert a | |
8233 | shared secret and some text into a message authentication code, as specified in | |
4964e932 | 8234 | RFC 2104. |
495ae4b0 | 8235 | This differs from \"@$@{md5:secret@_text...@}"\ or |
4964e932 PH |
8236 | \"@$@{sha1:secret@_text...@}"\ in that the hmac step adds a signature to the |
8237 | cryptographic hash, allowing for authentication that is not possible with MD5 | |
495ae4b0 PH |
8238 | or SHA-1 alone. |
8239 | The hash name must expand to either \"md5"\ or \"sha1"\ at present. For | |
8240 | example: | |
8241 | .display asis | |
8242 | ${hmac{md5}{somesecret}{$primary_hostname $tod_log}} | |
8243 | .endd | |
8244 | For the hostname \*mail.example.com*\ and time 2002-10-17 11:30:59, this | |
8245 | produces: | |
8246 | .display asis | |
8247 | dd97e3ba5d1a61b5006108f8c8252953 | |
8248 | .endd | |
8249 | As an example of how this might be used, you might put in the main part of | |
8250 | an Exim configuration: | |
8251 | .display asis | |
8252 | SPAMSCAN_SECRET=cohgheeLei2thahw | |
8253 | .endd | |
8254 | In a router or a transport you could then have: | |
8255 | .display asis | |
8256 | headers_add = \ | |
8257 | X-Spam-Scanned: ${primary_hostname} ${message_id} \ | |
8258 | ${hmac{md5}{SPAMSCAN_SECRET}\ | |
8259 | {${primary_hostname},${message_id},$h_message-id:}} | |
8260 | .endd | |
8261 | Then given a message, you can check where it was scanned by looking at the | |
4964e932 PH |
8262 | ::X-Spam-Scanned:: header line. If you know the secret, you can check that this |
8263 | header line is authentic by recomputing the authentication code from the host | |
495ae4b0 PH |
8264 | name, message ID and the ::Message-id:: header line. This can be done using |
8265 | Exim's \-be-\ option, or by other means, for example by using the | |
8266 | \*hmac@_md5@_hex()*\ function in Perl. | |
8267 | ||
8268 | ||
495ae4b0 PH |
8269 | .item "@${if <<condition>> @{<<string1>>@}@{<<string2>>@}@}" |
8270 | .index expansion||conditional | |
8271 | If <<condition>> is true, <<string1>> is expanded and replaces the whole item; | |
d43194df PH |
8272 | otherwise <<string2>> is used. The available conditions are described in |
8273 | section ~~SECTexpcond below. For example: | |
495ae4b0 PH |
8274 | .display asis |
8275 | ${if eq {$local_part}{postmaster} {yes}{no} } | |
8276 | .endd | |
8277 | The second string need not be present; if it is not and the condition is not | |
8278 | true, the item is replaced with nothing. Alternatively, the word `fail' may be | |
8279 | present instead of the second string (without any curly brackets). In this | |
d43194df PH |
8280 | case, the expansion is forced to fail if the condition is not true (see section |
8281 | ~~SECTforexpfai). | |
8282 | ||
8283 | .em | |
8284 | If both strings are omitted, the result is the string \"true"\ if the condition | |
8285 | is true, and the empty string if the condition is false. This makes it less | |
8286 | cumbersome to write custom ACL and router conditions. For example, instead of | |
8287 | .display asis | |
8288 | condition = ${if >{$acl_m4}{3}{true}{false}} | |
8289 | .endd | |
8290 | you can use | |
8291 | .display asis | |
8292 | condition = ${if >{$acl_m4}{3}} | |
8293 | .endd | |
8294 | .nem | |
495ae4b0 PH |
8295 | |
8296 | ||
8297 | .item "@$@{length@{<<string1>>@}@{<<string2>>@}@}" | |
8298 | .index expansion||string truncation | |
4964e932 | 8299 | The \length\ item is used to extract the initial portion of a string. Both |
495ae4b0 PH |
8300 | strings are expanded, and the first one must yield a number, <<n>>, say. If you |
8301 | are using a fixed value for the number, that is, if <<string1>> does not change | |
8302 | when expanded, you can use the simpler operator notation that avoids some of | |
8303 | the braces: | |
8304 | .display | |
8305 | @$@{length@_<<n>>:<<string>>@} | |
8306 | .endd | |
8307 | The result of this item is either the first <<n>> characters or the whole | |
4964e932 | 8308 | of <<string2>>, whichever is the shorter. Do not confuse \length\ with |
495ae4b0 PH |
8309 | \strlen\, which gives the length of a string. |
8310 | ||
8311 | ||
8312 | .item "@${lookup@{<<key>>@} <<search type>> @{<<file>>@} @{<<string1>>@} @{<<string2>>@}@}" | |
8313 | .item "@${lookup <<search type>> @{<<query>>@} @{<<string1>>@} @{<<string2>>@}@}" | |
8314 | .index expansion||lookup in | |
8315 | .index file||lookup | |
8316 | .index lookup||in expanded string | |
8317 | These items specify data lookups in files and databases, as discussed in | |
8318 | chapter ~~CHAPfdlookup. The first form is used for single-key lookups, and the | |
8319 | second is used for query-style lookups. The <<key>>, <<file>>, and <<query>> | |
8320 | strings are expanded before use. | |
8321 | ||
8322 | If there is any white space in a lookup item which is part of a filter command, | |
8323 | a retry or rewrite rule, a routing rule for the \%manualroute%\ router, or any | |
8324 | other place where white space is significant, the lookup item must be enclosed | |
8325 | in double quotes. The use of data lookups in users' filter files may be locked | |
8326 | out by the system administrator. | |
8327 | ||
8328 | .index \$value$\ | |
8329 | If the lookup succeeds, <<string1>> is expanded and replaces the entire item. | |
8330 | During its expansion, the variable \$value$\ contains the data returned by the | |
8331 | lookup. Afterwards it reverts to the value it had previously (at the outer | |
8332 | level it is empty). If the lookup fails, <<string2>> is expanded and replaces | |
d43194df PH |
8333 | the entire item. If @{<<string2>>@} is omitted, the replacement is the empty |
8334 | string on failure. If <<string2>> is provided, it can itself be a nested | |
8335 | lookup, thus providing a mechanism for looking up a default value when the | |
8336 | original lookup fails. | |
495ae4b0 PH |
8337 | |
8338 | If a nested lookup is used as part of <<string1>>, \$value$\ contains the data | |
8339 | for the outer lookup while the parameters of the second lookup are expanded, | |
8340 | and also while <<string2>> of the second lookup is expanded, should the second | |
8341 | lookup fail. | |
8342 | ||
8343 | Instead of @{<<string2>>@} the word `fail' can appear, and in this case, if the | |
d43194df PH |
8344 | lookup fails, the entire expansion is forced to fail (see section |
8345 | ~~SECTforexpfai). If both @{<<string1>>@} and @{<<string2>>@} are omitted, the | |
8346 | result is the looked up value in the case of a successful lookup, and nothing | |
8347 | in the case of failure. | |
495ae4b0 PH |
8348 | |
8349 | For single-key lookups, the string `partial' is permitted to precede the | |
8350 | search type in order to do partial matching, and $*$ or $*$@@ may follow a | |
8351 | search type to request default lookups if the key does not match (see sections | |
8352 | ~~SECTdefaultvaluelookups and ~~SECTpartiallookup for details). | |
8353 | ||
8354 | .index numerical variables (\$1$\, \$2$\, etc)||in lookup expansion | |
8355 | If a partial search is used, the variables \$1$\ and \$2$\ contain the wild | |
8356 | and non-wild parts of the key during the expansion of the replacement text. | |
8357 | They return to their previous values at the end of the lookup item. | |
8358 | ||
8359 | This example looks up the postmaster alias in the conventional alias file: | |
8360 | .display asis | |
8361 | ${lookup {postmaster} lsearch {/etc/aliases} {$value}} | |
8362 | .endd | |
8363 | This example uses NIS+ to look up the full name of the user corresponding to | |
8364 | the local part of an address, forcing the expansion to fail if it is not found: | |
8365 | .display asis | |
8366 | ${lookup nisplus {[name=$local_part],passwd.org_dir:gcos} \ | |
8367 | {$value}fail} | |
8368 | .endd | |
8369 | ||
8370 | ||
8371 | .item "@$@{nhash@{<<string1>>@}@{<<string2>>@}@{<<string3>>@}@}" | |
8372 | .index expansion||numeric hash | |
8373 | .index hash function||numeric | |
8374 | The three strings are expanded; the first two must yield numbers. Call them | |
8375 | <<n>> and <<m>>. If you are using fixed values for these numbers, that is, if | |
8376 | <<string1>> and <<string2>> do not change when they are expanded, you can use | |
8377 | the simpler operator notation that avoids some of the braces: | |
8378 | .display | |
8379 | @$@{nhash@_<<n>>@_<<m>>:<<string>>@} | |
8380 | .endd | |
8381 | The second number is optional (in both notations). If there is only one number, | |
8382 | the result is a number in the range 0--<<n>>-1. Otherwise, the string is | |
8383 | processed by a div/mod hash function that returns two numbers, separated by a | |
8384 | slash, in the ranges 0 to <<n>>-1 and 0 to <<m>>-1, respectively. For example, | |
8385 | .display asis | |
8386 | ${nhash{8}{64}{supercalifragilisticexpialidocious}} | |
8387 | .endd | |
8388 | returns the string `6/33'. | |
8389 | ||
8390 | ||
8391 | ||
8392 | .item "@$@{perl@{<<subroutine>>@}@{<<arg>>@}@{<<arg>>@}...@}" | |
8393 | .index Perl||use in expanded string | |
8394 | .index expansion||calling Perl from | |
8395 | This item is available only if Exim has been built to include an embedded Perl | |
8396 | interpreter. The subroutine name and the arguments are first separately | |
8397 | expanded, and then the Perl subroutine is called with those arguments. No | |
4964e932 | 8398 | additional arguments need be given; the maximum number permitted, including the |
495ae4b0 PH |
8399 | name of the subroutine, is nine. |
8400 | ||
8401 | The return value of the subroutine is inserted into the expanded string, unless | |
8402 | the return value is \undef\. In that case, the expansion fails in the same way | |
4964e932 PH |
8403 | as an explicit `fail' on a lookup item. |
8404 | The return value is a scalar. Whatever you return is evaluated in a scalar | |
495ae4b0 PH |
8405 | context. For example, if you return the name of a Perl vector, the |
8406 | return value is the size of the vector, not its contents. | |
8407 | ||
8408 | If the subroutine exits by calling Perl's \die\ function, the expansion fails | |
8409 | with the error message that was passed to \die\. More details of the embedded | |
8410 | Perl facility are given in chapter ~~CHAPperl. | |
8411 | ||
8412 | The \%redirect%\ router has an option called \forbid@_filter@_perl\ which locks | |
8413 | out the use of this expansion item in filter files. | |
8414 | ||
8415 | ||
8416 | .item "@$@{readfile@{<<file name>>@}@{<<eol string>>@}@}" | |
8417 | .index expansion||inserting an entire file | |
8418 | .index file||inserting into expansion | |
8419 | The file name and end-of-line string are first expanded separately. The file is | |
8420 | then read, and its contents replace the entire item. All newline characters in | |
8421 | the file are replaced by the end-of-line string if it is present. Otherwise, | |
8422 | newlines are left in the string. | |
4964e932 PH |
8423 | String expansion is not applied to the contents of the file. If you want this, |
8424 | you must wrap the item in an \expand\ operator. If the file cannot be read, the | |
495ae4b0 PH |
8425 | string expansion fails. |
8426 | ||
8427 | The \%redirect%\ router has an option called \forbid@_filter@_readfile\ which | |
8428 | locks out the use of this expansion item in filter files. | |
8429 | ||
8430 | ||
8431 | ||
8432 | .item "@$@{readsocket@{<<name>>@}@{<<request>>@}@{<<timeout>>@}@{<<eol string>>@}@{<<fail string>>@}@}" | |
8433 | .index expansion||inserting from a socket | |
8434 | .index socket, use of in expansion | |
8435 | This item inserts data that is read from a Unix domain socket into the expanded | |
8436 | string. The minimal way of using it uses just two arguments: | |
8437 | .display asis | |
8438 | ${readsocket{/socket/name}{request string}} | |
8439 | .endd | |
8440 | Exim connects to the socket, writes the request string (unless it is an | |
8441 | empty string) and reads from the socket until an end-of-file is read. A timeout | |
8442 | of 5 seconds is applied. Additional, optional arguments extend what can be | |
8443 | done. Firstly, you can vary the timeout. For example: | |
8444 | .display asis | |
8445 | ${readsocket{/socket/name}{request-string}{3s}} | |
8446 | .endd | |
8447 | A fourth argument allows you to change any newlines that are in the data | |
8448 | that is read, in the same way as for \readfile\ (see above). This example turns | |
8449 | them into spaces: | |
8450 | .display asis | |
8451 | ${readsocket{/socket/name}{request-string}{3s}{ }} | |
8452 | .endd | |
8453 | As with all expansions, the substrings are expanded before the processing | |
8454 | happens. Errors in these sub-expansions cause the expansion to fail. In | |
8455 | addition, the following errors can occur: | |
8456 | .numberpars $. | |
8457 | Failure to create a socket file descriptor; | |
8458 | .nextp | |
8459 | Failure to connect the socket; | |
8460 | .nextp | |
8461 | Failure to write the request-string; | |
8462 | .nextp | |
8463 | Timeout on reading from the socket. | |
8464 | .endp | |
8465 | By default, any of these errors causes the expansion to fail. However, if | |
8466 | you supply a fifth substring, it is expanded and used when any of the above | |
8467 | errors occurs. For example: | |
8468 | .display asis | |
8469 | ${readsocket{/socket/name}{request-string}{3s}{\n}\ | |
8470 | {socket failure}} | |
8471 | .endd | |
8472 | You can test for the existence of the socket by wrapping this expansion in | |
8473 | \"@$@{if exists"\, but there is a race condition between that test and the | |
8474 | actual opening of the socket, so it is safer to use the fifth argument if you | |
8475 | want to be absolutely sure of avoiding an expansion error for a non-existent | |
8476 | socket. | |
8477 | ||
8478 | The \%redirect%\ router has an option called \forbid@_filter@_readsocket\ which | |
8479 | locks out the use of this expansion item in filter files. | |
8480 | ||
8481 | .item "@$rheader@_<<header name>>:#$rm{or}#@$rh@_<<header name>>:" | |
4964e932 | 8482 | This item inserts `raw' header lines. It is described with the \header\ |
495ae4b0 PH |
8483 | expansion item above. |
8484 | ||
8485 | ||
8486 | ||
8487 | .item "@$@{run@{<<command>> <<args>>@}@{<<string1>>@}@{<<string2>>@}@}" | |
8488 | .index expansion||running a command | |
8489 | The command and its arguments are first expanded separately, and then the | |
8490 | command is run in a separate process, but under the same uid and gid. As in | |
8491 | other command executions from Exim, a shell is not used by default. If you want | |
8492 | a shell, you must explicitly code it. | |
8493 | .index return code||from \run\ expansion | |
8494 | If the command succeeds (gives a zero return code) <<string1>> is expanded and | |
8495 | replaces the entire item; during this expansion, the standard output from the | |
8496 | command is in the variable \$value$\. If the command fails, <<string2>>, if | |
8497 | present, is expanded. If it is absent, the result is empty. Alternatively, | |
8498 | <<string2>> can be the word `fail' (not in braces) to force expansion failure | |
8499 | if the command does not succeed. If both strings are omitted, the result is the | |
8500 | standard output on success, and nothing on failure. | |
8501 | ||
8502 | The return code from the command is put in the variable \$runrc$\, and this | |
8503 | remains set afterwards, so in a filter file you can do things like this: | |
8504 | .display asis | |
8505 | if "${run{x y z}{}}$runrc" is 1 then ... | |
8506 | elif $runrc is 2 then ... | |
8507 | ... | |
8508 | endif | |
8509 | .endd | |
8510 | If execution of the command fails (for example, the command does not exist), | |
4964e932 | 8511 | the return code is 127 -- the same code that shells use for non-existent |
495ae4b0 PH |
8512 | commands. |
8513 | ||
4964e932 PH |
8514 | \**Warning**\: In a router or transport, you cannot assume the order in which |
8515 | option values are expanded, except for those pre-conditions whose order of | |
8516 | testing is documented. Therefore, you cannot reliably expect to set \$runrc$\ | |
495ae4b0 PH |
8517 | by the expansion of one option, and use it in another. |
8518 | ||
8519 | The \%redirect%\ router has an option called \forbid@_filter@_run\ which locks | |
8520 | out the use of this expansion item in filter files. | |
8521 | ||
8522 | ||
8523 | .item "@$@{sg@{<<subject>>@}@{<<regex>>@}@{<<replacement>>@}@}" | |
8524 | .index expansion||string substitution | |
8525 | This item works like Perl's substitution operator (s) with the global (/g) | |
8526 | option; hence its name. However, unlike the Perl equivalent, Exim does not | |
8527 | modify the subject string; instead it returns the modified string for insertion | |
8528 | into the overall expansion. The item takes three arguments: the subject string, | |
8529 | a regular expression, and a substitution string. For example | |
8530 | .display asis | |
8531 | ${sg{abcdefabcdef}{abc}{xyz}} | |
8532 | .endd | |
8533 | yields `xyzdefxyzdef'. Because all three arguments are expanded before use, if | |
8534 | any @$ or @\ characters are required in the regular expression or in the | |
8535 | substitution string, they have to be escaped. For example | |
8536 | .display asis | |
8537 | ${sg{abcdef}{^(...)(...)\$}{\$2\$1}} | |
8538 | .endd | |
8539 | yields `defabc', and | |
8540 | .display asis | |
8541 | ${sg{1=A 4=D 3=C}{\N(\d+)=\N}{K\$1=}} | |
8542 | .endd | |
8543 | yields `K1=A K4=D K3=C'. | |
4964e932 | 8544 | Note the use of \"@\N"\ to protect the contents of the regular expression from |
495ae4b0 PH |
8545 | string expansion. |
8546 | ||
8547 | ||
8548 | ||
8549 | .item "@$@{substr@{<<string1>>@}@{<<string2>>@}@{<<string3>>@}@}" | |
8550 | .index \substr\ | |
8551 | .index substring extraction | |
8552 | .index expansion||substring extraction | |
8553 | The three strings are expanded; the first two must yield numbers. Call them | |
8554 | <<n>> and <<m>>. If you are using fixed values for these numbers, that is, if | |
8555 | <<string1>> and <<string2>> do not change when they are expanded, you can use | |
8556 | the simpler operator notation that avoids some of the braces: | |
8557 | .display | |
8558 | @$@{substr@_<<n>>@_<<m>>:<<string>>@} | |
8559 | .endd | |
8560 | The second number is optional (in both notations). | |
d43194df PH |
8561 | .em |
8562 | If it is absent in the simpler format, the preceding underscore must also be | |
8563 | omitted. | |
8564 | .nem | |
495ae4b0 PH |
8565 | |
8566 | The \substr\ item can be used to extract more general substrings than \length\. | |
8567 | The first number, <<n>>, is a starting offset, and <<m>> is the length | |
8568 | required. For example | |
8569 | .display asis | |
8570 | ${substr{3}{2}{$local_part}} | |
8571 | .endd | |
8572 | If the starting offset is greater than the string length the result is the null | |
8573 | string; if the length plus starting offset is greater than the string length, | |
8574 | the result is the right-hand part of the string, starting from the given | |
8575 | offset. The first character in the string has offset zero. | |
8576 | ||
8577 | The \substr\ expansion item can take negative offset values to count | |
8578 | from the right-hand end of its operand. The last character is offset -1, the | |
8579 | second-last is offset -2, and so on. Thus, for example, | |
8580 | .display asis | |
8581 | ${substr{-5}{2}{1234567}} | |
8582 | .endd | |
8583 | yields `34'. If the absolute value of a negative offset is greater than the | |
8584 | length of the string, the substring starts at the beginning of the string, and | |
8585 | the length is reduced by the amount of overshoot. Thus, for example, | |
8586 | .display asis | |
8587 | ${substr{-5}{2}{12}} | |
8588 | .endd | |
8589 | yields an empty string, but | |
8590 | .display asis | |
8591 | ${substr{-3}{2}{12}} | |
8592 | .endd | |
8593 | yields `1'. | |
8594 | ||
d43194df PH |
8595 | When the second number is omitted from \substr\, the remainder of the string is |
8596 | taken if the offset is positive. If it is negative, all characters in the | |
495ae4b0 | 8597 | string preceding the offset point are taken. For example, an offset of -1 and |
d43194df PH |
8598 | no length, as in these semantically identical examples: |
8599 | .display asis | |
8600 | ${substr_-1:abcde} | |
8601 | ${substr{-1}{abcde}} | |
8602 | .endd | |
8603 | yields all but the last character of the string, that is, `abcd'. | |
495ae4b0 PH |
8604 | |
8605 | ||
8606 | ||
8607 | .item "@$@{tr@{<<subject>>@}@{<<characters>>@}@{<<replacements>>@}@}" | |
8608 | .index expansion||character translation | |
8609 | This item does single-character translation on its subject string. The second | |
8610 | argument is a list of characters to be translated in the subject string. Each | |
8611 | matching character is replaced by the corresponding character from the | |
8612 | replacement list. For example | |
8613 | .display asis | |
8614 | ${tr{abcdea}{ac}{13}} | |
8615 | .endd | |
8616 | yields `1b3de1'. If there are duplicates in the second character string, the | |
8617 | last occurrence is used. If the third string is shorter than the second, its | |
8618 | last character is replicated. However, if it is empty, no translation takes | |
8619 | place. | |
8620 | ||
8621 | .enditems | |
8622 | ||
8623 | ||
8624 | .section Expansion operators | |
8625 | .rset SECTexpop "~~chapter.~~section" | |
8626 | .index expansion||operators | |
8627 | For expansion items that perform transformations on a single argument string, | |
8628 | the `operator' notation is used because it is simpler and uses fewer braces. | |
8629 | The substring is first expanded before the operation is applied to it. The | |
8630 | following operations can be performed: | |
8631 | ||
8632 | .startitems | |
8633 | ||
8634 | .item "@$@{address:<<string>>@}" | |
8635 | .index expansion||RFC 2822 address handling | |
8636 | The string is interpreted as an RFC 2822 address, as it might appear in a | |
8637 | header line, and the effective address is extracted from it. If the string does | |
8638 | not parse successfully, the result is empty. | |
8639 | ||
8640 | ||
8641 | .item "@$@{base62:<<digits>>@}" | |
8642 | .index base62 | |
8643 | .index expansion||conversion to base 62 | |
8644 | The string must consist entirely of decimal digits. The number is converted to | |
8645 | base 62 (sic) and output as a string of six characters, including leading | |
8646 | zeros. \**Note**\: Just to be absolutely clear: this is \*not*\ base64 | |
8647 | encoding. | |
8648 | ||
495ae4b0 PH |
8649 | .item "@$@{base62d:<<base-62 digits>>@}" |
8650 | .index base62 | |
8651 | .index expansion||conversion to base 62 | |
8652 | The string must consist entirely of base-62 digits. The number is converted to | |
8653 | decimal and output as a string. | |
495ae4b0 PH |
8654 | |
8655 | ||
8656 | .item "@$@{domain:<<string>>@}" | |
8657 | .index domain||extraction | |
8658 | .index expansion||domain extraction | |
8659 | The string is interpreted as an RFC 2822 address and the domain is extracted | |
8660 | from it. If the string does not parse successfully, the result is empty. | |
8661 | ||
8662 | ||
8663 | .item "@$@{escape:<<string>>@}" | |
8664 | .index expansion||escaping non-printing characters | |
8665 | If the string contains any non-printing characters, they are converted to | |
8666 | escape sequences starting with a backslash. Whether characters with the most | |
8667 | significant bit set (so-called `8-bit characters') count as printing or not is | |
8668 | controlled by the \print@_topbitchars\ option. | |
8669 | ||
8670 | ||
495ae4b0 PH |
8671 | .item "@$@{eval:<<string>>@}" |
8672 | .item "@$@{eval10:<<string>>@}" | |
8673 | .index expansion||expression evaluation | |
8674 | .index expansion||arithmetic expression | |
8675 | These items supports simple arithmetic in expansion strings. The string (after | |
8676 | expansion) must be a conventional arithmetic expression, but it is limited to | |
8677 | the four basic operators (plus, minus, times, divide) and parentheses. All | |
8678 | operations are carried out using integer arithmetic. Plus and minus have a | |
8679 | lower priority than times and divide; operators with the same priority are | |
4964e932 | 8680 | evaluated from left to right. |
495ae4b0 PH |
8681 | |
8682 | For \eval\, numbers may be decimal, octal (starting with `0') or hexadecimal | |
8683 | (starting with `0x'). For \eval10\, all numbers are taken as decimal, even if | |
8684 | they start with a leading zero. This can be useful when processing numbers | |
8685 | extracted from dates or times, which often do have leading zeros. | |
495ae4b0 PH |
8686 | |
8687 | A number may be followed by `K' or `M' to multiply it by 1024 or 1024$*$1024, | |
8688 | respectively. Negative numbers are supported. The result of the computation is | |
8689 | a decimal representation of the answer (without `K' or `M'). For example: | |
8690 | .display | |
8691 | @$@{eval:1+1@} $rm{yields} 2 | |
8692 | @$@{eval:1+2*3@} $rm{yields} 7 | |
8693 | @$@{eval:(1+2)*3@} $rm{yields} 9 | |
8694 | .endd | |
8695 | As a more realistic example, in an ACL you might have | |
8696 | .display asis | |
8697 | deny message = Too many bad recipients | |
8698 | condition = \ | |
8699 | ${if and { \ | |
8700 | {>{$rcpt_count}{10}} \ | |
8701 | { \ | |
8702 | < \ | |
8703 | {$recipients_count} \ | |
8704 | {${eval:$rcpt_count/2}} \ | |
8705 | } \ | |
8706 | }{yes}{no}} | |
8707 | .endd | |
8708 | The condition is true if there have been more than 10 \\RCPT\\ commands and | |
8709 | fewer than half of them have resulted in a valid recipient. | |
8710 | ||
8711 | ||
8712 | .item "@$@{expand:<<string>>@}" | |
8713 | .index expansion||re-expansion of substring | |
8714 | The \expand\ operator causes a string to be expanded for a second time. For | |
8715 | example, | |
8716 | .display asis | |
8717 | ${expand:${lookup{$domain}dbm{/some/file}{$value}}} | |
8718 | .endd | |
8719 | first looks up a string in a file while expanding the operand for \expand\, and | |
8720 | then re-expands what it has found. | |
8721 | ||
8722 | ||
8723 | .item "@$@{from@_utf8:<<string>>@}" | |
8724 | .index Unicode | |
8725 | .index UTF-8||conversion from | |
8726 | .index expansion||UTF-8 conversion | |
8727 | The world is slowly moving towards Unicode, although there are no standards for | |
8728 | email yet. However, other applications (including some databases) are starting | |
8729 | to store data in Unicode, using UTF-8 encoding. This operator converts from a | |
8730 | UTF-8 string to an ISO-8859-1 string. UTF-8 code values greater than 255 are | |
8731 | converted to underscores. The input must be a valid UTF-8 string. If it is not, | |
8732 | the result is an undefined sequence of bytes. | |
8733 | ||
8734 | Unicode code points with values less than 256 are compatible with ASCII and | |
8735 | ISO-8859-1 (also known as Latin-1). | |
4964e932 | 8736 | For example, character 169 is the copyright symbol in both cases, though the |
495ae4b0 PH |
8737 | way it is encoded is different. In UTF-8, more than one byte is needed for |
8738 | characters with code values greater than 127, whereas ISO-8859-1 is a | |
4964e932 | 8739 | single-byte encoding (but thereby limited to 256 characters). This makes |
495ae4b0 PH |
8740 | translation from UTF-8 to ISO-8859-1 straightforward. |
8741 | ||
8742 | ||
8743 | .item "@$@{hash@_<<n>>@_<<m>>:<<string>>@}" | |
8744 | .index hash function||textual | |
8745 | .index expansion||textual hash | |
4964e932 PH |
8746 | The \hash\ operator is a simpler interface to the hashing function that can be |
8747 | used when the two parameters are fixed numbers (as opposed to strings that | |
495ae4b0 PH |
8748 | change when expanded). The effect is the same as |
8749 | .display | |
8750 | @$@{hash@{<<n>>@}@{<<m>>@}@{<<string>>@}@} | |
8751 | .endd | |
8752 | See the description of the general \hash\ item above for details. The | |
8753 | abbreviation \h\ can be used when \hash\ is used as an operator. | |
8754 | ||
8755 | ||
8756 | ||
8757 | .item "@$@{hex2b64:<<hexstring>>@}" | |
8758 | .index base64 encoding||conversion from hex | |
8759 | .index expansion||hex to base64 | |
4964e932 | 8760 | This operator converts a hex string into one that is base64 encoded. This can |
495ae4b0 PH |
8761 | be useful for processing the output of the MD5 and SHA-1 hashing functions. |
8762 | ||
8763 | ||
8764 | .item "@$@{lc:<<string>>@}" | |
8765 | .index case forcing in strings | |
8766 | .index string||case forcing | |
8767 | .index lower casing | |
8768 | .index expansion||case forcing | |
8769 | This forces the letters in the string into lower-case, for example: | |
8770 | .display asis | |
8771 | ${lc:$local_part} | |
8772 | .endd | |
8773 | ||
8774 | ||
8775 | .item "@$@{length@_<<number>>:<<string>>@}" | |
8776 | .index expansion||string truncation | |
8777 | The \length\ operator is a simpler interface to the \length\ function that can | |
8778 | be used when the parameter is a fixed number (as opposed to a string that | |
8779 | changes when expanded). The effect is the same as | |
8780 | .display | |
8781 | @$@{length@{<<number>>@}@{<<string>>@}@} | |
8782 | .endd | |
4964e932 | 8783 | See the description of the general \length\ item above for details. Note that |
495ae4b0 PH |
8784 | \length\ is not the same as \strlen\. The abbreviation \l\ can be used when |
8785 | \length\ is used as an operator. | |
8786 | ||
8787 | ||
8788 | .item "@$@{local@_part:<<string>>@}" | |
8789 | .index expansion||local part extraction | |
8790 | The string is interpreted as an RFC 2822 address and the local part is | |
8791 | extracted from it. If the string does not parse successfully, the result is | |
8792 | empty. | |
8793 | ||
8794 | ||
8795 | .item "@$@{mask:<<IP address>>/<<bit count>>@}" | |
8796 | .index masked IP address | |
8797 | .index IP address||masking | |
8798 | .index CIDR notation | |
8799 | .index expansion||IP address masking | |
8800 | If the form of the string to be operated on is not an IP address followed by a | |
8801 | slash and an integer (that is, a network address in CIDR notation), the | |
8802 | expansion fails. Otherwise, this operator converts the IP address to binary, | |
8803 | masks off the least significant bits according to the bit count, and converts | |
8804 | the result back to text, with mask appended. For example, | |
8805 | .display asis | |
8806 | ${mask:10.111.131.206/28} | |
8807 | .endd | |
8808 | returns the string `10.111.131.192/28'. Since this operation is expected to be | |
8809 | mostly used for looking up masked addresses in files, the result for an IPv6 | |
8810 | address uses dots to separate components instead of colons, because colon | |
8811 | terminates a key string in lsearch files. So, for example, | |
8812 | .display asis | |
8813 | ${mask:3ffe:ffff:836f:0a00:000a:0800:200a:c031/99} | |
8814 | .endd | |
8815 | returns the string | |
8816 | .display asis | |
8817 | 3ffe.ffff.836f.0a00.000a.0800.2000.0000/99 | |
8818 | .endd | |
8819 | Letters in IPv6 addresses are always output in lower case. | |
8820 | ||
8821 | ||
8822 | .item "@$@{md5:<<string>>@}" | |
8823 | .index MD5 hash | |
8824 | .index expansion||MD5 hash | |
8825 | The \md5\ operator computes the MD5 hash value of the string, and returns it as | |
8826 | a 32-digit hexadecimal number, | |
8827 | in which any letters are in lower case. | |
8828 | ||
8829 | ||
8830 | .item "@$@{nhash@_<<n>>@_<<m>>:<<string>>@}" | |
8831 | .index expansion||numeric hash | |
8832 | .index hash function||numeric | |
8833 | The \nhash\ operator is a simpler interface to the numeric hashing function | |
8834 | that can be used when the two parameters are fixed numbers (as opposed to | |
8835 | strings that change when expanded). The effect is the same as | |
8836 | .display | |
8837 | @$@{nhash@{<<n>>@}@{<<m>>@}@{<<string>>@}@} | |
8838 | .endd | |
8839 | See the description of the general \nhash\ item above for details. | |
8840 | ||
8841 | ||
8842 | .item "@$@{quote:<<string>>@}" | |
8843 | .index quoting||in string expansions | |
8844 | .index expansion||quoting | |
4964e932 | 8845 | The \quote\ operator puts its argument into double quotes if it |
495ae4b0 PH |
8846 | is an empty string or |
8847 | contains anything other than letters, digits, underscores, dots, and hyphens. | |
8848 | Any occurrences of double quotes and backslashes are escaped with a backslash. | |
8849 | Newlines and carriage returns are converted to \"@\n"\ and \"@\r"\, | |
8850 | respectively For example, | |
8851 | .display asis | |
8852 | ${quote:ab"*"cd} | |
8853 | .endd | |
8854 | becomes | |
8855 | .display asis | |
8856 | "ab\"*\"cd" | |
8857 | .endd | |
8858 | The place where this is useful is when the argument is a substitution from a | |
8859 | variable or a message header. | |
8860 | ||
8861 | .item "@$@{quote@_local@_part:<<string>>@}" | |
4964e932 PH |
8862 | This operator is like \quote\, except that it quotes the string only if |
8863 | required to do so by the rules of RFC 2822 for quoting local parts. For | |
495ae4b0 PH |
8864 | example, a plus sign would not cause quoting (but it would for \quote\). |
8865 | If you are creating a new email address from the contents of \$local@_part$\ | |
8866 | (or any other unknown data), you should always use this operator. | |
8867 | ||
8868 | ||
8869 | .item "@$@{quote@_<<lookup-type>>:<<string>>@}" | |
8870 | .index quoting||lookup-specific | |
8871 | This operator applies lookup-specific quoting rules to the string. Each | |
8872 | query-style lookup type has its own quoting rules which are described with | |
8873 | the lookups in chapter ~~CHAPfdlookup. For example, | |
8874 | .display asis | |
8875 | ${quote_ldap:two * two} | |
8876 | .endd | |
4964e932 | 8877 | returns |
495ae4b0 PH |
8878 | .display asis |
8879 | two%20%5C2A%20two | |
8880 | .endd | |
8881 | For single-key lookup types, no quoting is ever necessary and this operator | |
8882 | yields an unchanged string. | |
8883 | ||
8884 | ||
8885 | .item "@$@{rxquote:<<string>>@}" | |
8886 | .index quoting||in regular expressions | |
8887 | .index regular expressions||quoting | |
8888 | The \rxquote\ operator inserts a backslash before any non-alphanumeric | |
8889 | characters in its argument. This is useful when substituting the values of | |
8890 | variables or headers inside regular expressions. | |
8891 | ||
8892 | ||
8893 | .item "@$@{rfc2047:<<string>>@}" | |
8894 | .index expansion||RFC 2047 | |
8895 | This operator encodes text according to the rules of RFC 2047. This is an | |
8896 | encoding that is used in header lines to encode non-ASCII characters. It is | |
8897 | assumed that the input string is in the encoding specified by the | |
d43194df PH |
8898 | \headers@_charset\ option, which defaults to ISO-8859-1. If the string contains |
8899 | only characters in the range 33--126, and no instances of the characters | |
495ae4b0 | 8900 | .display asis |
4964e932 | 8901 | ? = ( ) < > @ , ; : \ " . [ ] _ |
495ae4b0 | 8902 | .endd |
d43194df PH |
8903 | it is not modified. Otherwise, the result is the RFC 2047 encoding of the |
8904 | string, | |
8905 | .em | |
8906 | using as many `coded words' as necessary to encode all the characters. | |
8907 | .nem | |
495ae4b0 PH |
8908 | |
8909 | ||
8910 | .item "@$@{sha1:<<string>>@}" | |
8911 | .index SHA-1 hash | |
8912 | .index expansion||SHA-1 hashing | |
8913 | The \sha1\ operator computes the SHA-1 hash value of the string, and returns it | |
8914 | as a 40-digit hexadecimal number, in which any letters are in upper case. | |
8915 | ||
8916 | ||
8917 | .item "@$@{stat:<<string>>@}" | |
8918 | .index expansion||statting a file | |
8919 | .index file||extracting characteristics | |
8920 | The string, after expansion, must be a file path. A call to the \*stat()*\ | |
8921 | function is made for this path. If \*stat()*\ fails, an error occurs and the | |
8922 | expansion fails. If it succeeds, the data from the stat replaces the item, as a | |
4964e932 | 8923 | series of <<name>>=<<value>> pairs, where the values are all numerical, |
495ae4b0 PH |
8924 | except for the value of `smode'. The names are: `mode' (giving the mode as a |
8925 | 4-digit octal number), `smode' (giving the mode in symbolic format as a | |
8926 | 10-character string, as for the \*ls*\ command), `inode', `device', `links', | |
8927 | `uid', `gid', `size', `atime', `mtime', and `ctime'. You can extract individual | |
8928 | fields using the \extract\ expansion item. \**Warning**\: The file size may be | |
8929 | incorrect on 32-bit systems for files larger than 2GB. | |
8930 | ||
8931 | ||
d43194df PH |
8932 | .em |
8933 | .item "@$@{str2b64:<<string>>@}" | |
8934 | .index expansion||base64 encoding | |
8935 | .index base64 encoding||in string expansion | |
8936 | This operator converts a string into one that is base64 encoded. | |
8937 | .nem | |
8938 | ||
8939 | ||
495ae4b0 PH |
8940 | .item "@$@{strlen:<<string>>@}" |
8941 | .index expansion||string length | |
8942 | .index string||length in expansion | |
4964e932 | 8943 | The item is replace by the length of the expanded string, expressed as a |
495ae4b0 PH |
8944 | decimal number. \**Note**\: Do not confuse \strlen\ with \length\. |
8945 | ||
8946 | ||
8947 | .item "@$@{substr@_<<start>>@_<<length>>:<<string>>@}" | |
8948 | .index \substr\ | |
8949 | .index substring extraction | |
8950 | .index expansion||substring expansion | |
8951 | The \substr\ operator is a simpler interface to the \substr\ function that can | |
8952 | be used when the two parameters are fixed numbers (as opposed to strings that | |
8953 | change when expanded). The effect is the same as | |
8954 | .display | |
8955 | @$@{substr@{<<start>>@}@{<<length>>@}@{<<string>>@}@} | |
8956 | .endd | |
8957 | See the description of the general \substr\ item above for details. The | |
8958 | abbreviation \s\ can be used when \substr\ is used as an operator. | |
8959 | ||
495ae4b0 PH |
8960 | .item "@$@{time@_interval:<<string>>@}" |
8961 | .index \time@_interval\ | |
8962 | .index time interval||formatting | |
8963 | The argument (after sub-expansion) must be a sequence of decimal digits that | |
8964 | represents an interval of time as a number of seconds. It is converted into a | |
8965 | number of larger units and output in Exim's normal time format, for example, | |
8966 | \"1w3d4h2m6s"\. | |
495ae4b0 PH |
8967 | |
8968 | .item "@$@{uc:<<string>>@}" | |
8969 | .index case forcing in strings | |
8970 | .index string||case forcing | |
8971 | .index upper casing | |
8972 | .index expansion||case forcing | |
8973 | This forces the letters in the string into upper-case. | |
8974 | ||
8975 | .enditems | |
8976 | ||
8977 | ||
8978 | ||
8979 | .section Expansion conditions | |
8980 | .rset SECTexpcond "~~chapter.~~section" | |
8981 | .index expansion||conditions | |
8982 | The following conditions are available for testing by the \@$@{if\ construct | |
8983 | while expanding strings: | |
8984 | ||
8985 | .startitems | |
8986 | ||
8987 | .item "!<<condition>>" | |
8988 | .index expansion||negating a condition | |
8989 | Preceding any condition with an exclamation mark negates the result of the | |
8990 | condition. | |
8991 | ||
8992 | .item "<<symbolic operator>> @{<<string1>>@}@{<<string2>>@}" | |
8993 | .index numeric comparison | |
8994 | .index expansion||numeric comparison | |
8995 | There are a number of symbolic operators for doing numeric comparisons. They | |
8996 | are: | |
8997 | .display | |
8998 | .tabs 8 | |
8999 | = $t $rm{equal} | |
9000 | == $t $rm{equal} | |
9001 | > $t $rm{greater} | |
9002 | >= $t $rm{greater or equal} | |
9003 | < $t $rm{less} | |
9004 | <= $t $rm{less or equal} | |
9005 | .endd | |
9006 | For example, | |
9007 | .display asis | |
9008 | ${if >{$message_size}{10M} ... | |
9009 | .endd | |
9010 | Note that the general negation operator provides for inequality testing. The | |
9011 | two strings must take the form of optionally signed decimal integers, | |
9012 | optionally followed by one of the letters `K' or `M' (in either upper or lower | |
9013 | case), signifying multiplication by 1024 or 1024$*$1024, respectively. | |
9014 | ||
9015 | .item "crypteq @{<<string1>>@}@{<<string2>>@}" | |
9016 | .index expansion||encrypted comparison | |
9017 | .index encrypted strings, comparing | |
9018 | This condition is included in the Exim binary if it is built to support any | |
9019 | authentication mechanisms (see chapter ~~CHAPSMTPAUTH). Otherwise, it is | |
9020 | necessary to define \\SUPPORT@_CRYPTEQ\\ in \(Local/Makefile)\ to get \crypteq\ | |
9021 | included in the binary. | |
9022 | ||
9023 | The \crypteq\ condition has two arguments. The first is encrypted and compared | |
9024 | against the second, which is already encrypted. The second string may be in the | |
9025 | LDAP form for storing encrypted strings, which starts with the encryption type | |
9026 | in curly brackets, followed by the data. If the second string does not begin | |
9027 | with `{' it is assumed to be encrypted with \*crypt()*\ | |
9028 | or \*crypt16()*\ (see below), | |
9029 | since such strings cannot begin with `{'. Typically this will be a field from a | |
9030 | password file. | |
9031 | ||
9032 | An example of an encrypted string in LDAP form is: | |
9033 | .display asis | |
9034 | {md5}CY9rzUYh03PK3k6DJie09g== | |
9035 | .endd | |
9036 | If such a string appears directly in an expansion, the curly brackets have to | |
9037 | be quoted, because they are part of the expansion syntax. For example: | |
9038 | .display asis | |
9039 | ${if crypteq {test}{\{md5\}CY9rzUYh03PK3k6DJie09g==}{yes}{no}} | |
9040 | .endd | |
4964e932 | 9041 | The following encryption types |
495ae4b0 PH |
9042 | (whose names are matched case-independently) |
9043 | are supported: | |
9044 | .numberpars $. | |
9045 | .index MD5 hash | |
9046 | .index base64 encoding||in encrypted password | |
9047 | \@{md5@}\ computes the MD5 digest of the first string, and expresses this as | |
9048 | printable characters to compare with the remainder of the second string. If the | |
9049 | length of the comparison string is 24, Exim assumes that it is base64 encoded | |
9050 | (as in the above example). If the length is 32, Exim assumes that it is a | |
9051 | hexadecimal encoding of the MD5 digest. If the length not 24 or 32, the | |
9052 | comparison fails. | |
9053 | .nextp | |
9054 | .index SHA-1 hash | |
4964e932 PH |
9055 | \@{sha1@}\ computes the SHA-1 digest of the first string, and expresses this as |
9056 | printable characters to compare with the remainder of the second string. If the | |
9057 | length of the comparison string is 28, Exim assumes that it is base64 encoded. | |
9058 | If the length is 40, Exim assumes that it is a hexadecimal encoding of the | |
495ae4b0 PH |
9059 | SHA-1 digest. If the length is not 28 or 40, the comparison fails. |
9060 | .nextp | |
9061 | .index \*crypt()*\ | |
d43194df PH |
9062 | \@{crypt@}\ calls the \*crypt()*\ function, |
9063 | .em | |
9064 | which traditionally used to use only the first eight characters of the | |
9065 | password. However, in modern operating systems this is no longer true, and in | |
9066 | many cases the entire password is used, whatever its length. | |
9067 | .nem | |
495ae4b0 PH |
9068 | .nextp |
9069 | .index \*crypt16()*\ | |
9070 | \@{crypt16@}\ calls the \*crypt16()*\ function (also known as \*bigcrypt()*\), | |
d43194df PH |
9071 | which |
9072 | .em | |
9073 | was orginally created to use up to 16 characters of the password. Again, in | |
9074 | modern operating systems, more characters may be used. | |
9075 | .nem | |
495ae4b0 PH |
9076 | .endp |
9077 | Exim has its own version of \*crypt16()*\ (which is just a double call to | |
9078 | \*crypt()*\). For operating systems that have their own version, setting | |
9079 | \\HAVE@_CRYPT16\\ in \(Local/Makefile)\ when building Exim causes it to use the | |
4964e932 PH |
9080 | operating system version instead of its own. This option is set by default in |
9081 | the OS-dependent \(Makefile)\ for those operating systems that are known to | |
495ae4b0 PH |
9082 | support \*crypt16()*\. |
9083 | ||
9084 | If you do not put any curly bracket encryption type in a \crypteq\ comparison, | |
9085 | the default is either \"@{crypt@}"\ or \"@{crypt16@}"\, as determined by the | |
9086 | setting of \\DEFAULT@_CRYPT\\ in \(Local/Makefile)\. The default default is | |
9087 | \"@{crypt@}"\. Whatever the default, you can always use either function by | |
9088 | specifying it explicitly in curly brackets. | |
9089 | ||
9090 | Note that if a password is no longer than 8 characters, the results of | |
9091 | encrypting it with \*crypt()*\ and \*crypt16()*\ are identical. That means that | |
9092 | \*crypt16()*\ is backwards compatible, as long as nobody feeds it a password | |
9093 | longer than 8 characters. | |
9094 | ||
9095 | ||
9096 | .item "def:<<variable name>>" | |
9097 | .index expansion||checking for empty variable | |
9098 | The \def\ condition must be followed by the name of one of the expansion | |
9099 | variables defined in section ~~SECTexpvar. The condition is true if the named | |
9100 | expansion variable does not contain the empty string, for example | |
9101 | .display asis | |
9102 | ${if def:sender_ident {from $sender_ident}} | |
9103 | .endd | |
9104 | Note that the variable name is given without a leading \@$\ character. If the | |
9105 | variable does not exist, the expansion fails. | |
9106 | ||
9107 | .item "def:header@_<<header name>>:##or##def:h@_<<header name>>:" | |
9108 | .index expansion||checking header line existence | |
9109 | This condition is true if a message is being processed and the named header | |
9110 | exists in the message. For example, | |
9111 | .display asis | |
9112 | ${if def:header_reply-to:{$h_reply-to:}{$h_from:}} | |
9113 | .endd | |
9114 | Note that no \@$\ appears before \header@_\ or \h@_\ in the condition, | |
9115 | and that header names must be terminated by colons if white space does not | |
9116 | follow. | |
9117 | ||
9118 | .item "eq @{<<string1>>@}@{<<string2>>@}" | |
9119 | .item "eqi @{<<string1>>@}@{<<string2>>@}" | |
9120 | .index string||comparison | |
9121 | .index expansion||string comparison | |
9122 | The two substrings are first expanded. The condition is true if the two | |
4964e932 | 9123 | resulting strings are identical: for \eq\ the comparison includes the case of |
495ae4b0 PH |
9124 | letters, whereas for \eqi\ the comparison is case-independent. |
9125 | ||
9126 | .item "exists @{<<file name>>@}" | |
9127 | .index expansion||file existence test | |
9128 | .index file||existence test | |
9129 | The substring is first expanded and then interpreted as an absolute path. The | |
9130 | condition is true if the named file (or directory) exists. The existence test | |
9131 | is done by calling the \*stat()*\ function. The use of the \exists\ test in | |
9132 | users' filter files may be locked out by the system administrator. | |
9133 | ||
9134 | .item "first@_delivery" | |
9135 | .index delivery||first | |
9136 | .index first delivery | |
9137 | .index expansion||first delivery test | |
9138 | This condition, which has no data, is true during a message's first delivery | |
9139 | attempt. It is false during any subsequent delivery attempts. | |
9140 | ||
495ae4b0 PH |
9141 | .item "ge @{<<string1>>@}@{<<string2>>@}" |
9142 | .item "gei @{<<string1>>@}@{<<string2>>@}" | |
9143 | .index string||comparison | |
9144 | .index expansion||string comparison | |
9145 | The two substrings are first expanded. The condition is true if the first | |
9146 | string is lexically greater than or equal to the second string: for \ge\ the | |
9147 | comparison includes the case of letters, whereas for \gei\ the comparison is | |
9148 | case-independent. | |
9149 | ||
9150 | .item "gt @{<<string1>>@}@{<<string2>>@}" | |
9151 | .item "gti @{<<string1>>@}@{<<string2>>@}" | |
9152 | .index string||comparison | |
9153 | .index expansion||string comparison | |
9154 | The two substrings are first expanded. The condition is true if the first | |
9155 | string is lexically greater than the second string: for \gt\ the comparison | |
9156 | includes the case of letters, whereas for \gti\ the comparison is | |
9157 | case-independent. | |
495ae4b0 PH |
9158 | |
9159 | .item "isip @{<<string>>@}" 8 | |
9160 | .item "isip4 @{<<string>>@}" | |
9161 | .item "isip6 @{<<string>>@}" | |
9162 | .index IP address||testing string format | |
9163 | .index string||testing for IP address | |
4964e932 PH |
9164 | The substring is first expanded, and then tested to see if it has the form of |
9165 | an IP address. Both IPv4 and IPv6 addresses are valid for \isip\, whereas | |
9166 | \isip4\ and \isip6\ test just for IPv4 or IPv6 addresses, respectively. For | |
495ae4b0 | 9167 | example, you could use |
4964e932 | 9168 | .display asis |
495ae4b0 PH |
9169 | ${if isip4{$sender_host_address}... |
9170 | .endd | |
9171 | to test which version of IP an incoming SMTP connection is using. | |
9172 | ||
9173 | ||
9174 | .item "ldapauth @{<<ldap query>>@}" | |
9175 | .index LDAP||use for authentication | |
9176 | .index expansion||LDAP authentication test | |
9177 | This condition supports user authentication using LDAP. See section ~~SECTldap | |
9178 | for details of how to use LDAP in lookups and the syntax of queries. For this | |
9179 | use, the query must contain a user name and password. The query itself is not | |
9180 | used, and can be empty. The condition is true if | |
9181 | the password is not empty, and the user name and password are accepted by the | |
4964e932 | 9182 | LDAP server. An empty password is rejected without calling LDAP because LDAP |
495ae4b0 PH |
9183 | binds with an empty password are considered anonymous regardless of |
9184 | the username, and will succeed in most configurations. | |
9185 | See chapter ~~CHAPSMTPAUTH for details of SMTP authentication, and chapter | |
9186 | ~~CHAPplaintext for an example of how this can be used. | |
9187 | ||
9188 | ||
495ae4b0 PH |
9189 | .item "le @{<<string1>>@}@{<<string2>>@}" |
9190 | .item "lei @{<<string1>>@}@{<<string2>>@}" | |
9191 | .index string||comparison | |
9192 | .index expansion||string comparison | |
9193 | The two substrings are first expanded. The condition is true if the first | |
9194 | string is lexically less than or equal to the second string: for \le\ the | |
9195 | comparison includes the case of letters, whereas for \lei\ the comparison is | |
9196 | case-independent. | |
9197 | ||
9198 | .item "lt @{<<string1>>@}@{<<string2>>@}" | |
9199 | .item "lti @{<<string1>>@}@{<<string2>>@}" | |
9200 | .index string||comparison | |
9201 | .index expansion||string comparison | |
9202 | The two substrings are first expanded. The condition is true if the first | |
9203 | string is lexically less than the second string: for \lt\ the comparison | |
9204 | includes the case of letters, whereas for \lti\ the comparison is | |
9205 | case-independent. | |
495ae4b0 PH |
9206 | |
9207 | ||
9208 | .item "match @{<<string1>>@}@{<<string2>>@}" | |
9209 | .index expansion||regular expression comparison | |
9210 | .index regular expressions||match in expanded string | |
9211 | The two substrings are first expanded. The second is then treated as a regular | |
9212 | expression and applied to the first. Because of the pre-expansion, if the | |
9213 | regular expression contains dollar, or backslash characters, they must be | |
9214 | escaped. Care must also be taken if the regular expression contains braces | |
9215 | (curly brackets). A closing brace must be escaped so that it is not taken as a | |
9216 | premature termination of <<string2>>. The easiest approach is to use the | |
9217 | \"@\N"\ feature to disable expansion of the regular expression. | |
9218 | For example, | |
9219 | .display asis | |
9220 | ${if match {$local_part}{\N^\d{3}\N} ... | |
9221 | .endd | |
9222 | If the whole expansion string is in double quotes, further escaping of | |
9223 | backslashes is also required. | |
9224 | ||
4964e932 PH |
9225 | The condition is true if the regular expression match succeeds. |
9226 | The regular expression is not required to begin with a circumflex | |
495ae4b0 | 9227 | metacharacter, but if there is no circumflex, the expression is not anchored, |
4964e932 PH |
9228 | and it may match anywhere in the subject, not just at the start. If you want |
9229 | the pattern to match at the end of the subject, you must include the \"@$"\ | |
495ae4b0 | 9230 | metacharacter at an appropriate point. |
495ae4b0 PH |
9231 | |
9232 | .index numerical variables (\$1$\, \$2$\, etc)||in \if\ expansion | |
9233 | At the start of an \if\ expansion the values of the numeric variable | |
9234 | substitutions \$1$\ etc. are remembered. Obeying a \match\ condition that | |
9235 | succeeds causes them to be reset to the substrings of that condition and they | |
9236 | will have these values during the expansion of the success string. At the end | |
9237 | of the \if\ expansion, the previous values are restored. After testing a | |
9238 | combination of conditions using \or\, the subsequent values of the numeric | |
9239 | variables are those of the condition that succeeded. | |
9240 | ||
495ae4b0 PH |
9241 | .item "match@_domain @{<<string1>>@}@{<<string2>>@}" |
9242 | .item "match@_address @{<<string1>>@}@{<<string2>>@}" | |
9243 | .item "match@_local@_part @{<<string1>>@}@{<<string2>>@}" | |
9244 | .index domain list||in expansion condition | |
9245 | .index address list||in expansion condition | |
9246 | .index local part list||in expansion condition | |
9247 | These conditions make it possible to test domain, address, and local | |
9248 | part lists within expansions. Each condition requires two arguments: an item | |
9249 | and a list to match. A trivial example is: | |
9250 | .display asis | |
9251 | ${if match_domain{a.b.c}{x.y.z:a.b.c:p.q.r}{yes}{no}} | |
9252 | .endd | |
9253 | In each case, the second argument may contain any of the allowable items for a | |
9254 | list of the appropriate type. Also, because the second argument (after | |
9255 | expansion) is a standard form of list, it is possible to refer to a named list. | |
9256 | Thus, you can use conditions like this: | |
9257 | .display asis | |
9258 | ${if match_domain{$domain}{+local_domains}{... | |
9259 | .endd | |
9260 | .index \"+caseful"\ | |
9261 | For address lists, the matching starts off caselessly, but the \"+caseful"\ | |
9262 | item can be used, as in all address lists, to cause subsequent items to | |
9263 | have their local parts matched casefully. Domains are always matched | |
9264 | caselessly. | |
9265 | ||
9266 | \**Note**\: Host lists are \*not*\ supported in this way. This is because | |
9267 | hosts have two identities: a name and an IP address, and it is not clear | |
9268 | how to specify cleanly how such a test would work. At least, I haven't come | |
9269 | up with anything yet. | |
495ae4b0 PH |
9270 | |
9271 | .item "pam {<<string1>>:<<string2>>:...@}" | |
9272 | .index PAM authentication | |
9273 | .index \\AUTH\\||with PAM | |
9274 | .index Solaris||PAM support | |
9275 | .index expansion||PAM authentication test | |
9276 | \*Pluggable Authentication Modules*\ | |
9277 | (\?http://www.kernel.org/pub/linux/libs/pam/?\) | |
9278 | are a facility which is available in the latest releases of Solaris and in some | |
9279 | GNU/Linux distributions. The Exim support, which is intended for use in | |
9280 | conjunction with the SMTP \\AUTH\\ command, is available only if Exim is | |
9281 | compiled with | |
9282 | .display asis | |
9283 | SUPPORT_PAM=yes | |
9284 | .endd | |
9285 | in \(Local/Makefile)\. You probably need to add \-lpam-\ to \\EXTRALIBS\\, and | |
9286 | in some releases of GNU/Linux \-ldl-\ is also needed. | |
9287 | ||
9288 | The argument string is first expanded, and the result must be a colon-separated | |
4964e932 | 9289 | list of strings. |
495ae4b0 PH |
9290 | Leading and trailing whitespace is ignored. |
9291 | The PAM module is initialized with the service name `exim' and the user name | |
9292 | taken from the first item in the colon-separated data string (<<string1>>). The | |
9293 | remaining items in the data string are passed over in response to requests from | |
9294 | the authentication function. In the simple case there will only be one request, | |
9295 | for a password, so the data consists of just two strings. | |
9296 | ||
9297 | There can be problems if any of the strings are permitted to contain colon | |
9298 | characters. In the usual way, these have to be doubled to avoid being taken as | |
9299 | separators. If the data is being inserted from a variable, the \sg\ expansion | |
9300 | item can be used to double any existing colons. For example, the configuration | |
9301 | of a LOGIN authenticator might contain this setting: | |
9302 | .display asis | |
9303 | server_condition = ${if pam{$1:${sg{$2}{:}{::}}}{yes}{no}} | |
9304 | .endd | |
9305 | For a PLAIN authenticator you could use: | |
9306 | .display asis | |
9307 | server_condition = ${if pam{$2:${sg{$3}{:}{::}}}{yes}{no}} | |
9308 | .endd | |
9309 | In some operating systems, PAM authentication can be done only from a process | |
9310 | running as root. Since Exim is running as the Exim user when receiving | |
9311 | messages, this means that PAM cannot be used directly in those systems. | |
9312 | A patched version of the \*pam@_unix*\ module that comes with the | |
9313 | Linux PAM package is available from \?http:@/@/www.e-admin.de/pam@_exim/?\. | |
9314 | The patched module allows one special uid/gid combination, in addition to root, | |
9315 | to authenticate. If you build the patched module to allow the Exim user and | |
9316 | group, PAM can then be used from an Exim authenticator. | |
9317 | ||
9318 | ||
9319 | .item "pwcheck {<<string1>>:<<string2>>@}" | |
9320 | .index \*pwcheck*\ daemon | |
9321 | .index Cyrus | |
9322 | .index expansion||\*pwcheck*\ authentication test | |
9323 | This condition supports user authentication using the Cyrus \*pwcheck*\ daemon. | |
9324 | This is one way of making it possible for passwords to be checked by a process | |
9325 | that is not running as root. | |
9326 | \**Note:**\ The use of \*pwcheck*\ is now deprecated. Its replacement is | |
9327 | \*saslauthd*\ (see below). | |
9328 | ||
9329 | The pwcheck support is not included in Exim by default. You need to specify | |
9330 | the location of the pwcheck daemon's socket in \(Local/Makefile)\ before | |
9331 | building Exim. For example: | |
9332 | .display asis | |
9333 | CYRUS_PWCHECK_SOCKET=/var/pwcheck/pwcheck | |
9334 | .endd | |
9335 | You do not need to install the full Cyrus software suite in order to use | |
9336 | the pwcheck daemon. You can compile and install just the daemon alone | |
9337 | from the Cyrus SASL library. Ensure that \*exim*\ is the only user that has | |
9338 | access to the \(/var/pwcheck)\ directory. | |
9339 | ||
9340 | The \pwcheck\ condition takes one argument, which must be the user name and | |
9341 | password, separated by a colon. For example, in a LOGIN authenticator | |
9342 | configuration, you might have this: | |
9343 | .display asis | |
9344 | server_condition = ${if pwcheck{$1:$2}{1}{0}} | |
9345 | .endd | |
9346 | ||
9347 | .item "queue@_running" | |
9348 | .index queue runner||detecting when delivering from | |
9349 | .index expansion||queue runner test | |
9350 | This condition, which has no data, is true during delivery attempts that are | |
9351 | initiated by queue runner processes, and false otherwise. | |
9352 | ||
9353 | ||
9354 | .item "radius {<<authentication string>>@}" | |
9355 | .index Radius | |
9356 | .index expansion||Radius authentication | |
9357 | Radius authentication (RFC 2865) is supported in a similar way to PAM. You must | |
9358 | set \\RADIUS@_CONFIG@_FILE\\ in \(Local/Makefile)\ to specify the location of | |
9359 | the Radius client configuration file in order to build Exim with Radius | |
4964e932 | 9360 | support. |
d43194df PH |
9361 | .em |
9362 | With just that one setting, Exim expects to be linked with the \radiusclient\ | |
9363 | library. You can also link Exim with the \libradius\ library that comes with | |
9364 | FreeBSD. To do this, set | |
9365 | .display asis | |
9366 | RADIUS_LIB_TYPE=RADLIB | |
9367 | .endd | |
9368 | in \(Local/Makefile)\, in addition to setting \\RADIUS@_CONFIGURE@_FILE\\. | |
9369 | .nem | |
495ae4b0 PH |
9370 | You may also have to supply a suitable setting in \\EXTRALIBS\\ so that the |
9371 | Radius library can be found when Exim is linked. | |
d43194df | 9372 | |
495ae4b0 PH |
9373 | The string specified by \\RADIUS@_CONFIG@_FILE\\ is expanded and passed to the |
9374 | Radius client library, which calls the Radius server. The condition is true if | |
9375 | the authentication is successful. For example | |
9376 | .display | |
9377 | server@_condition = @$@{if radius@{<<arguments>>@}@{yes@}@{no@}@} | |
9378 | .endd | |
9379 | ||
9380 | ||
9381 | ||
9382 | .item "saslauthd @{@{<<user>>@}@{<<password>>@}@{<<service>>@}@{<<realm>>@}@}" | |
9383 | .index \*saslauthd*\ daemon | |
9384 | .index Cyrus | |
9385 | .index expansion||\*saslauthd*\ authentication test | |
9386 | This condition supports user authentication using the Cyrus \*saslauthd*\ | |
9387 | daemon. This replaces the older \*pwcheck*\ daemon, which is now deprecated. | |
9388 | Using this daemon is one way of making it possible for passwords to be checked | |
9389 | by a process that is not running as root. | |
9390 | ||
9391 | The saslauthd support is not included in Exim by default. You need to specify | |
9392 | the location of the saslauthd daemon's socket in \(Local/Makefile)\ before | |
9393 | building Exim. For example: | |
9394 | .display asis | |
9395 | CYRUS_SASLAUTHD_SOCKET=/var/state/saslauthd/mux | |
9396 | .endd | |
9397 | You do not need to install the full Cyrus software suite in order to use | |
9398 | the saslauthd daemon. You can compile and install just the daemon alone | |
9399 | from the Cyrus SASL library. | |
9400 | ||
9401 | Up to four arguments can be supplied to the \saslauthd\ condition, but only two | |
9402 | are mandatory. For example: | |
9403 | .display asis | |
9404 | server_condition = ${if saslauthd{{$1}{$2}}{1}{0}} | |
9405 | .endd | |
9406 | The service and the realm are optional (which is why the arguments are enclosed | |
9407 | in their own set of braces). For details of the meaning of the service and | |
9408 | realm, and how to run the daemon, consult the Cyrus documentation. | |
9409 | ||
9410 | .enditems | |
9411 | ||
9412 | ||
9413 | ||
9414 | .section Combining expansion conditions | |
9415 | .index expansion||combining conditions | |
9416 | Several conditions can be tested at once by combining them using the \and\ and | |
9417 | \or\ combination conditions. Note that \and\ and \or\ are complete conditions | |
9418 | on their own, and precede their lists of sub-conditions. Each sub-condition | |
9419 | must be enclosed in braces within the overall braces that contain the list. No | |
9420 | repetition of \if\ is used. | |
9421 | ||
9422 | .startitems | |
9423 | ||
9424 | .item "or @{@{<<cond1>>@}@{<<cond2>>@}...@}" | |
9425 | .index `or' expansion condition | |
9426 | .index expansion||`or' of conditions | |
9427 | The sub-conditions are evaluated from left to right. The condition is true if | |
9428 | any one of the sub-conditions is true. | |
9429 | For example, | |
9430 | .display asis | |
9431 | ${if or {{eq{$local_part}{spqr}}{eq{$domain}{testing.com}}}... | |
9432 | .endd | |
9433 | When a true sub-condition is found, the following ones are parsed but not | |
9434 | evaluated. If there are several `match' sub-conditions the values of the | |
9435 | numeric variables afterwards are taken from the first one that succeeds. | |
9436 | ||
9437 | .item "and @{@{<<cond1>>@}@{<<cond2>>@}...@}" | |
9438 | .index `and' expansion condition | |
9439 | .index expansion||`and' of conditions | |
9440 | The sub-conditions are evaluated from left to right. The condition is true if | |
9441 | all of the sub-conditions are true. If there are several `match' | |
9442 | sub-conditions, the values of the numeric variables afterwards are taken from | |
9443 | the last one. When a false sub-condition is found, the following ones are | |
9444 | parsed but not evaluated. | |
9445 | ||
9446 | .enditems | |
9447 | ||
9448 | ||
9449 | ||
9450 | .section Expansion variables | |
9451 | .rset SECTexpvar "~~chapter.~~section" | |
9452 | .index expansion||variables, list of | |
9453 | ||
d43194df PH |
9454 | .em |
9455 | This section contains an alphabetical list of all the expansion variables. Some | |
9456 | of them are available only when Exim is compiled with specific options such as | |
9457 | support for TLS or the content scanning extension. | |
9458 | .nem | |
495ae4b0 PH |
9459 | |
9460 | .push | |
9461 | .indent 2em | |
495ae4b0 | 9462 | .index numerical variables (\$1$\, \$2$\, etc) |
d43194df | 9463 | .tempindent 0 |
495ae4b0 PH |
9464 | \$0$\, \$1$\, etc: When a \match\ expansion condition succeeds, these |
9465 | variables contain the captured substrings identified by the regular expression | |
9466 | during subsequent processing of the success string of the containing \if\ | |
9467 | expansion item. They may also be set externally by some other matching process | |
9468 | which precedes the expansion of the string. For example, the commands available | |
9469 | in Exim filter files include an \if\ command with its own regular expression | |
9470 | matching condition. | |
9471 | ||
9472 | .tempindent 0 | |
4964e932 | 9473 | \$acl@_c0$\ -- \$acl@_c9$\: Values can be placed in these variables by the |
495ae4b0 PH |
9474 | \set\ modifier in an ACL. The values persist throughout the lifetime of an SMTP |
9475 | connection. They can be used to pass information between ACLs and different | |
4964e932 | 9476 | invocations of the same ACL. |
495ae4b0 | 9477 | When a message is received, the values of these variables are saved with the |
4964e932 | 9478 | message, and can be accessed by filters, routers, and transports during |
495ae4b0 PH |
9479 | subsequent delivery. |
9480 | ||
9481 | .tempindent 0 | |
9482 | \$acl@_m0$\ -- \$acl@_m9$\: Values can be placed in these variables by the | |
9483 | \set\ modifier in an ACL. They retain their values while a message is being | |
9484 | received, but are reset afterwards. They are also reset by \\MAIL\\, \\RSET\\, | |
9485 | \\EHLO\\, \\HELO\\, and after starting a TLS session. | |
9486 | When a message is received, the values of these variables are saved with the | |
9487 | message, and can be accessed by filters, routers, and transports during | |
9488 | subsequent delivery. | |
9489 | ||
9490 | ||
9491 | .tempindent 0 | |
4964e932 | 9492 | \$acl@_verify@_message$\: During the expansion of the \message\ and |
495ae4b0 PH |
9493 | \log@_message\ modifiers in an ACL statement after an address verification has |
9494 | failed, this variable contains the original failure message that will be | |
9495 | overridden by the expanded string. | |
9496 | ||
9497 | .tempindent 0 | |
9498 | \$address@_data$\: This variable is set by means of the \address@_data\ | |
9499 | option in routers. The value then remains with the address while it is | |
9500 | processed by subsequent routers and eventually a transport. If the transport is | |
9501 | handling multiple addresses, the value from the first address is used. See | |
d43194df PH |
9502 | chapter ~~CHAProutergeneric for more details. \**Note**\: the contents of |
9503 | \$address@_data$\ are visible in user filter files. | |
9504 | ||
9505 | .em | |
9506 | If \$address@_data$\ is set when the routers are called from an ACL to verify | |
9507 | a recipient address, the final value is still in the variable for subsequent | |
9508 | conditions and modifiers of the ACL statement. If routing the address caused it | |
9509 | to be redirected to just one address, the child address is also routed as part | |
9510 | of the verification, and in this case the final value of \$address@_data$\ is | |
9511 | from the child's routing. | |
9512 | ||
9513 | If \$address@_data$\ is set when the routers are called from an ACL to verify a | |
9514 | sender address, the final value is also preserved, but this time in | |
9515 | \$sender@_address@_data$\, to distinguish it from data from a recipient | |
9516 | address. | |
495ae4b0 | 9517 | |
d43194df PH |
9518 | In both cases (recipient and sender verification), the value does not persist |
9519 | after the end of the current ACL statement. If you want to preserve | |
9520 | these values for longer, you can save them in ACL variables. | |
9521 | .nem | |
495ae4b0 PH |
9522 | |
9523 | .tempindent 0 | |
9524 | \$address@_file$\: When, as a result of aliasing, forwarding, or filtering, a | |
9525 | message is directed to a specific file, this variable holds the name of the | |
9526 | file when the transport is running. At other times, the variable is empty. For | |
9527 | example, using the default configuration, if user \r2d2\ has a \(.forward)\ | |
9528 | file containing | |
9529 | .display asis | |
9530 | /home/r2d2/savemail | |
9531 | .endd | |
9532 | then when the \%address@_file%\ transport is running, \$address@_file$\ | |
9533 | contains `/home/r2d2/savemail'. | |
9534 | .index Sieve filter||value of \$address@_file$\ | |
4964e932 PH |
9535 | For Sieve filters, the value may be `inbox' or a relative folder name. It is |
9536 | then up to the transport configuration to generate an appropriate absolute path | |
495ae4b0 PH |
9537 | to the relevant file. |
9538 | ||
9539 | ||
9540 | .tempindent 0 | |
9541 | \$address@_pipe$\: When, as a result of aliasing or forwarding, a message is | |
9542 | directed to a pipe, this variable holds the pipe command when the transport is | |
9543 | running. | |
9544 | ||
9545 | .index authentication||id | |
9546 | .tempindent 0 | |
9547 | \$authenticated@_id$\: When a server successfully authenticates a client it may | |
9548 | be configured to preserve some of the authentication information in the | |
9549 | variable \$authenticated@_id$\ (see chapter ~~CHAPSMTPAUTH). For example, a | |
9550 | user/password authenticator configuration might preserve the user name for use | |
9551 | in the routers. When a message is submitted locally (that is, not over a TCP | |
9552 | connection), the value of \$authenticated@_id$\ is the login name of the | |
9553 | calling process. | |
9554 | ||
9555 | .index sender||authenticated | |
9556 | .index authentication||sender | |
9557 | .index \\AUTH\\||on \\MAIL\\ command | |
9558 | .tempindent 0 | |
9559 | \$authenticated@_sender$\: | |
495ae4b0 PH |
9560 | When acting as a server, Exim takes note of the \\AUTH=\\ parameter on an |
9561 | incoming SMTP \\MAIL\\ command | |
495ae4b0 PH |
9562 | if it believes the sender is sufficiently trusted, as described in section |
9563 | ~~SECTauthparamail. Unless the data is the string `@<@>', it is set as the | |
9564 | authenticated sender of the message, and the value is available during delivery | |
9565 | in the \$authenticated@_sender$\ variable. If the sender is not trusted, Exim | |
9566 | accepts the syntax of \\AUTH=\\, but ignores the data. | |
9567 | ||
9568 | When a message is submitted locally (that is, not over a TCP connection), the | |
9569 | value of \$authenticated@_sender$\ is an address constructed from the login | |
9570 | name of the calling process and \$qualify@_domain$\. | |
9571 | ||
9572 | ||
9573 | .index authentication||failure | |
9574 | .tempindent 0 | |
4964e932 | 9575 | \$authentication@_failed$\: |
495ae4b0 PH |
9576 | This variable is set to `1' in an Exim server if a client issues an \\AUTH\\ |
9577 | command that does not succeed. Otherwise it is set to `0'. This makes it | |
9578 | possible to distinguish between `did not try to authenticate' | |
9579 | (\$sender@_host@_authenticated$\ is empty and \$authentication__failed$\ is set | |
9580 | to `0') and `tried to authenticate but failed' (\$sender@_host@_authenticated$\ | |
9581 | is empty and \$authentication@_failed$\ is set to `1'). Failure includes any | |
9582 | negative response to an \\AUTH\\ command, including (for example) an attempt to | |
9583 | use an undefined mechanism. | |
9584 | ||
9585 | ||
9586 | .index message||body, line count | |
9587 | .index body of message||line count | |
9588 | .tempindent 0 | |
9589 | \$body@_linecount$\: | |
9590 | When a message is being received or delivered, this variable contains the | |
9591 | number of lines in the message's body. | |
9592 | ||
9593 | .index message||body, binary zero count | |
9594 | .index body of message||binary zero count | |
9595 | .index binary zero||in message body | |
9596 | .tempindent 0 | |
495ae4b0 PH |
9597 | \$body@_zerocount$\: |
9598 | When a message is being received or delivered, this variable contains the | |
9599 | number of binary zero bytes in the message's body. | |
495ae4b0 PH |
9600 | |
9601 | .tempindent 0 | |
9602 | \$bounce@_recipient$\: | |
9603 | This is set to the recipient address of a bounce message while Exim is creating | |
9604 | it. It is useful if a customized bounce message text file is in use (see | |
9605 | chapter ~~CHAPemsgcust). | |
9606 | ||
9607 | .tempindent 0 | |
9608 | \$bounce@_return@_size@_limit$\: This contains the value set in the | |
9609 | \bounce@_return@_size@_limit\ option, rounded up to a multiple of 1000. It is | |
9610 | useful when a customized error message text file is in use (see chapter | |
9611 | ~~CHAPemsgcust). | |
9612 | ||
9613 | .index gid (group id)||caller | |
9614 | .tempindent 0 | |
4964e932 PH |
9615 | \$caller@_gid$\: The |
9616 | real | |
495ae4b0 PH |
9617 | group id under which the process that called Exim was |
9618 | running. This is not the same as the group id of the originator of a message | |
9619 | (see \$originator@_gid$\). If Exim re-execs itself, this variable in the new | |
9620 | incarnation normally contains the Exim gid. | |
9621 | ||
9622 | .index uid (user id)||caller | |
9623 | .tempindent 0 | |
4964e932 | 9624 | \$caller@_uid$\: The |
495ae4b0 | 9625 | real |
495ae4b0 PH |
9626 | user id under which the process that called Exim was |
9627 | running. This is not the same as the user id of the originator of a message | |
9628 | (see \$originator@_uid$\). If Exim re-execs itself, this variable in the new | |
9629 | incarnation normally contains the Exim uid. | |
9630 | ||
9631 | .tempindent 0 | |
9632 | \$compile@_date$\: The date on which the Exim binary was compiled. | |
9633 | ||
9634 | .tempindent 0 | |
9635 | \$compile@_number$\: The building process for Exim keeps a count of the number | |
9636 | of times it has been compiled. This serves to distinguish different | |
9637 | compilations of the same version of the program. | |
9638 | ||
d43194df PH |
9639 | .em |
9640 | .tempindent 0 | |
8408f763 PH |
9641 | \$demime@_errorlevel$\: This variable is available when Exim is compiled with |
9642 | the content-scanning extension and the obsolete \demime\ condition. For | |
9643 | details, see section ~~SECTdemimecond. | |
9644 | ||
9645 | .tempindent 0 | |
9646 | \$demime@_reason$\: This variable is available when Exim is compiled with the | |
9647 | content-scanning extension and the obsolete \demime\ condition. For details, | |
9648 | see section ~~SECTdemimecond. | |
d43194df PH |
9649 | .nem |
9650 | ||
495ae4b0 PH |
9651 | .index black list (DNS) |
9652 | .tempindent 0 | |
9653 | \$dnslist@_domain$\: When a client host is found to be on a DNS (black) list, | |
9654 | the list's domain name is put into this variable so that it can be included in | |
9655 | the rejection message. | |
9656 | ||
9657 | .tempindent 0 | |
9658 | \$dnslist@_text$\: When a client host is found to be on a DNS (black) list, the | |
9659 | contents of any associated TXT record are placed in this variable. | |
9660 | ||
9661 | .tempindent 0 | |
9662 | \$dnslist@_value$\: When a client host is found to be on a DNS (black) list, | |
9663 | the IP address from the resource record is placed in this variable. | |
4964e932 | 9664 | If there are multiple records, all the addresses are included, comma-space |
495ae4b0 PH |
9665 | separated. |
9666 | ||
9667 | .tempindent 0 | |
9668 | \$domain$\: When an address is being routed, or delivered on its own, this | |
9669 | variable contains the domain. Global address rewriting happens when a message | |
9670 | is received, so the value of \$domain$\ during routing and delivery is the | |
9671 | value after rewriting. \$domain$\ is set during user filtering, but not during | |
9672 | system filtering, because a message may have many recipients and the system | |
9673 | filter is called just once. | |
9674 | ||
9675 | When more than one address is being delivered at once (for example, several | |
9676 | \\RCPT\\ commands in one SMTP delivery), \$domain$\ is set only if they all | |
9677 | have the same domain. Transports can be restricted to handling only one domain | |
9678 | at a time if the value of \$domain$\ is required at transport time -- this is | |
9679 | the default for local transports. For further details of the environment in | |
9680 | which local transports are run, see chapter ~~CHAPenvironment. | |
9681 | ||
9682 | .index \delay@_warning@_condition\ | |
9683 | At the end of a delivery, if all deferred addresses have the same domain, it is | |
9684 | set in \$domain$\ during the expansion of \delay@_warning@_condition\. | |
9685 | ||
9686 | The \$domain$\ variable is also used in some other circumstances: | |
9687 | .numberpars $. | |
9688 | When an ACL is running for a \\RCPT\\ command, \$domain$\ contains the domain | |
9689 | of the recipient address. | |
4964e932 PH |
9690 | \**Note:**\ the domain of the sender address is in \$sender@_address@_domain$\ |
9691 | at \\MAIL\\ time and at \\RCPT\\ time. \$domain$\ is not set for the \\MAIL\\ | |
495ae4b0 PH |
9692 | ACL. |
9693 | .nextp | |
9694 | When a rewrite item is being processed (see chapter ~~CHAPrewrite), \$domain$\ | |
9695 | contains the domain portion of the address that is being rewritten; it can be | |
9696 | used in the expansion of the replacement address, for example, to rewrite | |
9697 | domains by file lookup. | |
9698 | .nextp | |
9699 | With one important exception, whenever a domain list is being scanned, | |
9700 | \$domain$\ contains the subject domain. \**Exception**\: When a domain list in | |
9701 | a \sender@_domains\ condition in an ACL is being processed, the subject domain | |
9702 | is in \$sender@_address@_domain$\ and not in \$domain$\. It works this way so | |
9703 | that, in a \\RCPT\\ ACL, the sender domain list can be dependent on the | |
9704 | recipient domain (which is what is in \$domain$\ at this time). | |
9705 | .nextp | |
9706 | .index \\ETRN\\||value of \$domain$\ | |
9707 | .index \smtp@_etrn@_command\ | |
9708 | When the \smtp@_etrn@_command\ option is being expanded, \$domain$\ contains | |
9709 | the complete argument of the \\ETRN\\ command (see section ~~SECTETRN). | |
9710 | .endp | |
9711 | ||
9712 | .tempindent 0 | |
9713 | \$domain@_data$\: When the \domains\ option on a router matches a domain by | |
9714 | means of a lookup, the data read by the lookup is available during the running | |
9715 | of the router as \$domain@_data$\. In addition, if the driver routes the | |
9716 | address to a transport, the value is available in that transport. If the | |
9717 | transport is handling multiple addresses, the value from the first address is | |
4964e932 | 9718 | used. |
495ae4b0 | 9719 | |
4964e932 PH |
9720 | \$domain@_data$\ is also set when the \domains\ condition in an ACL matches a |
9721 | domain by means of a lookup. The data read by the lookup is available during | |
495ae4b0 PH |
9722 | the rest of the ACL statement. In all other situations, this variable expands |
9723 | to nothing. | |
9724 | ||
495ae4b0 PH |
9725 | .tempindent 0 |
9726 | \$exim@_gid$\: This variable contains the numerical value of the Exim group id. | |
9727 | ||
9728 | .tempindent 0 | |
9729 | \$exim@_path$\: This variable contains the path to the Exim binary. | |
9730 | ||
9731 | .tempindent 0 | |
9732 | \$exim@_uid$\: This variable contains the numerical value of the Exim user id. | |
495ae4b0 | 9733 | |
d43194df PH |
9734 | .em |
9735 | .tempindent 0 | |
9736 | \$found@_extension$\: This variable is available when Exim is compiled with the | |
9737 | content-scanning extension and the obsolete \demime\ condition. For details, | |
9738 | see section ~~SECTdemimecond. | |
9739 | .nem | |
9740 | ||
495ae4b0 PH |
9741 | .tempindent 0 |
9742 | \$header@_<<name>>$\: This is not strictly an expansion variable. It is | |
9743 | expansion syntax for inserting the message header line with the given name. | |
9744 | Note that the name must be terminated by colon or white space, because it may | |
9745 | contain a wide variety of characters. | |
9746 | Note also that braces must \*not*\ be used. | |
9747 | ||
9748 | .tempindent 0 | |
9749 | \$home$\: | |
9750 | When the \check@_local@_user\ option is set for a router, the user's home | |
9751 | directory is placed in \$home$\ when the check succeeds. In particular, this | |
9752 | means it is set during the running of users' filter files. A router may also | |
9753 | explicitly set a home directory for use by a transport; this can be overridden | |
9754 | by a setting on the transport itself. | |
9755 | ||
9756 | When running a filter test via the \-bf-\ option, \$home$\ is set to the value | |
9757 | of the environment variable \\HOME\\. | |
9758 | ||
9759 | .tempindent 0 | |
9760 | \$host$\: | |
9761 | When the \%smtp%\ transport is expanding its options for encryption using TLS, | |
9762 | \$host$\ contains the name of the host to which it is connected. Likewise, when | |
9763 | used in the client part of an authenticator configuration (see chapter | |
9764 | ~~CHAPSMTPAUTH), \$host$\ contains the name of the server to which the client | |
9765 | is connected. | |
9766 | .index transport||filter | |
9767 | .index filter||transport filter | |
9768 | When used in a transport filter (see chapter ~~CHAPtransportgeneric) \$host$\ | |
9769 | refers to the host involved in the current connection. When a local transport | |
9770 | is run as a result of a router that sets up a host list, \$host$\ contains the | |
9771 | name of the first host. | |
9772 | ||
9773 | .tempindent 0 | |
9774 | \$host@_address$\: | |
9775 | This variable is set to the remote host's IP address whenever \$host$\ is set | |
9776 | for a remote connection. | |
d43194df PH |
9777 | .em |
9778 | It is also set to the IP address that is being checked when the | |
9779 | \ignore@_target@_hosts\ option is being processed. | |
9780 | .nem | |
495ae4b0 PH |
9781 | |
9782 | .tempindent 0 | |
9783 | \$host@_data$\: | |
9784 | If a \hosts\ condition in an ACL is satisfied by means of a lookup, the result | |
9785 | of the lookup is made available in the \$host@_data$\ variable. This | |
9786 | allows you, for example, to do things like this: | |
9787 | .display asis | |
9788 | deny hosts = net-lsearch;/some/file | |
9789 | message = $host_data | |
9790 | .endd | |
9791 | ||
d43194df | 9792 | .em |
495ae4b0 PH |
9793 | .index host||name lookup, failure of |
9794 | .tempindent 0 | |
d43194df PH |
9795 | \$host@_lookup@_deferred$\: |
9796 | This variable normally contains `0', as does \$host@_lookup@_failed$\. When a | |
9797 | message comes from a remote host and there is an attempt to look up the host's | |
9798 | name from its IP address, and the attempt is not successful, one of these | |
9799 | variables is set to `1'. | |
9800 | .numberpars $. | |
9801 | If the lookup receives a definite negative response (for example, a DNS lookup | |
9802 | succeeded, but no records were found), \$host@_lookup@_failed$\ is set to `1'. | |
9803 | .nextp | |
9804 | If there is any kind of problem during the lookup, such that Exim cannot | |
9805 | tell whether or not the host name is defined (for example, a timeout for a DNS | |
9806 | lookup), \$host@_lookup@_deferred$\ is set to `1'. | |
9807 | .endp | |
9808 | Looking up a host's name from its IP address consists of more than just a | |
9809 | single reverse lookup. Exim checks that a forward lookup of at least one of the | |
9810 | names it receives from a reverse lookup yields the original IP address. If this | |
9811 | is not the case, Exim does not accept the looked up name(s), and | |
9812 | \$host@_lookup@_failed$\ is set to `1'. Thus, being able to find a name from an | |
9813 | IP address (for example, the existence of a PTR record in the DNS) is not | |
9814 | sufficient on its own for the success of a host name lookup. If the reverse | |
9815 | lookup succeeds, but there is a lookup problem such as a timeout when checking | |
9816 | the result, the name is not accepted, and \$host@_lookup@_deferred$\ is set to | |
9817 | `1'. See also \$sender@_host@_name$\. | |
9818 | ||
9819 | .tempindent 0 | |
9820 | \$host@_lookup@_failed$\: See \$host@_lookup@_deferred$\. | |
9821 | .nem | |
495ae4b0 PH |
9822 | |
9823 | .tempindent 0 | |
9824 | \$inode$\: | |
9825 | The only time this variable is set is while expanding the \directory@_file\ | |
9826 | option in the \%appendfile%\ transport. The variable contains the inode number | |
9827 | of the temporary file which is about to be renamed. It can be used to construct | |
9828 | a unique name for the file. | |
9829 | ||
9830 | .tempindent 0 | |
9831 | \$interface@_address$\: | |
9832 | When a message is received over a TCP/IP connection, this variable contains the | |
9833 | address of the local IP interface. See also the \-oMi-\ command line option. | |
4964e932 | 9834 | This variable can be used in ACLs and also, for example, to make the file name |
495ae4b0 PH |
9835 | for a TLS certificate depend on which interface is being used. |
9836 | ||
9837 | .tempindent 0 | |
9838 | \$interface@_port$\: | |
9839 | When a message is received over a TCP/IP connection, this variable contains the | |
9840 | local port number. See also the \-oMi-\ command line option. | |
4964e932 | 9841 | This variable can be used in ACLs and also, for example, to make the file name |
495ae4b0 PH |
9842 | for a TLS certificate depend on which port is being used. |
9843 | ||
9844 | .tempindent 0 | |
9845 | \$ldap@_dn$\: | |
4964e932 PH |
9846 | This variable, which is available only when Exim is compiled with LDAP support, |
9847 | contains the DN from the last entry in the most recently successful LDAP | |
495ae4b0 PH |
9848 | lookup. |
9849 | ||
495ae4b0 PH |
9850 | .tempindent 0 |
9851 | \$load@_average$\: | |
4964e932 PH |
9852 | This variable contains the system load average, multiplied by 1000 to that it |
9853 | is an integer. For example, if the load average is 0.21, the value of the | |
495ae4b0 PH |
9854 | variable is 210. The value is recomputed every time the variable is referenced. |
9855 | ||
9856 | .tempindent 0 | |
9857 | \$local@_part$\: When an address is being routed, or delivered on its own, this | |
9858 | variable contains the local part. When a number of addresses are being | |
9859 | delivered together (for example, multiple \\RCPT\\ commands in an SMTP | |
9860 | session), \$local@_part$\ is not set. | |
9861 | ||
9862 | Global address rewriting happens when a message is received, so the value of | |
9863 | \$local@_part$\ during routing and delivery is the value after rewriting. | |
9864 | \$local@_part$\ is set during user filtering, but not during system filtering, | |
9865 | because a message may have many recipients and the system filter is called just | |
9866 | once. | |
9867 | ||
9868 | If a local part prefix or suffix has been recognized, it is not included in the | |
9869 | value of \$local@_part$\ during routing and subsequent delivery. The values of | |
9870 | any prefix or suffix are in \$local@_part@_prefix$\ and | |
9871 | \$local@_part@_suffix$\, respectively. | |
9872 | ||
9873 | When a message is being delivered to a file, pipe, or autoreply transport as a | |
9874 | result of aliasing or forwarding, \$local@_part$\ is set to the local part of | |
9875 | the parent address, not to the file name or command (see \$address@_file$\ and | |
9876 | \$address@_pipe$\). | |
9877 | ||
9878 | When an ACL is running for a \\RCPT\\ command, \$local@_part$\ contains the | |
9879 | local part of the recipient address. | |
9880 | ||
9881 | When a rewrite item is being processed (see chapter ~~CHAPrewrite), | |
9882 | \$local@_part$\ contains the local part of the address that is being rewritten; | |
9883 | it can be used in the expansion of the replacement address, for example. | |
9884 | ||
9885 | In all cases, all quoting is removed from the local part. For example, for both | |
9886 | the addresses | |
9887 | .display asis | |
9888 | "abc:xyz"@test.example | |
9889 | abc\:xyz@test.example | |
9890 | .endd | |
9891 | the value of \$local@_part$\ is | |
9892 | .display asis | |
9893 | abc:xyz | |
9894 | .endd | |
9895 | If you use \$local@_part$\ to create another address, you should always wrap it | |
9896 | inside a quoting operator. For example, in a \%redirect%\ router you could have: | |
9897 | .display asis | |
9898 | data = ${quote_local_part:$local_part}@new.domain.example | |
9899 | .endd | |
4964e932 PH |
9900 | \**Note**\: The value of \$local@_part$\ is normally lower cased. If you want |
9901 | to process local parts in a case-dependent manner in a router, you can set the | |
495ae4b0 | 9902 | \caseful@_local@_part\ option (see chapter ~~CHAProutergeneric). |
495ae4b0 PH |
9903 | |
9904 | .tempindent 0 | |
9905 | \$local@_part@_data$\: | |
9906 | When the \local@_parts\ option on a router matches a local part by means of a | |
9907 | lookup, the data read by the lookup is available during the running of the | |
9908 | router as \$local@_part@_data$\. In addition, if the driver routes the address | |
9909 | to a transport, the value is available in that transport. If the transport is | |
9910 | handling multiple addresses, the value from the first address is used. | |
9911 | ||
9912 | \$local@_part@_data$\ is also set when the \local@_parts\ condition in an ACL | |
9913 | matches a local part by means of a lookup. The data read by the lookup is | |
9914 | available during the rest of the ACL statement. In all other situations, this | |
9915 | variable expands to nothing. | |
9916 | ||
9917 | .tempindent 0 | |
9918 | \$local@_part@_prefix$\: When an address is being routed or delivered, and a | |
9919 | specific prefix for the local part was recognized, it is available in this | |
9920 | variable, having been removed from \$local@_part$\. | |
9921 | ||
9922 | .tempindent 0 | |
9923 | \$local@_part@_suffix$\: When an address is being routed or delivered, and a | |
9924 | specific suffix for the local part was recognized, it is available in this | |
9925 | variable, having been removed from \$local@_part$\. | |
9926 | ||
9927 | .tempindent 0 | |
9928 | \$local@_scan@_data$\: This variable contains the text returned by the | |
9929 | \*local@_scan()*\ function when a message is received. See chapter | |
9930 | ~~CHAPlocalscan for more details. | |
9931 | ||
9932 | .tempindent 0 | |
9933 | \$local@_user@_gid$\: See \$local@_user@_uid$\. | |
9934 | ||
9935 | .tempindent 0 | |
9936 | \$local@_user@_uid$\: This variable and \$local@_user@_gid$\ are set to | |
9937 | the uid and gid after the \check__local__user\ router precondition succeeds. | |
9938 | This means that their values are available for the remaining preconditions | |
9939 | (\senders\, \require@_files\, and \condition\), for the \address@_data\ | |
9940 | expansion, and for any router-specific expansions. At all other times, the | |
9941 | values in these variables are \"(uid@_t)(-1)"\ and \"(gid@_t)(-1)"\, | |
9942 | respectively. | |
9943 | ||
495ae4b0 PH |
9944 | .tempindent 0 |
9945 | \$localhost@_number$\: This contains the expanded value of the | |
9946 | \localhost@_number\ option. The expansion happens after the main options have | |
9947 | been read. | |
9948 | ||
d43194df PH |
9949 | .em |
9950 | .tempindent 0 | |
9951 | \$log@_inodes$\: The number of free inodes in the disk partition where Exim's | |
9952 | log files are being written. The value is recalculated whenever the variable is | |
9953 | referenced. If the relevant file system does not have the concept of inodes, | |
9954 | the value of is -1. See also the \check@_log@_inodes\ option. | |
9955 | ||
9956 | .tempindent 0 | |
9957 | \$log@_space$\: The amount of free space (as a number of kilobytes) in the disk | |
9958 | partition where Exim's log files are being written. The value is recalculated | |
9959 | whenever the variable is referenced. If the operating system does not have the | |
9960 | ability to find the amount of free space (only true for experimental systems), | |
9961 | the space value is -1. See also the \check@_log@_space\ option. | |
9962 | .nem | |
9963 | ||
495ae4b0 | 9964 | .tempindent 0 |
4964e932 PH |
9965 | \$mailstore@_basename$\: This variable is set only when doing deliveries in |
9966 | `mailstore' format in the \%appendfile%\ transport. During the expansion of the | |
9967 | \mailstore@_prefix\, \mailstore@_suffix\, \message__prefix\, and | |
495ae4b0 PH |
9968 | \message@_suffix\ options, it contains the basename of the files that are being |
9969 | written, that is, the name without the `.tmp', `.env', or `.msg' suffix. At all | |
9970 | other times, this variable is empty. | |
9971 | ||
d43194df PH |
9972 | .em |
9973 | .tempindent 0 | |
9974 | \$malware@_name$\: This variable is available when Exim is compiled with the | |
9975 | content-scanning extension. It is set to the name of the virus that was found | |
9976 | when the ACL \malware\ condition is true (see section ~~SECTscanvirus). | |
9977 | .nem | |
9978 | ||
495ae4b0 PH |
9979 | .index message||age of |
9980 | .tempindent 0 | |
9981 | \$message@_age$\: This variable is set at the start of a delivery attempt to | |
9982 | contain the number of seconds since the message was received. It does not | |
9983 | change during a single delivery attempt. | |
9984 | ||
9985 | .index body of message||expansion variable | |
9986 | .index message||body, in expansion | |
9987 | .index binary zero||in message body | |
9988 | .tempindent 0 | |
9989 | \$message@_body$\: This variable contains the initial portion of a message's | |
9990 | body while it is being delivered, and is intended mainly for use in filter | |
9991 | files. The maximum number of characters of the body that are put into the | |
9992 | variable is set by the \message@_body@_visible\ configuration option; the | |
9993 | default is 500. Newlines are converted into spaces to make it easier to search | |
9994 | for phrases that might be split over a line break. | |
9995 | Binary zeros are also converted into spaces. | |
9996 | ||
9997 | .index body of message||expansion variable | |
9998 | .index message||body, in expansion | |
9999 | .tempindent 0 | |
10000 | \$message@_body@_end$\: This variable contains the final portion of a message's | |
10001 | body while it is being delivered. The format and maximum size are as for | |
10002 | \$message@_body$\. | |
10003 | ||
10004 | .index body of message||size | |
10005 | .index message||body, size | |
10006 | .tempindent 0 | |
d43194df | 10007 | \$message@_body@_size$\: When a message is being delivered, this variable |
495ae4b0 PH |
10008 | contains the size of the body in bytes. The count starts from the character |
10009 | after the blank line that separates the body from the header. Newlines are | |
d43194df PH |
10010 | included in the count. See also \$message@_size$\, \$body@_linecount$\, and |
10011 | \$body@_zerocount$\. | |
495ae4b0 PH |
10012 | |
10013 | .tempindent 0 | |
10014 | \$message@_headers$\: | |
10015 | This variable contains a concatenation of all the header lines when a message | |
10016 | is being processed, except for lines added by routers or transports. The header | |
10017 | lines are separated by newline characters. | |
10018 | ||
10019 | .tempindent 0 | |
4964e932 | 10020 | \$message@_id$\: |
495ae4b0 PH |
10021 | When a message is being received or delivered, this variable contains the |
10022 | unique message id that is used by Exim to identify the message. | |
4964e932 | 10023 | An id is not created for a message until after its header has been |
495ae4b0 | 10024 | successfully received. |
4964e932 PH |
10025 | \**Note**\: This is \*not*\ the contents of the ::Message-ID:: header line; it |
10026 | is the local id that Exim assigns to the message, for example: | |
495ae4b0 | 10027 | \"1BXTIK-0001yO-VA"\. |
495ae4b0 PH |
10028 | |
10029 | .index size||of message | |
10030 | .index message||size | |
10031 | .tempindent 0 | |
4964e932 | 10032 | \$message@_size$\: |
495ae4b0 PH |
10033 | When a message is being processed, this variable contains its size in bytes. In |
10034 | most cases, the size includes those headers that were received with the | |
10035 | message, but not those (such as ::Envelope-to::) that are added to individual | |
10036 | deliveries as they are written. However, there is one special case: during the | |
10037 | expansion of the \maildir@_tag\ option in the \%appendfile%\ transport while | |
10038 | doing a delivery in maildir format, the value of \$message@_size$\ is the | |
10039 | precise size of the file that has been written. See also | |
d43194df | 10040 | \$message@_body@_size$\, \$body@_linecount$\, and \$body@_zerocount$\. |
495ae4b0 PH |
10041 | |
10042 | .index \\RCPT\\||value of \$message@_size$\ | |
10043 | While running an ACL at the time of an SMTP \\RCPT\\ command, \$message@_size$\ | |
4964e932 | 10044 | contains the size supplied on the \\MAIL\\ command, or |
495ae4b0 PH |
10045 | -1 |
10046 | if no size was given. The value may not, of course, be truthful. | |
10047 | ||
d43194df PH |
10048 | .em |
10049 | .tempindent 0 | |
8408f763 PH |
10050 | \$mime@_$\\*xxx*\: A number of variables whose names start with \$mime$\ are |
10051 | available when Exim is compiled with the content-scanning extension. For | |
10052 | details, see section ~~SECTscanmimepart. | |
d43194df PH |
10053 | .nem |
10054 | ||
495ae4b0 PH |
10055 | .tempindent 0 |
10056 | \$n0$\ -- \$n9$\: These variables are counters that can be incremented by means | |
10057 | of the \add\ command in filter files. | |
10058 | ||
10059 | .tempindent 0 | |
10060 | \$original@_domain$\: When a top-level address is being processed for delivery, | |
10061 | this contains the same value as \$domain$\. However, if a `child' address (for | |
10062 | example, generated by an alias, forward, or filter file) is being processed, | |
10063 | this variable contains the domain of the original address. This differs from | |
10064 | \$parent@_domain$\ only when there is more than one level of aliasing or | |
10065 | forwarding. When more than one address is being delivered in a single transport | |
10066 | run, \$original@_domain$\ is not set. | |
10067 | ||
10068 | If new an address is created by means of a \deliver\ command in a system | |
10069 | filter, it is set up with an artificial `parent' address. This has the local | |
10070 | part \*system-filter*\ and the default qualify domain. | |
10071 | ||
10072 | .tempindent 0 | |
10073 | \$original@_local@_part$\: When a top-level address is being processed for | |
10074 | delivery, this contains the same value as \$local@_part$\, unless a prefix or | |
d43194df PH |
10075 | suffix was removed from the local part, because \$original@_local@_part$\ |
10076 | always contains the full local part. When a `child' address (for example, | |
10077 | generated by an alias, forward, or filter file) is being processed, this | |
10078 | variable contains the full local part of the original address. | |
10079 | ||
10080 | If the router that did the redirection processed the local part | |
10081 | case-insensitively, the value in \$original@_local@_part$\ is in lower case. | |
10082 | This variable differs from \$parent@_local@_part$\ only when there is more than | |
10083 | one level of aliasing or forwarding. When more than one address is being | |
10084 | delivered in a single transport run, \$original@_local@_part$\ is not set. | |
495ae4b0 PH |
10085 | |
10086 | If new an address is created by means of a \deliver\ command in a system | |
10087 | filter, it is set up with an artificial `parent' address. This has the local | |
10088 | part \*system-filter*\ and the default qualify domain. | |
10089 | ||
10090 | ||
10091 | .index gid (group id)||of originating user | |
10092 | .index sender||gid | |
10093 | .tempindent 0 | |
10094 | \$originator@_gid$\: The value of \$caller@_gid$\ that was set when the message | |
10095 | was received. For messages received via the command line, this is the gid of | |
10096 | the sending user. For messages received by SMTP over TCP/IP, this is normally | |
10097 | the gid of the Exim user. | |
10098 | ||
10099 | .index uid (user id)||of originating user | |
10100 | .index sender||uid | |
10101 | .tempindent 0 | |
10102 | \$originator@_uid$\: The value of \$caller@_uid$\ that was set when the message | |
10103 | was received. For messages received via the command line, this is the uid of | |
10104 | the sending user. For messages received by SMTP over TCP/IP, this is normally | |
10105 | the uid of the Exim user. | |
10106 | ||
10107 | .tempindent 0 | |
10108 | \$parent@_domain$\: This variable is similar to \$original@_domain$\ (see | |
10109 | above), except that it refers to the immediately preceding parent address. | |
10110 | ||
10111 | .tempindent 0 | |
10112 | \$parent@_local@_part$\: This variable is similar to \$original@_local@_part$\ | |
10113 | (see above), except that it refers to the immediately preceding parent address. | |
10114 | ||
10115 | .index pid (process id)||of current process | |
10116 | .tempindent 0 | |
10117 | \$pid$\: This variable contains the current process id. | |
10118 | ||
10119 | .index filter||transport filter | |
10120 | .index transport||filter | |
10121 | .tempindent 0 | |
10122 | \$pipe@_addresses$\: This is not an expansion variable, but is mentioned here | |
10123 | because the string `@$pipe@_addresses' is handled specially in the command | |
10124 | specification for the \%pipe%\ transport (chapter ~~CHAPpipetransport) and in | |
10125 | transport filters (described under \transport@_filter\ in chapter | |
10126 | ~~CHAPtransportgeneric). It cannot be used in general expansion strings, and | |
10127 | provokes an `unknown variable' error if encountered. | |
10128 | ||
10129 | .tempindent 0 | |
10130 | \$primary@_hostname$\: The value set in the configuration file, or read by the | |
10131 | \*uname()*\ function. If \*uname()*\ returns a single-component name, Exim | |
10132 | calls \*gethostbyname()*\ (or \*getipnodebyname()*\ where available) in an | |
10133 | attempt to acquire a fully qualified host name. | |
495ae4b0 | 10134 | See also \$smtp@_active@_hostname$\. |
495ae4b0 PH |
10135 | |
10136 | .tempindent 0 | |
10137 | \$qualify@_domain$\: The value set for this option in the configuration file. | |
10138 | ||
10139 | .tempindent 0 | |
10140 | \$qualify@_recipient$\: The value set for this option in the configuration file, | |
10141 | or if not set, the value of \$qualify@_domain$\. | |
10142 | ||
10143 | .tempindent 0 | |
4964e932 | 10144 | \$rcpt@_count$\: When a message is being received by SMTP, this variable |
495ae4b0 PH |
10145 | contains the number of \\RCPT\\ commands received for the current message. If |
10146 | this variable is used in a \\RCPT\\ ACL, its value includes the current | |
10147 | command. | |
10148 | ||
10149 | .tempindent 0 | |
4964e932 | 10150 | \$rcpt@_defer@_count$\: When a message is being received by SMTP, this variable |
495ae4b0 PH |
10151 | contains the number of \\RCPT\\ commands in the current message that have |
10152 | previously been rejected with a temporary (4\*xx*\) response. | |
10153 | ||
10154 | .tempindent 0 | |
10155 | \$rcpt@_fail@_count$\: When a message is being received by SMTP, this variable | |
10156 | contains the number of \\RCPT\\ commands in the current message that have | |
10157 | previously been rejected with a permanent (5\*xx*\) response. | |
10158 | ||
10159 | .tempindent 0 | |
10160 | \$received@_count$\: This variable contains the number of ::Received:: header | |
10161 | lines in the message, including the one added by Exim (so its value is always | |
10162 | greater than zero). It is available in the \\DATA\\ ACL, the non-SMTP ACL, and | |
10163 | while routing and delivering. | |
10164 | ||
10165 | .tempindent 0 | |
10166 | \$received@_for$\: If there is only a single recipient address in an incoming | |
10167 | message, this variable contains that address when the ::Received:: header line | |
10168 | is being built. | |
495ae4b0 PH |
10169 | The value is copied after recipient rewriting has happened, but before the |
10170 | \*local@_scan()*\ function is run. | |
495ae4b0 PH |
10171 | |
10172 | .tempindent 0 | |
10173 | \$received@_protocol$\: When a message is being processed, this variable | |
d43194df PH |
10174 | contains the name of the protocol by which it was received. |
10175 | .em | |
10176 | Most of the names used by Exim are defined by RFCs 821, 2821, and 3848. They | |
10177 | start with `smtp' (the client used \\HELO\\) or `esmtp' (the client used | |
10178 | \\EHLO\\). This can be followed by `s' for secure (encrypted) and/or `a' for | |
10179 | authenticated. Thus, for example, if the protocol is set to `esmtpsa', the | |
10180 | message was received over an encrypted SMTP connection and the client was | |
10181 | successfully authenticated. | |
10182 | ||
8408f763 PH |
10183 | Exim uses the protocol name `smtps' for the case when encryption is |
10184 | automatically set up on connection without the use of \\STARTTLS\\ (see | |
10185 | \tls@_on@_connect@_ports\), and the client uses \\HELO\\ to initiate the | |
10186 | encrypted SMTP session. The name `smtps' is also used for the rare situation | |
10187 | where the client initially uses \\EHLO\\, sets up an encrypted connection using | |
10188 | \\STARTTLS\\, and then uses \\HELO\\ afterwards. | |
d43194df PH |
10189 | |
10190 | The \-oMr-\ option provides a way of specifying a custom protocol name for | |
10191 | messages that are injected locally by trusted callers. This is commonly used to | |
10192 | identify messages that are being re-injected after some kind of scanning. | |
10193 | .nem | |
495ae4b0 | 10194 | |
495ae4b0 PH |
10195 | .tempindent 0 |
10196 | \$recipient@_data$\: This variable is set after an indexing lookup success in | |
10197 | an ACL \recipients\ condition. It contains the data from the lookup, and the | |
10198 | value remains set until the next \recipients\ test. Thus, you can do things | |
10199 | like this: | |
10200 | .display | |
10201 | require recipients = cdb*@@;/some/file | |
10202 | deny \*some further test involving*\ @$recipient@_data | |
10203 | .endd | |
4964e932 | 10204 | \**Warning**\: This variable is set only when a lookup is used as an indexing |
495ae4b0 PH |
10205 | method in the address list, using the semicolon syntax as in the example above. |
10206 | The variable is not set for a lookup that is used as part of the string | |
10207 | expansion that all such lists undergo before being interpreted. | |
495ae4b0 | 10208 | |
d43194df PH |
10209 | .em |
10210 | .tempindent 0 | |
10211 | \$recipient@_verify@_failure$\: In an ACL, when a recipient verification fails, | |
10212 | this variable contains information about the failure. It is set to one of the | |
10213 | following words: | |
10214 | .numberpars " " | |
10215 | `qualify': The address was unqualified (no domain), and the message | |
10216 | was neither local nor came from an exempted host. | |
10217 | .nextp | |
10218 | `route': Routing failed. | |
10219 | .nextp | |
10220 | `mail': Routing succeeded, and a callout was attempted; rejection occurred at | |
10221 | or before the \\MAIL\\ command (that is, on initial connection, \\HELO\\, or | |
10222 | \\MAIL\\). | |
10223 | .nextp | |
10224 | `recipient': The \\RCPT\\ command in a callout was rejected. | |
10225 | .nextp | |
10226 | `postmaster': The postmaster check in a callout was rejected. | |
10227 | .endp | |
10228 | The main use of this variable is expected to be to distinguish between | |
10229 | rejections of \\MAIL\\ and rejections of \\RCPT\\. | |
10230 | .nem | |
10231 | ||
495ae4b0 PH |
10232 | .tempindent 0 |
10233 | \$recipients$\: This variable contains a list of envelope recipients for a | |
10234 | message. A comma and a space separate the addresses in the replacement text. | |
10235 | However, the variable is not generally available, to prevent exposure of Bcc | |
10236 | recipients in unprivileged users' filter files. You can use \$recipients$\ only | |
d43194df | 10237 | in these two cases: |
495ae4b0 PH |
10238 | .numberpars |
10239 | In a system filter file. | |
10240 | .nextp | |
d43194df PH |
10241 | .em |
10242 | In the ACLs associated with the \\DATA\\ command, that is, the ACLs defined by | |
10243 | \acl@_smtp@_predata\ and \acl@_smtp@_data\. | |
10244 | .nem | |
495ae4b0 PH |
10245 | .endp |
10246 | ||
10247 | .tempindent 0 | |
10248 | \$recipients@_count$\: When a message is being processed, this variable | |
10249 | contains the number of envelope recipients that came with the message. | |
10250 | Duplicates are not excluded from the count. While a message is being received | |
10251 | over SMTP, the number increases for each accepted recipient. It can be | |
10252 | referenced in an ACL. | |
10253 | ||
10254 | .tempindent 0 | |
10255 | \$reply@_address$\: When a message is being processed, this variable contains | |
10256 | the contents of the ::Reply-To:: header line if one exists | |
10257 | and it is not empty, | |
10258 | or otherwise the contents of the ::From:: header line. | |
10259 | ||
10260 | .tempindent 0 | |
10261 | \$return@_path$\: When a message is being delivered, this variable contains the | |
10262 | return path -- the sender field that will be sent as part of the envelope. It | |
4964e932 PH |
10263 | is not enclosed in @<@> characters. |
10264 | At the start of routing an address, | |
495ae4b0 PH |
10265 | \$return@_path$\ has the same value as \$sender@_address$\, but if, for |
10266 | example, an incoming message to a mailing list has been expanded by a router | |
10267 | which specifies a different address for bounce messages, \$return@_path$\ | |
10268 | subsequently contains the new bounce address, whereas \$sender@_address$\ | |
10269 | always contains the original sender address that was received with the message. | |
4964e932 | 10270 | In other words, \$sender@_address$\ contains the incoming envelope sender, and |
495ae4b0 PH |
10271 | \$return@_path$\ contains the outgoing envelope sender. |
10272 | ||
10273 | .tempindent 0 | |
10274 | \$return@_size@_limit$\: This is an obsolete name for | |
10275 | \$bounce@_return@_size@_limit$\. | |
10276 | ||
10277 | .index return code||from \run\ expansion | |
10278 | .tempindent 0 | |
10279 | \$runrc$\: This variable contains the return code from a command that is run by | |
10280 | the \@$@{run...@}\ expansion item. | |
4964e932 PH |
10281 | \**Warning**\: In a router or transport, you cannot assume the order in which |
10282 | option values are expanded, except for those pre-conditions whose order of | |
10283 | testing is documented. Therefore, you cannot reliably expect to set \$runrc$\ | |
495ae4b0 PH |
10284 | by the expansion of one option, and use it in another. |
10285 | ||
10286 | .tempindent 0 | |
10287 | \$self@_hostname$\: When an address is routed to a supposedly remote host that | |
4964e932 | 10288 | turns out to be the local host, what happens is controlled by the |
495ae4b0 PH |
10289 | .index \self\ option||value of host name |
10290 | \self\ generic router option. One of its values causes the address to be passed | |
10291 | to another router. When this happens, \$self@_hostname$\ is set to the name of | |
10292 | the local host that the original router encountered. In other circumstances its | |
10293 | contents are null. | |
10294 | ||
10295 | .tempindent 0 | |
10296 | \$sender@_address$\: When a message is being processed, this variable contains | |
10297 | the sender's address that was received in the message's envelope. For bounce | |
10298 | messages, the value of this variable is the empty string. | |
10299 | See also \$return@_path$\. | |
10300 | ||
d43194df PH |
10301 | .em |
10302 | .tempindent 0 | |
10303 | \$sender@_address@_data$\: If \$address@_data$\ is set when the routers are | |
10304 | called from an ACL to verify a sender address, the final value is preserved in | |
10305 | \$sender@_address@_data$\, to distinguish it from data from a recipient | |
10306 | address. The value does not persist after the end of the current ACL statement. | |
10307 | If you want to preserve it for longer, you can save it in an ACL variable. | |
10308 | .nem | |
10309 | ||
495ae4b0 PH |
10310 | .tempindent 0 |
10311 | \$sender@_address@_domain$\: The domain portion of \$sender@_address$\. | |
10312 | ||
10313 | .tempindent 0 | |
10314 | \$sender@_address@_local@_part$\: The local part portion of \$sender@_address$\. | |
10315 | ||
495ae4b0 | 10316 | .tempindent 0 |
4964e932 | 10317 | \$sender@_data$\: This variable is set after a lookup success in an ACL |
495ae4b0 PH |
10318 | \senders\ condition or in a router \senders\ option. It contains the data from |
10319 | the lookup, and the value remains set until the next \senders\ test. Thus, you | |
10320 | can do things like this: | |
10321 | .display | |
10322 | require senders = cdb*@@;/some/file | |
10323 | deny \*some further test involving*\ @$sender@_data | |
10324 | .endd | |
4964e932 | 10325 | \**Warning**\: This variable is set only when a lookup is used as an indexing |
495ae4b0 PH |
10326 | method in the address list, using the semicolon syntax as in the example above. |
10327 | The variable is not set for a lookup that is used as part of the string | |
10328 | expansion that all such lists undergo before being interpreted. | |
495ae4b0 PH |
10329 | |
10330 | .tempindent 0 | |
10331 | \$sender@_fullhost$\: When a message is received from a remote host, this | |
10332 | variable contains the host name and IP address in a single string. It ends | |
10333 | with the IP address in square brackets, followed by a colon and a port number | |
10334 | if the logging of ports is enabled. The format of the rest of the string | |
10335 | depends on whether the host issued a \\HELO\\ or \\EHLO\\ SMTP command, and | |
10336 | whether the host name was verified by looking up its IP address. (Looking up | |
10337 | the IP address can be forced by the \host@_lookup\ option, independent of | |
10338 | verification.) A plain host name at the start of the string is a verified host | |
10339 | name; if this is not present, verification either failed or was not requested. | |
10340 | A host name in parentheses is the argument of a \\HELO\\ or \\EHLO\\ command. | |
10341 | This is omitted if it is identical to the verified host name or to the host's | |
10342 | IP address in square brackets. | |
10343 | ||
10344 | .tempindent 0 | |
10345 | \$sender@_helo@_name$\: When a message is received from a remote host that has | |
10346 | issued a \\HELO\\ or \\EHLO\\ command, the argument of that command is placed | |
10347 | in this variable. It is also set if \\HELO\\ or \\EHLO\\ is used when a message | |
10348 | is received using SMTP locally via the \-bs-\ or \-bS-\ options. | |
10349 | ||
10350 | .tempindent 0 | |
10351 | \$sender@_host@_address$\: When a message is received from a remote host, this | |
10352 | variable contains that host's IP address. For locally submitted messages, it is | |
10353 | empty. | |
10354 | ||
10355 | .tempindent 0 | |
10356 | \$sender@_host@_authenticated$\: This variable contains the name (not the | |
10357 | public name) of the authenticator driver which successfully authenticated the | |
10358 | client from which the message was received. It is empty if there was no | |
10359 | successful authentication. | |
10360 | ||
10361 | .tempindent 0 | |
10362 | \$sender@_host@_name$\: When a message is received from a remote host, this | |
4964e932 | 10363 | variable contains the host's name as obtained by looking up its IP address. |
495ae4b0 PH |
10364 | For messages received by other means, this variable is empty. |
10365 | ||
10366 | If the host name has not previously been looked up, a reference to | |
4964e932 | 10367 | \$sender@_host@_name$\ triggers a lookup (for messages from remote hosts). |
495ae4b0 | 10368 | A looked up name is accepted only if it leads back to the original IP address |
d43194df PH |
10369 | via a forward lookup. If either the reverse or the forward lookup fails |
10370 | .em | |
10371 | to find any data, | |
10372 | .nem | |
10373 | or if the forward lookup does not yield the original IP address, | |
495ae4b0 PH |
10374 | \$sender@_host@_name$\ remains empty, and \$host@_lookup@_failed$\ is set to |
10375 | `1'. | |
d43194df PH |
10376 | .em |
10377 | However, if either of the lookups cannot be completed (for example, there is a | |
10378 | DNS timeout), \$host@_lookup@_deferred$\ is set to `1', and | |
10379 | \$host@_lookup@_failed$\ remains set to `0'. | |
10380 | ||
10381 | Once \$host@_lookup@_failed$\ is set to `1', Exim does not try to look up the | |
10382 | host name again if there is a subsequent reference to \$sender@_host@_name$\ | |
10383 | in the same Exim process, but it does try again if \$sender@_host@_deferred$\ | |
10384 | is set to `1'. | |
10385 | .nem | |
495ae4b0 PH |
10386 | |
10387 | Exim does not automatically look up every calling host's name. If you want | |
10388 | maximum efficiency, you should arrange your configuration so that it avoids | |
10389 | these lookups altogether. The lookup happens only if one or more of the | |
10390 | following are true: | |
10391 | .numberpars | |
10392 | A string containing \$sender@_host@_name$\ is expanded. | |
10393 | .nextp | |
4964e932 | 10394 | The calling host matches the list in \host@_lookup\. In the default |
495ae4b0 PH |
10395 | configuration, this option is set to $*$, so it must be changed if lookups are |
10396 | to be avoided. (In the code, the default for \host@_lookup\ is unset.) | |
10397 | .nextp | |
10398 | Exim needs the host name in order to test an item in a host list. The items | |
10399 | that require this are described in sections ~~SECThoslispatnam and | |
10400 | ~~SECThoslispatnamsk. | |
10401 | .nextp | |
4964e932 PH |
10402 | The calling host matches \helo@_try@_verify@_hosts\ or \helo@_verify@_hosts\. |
10403 | In this case, the host name is required to compare with the name quoted in any | |
495ae4b0 PH |
10404 | \\EHLO\\ or \\HELO\\ commands that the client issues. |
10405 | .nextp | |
4964e932 PH |
10406 | The remote host issues a \\EHLO\\ or \\HELO\\ command that quotes one of the |
10407 | domains in \helo@_lookup@_domains\. The default value of this option is | |
495ae4b0 PH |
10408 | .display asis |
10409 | helo_lookup_domains = @ : @[] | |
10410 | .endd | |
4964e932 | 10411 | which causes a lookup if a remote host (incorrectly) gives the server's name or |
495ae4b0 PH |
10412 | IP address in an \\EHLO\\ or \\HELO\\ command. |
10413 | .endp | |
10414 | ||
10415 | .tempindent 0 | |
10416 | \$sender@_host@_port$\: When a message is received from a remote host, this | |
10417 | variable contains the port number that was used on the remote host. | |
10418 | ||
10419 | .tempindent 0 | |
10420 | \$sender@_ident$\: When a message is received from a remote host, this variable | |
10421 | contains the identification received in response to an RFC 1413 request. When a | |
10422 | message has been received locally, this variable contains the login name of the | |
10423 | user that called Exim. | |
10424 | ||
10425 | .tempindent 0 | |
10426 | \$sender@_rcvhost$\: This is provided specifically for use in ::Received:: | |
10427 | headers. It starts with either the verified host name (as obtained from a | |
10428 | .index DNS||reverse lookup | |
10429 | .index reverse DNS lookup | |
10430 | reverse DNS lookup) or, if there is no verified host name, the IP address in | |
10431 | square brackets. After that there may be text in parentheses. When the first | |
10432 | item is a verified host name, the first thing in the parentheses is the IP | |
10433 | address in square brackets, followed by a colon and a port number if port | |
10434 | logging is enabled. When the first item is an IP address, the port is recorded | |
10435 | as `port=$it{xxxx}' inside the parentheses. | |
10436 | ||
10437 | There may also be items of the form `helo=$it{xxxx}' if \\HELO\\ or \\EHLO\\ | |
10438 | was used and its argument was not identical to the real host name or IP | |
10439 | address, and `ident=$it{xxxx}' if an RFC 1413 ident string is available. If all | |
10440 | three items are present in the parentheses, a newline and tab are inserted into | |
10441 | the string, to improve the formatting of the ::Received:: header. | |
10442 | ||
d43194df PH |
10443 | .em |
10444 | .tempindent 0 | |
10445 | \$sender@_verify@_failure$\: In an ACL, when a sender verification fails, this | |
10446 | variable contains information about the failure. The details are the same as | |
10447 | for \$recipient@_verify@_failure$\. | |
10448 | ||
10449 | .tempindent 0 | |
10450 | \$smtp@_active@_hostname$\: During an SMTP session, this variable contains the | |
10451 | value of the active host name, as specified by the \smtp@_active@_hostname\ | |
10452 | option. The value of \$smtp@_active@_hostname$\ is saved with any message that | |
10453 | is received, so its value can be consulted during routing and delivery. | |
10454 | .nem | |
10455 | ||
495ae4b0 PH |
10456 | .index \\AUTH\\||argument |
10457 | .index \\EXPN\\||argument | |
10458 | .index \\ETRN\\||argument | |
10459 | .index \\VRFY\\||argument | |
10460 | .tempindent 0 | |
10461 | \$smtp@_command@_argument$\: While an ACL is running to check an \\AUTH\\, | |
10462 | \\EHLO\\, \\EXPN\\, \\ETRN\\, \\HELO\\, or \\VRFY\\ command, this variable | |
10463 | contains the argument for the SMTP command. | |
10464 | ||
10465 | .tempindent 0 | |
10466 | \$sn0$\ -- \$sn9$\: These variables are copies of the values of the \$n0$\ | |
10467 | -- \$n9$\ accumulators that were current at the end of the system filter file. | |
10468 | This allows a system filter file to set values that can be tested in users' | |
10469 | filter files. For example, a system filter could set a value indicating how | |
10470 | likely it is that a message is junk mail. | |
10471 | ||
d43194df PH |
10472 | .em |
10473 | .tempindent 0 | |
10474 | \$spam@_$\\*xxx*\: A number of variables whose names start with \$spam$\ are | |
10475 | available when Exim is compiled with the content-scanning extension. For | |
10476 | details, see section ~~SECTscanspamass. | |
10477 | .nem | |
10478 | ||
495ae4b0 PH |
10479 | .tempindent 0 |
10480 | \$spool@_directory$\: The name of Exim's spool directory. | |
10481 | ||
d43194df PH |
10482 | .em |
10483 | .tempindent 0 | |
10484 | \$spool@_inodes$\: The number of free inodes in the disk partition where Exim's | |
10485 | spool files are being written. The value is recalculated whenever the variable | |
10486 | is referenced. If the relevant file system does not have the concept of inodes, | |
10487 | the value of is -1. | |
10488 | See also the \check@_spool@_inodes\ option. | |
10489 | ||
10490 | .tempindent 0 | |
10491 | \$spool@_space$\: The amount of free space (as a number of kilobytes) in the | |
10492 | disk partition where Exim's spool files are being written. The value is | |
10493 | recalculated whenever the variable is referenced. If the operating system does | |
10494 | not have the ability to find the amount of free space (only true for | |
10495 | experimental systems), the space value is -1. For example, to check in an ACL | |
10496 | that there is at least 50 megabytes free on the spool, you could write: | |
10497 | .display asis | |
10498 | condition = ${if > {$spool_space}{50000}} | |
10499 | .endd | |
10500 | See also the \check@_spool@_space\ option. | |
10501 | .nem | |
10502 | ||
495ae4b0 PH |
10503 | .tempindent 0 |
10504 | \$thisaddress$\: This variable is set only during the processing of the | |
10505 | \foranyaddress\ command in a filter file. Its use is explained in the | |
10506 | description of that command. | |
10507 | ||
10508 | .tempindent 0 | |
10509 | \$tls@_certificate@_verified$\: | |
10510 | This variable is set to `1' if a TLS certificate was verified when the message | |
10511 | was received, and `0' otherwise. | |
10512 | ||
10513 | .tempindent 0 | |
10514 | \$tls@_cipher$\: When a message is received from a remote host over an | |
10515 | encrypted SMTP connection, this variable is set to the cipher suite that was | |
4964e932 PH |
10516 | negotiated, for example DES-CBC3-SHA. |
10517 | In other circumstances, in particular, for message received over unencrypted | |
495ae4b0 PH |
10518 | connections, the variable is empty. |
10519 | See chapter ~~CHAPTLS for details of TLS support. | |
10520 | ||
10521 | .tempindent 0 | |
10522 | \$tls@_peerdn$\: When a message is received from a remote host over an | |
4964e932 | 10523 | encrypted SMTP connection, |
495ae4b0 PH |
10524 | and Exim is configured to request a certificate from the client, |
10525 | the value of the Distinguished Name of the certificate is made available in the | |
10526 | \$tls@_peerdn$\ during subsequent processing. | |
10527 | ||
10528 | .tempindent 0 | |
10529 | \$tod@_bsdinbox$\: The time of day and date, in the format required for | |
10530 | BSD-style mailbox files, for example: Thu Oct 17 17:14:09 1995. | |
10531 | ||
10532 | .tempindent 0 | |
10533 | \$tod@_epoch$\: The time and date as a number of seconds since the start of the | |
10534 | Unix epoch. | |
10535 | ||
10536 | .tempindent 0 | |
10537 | \$tod@_full$\: A full version of the time and date, for example: Wed, 16 Oct | |
10538 | 1995 09:51:40 +0100. The timezone is always given as a numerical offset from | |
4964e932 | 10539 | UTC, with positive values used for timezones that are ahead (east) of UTC, and |
495ae4b0 PH |
10540 | negative values for those that are behind (west). |
10541 | ||
10542 | .tempindent 0 | |
10543 | \$tod@_log$\: The time and date in the format used for writing Exim's log | |
10544 | files, for example: 1995-10-12 15:32:29, | |
10545 | but without a timezone. | |
10546 | ||
10547 | .tempindent 0 | |
10548 | \$tod@_logfile$\: | |
10549 | This variable contains the date in the format yyyymmdd. This is the format that | |
10550 | is used for datestamping log files when \log@_file@_path\ contains the \"%D"\ | |
10551 | flag. | |
10552 | ||
10553 | .tempindent 0 | |
10554 | \$tod@_zone$\: This variable contains the numerical value of the local | |
10555 | timezone, for example: -0500. | |
10556 | ||
10557 | .tempindent 0 | |
10558 | \$tod@_zulu$\: | |
10559 | This variable contains the UTC date and time in `Zulu' format, as specified by | |
10560 | ISO 8601, for example: 20030221154023Z. | |
10561 | ||
10562 | .index \$value$\ | |
10563 | .tempindent 0 | |
10564 | \$value$\: This variable contains the result of an expansion lookup, extraction | |
10565 | operation, or external command, as described above. | |
10566 | ||
10567 | .tempindent 0 | |
10568 | \$version@_number$\: The version number of Exim. | |
10569 | ||
10570 | .tempindent 0 | |
10571 | \$warn@_message@_delay$\: This variable is set only during the creation of a | |
10572 | message warning about a delivery delay. Details of its use are explained in | |
10573 | section ~~SECTcustwarn. | |
10574 | ||
10575 | .tempindent 0 | |
10576 | \$warn@_message@_recipients$\: This variable is set only during the creation of | |
10577 | a message warning about a delivery delay. Details of its use are explained in | |
10578 | section ~~SECTcustwarn. | |
10579 | .pop | |
10580 | ||
10581 | ||
10582 | ||
10583 | . | |
10584 | . | |
10585 | . ============================================================================ | |
10586 | .chapter Embedded Perl | |
10587 | .set runningfoot "embedded Perl" | |
10588 | .rset CHAPperl "~~chapter" | |
10589 | .index Perl||calling from Exim | |
10590 | ||
10591 | Exim can be built to include an embedded Perl interpreter. When this is done, | |
10592 | Perl subroutines can be called as part of the string expansion process. To make | |
10593 | use of the Perl support, you need version 5.004 or later of Perl installed on | |
10594 | your system. To include the embedded interpreter in the Exim binary, include | |
10595 | the line | |
10596 | .display asis | |
10597 | EXIM_PERL = perl.o | |
10598 | .endd | |
10599 | in your \(Local/Makefile)\ and then build Exim in the normal way. | |
10600 | ||
d43194df | 10601 | .section Setting up so Perl can be used |
495ae4b0 PH |
10602 | Access to Perl subroutines is via a global configuration option called |
10603 | .index \perl@_startup\ | |
10604 | \perl@_startup\ and an expansion string operator \@$@{perl ...@}\. If there is | |
10605 | no \perl@_startup\ option in the Exim configuration file then no Perl | |
10606 | interpreter is started and there is almost no overhead for Exim (since none of | |
10607 | the Perl library will be paged in unless used). If there is a \perl@_startup\ | |
10608 | option then the associated value is taken to be Perl code which is executed in | |
10609 | a newly created Perl interpreter. | |
10610 | ||
10611 | The value of \perl@_startup\ is not expanded in the Exim sense, so you do not | |
10612 | need backslashes before any characters to escape special meanings. The option | |
10613 | should usually be something like | |
10614 | .display asis | |
10615 | perl_startup = do '/etc/exim.pl' | |
10616 | .endd | |
10617 | where \(/etc/exim.pl)\ is Perl code which defines any subroutines you want to | |
10618 | use from Exim. Exim can be configured either to start up a Perl interpreter as | |
10619 | soon as it is entered, or to wait until the first time it is needed. Starting | |
10620 | the interpreter at the beginning ensures that it is done while Exim still has | |
10621 | its setuid privilege, but can impose an unnecessary overhead if Perl is not in | |
10622 | fact used in a particular run. Also, note that this does not mean that Exim is | |
10623 | necessarily running as root when Perl is called at a later time. By default, | |
10624 | the interpreter is started only when it is needed, but this can be changed in | |
10625 | two ways: | |
10626 | .numberpars $. | |
10627 | .index \perl@_at@_start\ | |
10628 | Setting \perl@_at@_start\ (a boolean option) in the configuration requests | |
10629 | a startup when Exim is entered. | |
10630 | .nextp | |
10631 | The command line option \-ps-\ also requests a startup when Exim is entered, | |
10632 | overriding the setting of \perl@_at@_start\. | |
10633 | .endp | |
10634 | There is also a command line option \-pd-\ (for delay) which suppresses the | |
10635 | initial startup, even if \perl@_at@_start\ is set. | |
10636 | ||
d43194df | 10637 | .section Calling Perl subroutines |
495ae4b0 PH |
10638 | When the configuration file includes a \perl@_startup\ option you can make use |
10639 | of the string expansion item to call the Perl subroutines that are defined | |
10640 | by the \perl@_startup\ code. The operator is used in any of the following | |
10641 | forms: | |
10642 | .display asis | |
10643 | ${perl{foo}} | |
10644 | ${perl{foo}{argument}} | |
10645 | ${perl{foo}{argument1}{argument2} ... } | |
10646 | .endd | |
10647 | which calls the subroutine \foo\ with the given arguments. A maximum of eight | |
10648 | arguments may be passed. Passing more than this results in an expansion failure | |
10649 | with an error message of the form | |
10650 | .display asis | |
10651 | Too many arguments passed to Perl subroutine "foo" (max is 8) | |
10652 | .endd | |
10653 | The return value of the Perl subroutine is evaluated in a scalar context before | |
10654 | it is passed back to Exim to be inserted into the expanded string. If the | |
d43194df PH |
10655 | return value is \*undef*\, the expansion is forced to fail in the same way as |
10656 | an explicit `fail' on an \@$@{if ...@}\ or \@$@{lookup...@}\ item. If the | |
10657 | subroutine aborts by obeying Perl's \die\ function, the expansion fails with | |
10658 | the error message that was passed to \die\. | |
495ae4b0 | 10659 | |
d43194df | 10660 | .section Calling Exim functions from Perl |
495ae4b0 PH |
10661 | Within any Perl code called from Exim, the function \*Exim@:@:expand@_string*\ |
10662 | is available to call back into Exim's string expansion function. For example, | |
10663 | the Perl code | |
10664 | .display asis | |
10665 | my $lp = Exim::expand_string('$local_part'); | |
10666 | .endd | |
10667 | makes the current Exim \$local@_part$\ available in the Perl variable \$lp$\. | |
10668 | Note those are single quotes and not double quotes to protect against | |
10669 | \$local@_part$\ being interpolated as a Perl variable. | |
10670 | ||
10671 | If the string expansion is forced to fail by a `fail' item, the result of | |
10672 | \*Exim@:@:expand@_string*\ is \undef\. If there is a syntax error in the | |
10673 | expansion string, the Perl call from the original expansion string fails with | |
10674 | an appropriate error message, in the same way as if \die\ were used. | |
10675 | ||
10676 | .index debugging||from embedded Perl | |
10677 | .index log||writing from embedded Perl | |
10678 | Two other Exim functions are available for use from within Perl code. | |
10679 | \*Exim@:@:debug@_write(<<string>>)*\ writes the string to the standard error | |
10680 | stream if Exim's debugging is enabled. If you want a newline at the end, you | |
10681 | must supply it. \*Exim@:@:log@_write(<<string>>)*\ writes the string to Exim's | |
10682 | main log, adding a leading timestamp. In this case, you should not supply a | |
10683 | terminating newline. | |
10684 | ||
d43194df PH |
10685 | .em |
10686 | .section Use of standard output and error by Perl | |
76a2d7ba | 10687 | .index Perl||standard output and error |
d43194df | 10688 | You should not write to the standard error or output streams from within your |
76a2d7ba PH |
10689 | Perl code, as it is not defined how these are set up. In versions of Exim |
10690 | before 4.50, it is possible for the standard output or error to refer to the | |
10691 | SMTP connection during message reception via the daemon. Writing to this stream | |
10692 | is certain to cause chaos. From Exim 4.50 onwards, the standard output and | |
10693 | error streams are connected to \(/dev/null)\ in the daemon. The chaos is | |
10694 | avoided, but the output is lost. | |
10695 | ||
10696 | .index Perl||\warn\, use of | |
10697 | The Perl \warn\ statement writes to the standard error stream by default. Calls | |
10698 | to \warn\ may be embedded in Perl modules that you use, but over which you have | |
10699 | no control. When Exim starts up the Perl interpreter, it arranges for output | |
10700 | from the \warn\ statement to be written to the Exim main log. You can change | |
10701 | this by including appropriate Perl magic somewhere in your Perl code. For | |
10702 | example, to discard \warn\ output completely, you need this: | |
10703 | .display asis | |
10704 | $SIG{__WARN__} = sub { }; | |
10705 | .endd | |
10706 | Whenever a \warn\ is obeyed, the anonymous subroutine is called. In this | |
10707 | example, the code for the subroutine is empty, so it does nothing, but you can | |
10708 | include any Perl code that you like. The text of the \warn\ message is passed | |
10709 | as the first subroutine argument. | |
d43194df | 10710 | .nem |
495ae4b0 PH |
10711 | |
10712 | ||
10713 | . | |
10714 | . | |
10715 | . | |
10716 | . | |
10717 | . ============================================================================ | |
10718 | .chapter Starting the daemon and the use of network interfaces | |
10719 | .set runningfoot "starting the daemon" | |
10720 | .rset CHAPinterfaces "~~chapter" | |
10721 | .index daemon||starting | |
10722 | .index interface||listening | |
10723 | .index network interface | |
10724 | .index interface||network | |
10725 | .index IP address||for listening | |
10726 | .index daemon||listening IP addresses | |
10727 | .index TCP/IP||setting listening interfaces | |
10728 | .index TCP/IP||setting listening ports | |
10729 | ||
10730 | A host that is connected to a TCP/IP network may have one or more physical | |
10731 | hardware network interfaces. Each of these interfaces may be configured as one | |
10732 | or more `logical' interfaces, which are the entities that a program actually | |
10733 | works with. Each of these logical interfaces is associated with an IP address. | |
10734 | In addition, TCP/IP software supports `loopback' interfaces (127.0.0.1 in IPv4 | |
10735 | and @:@:1 in IPv6), which do not use any physical hardware. Exim requires | |
10736 | knowledge about the host's interfaces for use in three different circumstances: | |
10737 | .numberpars | |
10738 | When a listening daemon is started, Exim needs to know which interfaces | |
10739 | and ports to listen on. | |
10740 | .nextp | |
10741 | When Exim is routing an address, it needs to know which IP addresses | |
10742 | are associated with local interfaces. This is required for the correct | |
10743 | processing of MX lists by removing the local host and others with the | |
10744 | same or higher priority values. Also, Exim needs to detect cases | |
10745 | when an address is routed to an IP address that in fact belongs to the | |
10746 | local host. Unless the \self\ router option or the \allow@_localhost\ | |
10747 | option of the smtp transport is set (as appropriate), this is treated | |
10748 | as an error situation. | |
10749 | .nextp | |
10750 | When Exim connects to a remote host, it may need to know which interface to use | |
10751 | for the outgoing connection. | |
10752 | .endp | |
10753 | ||
10754 | Exim's default behaviour is likely to be appropriate in the vast majority | |
10755 | of cases. If your host has only one interface, and you want all its IP | |
10756 | addresses to be treated in the same way, and you are using only the | |
10757 | standard SMTP port, you should not need to take any special action. The | |
10758 | rest of this chapter does not apply to you. | |
10759 | ||
4964e932 | 10760 | In a more complicated situation you may want to listen only on certain |
495ae4b0 PH |
10761 | interfaces, or on different ports, and for this reason there are a number of |
10762 | options that can be used to influence Exim's behaviour. The rest of this | |
10763 | chapter describes how they operate. | |
10764 | ||
10765 | When a message is received over TCP/IP, the interface and port that were | |
10766 | actually used are set in \$interface@_address$\ and \$interface@_port$\. | |
10767 | ||
10768 | ||
10769 | .section Starting a listening daemon | |
10770 | When a listening daemon is started (by means of the \-bd-\ command line | |
10771 | option), the interfaces and ports on which it listens are controlled by the | |
10772 | following options: | |
10773 | .numberpars $. | |
10774 | \daemon@_smtp@_ports\ contains a list of default ports. (For backward | |
10775 | compatibility, this option can also be specified in the singular.) | |
10776 | .nextp | |
10777 | \local@_interfaces\ contains list of interface IP addresses on which to | |
10778 | listen. Each item may optionally also specify a port. | |
10779 | .endp | |
10780 | The default list separator in both cases is a colon, but this can be changed as | |
10781 | described in section ~~SECTlistconstruct. When IPv6 addresses are involved, it | |
10782 | is usually best to change the separator to avoid having to double all the | |
10783 | colons. For example: | |
10784 | .display asis | |
10785 | local_interfaces = <; 127.0.0.1 ; \ | |
10786 | 192.168.23.65 ; \ | |
10787 | ::1 ; \ | |
10788 | 3ffe:ffff:836f::fe86:a061 | |
4964e932 | 10789 | .endd |
495ae4b0 PH |
10790 | There are two different formats for specifying a port along with an IP address |
10791 | in \local@_interfaces\: | |
10792 | .numberpars | |
4964e932 | 10793 | The port is added onto the address with a dot separator. For example, to listen |
495ae4b0 PH |
10794 | on port 1234 on two different IP addresses: |
10795 | .display asis | |
10796 | local_interfaces = <; 192.168.23.65.1234 ; \ | |
10797 | 3ffe:ffff:836f::fe86:a061.1234 | |
4964e932 | 10798 | .endd |
495ae4b0 PH |
10799 | .nextp |
10800 | The IP address is enclosed in square brackets, and the port is added | |
10801 | with a colon separator, for example: | |
10802 | .display asis | |
10803 | local_interfaces = <; [192.168.23.65]:1234 ; \ | |
10804 | [3ffe:ffff:836f::fe86:a061]:1234 | |
4964e932 | 10805 | .endd |
495ae4b0 PH |
10806 | .endp |
10807 | When a port is not specified, the value of \daemon@_smtp@_ports\ is used. The | |
10808 | default setting contains just one port: | |
10809 | .display asis | |
10810 | daemon_smtp_ports = smtp | |
10811 | .endd | |
10812 | If more than one port is listed, each interface that does not have its own port | |
10813 | specified listens on all of them. Ports that are listed in | |
10814 | \daemon@_smtp@_ports\ can be identified either by name (defined in | |
10815 | \(/etc/services)\) or by number. However, when ports are given with individual | |
10816 | IP addresses in \local@_interfaces\, only numbers (not names) can be used. | |
10817 | ||
10818 | ||
4964e932 | 10819 | .section Special IP listening addresses |
495ae4b0 PH |
10820 | The addresses 0.0.0.0 and @:@:0 are treated specially. They are interpreted |
10821 | as `all IPv4 interfaces' and `all IPv6 interfaces', respectively. In each | |
10822 | case, Exim tells the TCP/IP stack to `listen on all IPv\*x*\ interfaces' | |
10823 | instead of setting up separate listening sockets for each interface. The | |
10824 | default value of \local@_interfaces\ is | |
10825 | .display asis | |
10826 | local_interfaces = 0.0.0.0 | |
10827 | .endd | |
10828 | when Exim is built without IPv6 support; otherwise it is: | |
10829 | .display asis | |
10830 | local_interfaces = <; ::0 ; 0.0.0.0 | |
10831 | .endd | |
10832 | Thus, by default, Exim listens on all available interfaces, on the SMTP port. | |
10833 | ||
10834 | ||
10835 | .section Overriding local@_interfaces and daemon@_smtp@_ports | |
10836 | The \-oX-\ command line option can be used to override the values of | |
10837 | \daemon@_smtp@_ports\ and/or \local@_interfaces\ for a particular daemon | |
10838 | instance. Another way of doing this would be to use macros and the \-D-\ | |
10839 | option. However, \-oX-\ can be used by any admin user, whereas modification of | |
10840 | the runtime configuration by \-D-\ is allowed only when the caller is root or | |
10841 | exim. | |
10842 | ||
10843 | The value of \-oX-\ is a list of items. The default colon separator can be | |
10844 | changed in the usual way if required. If there are any items that do not | |
10845 | contain dots or colons (that is, are not IP addresses), the value of | |
10846 | \daemon@_smtp@_ports\ is replaced by the list of those items. If there are any | |
10847 | items that do contain dots or colons, the value of \local@_interfaces\ is | |
10848 | replaced by those items. Thus, for example, | |
10849 | .display asis | |
10850 | -oX 1225 | |
10851 | .endd | |
10852 | overrides \daemon@_smtp@_ports\, but leaves \local@_interfaces\ unchanged, | |
10853 | whereas | |
10854 | .display asis | |
10855 | -oX 192.168.34.5.1125 | |
10856 | .endd | |
10857 | overrides \local@_interfaces\, leaving \daemon@_smtp@_ports\ unchanged. | |
10858 | (However, since \local@_interfaces\ now contains no items without ports, the | |
10859 | value of \daemon@_smtp@_ports\ is no longer relevant in this example.) | |
10860 | ||
10861 | ||
d43194df | 10862 | .em |
8408f763 | 10863 | .section Support for the obsolete SSMTP (or SMTPS) protocol |
d43194df PH |
10864 | .rset SECTsupobssmt "~~chapter.~~section" |
10865 | .index ssmtp protocol | |
8408f763 | 10866 | .index smtps protocol |
d43194df | 10867 | .index SMTP||ssmtp protocol |
8408f763 PH |
10868 | .index SMTP||smtps protocol |
10869 | Exim supports the obsolete SSMTP protocol (also known as SMTPS) that was used | |
10870 | before the \\STARTTLS\\ command was standardized for SMTP. Some legacy clients | |
10871 | still use this protocol. If the \tls@_on@_connect@_ports\ option is set to a | |
10872 | list of port numbers, connections to those ports must use SSMTP. The most | |
10873 | common use of this option is expected to be | |
d43194df PH |
10874 | .display asis |
10875 | tls_on_connect_ports = 465 | |
10876 | .endd | |
10877 | because 465 is the usual port number used by the legacy clients. There is also | |
10878 | a command line option \-tls-on-connect-\, which forces all ports to behave in | |
10879 | this way when a daemon is started. | |
10880 | ||
10881 | \**Warning**\: Setting \tls@_on@_connect@_ports\ does not of itself cause the | |
10882 | daemon to listen on those ports. You must still specify them in | |
10883 | \daemon@_smtp@_ports\, \local@_interfaces\, or the \-oX-\ option. (This is | |
10884 | because \tls@_on@_connect@_ports\ applies to \inetd\ connections as well as to | |
10885 | connections via the daemon.) | |
10886 | .nem | |
10887 | ||
10888 | ||
495ae4b0 PH |
10889 | .section IPv6 address scopes |
10890 | IPv6 addresses have `scopes', and a host with multiple hardware interfaces | |
10891 | can, in principle, have the same link-local IPv6 address on different | |
10892 | interfaces. Thus, additional information is needed, over and above the IP | |
10893 | address, to distinguish individual interfaces. A convention of using a | |
10894 | percent sign followed by something (often the interface name) has been | |
10895 | adopted in some cases, leading to addresses like this: | |
10896 | .display asis | |
d43194df | 10897 | fe80::202:b3ff:fe03:45c1%eth0 |
495ae4b0 PH |
10898 | .endd |
10899 | To accommodate this usage, a percent sign followed by an arbitrary string is | |
10900 | allowed at the end of an IPv6 address. By default, Exim calls \*getaddrinfo()*\ | |
10901 | to convert a textual IPv6 address for actual use. This function recognizes the | |
10902 | percent convention in operating systems that support it, and it processes the | |
10903 | address appropriately. Unfortunately, some older libraries have problems with | |
10904 | \*getaddrinfo()*\. If | |
10905 | .display asis | |
10906 | IPV6_USE_INET_PTON=yes | |
10907 | .endd | |
10908 | is set in \(Local/Makefile)\ (or an OS-dependent Makefile) when Exim is built, | |
10909 | Exim uses \*inet@_pton()*\ to convert a textual IPv6 address for actual use, | |
10910 | instead of \*getaddrinfo()*\. (Before version 4.14, it always used this | |
10911 | function.) Of course, this means that the additional functionality of | |
10912 | \*getaddrinfo()*\ -- recognizing scoped addresses -- is lost. | |
10913 | ||
10914 | ||
10915 | .section Examples of starting a listening daemon | |
10916 | The default case in an IPv6 environment is | |
10917 | .display asis | |
d43194df | 10918 | daemon_smtp_ports = smtp |
495ae4b0 PH |
10919 | local_interfaces = <; ::0 ; 0.0.0.0 |
10920 | .endd | |
10921 | This specifies listening on the smtp port on all IPv6 and IPv4 interfaces. | |
10922 | Either one or two sockets may be used, depending on the characteristics of | |
10923 | the TCP/IP stack. (This is complicated and messy; for more information, | |
10924 | read the comments in the \(daemon.c)\ source file.) | |
10925 | ||
10926 | To specify listening on ports 25 and 26 on all interfaces: | |
10927 | .display asis | |
10928 | daemon_smtp_ports = 25 : 26 | |
10929 | .endd | |
10930 | (leaving \local@_interfaces\ at the default setting) or, more explicitly: | |
10931 | .display asis | |
10932 | local_interfaces = <; ::0.25 ; ::0.26 \ | |
10933 | 0.0.0.0.25 ; 0.0.0.0.26 | |
10934 | .endd | |
10935 | To listen on the default port on all IPv4 interfaces, and on port 26 on the | |
10936 | IPv4 loopback address only: | |
10937 | .display asis | |
10938 | local_interfaces = 0.0.0.0 : 127.0.0.1.26 | |
10939 | .endd | |
10940 | To specify listening on the default port on specific interfaces only: | |
10941 | .display asis | |
10942 | local_interfaces = 192.168.34.67 : 192.168.34.67 | |
10943 | .endd | |
d43194df | 10944 | \**Warning**\: such a setting excludes listening on the loopback interfaces. |
495ae4b0 PH |
10945 | |
10946 | ||
10947 | .section Recognising the local host | |
10948 | .rset SECTreclocipadd "~~chapter.~~section" | |
10949 | The \local@_interfaces\ option is also used when Exim needs to determine | |
10950 | whether or not an IP address refers to the local host. That is, the IP | |
10951 | addresses of all the interfaces on which a daemon is listening are always | |
10952 | treated as local. | |
10953 | ||
10954 | For this usage, port numbers in \local@_interfaces\ are ignored. If either of | |
10955 | the items 0.0.0.0 or @:@:0 are encountered, Exim gets a complete list of | |
10956 | available interfaces from the operating system, and extracts the relevant | |
10957 | (that is, IPv4 or IPv6) addresses to use for checking. | |
10958 | ||
10959 | Some systems set up large numbers of virtual interfaces in order to provide | |
10960 | many virtual web servers. In this situation, you may want to listen for | |
10961 | email on only a few of the available interfaces, but nevertheless treat all | |
10962 | interfaces as local when routing. You can do this by setting | |
10963 | \extra@_local@_interfaces\ to a list of IP addresses, possibly including the | |
10964 | `all' wildcard values. These addresses are recognized as local, but are not | |
10965 | used for listening. Consider this example: | |
10966 | .display asis | |
10967 | local_interfaces = <; 127.0.0.1 ; ::1 ; \ | |
10968 | 192.168.53.235 ; \ | |
10969 | 3ffe:2101:12:1:a00:20ff:fe86:a061 | |
10970 | ||
10971 | extra_local_interfaces = <; ::0 ; 0.0.0.0 | |
10972 | .endd | |
10973 | The daemon listens on the loopback interfaces and just one IPv4 and one IPv6 | |
10974 | address, but all available interface addresses are treated as local when | |
10975 | Exim is routing. | |
10976 | ||
4964e932 PH |
10977 | In some environments the local host name may be in an MX list, but with an IP |
10978 | address that is not assigned to any local interface. In other cases it may be | |
495ae4b0 PH |
10979 | desirable to treat other host names as if they referred to the local host. Both |
10980 | these cases can be handled by setting the \hosts@_treat@_as@_local\ option. | |
10981 | This contains host names rather than IP addresses. When a host is referenced | |
10982 | during routing, either via an MX record or directly, it is treated as the local | |
10983 | host if its name matches \hosts@_treat@_as@_local\, or if any of its IP | |
10984 | addresses match \local@_interfaces\ or \extra@_local@_interfaces\. | |
10985 | ||
10986 | ||
10987 | .section Delivering to a remote host | |
10988 | Delivery to a remote host is handled by the smtp transport. By default, it | |
10989 | allows the system's TCP/IP functions to choose which interface to use (if | |
10990 | there is more than one) when connecting to a remote host. However, the | |
10991 | \interface\ option can be set to specify which interface is used. See the | |
10992 | description of the smtp transport in chapter ~~CHAPsmtptrans for more details. | |
10993 | ||
10994 | ||
10995 | ||
10996 | ||
495ae4b0 PH |
10997 | . |
10998 | . | |
10999 | . | |
11000 | . | |
11001 | . ============================================================================ | |
11002 | .chapter Main configuration | |
11003 | .set runningfoot "main configuration" | |
11004 | .rset CHAPmainconfig "~~chapter" | |
11005 | .index configuration file||main section | |
11006 | .index main configuration | |
11007 | The first part of the run time configuration file contains three types of item: | |
11008 | .numberpars $. | |
11009 | Macro definitions: These lines start with an upper case letter. See section | |
11010 | ~~SECTmacrodefs for details of macro processing. | |
11011 | .nextp | |
11012 | Named list definitions: These lines start with one of the words `domainlist', | |
11013 | `hostlist', `addresslist', or `localpartlist'. Their use is described in | |
11014 | section ~~SECTnamedlists. | |
11015 | .nextp | |
11016 | Main configuration settings: Each setting occupies one line of the file | |
11017 | (with possible continuations). If any setting is preceded by the word | |
11018 | `hide', the \-bP-\ command line option displays its value to admin users only. | |
11019 | See section ~~SECTcos for a description of the syntax of these option settings. | |
11020 | .endp | |
11021 | This chapter specifies all the main configuration options, along with their | |
11022 | types and default values. For ease of finding a particular option, they appear | |
11023 | in alphabetical order in section ~~SECTalomo below. However, because there are | |
11024 | now so many options, they are first listed briefly in functional groups, as an | |
d43194df PH |
11025 | aid to finding the name of the option you are looking for. Some options are |
11026 | listed in more than one group. | |
495ae4b0 PH |
11027 | |
11028 | .set savedisplayflowcheck ~~displayflowcheck | |
11029 | .set displayflowcheck 0 | |
11030 | ||
11031 | .section Miscellaneous | |
11032 | .display flow rm | |
11033 | .tabs 31 | |
11034 | \bi@_command\ $t$rm{to run for \-bi-\ command line option} | |
11035 | \keep@_malformed\ $t$rm{for broken files -- should not happen} | |
11036 | \localhost@_number\ $t$rm{for unique message ids in clusters} | |
11037 | \message@_body@_visible\ $t$rm{how much to show in \$message@_body$\} | |
d43194df PH |
11038 | .newline |
11039 | .em | |
11040 | \mua@_wrapper\ $t$rm{run in `MUA wrapper' mode} | |
11041 | .nem | |
11042 | .newline | |
495ae4b0 PH |
11043 | \print@_topbitchars\ $t$rm{top-bit characters are printing} |
11044 | \timezone\ $t$rm{force time zone} | |
11045 | .endd | |
11046 | ||
11047 | .section Exim parameters | |
11048 | .display flow rm | |
11049 | .tabs 31 | |
11050 | \exim@_group\ $t$rm{override compiled-in value} | |
11051 | \exim@_path\ $t$rm{override compiled-in value} | |
11052 | \exim@_user\ $t$rm{override compiled-in value} | |
11053 | \primary@_hostname\ $t$rm{default from \*uname()*\} | |
11054 | \split@_spool@_directory\ $t$rm{use multiple directories} | |
11055 | \spool@_directory\ $t$rm{override compiled-in value} | |
11056 | .endd | |
11057 | ||
11058 | .section Privilege controls | |
11059 | .display flow rm | |
11060 | .tabs 31 | |
11061 | \admin@_groups\ $t$rm{groups that are Exim admin users} | |
11062 | \deliver@_drop@_privilege\ $t$rm{drop root for delivery processes} | |
11063 | \local@_from@_check\ $t$rm{insert ::Sender:: if necessary} | |
11064 | \local@_from@_prefix\ $t$rm{for testing ::From:: for local sender} | |
11065 | \local@_from@_suffix\ $t$rm{for testing ::From:: for local sender} | |
11066 | \local@_sender@_retain\ $t$rm{keep ::Sender:: from untrusted user} | |
11067 | \never@_users\ $t$rm{do not run deliveries as these} | |
11068 | \prod@_requires@_admin\ $t$rm{forced delivery requires admin user} | |
11069 | \queue@_list@_requires@_admin\ $t$rm{queue listing requires admin user} | |
11070 | \trusted@_groups\ $t$rm{groups that are trusted} | |
11071 | \trusted@_users\ $t$rm{users that are trusted} | |
11072 | .endd | |
11073 | ||
11074 | .section Logging | |
11075 | .display flow rm | |
11076 | .tabs 31 | |
d43194df PH |
11077 | .em |
11078 | \hosts@_connection@_nolog\ $t$rm{exemption from connect logging} | |
11079 | .nem | |
11080 | .newline | |
495ae4b0 PH |
11081 | \log@_file@_path\ $t$rm{override compiled-in value} |
11082 | \log@_selector\ $t$rm{set/unset optional logging} | |
11083 | \log@_timezone\ $t$rm{add timezone to log lines} | |
11084 | \message@_logs\ $t$rm{create per-message logs} | |
4964e932 | 11085 | \preserve@_message@_logs\ $t$rm{after message completion} |
495ae4b0 PH |
11086 | \process@_log@_path\ $t$rm{for SIGUSR1 and \*exiwhat*\} |
11087 | \syslog@_duplication\ $t$rm{controls duplicate log lines on syslog } | |
11088 | \syslog@_facility\ $t$rm{set syslog `facility' field} | |
11089 | \syslog@_processname\ $t$rm{set syslog `ident' field} | |
11090 | \syslog@_timestamp\ $t$rm{timestamp syslog lines} | |
11091 | .newline | |
495ae4b0 PH |
11092 | \write@_rejectlog\ $t$rm{control use of message log} |
11093 | .newline | |
495ae4b0 PH |
11094 | .endd |
11095 | ||
11096 | .section Frozen messages | |
11097 | .display flow rm | |
11098 | .tabs 31 | |
11099 | \auto@_thaw\ $t$rm{sets time for retrying frozen messages} | |
11100 | \freeze@_tell\ $t$rm{send message when freezing} | |
11101 | \move@_frozen@_messages\ $t$rm{to another directory} | |
11102 | \timeout@_frozen@_after\ $t$rm{keep frozen messages only so long} | |
11103 | .endd | |
11104 | ||
11105 | .section Data lookups | |
11106 | .display flow rm | |
11107 | .tabs 31 | |
11108 | \ldap@_default@_servers\ $t$rm{used if no server in query} | |
11109 | \ldap@_version\ $t$rm{set protocol version} | |
11110 | \lookup@_open@_max\ $t$rm{lookup files held open} | |
11111 | \mysql@_servers\ $t$rm{as it says} | |
11112 | \oracle@_servers\ $t$rm{as it says} | |
11113 | \pgsql@_servers\ $t$rm{as it says} | |
11114 | .endd | |
11115 | ||
11116 | .section Message ids | |
11117 | .display flow rm | |
11118 | .tabs 31 | |
11119 | \message@_id@_header@_domain\ $t$rm{used to build ::Message-ID:: header} | |
11120 | \message@_id@_header@_text\ $t$rm{ditto} | |
11121 | .endd | |
11122 | ||
11123 | .section Embedded Perl Startup | |
11124 | .display flow rm | |
11125 | .tabs 31 | |
11126 | \perl@_at@_start\ $t$rm{always start the interpreter} | |
11127 | \perl@_startup\ $t$rm{code to obey when starting Perl} | |
11128 | .endd | |
11129 | ||
11130 | .section Daemon | |
11131 | .display flow rm | |
11132 | .tabs 31 | |
11133 | \daemon@_smtp@_ports\ $t$rm{default ports} | |
11134 | \extra@_local@_interfaces\ $t$rm{not necessarily listened on} | |
11135 | \local@_interfaces\ $t$rm{on which to listen, with optional ports} | |
11136 | \pid@_file@_path\ $t$rm{override compiled-in value} | |
4964e932 | 11137 | \queue@_run@_max\ $t$rm{maximum simultaneous queue runners} |
495ae4b0 PH |
11138 | .endd |
11139 | ||
11140 | .section Resource control | |
11141 | .display flow rm | |
11142 | .tabs 31 | |
11143 | \check@_log@_inodes\ $t$rm{before accepting a message} | |
11144 | \check@_log@_space\ $t$rm{before accepting a message} | |
11145 | \check@_spool@_inodes\ $t$rm{before accepting a message} | |
11146 | \check@_spool@_space\ $t$rm{before accepting a message} | |
11147 | \deliver@_queue@_load@_max\ $t$rm{no queue deliveries if load high} | |
11148 | \queue@_only@_load\ $t$rm{queue incoming if load high} | |
4964e932 | 11149 | \queue@_run@_max\ $t$rm{maximum simultaneous queue runners} |
495ae4b0 PH |
11150 | \remote@_max@_parallel\ $t$rm{parallel SMTP delivery per message} |
11151 | \smtp@_accept@_max\ $t$rm{simultaneous incoming connections} | |
11152 | \smtp@_accept@_max@_nommail\ $t$rm{non-mail commands} | |
11153 | \smtp@_accept@_max@_nonmail@_hosts\ $t$rm{hosts to which the limit applies} | |
11154 | \smtp@_accept@_max@_per@_connection\ $t$rm{messages per connection} | |
11155 | \smtp@_accept@_max@_per@_host\ $t$rm{connections from one host} | |
11156 | \smtp@_accept@_queue\ $t$rm{queue mail if more connections} | |
11157 | \smtp@_accept@_queue@_per@_connection\ $t$rm{queue if more messages per connection} | |
11158 | \smtp@_accept@_reserve\ $t$rm{only reserve hosts if more connections} | |
11159 | \smtp@_check@_spool@_space\ $t$rm{from \\SIZE\\ on \\MAIL\\ command} | |
11160 | \smtp@_connect@_backlog\ $t$rm{passed to TCP/IP stack} | |
11161 | \smtp@_load@_reserve\ $t$rm{SMTP from reserved hosts if load high} | |
11162 | \smtp@_reserve@_hosts\ $t$rm{these are the reserve hosts} | |
11163 | .endd | |
11164 | ||
11165 | .section Policy controls | |
11166 | .display flow rm | |
11167 | .tabs 31 | |
11168 | \acl@_not@_smtp\ $t$rm{set ACL for non-SMTP messages} | |
11169 | \acl@_smtp@_auth\ $t$rm{set ACL for \\AUTH\\} | |
11170 | \acl@_smtp@_connect\ $t$rm{set ACL for connection} | |
11171 | \acl@_smtp@_data\ $t$rm{set ACL for \\DATA\\} | |
11172 | \acl@_smtp@_etrn\ $t$rm{set ACL for \\ETRN\\} | |
11173 | \acl@_smtp@_expn\ $t$rm{set ACL for \\EXPN\\} | |
11174 | \acl@_smtp@_helo\ $t$rm{set ACL for \\EHLO\\ or \\HELO\\} | |
11175 | \acl@_smtp@_mail\ $t$rm{set ACL for \\MAIL\\} | |
11176 | \acl@_smtp@_mailauth\ $t$rm{set ACL for \\AUTH\\ on \\MAIL\\ command} | |
d43194df PH |
11177 | .newline |
11178 | .em | |
11179 | \acl@_smtp@_mime\ $t$rm{set ACL for MIME parts} | |
11180 | \acl@_smtp@_predata\ $t$rm{set ACL for start of data} | |
11181 | \acl@_smtp@_quit\ $t$rm{set ACL for \\QUIT\\} | |
11182 | .nem | |
11183 | .newline | |
495ae4b0 PH |
11184 | \acl@_smtp@_rcpt\ $t$rm{set ACL for \\RCPT\\} |
11185 | \acl@_smtp@_starttls\ $t$rm{set ACL for \\STARTTLS\\} | |
11186 | \acl@_smtp@_vrfy\ $t$rm{set ACL for \\VRFY\\} | |
d43194df PH |
11187 | .newline |
11188 | .em | |
11189 | \av@_scanner\ $t$rm{specify virus scanner} | |
11190 | .nem | |
11191 | .newline | |
495ae4b0 PH |
11192 | \header@_maxsize\ $t$rm{total size of message header} |
11193 | \header@_line@_maxsize\ $t$rm{individual header line limit} | |
11194 | \helo@_accept@_junk@_hosts\ $t$rm{allow syntactic junk from these hosts} | |
11195 | \helo@_allow@_chars\ $t$rm{allow illegal chars in \\HELO\\ names} | |
11196 | \helo@_lookup@_domains\ $t$rm{lookup hostname for these \\HELO\\ names} | |
11197 | \helo@_try@_verify@_hosts\ $t$rm{\\HELO\\ soft-checked for these hosts} | |
11198 | \helo@_verify@_hosts\ $t$rm{\\HELO\\ hard-checked for these hosts} | |
11199 | \host@_lookup\ $t$rm{host name looked up for these hosts} | |
11200 | \host@_lookup@_order\ $t$rm{order of DNS and local name lookups} | |
11201 | \host@_reject@_connection\ $t$rm{reject connection from these hosts} | |
11202 | \hosts@_treat@_as@_local\ $t$rm{useful in some cluster configurations} | |
11203 | \local@_scan@_timeout\ $t$rm{timeout for \*local@_scan()*\} | |
11204 | \message@_size@_limit\ $t$rm{for all messages} | |
11205 | \percent@_hack@_domains\ $t$rm{recognize %-hack for these domains} | |
d43194df PH |
11206 | .newline |
11207 | .em | |
11208 | \spamd@_address\ $t$rm{set interface to SpamAssassin} | |
11209 | .nem | |
11210 | .newline | |
495ae4b0 PH |
11211 | .endd |
11212 | ||
11213 | .section Callout cache | |
11214 | .display flow rm | |
11215 | .tabs 31 | |
11216 | \callout@_domain@_negative@_expire\ $t$rm{timeout for negative domain cache item} | |
11217 | \callout@_domain@_positive@_expire\ $t$rm{timeout for positive domain cache item} | |
11218 | \callout@_negative@_expire\ $t$rm{timeout for negative address cache item} | |
11219 | \callout@_positive@_expire\ $t$rm{timeout for positive address cache item} | |
11220 | \callout@_random@_local@_part\ $t$rm{string to use for `random' testing} | |
11221 | .endd | |
11222 | ||
11223 | .section TLS | |
11224 | .display flow rm | |
11225 | .tabs 31 | |
11226 | \tls@_advertise@_hosts\ $t$rm{advertise TLS to these hosts} | |
11227 | \tls@_certificate\ $t$rm{location of server certificate} | |
495ae4b0 | 11228 | \tls@_crl\ $t$rm{certificate revocation list} |
495ae4b0 | 11229 | \tls@_dhparam\ $t$rm{DH parameters for server} |
d43194df PH |
11230 | .newline |
11231 | .em | |
8408f763 | 11232 | \tls@_on@_connect@_ports\ $t$rm{specify SSMTP (SMTPS) ports} |
d43194df PH |
11233 | .nem |
11234 | .newline | |
495ae4b0 PH |
11235 | \tls@_privatekey\ $t$rm{location of server private key} |
11236 | \tls@_remember@_esmtp\ $t$rm{don't reset after starting TLS} | |
495ae4b0 | 11237 | \tls@_require@_ciphers\ $t$rm{specify acceptable cipers} |
495ae4b0 PH |
11238 | \tls@_try@_verify@_hosts\ $t$rm{try to verify client certificate} |
11239 | \tls@_verify@_certificates\ $t$rm{expected client certificates} | |
11240 | \tls@_verify@_hosts\ $t$rm{insist on client certificate verify} | |
11241 | .endd | |
11242 | ||
4964e932 | 11243 | .section Local user handling |
495ae4b0 PH |
11244 | .display flow rm |
11245 | .tabs 31 | |
11246 | \finduser@_retries\ $t$rm{useful in NIS environments} | |
11247 | \gecos@_name\ $t$rm{used when creating ::Sender::} | |
11248 | \gecos@_pattern\ $t$rm{ditto} | |
11249 | \max@_username@_length\ $t$rm{for systems that truncate} | |
11250 | \unknown@_login\ $t$rm{used when no login name found} | |
11251 | \unknown@_username\ $t$rm{ditto} | |
11252 | \uucp@_from@_pattern\ $t$rm{for recognizing `From ' lines} | |
11253 | \uucp@_from@_sender\ $t$rm{ditto} | |
11254 | .endd | |
11255 | ||
11256 | .section All incoming messages (SMTP and non-SMTP) | |
11257 | .display flow rm | |
11258 | .tabs 31 | |
11259 | \header@_maxsize\ $t$rm{total size of message header} | |
11260 | \header@_line@_maxsize\ $t$rm{individual header line limit} | |
11261 | \message@_size@_limit\ $t$rm{applies to all messages} | |
11262 | \percent@_hack@_domains\ $t$rm{recognize %-hack for these domains} | |
11263 | \received@_header@_text\ $t$rm{expanded to make ::Received::} | |
11264 | \received@_headers@_max\ $t$rm{for mail loop detection} | |
11265 | \recipients@_max\ $t$rm{limit per message} | |
11266 | \recipients@_max@_reject\ $t$rm{permanently reject excess} | |
11267 | .endd | |
11268 | ||
11269 | ||
11270 | .section Non-SMTP incoming messages | |
11271 | .display rm | |
11272 | .tabs 31 | |
11273 | \receive@_timeout\ $t$rm{for non-SMTP messages} | |
11274 | .endd | |
11275 | ||
11276 | ||
11277 | ||
11278 | .section Incoming SMTP messages | |
11279 | See also the \*Policy controls*\ section above. | |
11280 | .display flow rm | |
11281 | .tabs 31 | |
11282 | \host@_lookup\ $t$rm{host name looked up for these hosts} | |
11283 | \host@_lookup@_order\ $t$rm{order of DNS and local name lookups} | |
11284 | \recipient@_unqualified@_hosts\ $t$rm{may send unqualified recipients} | |
11285 | \rfc1413@_hosts\ $t$rm{make ident calls to these hosts} | |
11286 | \rfc1413@_query@_timeout\ $t$rm{zero disables ident calls} | |
11287 | \sender@_unqualified@_hosts\ $t$rm{may send unqualified senders} | |
11288 | \smtp@_accept@_keepalive\ $t$rm{some TCP/IP magic} | |
11289 | \smtp@_accept@_max\ $t$rm{simultaneous incoming connections} | |
11290 | \smtp@_accept@_max@_nommail\ $t$rm{non-mail commands} | |
11291 | \smtp@_accept@_max@_nonmail@_hosts\ $t$rm{hosts to which the limit applies} | |
11292 | \smtp@_accept@_max@_per@_connection\ $t$rm{messages per connection} | |
11293 | \smtp@_accept@_max@_per@_host\ $t$rm{connections from one host} | |
11294 | \smtp@_accept@_queue\ $t$rm{queue mail if more connections} | |
11295 | \smtp@_accept@_queue@_per@_connection\ $t$rm{queue if more messages per connection} | |
11296 | \smtp@_accept@_reserve\ $t$rm{only reserve hosts if more connections} | |
11297 | .newline | |
495ae4b0 PH |
11298 | \smtp@_active@_hostname\ $t$rm{host name to use in messages} |
11299 | .newline | |
495ae4b0 PH |
11300 | \smtp@_banner\ $t$rm{text for welcome banner} |
11301 | \smtp@_check@_spool@_space\ $t$rm{from \\SIZE\\ on \\MAIL\\ command} | |
11302 | \smtp@_connect@_backlog\ $t$rm{passed to TCP/IP stack} | |
11303 | \smtp@_enforce@_sync\ $t$rm{of SMTP command/responses} | |
11304 | \smtp@_etrn@_command\ $t$rm{what to run for \\ETRN\\} | |
11305 | \smtp@_etrn@_serialize\ $t$rm{only one at once} | |
11306 | \smtp@_load@_reserve\ $t$rm{only reserve hosts if this load} | |
11307 | \smtp@_max@_unknown@_commands\ $t$rm{before dropping connection} | |
11308 | \smtp@_ratelimit@_hosts\ $t$rm{apply ratelimiting to these hosts} | |
11309 | \smtp@_ratelimit@_mail\ $t$rm{ratelimit for \\MAIL\\ commands} | |
11310 | \smtp@_ratelimit@_rcpt\ $t$rm{ratelimit for \\RCPT\\ commands} | |
11311 | \smtp@_receive@_timeout\ $t$rm{per command or data line} | |
11312 | \smtp@_reserve@_hosts\ $t$rm{these are the reserve hosts} | |
11313 | \smtp@_return@_error@_details\ $t$rm{give detail on rejections} | |
11314 | .endd | |
11315 | ||
11316 | .section SMTP extensions | |
11317 | .display flow rm | |
11318 | .tabs 31 | |
11319 | \accept@_8bitmime\ $t$rm{advertise \\8BITMIME\\} | |
11320 | \auth@_advertise@_hosts\ $t$rm{advertise \\AUTH\\ to these hosts} | |
11321 | \ignore@_fromline@_hosts\ $t$rm{allow `From ' from these hosts} | |
11322 | \ignore@_fromline@_local\ $t$rm{allow `From ' from local SMTP} | |
11323 | \pipelining@_advertise@_hosts\ $t$rm{advertise pipelining to these hosts} | |
11324 | \tls@_advertise@_hosts\ $t$rm{advertise TLS to these hosts} | |
11325 | .endd | |
11326 | ||
11327 | .section Processing messages | |
11328 | .display flow rm | |
11329 | .tabs 31 | |
11330 | \allow@_domain@_literals\ $t$rm{recognize domain literal syntax} | |
11331 | \allow@_mx@_to@_ip\ $t$rm{allow MX to point to IP address} | |
11332 | \allow@_utf8@_domains\ $t$rm{in addresses} | |
11333 | \delivery@_date@_remove\ $t$rm{from incoming messages} | |
11334 | \envelope@_to@_remote\ $t$rm{from incoming messages} | |
11335 | \extract@_addresses@_remove@_arguments\ $t$rm{affects \-t-\ processing} | |
11336 | \headers@_charset\ $t$rm{default for translations} | |
11337 | \qualify@_domain\ $t$rm{default for senders} | |
11338 | \qualify@_recipient\ $t$rm{default for recipients} | |
11339 | \return@_path@_remove\ $t$rm{from incoming messages} | |
11340 | \strip@_excess@_angle@_brackets\ $t$rm{in addresses} | |
11341 | \strip@_trailing@_dot\ $t$rm{at end of addresses} | |
11342 | \untrusted@_set@_sender\ $t$rm{untrusted can set envelope sender} | |
11343 | .endd | |
11344 | ||
11345 | .section System filter | |
11346 | .display flow rm | |
11347 | .tabs 31 | |
11348 | \system@_filter\ $t$rm{locate system filter} | |
11349 | \system@_filter@_directory@_transport\ $t$rm{transport for delivery to a directory} | |
11350 | \system@_filter@_file@_transport\ $t$rm{transport for delivery to a file} | |
11351 | \system@_filter@_group\ $t$rm{group for filter running} | |
11352 | \system@_filter@_pipe@_transport\ $t$rm{transport for delivery to a pipe} | |
11353 | \system@_filter@_reply@_transport\ $t$rm{transport for autoreply delivery} | |
11354 | \system@_filter@_user\ $t$rm{user for filter running} | |
11355 | .endd | |
11356 | ||
11357 | .section Routing and delivery | |
11358 | .display flow rm | |
11359 | .tabs 31 | |
11360 | \dns@_again@_means@_nonexist\ $t$rm{for broken domains} | |
11361 | \dns@_check@_names@_pattern\ $t$rm{pre-DNS syntax check} | |
11362 | \dns@_ipv4@_lookup\ $t$rm{only v4 lookup for these domains} | |
11363 | \dns@_retrans\ $t$rm{parameter for resolver} | |
11364 | \dns@_retry\ $t$rm{parameter for resolver} | |
11365 | \hold@_domains\ $t$rm{hold delivery for these domains} | |
11366 | \local@_interfaces\ $t$rm{for routing checks} | |
11367 | \queue@_domains\ $t$rm{no immediate delivery for these} | |
11368 | \queue@_only\ $t$rm{no immediate delivery at all} | |
11369 | \queue@_only@_file\ $t$rm{no immediate deliveryif file exists} | |
11370 | \queue@_only@_load\ $t$rm{no immediate delivery if load is high} | |
11371 | \queue@_only@_override\ $t$rm{allow command line to override} | |
11372 | \queue@_run@_in@_order\ $t$rm{order of arrival} | |
11373 | \queue@_run@_max\ $t$rm{of simultaneous queue runners} | |
11374 | \queue@_smtp@_domains\ $t$rm{no immediate SMTP delivery for these} | |
4964e932 | 11375 | \remote@_max@_parallel\ $t$rm{parallel SMTP delivery per message} |
495ae4b0 PH |
11376 | \remote@_sort@_domains\ $t$rm{order of remote deliveries} |
11377 | \retry@_data@_expire\ $t$rm{timeout for retry data} | |
11378 | \retry@_interval@_max\ $t$rm{safety net for retry rules} | |
11379 | .endd | |
11380 | ||
11381 | .section Bounce and warning messages | |
11382 | .display flow rm | |
11383 | .tabs 31 | |
11384 | \bounce@_message@_file\ $t$rm{content of bounce} | |
11385 | \bounce@_message@_text\ $t$rm{content of bounce} | |
11386 | \bounce@_return@_body\ $t$rm{include body if returning message} | |
11387 | \bounce@_return@_message\ $t$rm{include original message in bounce} | |
11388 | \bounce@_return@_size@_limit\ $t$rm{limit on returned message} | |
11389 | \bounce@_sender@_authentication\ $t$rm{send authenticated sender with bounce} | |
11390 | \errors@_copy\ $t$rm{copy bounce messages} | |
11391 | \errors@_reply@_to\ $t$rm{::Reply-to:: in bounces} | |
11392 | \delay@_warning\ $t$rm{time schedule} | |
11393 | \delay@_warning@_condition\ $t$rm{condition for warning messages} | |
11394 | \ignore@_bounce@_errors@_after\ $t$rm{discard undeliverable bounces} | |
11395 | \warn@_message@_file\ $t$rm{content of warning message} | |
11396 | .endd | |
11397 | ||
11398 | .set displayflowcheck ~~savedisplayflowcheck | |
11399 | ||
11400 | .section Alphabetical list of main options | |
11401 | .rset SECTalomo "~~chapter.~~section" | |
11402 | .if ~~sgcal | |
11403 | Those options that undergo string expansion before use are marked with $**$. | |
11404 | .fi | |
11405 | ||
d43194df | 11406 | .startconf main |
495ae4b0 PH |
11407 | |
11408 | .index \\8BITMIME\\ | |
11409 | .index 8-bit characters | |
11410 | .conf accept@_8bitmime boolean false | |
11411 | This option causes Exim to send \\8BITMIME\\ in its response to an SMTP | |
11412 | \\EHLO\\ command, and to accept the \\BODY=\\ parameter on \\MAIL\\ commands. | |
11413 | However, though Exim is 8-bit clean, it is not a protocol converter, and it | |
11414 | takes no steps to do anything special with messages received by this route. | |
11415 | Consequently, this option is turned off by default. | |
11416 | ||
11417 | .index ~~ACL||for non-SMTP messages | |
11418 | .index non-SMTP messages, ACL for | |
11419 | .conf acl@_not@_smtp string$**$ unset | |
4964e932 | 11420 | This option defines the ACL that is run when a non-SMTP message is on the point |
495ae4b0 PH |
11421 | of being accepted. See chapter ~~CHAPACL for further details. |
11422 | ||
495ae4b0 PH |
11423 | .index ~~ACL||setting up for SMTP commands |
11424 | .index \\AUTH\\||ACL for | |
11425 | .conf acl@_smtp@_auth string$**$ unset | |
11426 | This option defines the ACL that is run when an SMTP \\AUTH\\ command is | |
11427 | received. See chapter ~~CHAPACL for further details. | |
11428 | ||
8408f763 PH |
11429 | .index ~~ACL||on SMTP connection |
11430 | .conf acl@_smtp@_connect string$**$ unset | |
11431 | This option defines the ACL that is run when an SMTP connection is received. | |
11432 | See chapter ~~CHAPACL for further details. | |
11433 | ||
495ae4b0 PH |
11434 | .index \\DATA\\, ACL for |
11435 | .conf acl@_smtp@_data string$**$ unset | |
11436 | This option defines the ACL that is run after an SMTP \\DATA\\ command has been | |
11437 | processed and the message itself has been received, but before the final | |
11438 | acknowledgement is sent. See chapter ~~CHAPACL for further details. | |
11439 | ||
11440 | .index \\ETRN\\||ACL for | |
11441 | .conf acl@_smtp@_etrn string$**$ unset | |
11442 | This option defines the ACL that is run when an SMTP \\ETRN\\ command is | |
11443 | received. See chapter ~~CHAPACL for further details. | |
11444 | ||
11445 | .index \\EXPN\\||ACL for | |
11446 | .conf acl@_smtp@_expn string$**$ unset | |
11447 | This option defines the ACL that is run when an SMTP \\EXPN\\ command is | |
11448 | received. See chapter ~~CHAPACL for further details. | |
11449 | ||
11450 | .index \\EHLO\\||ACL for | |
11451 | .index \\HELO\\||ACL for | |
11452 | .conf acl@_smtp@_helo string$**$ unset | |
11453 | This option defines the ACL that is run when an SMTP \\EHLO\\ or \\HELO\\ | |
11454 | command is received. See chapter ~~CHAPACL for further details. | |
11455 | ||
11456 | .index \\MAIL\\||ACL for | |
11457 | .conf acl@_smtp@_mail string$**$ unset | |
11458 | This option defines the ACL that is run when an SMTP \\MAIL\\ command is | |
11459 | received. See chapter ~~CHAPACL for further details. | |
11460 | ||
11461 | .index \\AUTH\\||on \\MAIL\\ command | |
11462 | .conf acl@_smtp@_mailauth string$**$ unset | |
4964e932 | 11463 | This option defines the ACL that is run when there is an \\AUTH\\ parameter on |
495ae4b0 PH |
11464 | a \\MAIL\\ command. See chapter ~~CHAPACL for details of ACLs, and chapter |
11465 | ~~CHAPSMTPAUTH for details of authentication. | |
11466 | ||
d43194df PH |
11467 | .em |
11468 | .index MIME content scanning||ACL for | |
11469 | .conf acl@_smtp@_mime string$**$ unset | |
11470 | This option is available when Exim is built with the content-scanning | |
11471 | extension. It defines the ACL that is run for each MIME part in a message. See | |
11472 | section ~~SECTscanmimepart for details. | |
11473 | ||
11474 | .conf acl@_smtp@_predata string$**$ unset | |
11475 | This option defines the ACL that is run when an SMTP \\DATA\\ command is | |
11476 | received, before the message itself is received. See chapter ~~CHAPACL for | |
11477 | further details. | |
11478 | ||
11479 | .index \\QUIT\\||ACL for | |
11480 | .conf acl@_smtp@_quit string$**$ unset | |
11481 | This option defines the ACL that is run when an SMTP \\QUIT\\ command is | |
11482 | received. See chapter ~~CHAPACL for further details. | |
11483 | .nem | |
11484 | ||
11485 | .index \\RCPT\\||ACL for | |
11486 | .conf acl@_smtp@_rcpt string$**$ unset | |
495ae4b0 PH |
11487 | This option defines the ACL that is run when an SMTP \\RCPT\\ command is |
11488 | received. See chapter ~~CHAPACL for further details. | |
11489 | ||
11490 | .index \\STARTTLS\\, ACL for | |
11491 | .conf acl@_smtp@_starttls string$**$ unset | |
11492 | This option defines the ACL that is run when an SMTP \\STARTTLS\\ command is | |
11493 | received. See chapter ~~CHAPACL for further details. | |
11494 | ||
11495 | .index \\VRFY\\||ACL for | |
11496 | .conf acl@_smtp@_vrfy string$**$ unset | |
11497 | This option defines the ACL that is run when an SMTP \\VRFY\\ command is | |
11498 | received. See chapter ~~CHAPACL for further details. | |
11499 | ||
11500 | .conf admin@_groups "string list" unset | |
11501 | .index admin user | |
11502 | If the current group or any of the supplementary groups of the caller is in | |
11503 | this colon-separated list, the caller has admin privileges. If all your system | |
11504 | programmers are in a specific group, for example, you can give them all Exim | |
11505 | admin privileges by putting that group in \admin@_groups\. However, this does | |
11506 | not permit them to read Exim's spool files (whose group owner is the Exim gid). | |
11507 | To permit this, you have to add individuals to the Exim group. | |
11508 | ||
11509 | .conf allow@_domain@_literals boolean false | |
11510 | .index domain literal | |
11511 | If this option is set, the RFC 2822 domain literal format is permitted in | |
11512 | email addresses. The option is not set by default, because the domain literal | |
11513 | format is not normally required these days, and few people know about it. It | |
11514 | has, however, been exploited by mail abusers. | |
11515 | ||
4964e932 PH |
11516 | Unfortunately, it seems that some DNS black list maintainers are using this |
11517 | format to report black listing to postmasters. If you want to accept messages | |
11518 | addressed to your hosts by IP address, you need to set | |
11519 | \allow@_domain@_literals\ true, and also to add \"@@[]"\ to the list of local | |
11520 | domains (defined in the named domain list \local@_domains\ in the default | |
11521 | configuration). This `magic string' matches the domain literal form of all the | |
495ae4b0 PH |
11522 | local host's IP addresses. |
11523 | ||
11524 | .conf allow@_mx@_to@_ip boolean false | |
11525 | .index MX record||pointing to IP address | |
11526 | It appears that more and more DNS zone administrators are breaking the rules | |
11527 | and putting domain names that look like IP addresses on the right hand side of | |
11528 | MX records. Exim follows the rules and rejects this, giving an error message | |
11529 | that explains the mis-configuration. However, some other MTAs support this | |
11530 | practice, so to avoid `Why can't Exim do this?' complaints, \allow@_mx@_to@_ip\ | |
11531 | exists, in order to enable this heinous activity. It is not recommended, except | |
11532 | when you have no other choice. | |
11533 | ||
11534 | .index domain||UTF-8 characters in | |
11535 | .index UTF-8||in domain name | |
11536 | .conf allow@_utf8@_domains boolean false | |
11537 | Lots of discussion is going on about internationalized domain names. One | |
11538 | camp is strongly in favour of just using UTF-8 characters, and it seems | |
4964e932 | 11539 | that at least two other MTAs permit this. This option allows Exim users to |
495ae4b0 PH |
11540 | experiment if they wish. |
11541 | ||
11542 | If it is set true, Exim's domain parsing function allows valid | |
11543 | UTF-8 multicharacters to appear in domain name components, in addition to | |
11544 | letters, digits, and hyphens. However, just setting this option is not | |
11545 | enough; if you want to look up these domain names in the DNS, you must also | |
11546 | adjust the value of \dns@_check@_names@_pattern\ to match the extended form. A | |
11547 | suitable setting is: | |
11548 | .display asis | |
11549 | dns_check_names_pattern = (?i)^(?>(?(1)\.|())[a-z0-9\xc0-\xff]\ | |
11550 | (?>[-a-z0-9\x80-\xff]*[a-z0-9\x80-\xbf])?)+$ | |
11551 | .endd | |
11552 | Alternatively, you can just disable this feature by setting | |
11553 | .display asis | |
11554 | dns_check_names_pattern = | |
11555 | .endd | |
11556 | That is, set the option to an empty string so that no check is done. | |
11557 | ||
11558 | .conf auth@_advertise@_hosts "host list$**$" $*$ | |
11559 | .index authentication||advertising | |
11560 | .index \\AUTH\\||advertising | |
11561 | If any server authentication mechanisms are configured, Exim advertises them in | |
11562 | response to an \\EHLO\\ command only if the calling host matches this list. | |
11563 | Otherwise, Exim does not advertise \\AUTH\\. | |
4964e932 PH |
11564 | Exim does not accept \\AUTH\\ commands from clients to which it has not |
11565 | advertised the availability of \\AUTH\\. The advertising of individual | |
495ae4b0 | 11566 | authentication mechanisms can be controlled by the use of the |
4964e932 | 11567 | \server@_advertise@_condition\ generic authenticator option on the individual |
495ae4b0 PH |
11568 | authenticators. See chapter ~~CHAPSMTPAUTH for further details. |
11569 | ||
11570 | Certain mail clients (for example, Netscape) require the user to provide a name | |
11571 | and password for authentication if \\AUTH\\ is advertised, even though it may | |
11572 | not be needed (the host may accept messages from hosts on its local LAN without | |
11573 | authentication, for example). The \auth@_advertise@_hosts\ option can be used | |
11574 | to make these clients more friendly by excluding them from the set of hosts to | |
11575 | which Exim advertises \\AUTH\\. | |
11576 | ||
11577 | .index \\AUTH\\||advertising when encrypted | |
11578 | If you want to advertise the availability of \\AUTH\\ only when the connection | |
11579 | is encrypted using TLS, you can make use of the fact that the value of this | |
11580 | option is expanded, with a setting like this: | |
11581 | .display asis | |
11582 | auth_advertise_hosts = ${if eq{$tls_cipher}{}{}{*}} | |
11583 | .endd | |
4964e932 PH |
11584 | If \$tls@_cipher$\ is empty, the session is not encrypted, and the result of |
11585 | the expansion is empty, thus matching no hosts. Otherwise, the result of the | |
495ae4b0 PH |
11586 | expansion is $*$, which matches all hosts. |
11587 | ||
11588 | .conf auto@_thaw time 0s | |
11589 | .index thawing messages | |
11590 | .index unfreezing messages | |
11591 | If this option is set to a time greater than zero, a queue runner will try a | |
11592 | new delivery attempt on any frozen message if this much time has passed since | |
11593 | it was frozen. This may result in the message being re-frozen if nothing has | |
11594 | changed since the last attempt. It is a way of saying `keep on trying, even | |
11595 | though there are big problems'. See also \timeout@_frozen@_after\ and | |
11596 | \ignore@_bounce@_errors@_after\. | |
11597 | ||
d43194df PH |
11598 | .em |
11599 | .conf av@_scanner string "see below" | |
11600 | This option is available if Exim is built with the content-scanning extension. | |
11601 | It specifies which anti-virus scanner to use. The default value is: | |
11602 | .display asis | |
11603 | sophie:/var/run/sophie | |
11604 | .endd | |
11605 | If the value of \av@_scanner\ starts with dollar character, it is expanded | |
11606 | before use. See section ~~SECTscanvirus for further details. | |
11607 | .nem | |
11608 | ||
495ae4b0 PH |
11609 | .conf bi@_command string unset |
11610 | .index \-bi-\ option | |
11611 | This option supplies the name of a command that is run when Exim is called with | |
11612 | the \-bi-\ option (see chapter ~~CHAPcommandline). The string value is just the | |
11613 | command name, it is not a complete command line. If an argument is required, it | |
11614 | must come from the \-oA-\ command line option. | |
11615 | ||
11616 | .conf bounce@_message@_file string unset | |
11617 | .index bounce message||customizing | |
11618 | .index customizing||bounce message | |
11619 | This option defines a template file containing paragraphs of text to be used | |
11620 | for constructing bounce messages. Details of the file's contents are given in | |
11621 | chapter ~~CHAPemsgcust. See also \warn@_message@_file\. | |
11622 | ||
11623 | .conf bounce@_message@_text string unset | |
11624 | When this option is set, its contents are included in the default bounce | |
11625 | message immediately after `This message was created automatically by mail | |
11626 | delivery software.' It is not used if \bounce@_message@_file\ is set. | |
11627 | ||
11628 | .index bounce message||including body | |
11629 | .conf bounce@_return@_body boolean true | |
4964e932 PH |
11630 | This option controls whether the body of an incoming message is included in a |
11631 | bounce message when \bounce@_return@_message\ is true. If it is not set, only | |
495ae4b0 PH |
11632 | the message header is included. |
11633 | ||
11634 | .index bounce message||including original | |
11635 | .conf bounce@_return@_message boolean true | |
11636 | If this option is set false, the original message is not included in bounce | |
11637 | messages generated by Exim. See also \bounce@_return@_size@_limit\. | |
11638 | ||
11639 | .conf bounce@_return@_size@_limit integer 100K | |
11640 | .index size||of bounce, limit | |
11641 | .index bounce message||size limit | |
11642 | .index limit||bounce message size | |
11643 | This option sets a limit in bytes on the size of messages that are returned to | |
11644 | senders as part of bounce messages when \bounce@_return@_message\ is true. The | |
11645 | limit should be less than the value of the global \message@_size@_limit\ and of | |
11646 | any \message@_size@_limit\ settings on transports, to allow for the bounce text | |
11647 | that Exim generates. If this option is set to zero there is no limit. | |
11648 | ||
11649 | When the body of any message that is to be included in a bounce message is | |
11650 | greater than the limit, it is truncated, and a comment pointing this out is | |
11651 | added at the top. The actual cutoff may be greater than the value given, owing | |
11652 | to the use of buffering for transferring the message in chunks (typically 8K in | |
11653 | size). The idea is to save bandwidth on those undeliverable 15-megabyte | |
11654 | messages. | |
11655 | ||
11656 | .index bounce message||sender authentication | |
11657 | .index authentication||bounce message | |
11658 | .index \\AUTH\\||on bounce message | |
11659 | .conf bounce@_sender@_authentication string unset | |
11660 | This option provides an authenticated sender address that is sent with any | |
11661 | bounce messages generated by Exim that are sent over an authenticated SMTP | |
11662 | connection. A typical setting might be: | |
11663 | .display asis | |
11664 | bounce_sender_authentication = mailer-daemon@my.domain.example | |
11665 | .endd | |
11666 | which would cause bounce messages to be sent using the SMTP command: | |
11667 | .display asis | |
11668 | MAIL FROM:<> AUTH=mailer-daemon@my.domain.example | |
11669 | .endd | |
11670 | The value of \bounce@_sender@_authentication\ must always be a complete email | |
11671 | address. | |
11672 | ||
11673 | .index caching||callout, timeouts | |
11674 | .index callout||caching timeouts | |
11675 | .conf callout@_domain@_negative@_expire time 3h | |
11676 | This option specifies the expiry time for negative callout cache data for a | |
11677 | domain. See section ~~SECTcallver for details of callout verification, and | |
11678 | section ~~SECTcallvercache for details of the caching. | |
11679 | ||
11680 | .conf callout@_domain@_positive@_expire time 7d | |
11681 | This option specifies the expiry time for positive callout cache data for a | |
11682 | domain. See section ~~SECTcallver for details of callout verification, and | |
11683 | section ~~SECTcallvercache for details of the caching. | |
11684 | ||
11685 | .conf callout@_negative@_expire time 2h | |
11686 | This option specifies the expiry time for negative callout cache data for an | |
11687 | address. See section ~~SECTcallver for details of callout verification, and | |
11688 | section ~~SECTcallvercache for details of the caching. | |
11689 | ||
11690 | .conf callout@_positive@_expire time 24h | |
11691 | This option specifies the expiry time for positive callout cache data for an | |
11692 | address. See section ~~SECTcallver for details of callout verification, and | |
11693 | section ~~SECTcallvercache for details of the caching. | |
11694 | ||
11695 | .conf callout@_random@_local@_part string$**$ "see below" | |
4964e932 | 11696 | This option defines the `random' local part that can be used as part of callout |
495ae4b0 PH |
11697 | verification. The default value is |
11698 | .display asis | |
11699 | $primary_host_name-$tod_epoch-testing | |
11700 | .endd | |
11701 | See section ~~CALLaddparcall for details of how this value is used. | |
11702 | ||
11703 | .conf check@_log@_inodes integer 0 | |
11704 | See \check@_spool@_space\ below. | |
11705 | ||
11706 | .conf check@_log@_space integer 0 | |
11707 | See \check@_spool@_space\ below. | |
11708 | ||
11709 | .conf check@_spool@_inodes integer 0 | |
11710 | See \check@_spool@_space\ below. | |
11711 | ||
11712 | .conf check@_spool@_space integer 0 | |
11713 | .index checking disk space | |
11714 | .index disk space, checking | |
11715 | .index spool directory||checking space | |
11716 | The four \check@_...\ options allow for checking of disk resources before a | |
d43194df PH |
11717 | message is accepted. |
11718 | .em | |
11719 | When any of these options are set, they apply to all incoming messages. If you | |
11720 | want to apply different checks to different kinds of message, you can do so | |
11721 | by testing the the variables \$log@_inodes$\, \$log@_space$\, | |
11722 | \$spool@_inodes$\, and \$spool@_space$\ in an ACL with appropriate additional | |
11723 | conditions. | |
11724 | .nem | |
11725 | ||
11726 | \check@_spool@_space\ and \check@_spool@_inodes\ check the spool partition if | |
11727 | either value is greater than zero, for example: | |
495ae4b0 PH |
11728 | .display asis |
11729 | check_spool_space = 10M | |
11730 | check_spool_inodes = 100 | |
11731 | .endd | |
d43194df | 11732 | The spool partition is the one that contains the directory defined by |
495ae4b0 PH |
11733 | \\SPOOL@_DIRECTORY\\ in \(Local/Makefile)\. It is used for holding messages in |
11734 | transit. | |
11735 | ||
11736 | \check@_log@_space\ and \check@_log@_inodes\ check the partition in which log | |
11737 | files are written if either is greater than zero. These should be set only if | |
11738 | \log@_file@_path\ and \spool@_directory\ refer to different partitions. | |
11739 | ||
11740 | If there is less space or fewer inodes than requested, Exim refuses to accept | |
11741 | incoming mail. In the case of SMTP input this is done by giving a 452 temporary | |
11742 | error response to the \\MAIL\\ command. If ESMTP is in use and there was a | |
11743 | \\SIZE\\ parameter on the \\MAIL\\ command, its value is added to the | |
11744 | \check@_spool@_space\ value, and the check is performed even if | |
11745 | \check@_spool@_space\ is zero, unless \no@_smtp@_check@_spool@_space\ is set. | |
11746 | ||
11747 | The values for \check@_spool@_space\ and \check@_log@_space\ are held as a | |
11748 | number of kilobytes. If a non-multiple of 1024 is specified, it is rounded up. | |
11749 | ||
11750 | For non-SMTP input and for batched SMTP input, the test is done at start-up; on | |
11751 | failure a message is written to stderr and Exim exits with a non-zero code, as | |
11752 | it obviously cannot send an error message of any kind. | |
11753 | ||
11754 | .index port||for daemon | |
11755 | .index TCP/IP||setting listening ports | |
11756 | .conf daemon@_smtp@_ports string "$tt{smtp}" | |
11757 | This option specifies one or more default SMTP ports on which the Exim daemon | |
4964e932 | 11758 | listens. See chapter ~~CHAPinterfaces for details of how it is used. For |
495ae4b0 PH |
11759 | backward compatibility, \daemon@_smtp@_port\ (singular) is a synonym. |
11760 | ||
11761 | .conf delay@_warning "time list" 24h | |
11762 | .index warning of delay | |
11763 | .index delay warning, specifying | |
11764 | When a message is delayed, Exim sends a warning message to the sender at | |
d43194df PH |
11765 | intervals specified by this option. The data is a colon-separated list of times |
11766 | after which to send warning messages. | |
11767 | .em | |
11768 | If the value of the option is an empty string or a zero time, no warnings are | |
11769 | sent. | |
11770 | .nem | |
11771 | Up to 10 times may be given. If a message has been on the queue for longer than | |
11772 | the last time, the last interval between the times is used to compute | |
11773 | subsequent warning times. For example, with | |
495ae4b0 PH |
11774 | .display asis |
11775 | delay_warning = 4h:8h:24h | |
11776 | .endd | |
11777 | the first message is sent after 4 hours, the second after 8 hours, and | |
4964e932 PH |
11778 | the third one after 24 hours. After that, messages are sent every 16 hours, |
11779 | because that is the interval between the last two times on the list. If you set | |
495ae4b0 PH |
11780 | just one time, it specifies the repeat interval. For example, with: |
11781 | .display asis | |
11782 | delay_warning = 6h | |
11783 | .endd | |
11784 | messages are repeated every six hours. To stop warnings after a given time, set | |
11785 | a very large time at the end of the list. For example: | |
11786 | .display asis | |
11787 | delay_warning = 2h:12h:99d | |
11788 | .endd | |
11789 | ||
11790 | .conf delay@_warning@_condition string$**$ "see below" | |
11791 | The string is expanded at the time a warning message might be sent. If all the | |
11792 | deferred addresses have the same domain, it is set in \$domain$\ during the | |
11793 | expansion. Otherwise \$domain$\ is empty. If the result of the expansion is a | |
11794 | forced failure, an empty string, or a string matching any of `0', `no' or | |
11795 | `false' (the comparison being done caselessly) then the warning message is not | |
11796 | sent. The default is | |
11797 | .display asis | |
11798 | delay_warning_condition = \ | |
11799 | ${if match{$h_precedence:}{(?i)bulk|list|junk}{no}{yes}} | |
11800 | .endd | |
11801 | which suppresses the sending of warnings about messages that have `bulk', | |
11802 | `list' or `junk' in a ::Precedence:: header. | |
11803 | ||
11804 | .index unprivileged delivery | |
11805 | .index delivery||unprivileged | |
11806 | .conf deliver@_drop@_privilege boolean false | |
11807 | If this option is set true, Exim drops its root privilege at the start of a | |
11808 | delivery process, and runs as the Exim user throughout. This severely restricts | |
11809 | the kinds of local delivery that are possible, but is viable in certain types | |
11810 | of configuration. There is a discussion about the use of root privilege in | |
11811 | chapter ~~CHAPsecurity. | |
11812 | ||
11813 | .index load average | |
11814 | .index queue runner||abandoning | |
11815 | .conf deliver@_queue@_load@_max fixed-point unset | |
11816 | When this option is set, a queue run is abandoned if the system load average | |
11817 | becomes greater than the value of the option. The option has no effect on | |
11818 | ancient operating systems on which Exim cannot determine the load average. | |
11819 | See also \queue@_only@_load\ and \smtp@_load@_reserve\. | |
11820 | ||
11821 | .conf delivery@_date@_remove boolean true | |
11822 | .index ::Delivery-date:: header line | |
11823 | Exim's transports have an option for adding a ::Delivery-date:: header to a | |
11824 | message when it is delivered -- in exactly the same way as ::Return-path:: is | |
11825 | handled. ::Delivery-date:: records the actual time of delivery. Such headers | |
11826 | should not be present in incoming messages, and this option causes them to be | |
11827 | removed at the time the message is received, to avoid any problems that might | |
11828 | occur when a delivered message is subsequently sent on to some other recipient. | |
11829 | ||
11830 | .index DNS||`try again' response, overriding | |
11831 | .conf dns@_again@_means@_nonexist "domain list$**$" unset | |
11832 | DNS lookups give a `try again' response for the DNS errors `non-authoritative | |
11833 | host not found' and `\\SERVERFAIL\\'. This can cause Exim to keep trying to | |
11834 | deliver a message, or to give repeated temporary errors to incoming mail. | |
11835 | Sometimes the effect is caused by a badly set up name server and may persist | |
11836 | for a long time. If a domain which exhibits this problem matches anything in | |
11837 | \dns__again__means__nonexist\, it is treated as if it did not exist. This | |
11838 | option should be used with care. | |
495ae4b0 PH |
11839 | You can make it apply to reverse lookups by a setting such as this: |
11840 | .display asis | |
11841 | dns_again_means_nonexist = *.in-addr.arpa | |
11842 | .endd | |
d43194df PH |
11843 | .em |
11844 | This option applies to all DNS lookups that Exim does. The \%dnslookup%\ router | |
11845 | has some options of its own for controlling what happens when lookups for MX or | |
11846 | SRV records give temporary errors. These more specific options are applied | |
11847 | after the global option. | |
11848 | .nem | |
495ae4b0 PH |
11849 | |
11850 | .index DNS||pre-check of name syntax | |
11851 | .conf dns@_check@_names@_pattern string "see below" | |
11852 | When this option is set to a non-empty string, it causes Exim to check domain | |
11853 | names for illegal characters before handing them to the DNS resolver, because | |
11854 | some resolvers give temporary errors for malformed names. If a domain name | |
11855 | contains any illegal characters, a `not found' result is forced, and the | |
11856 | resolver is not called. The check is done by matching the domain name against a | |
11857 | regular expression, which is the value of this option. The default pattern is | |
11858 | .display asis | |
11859 | dns_check_names_pattern = \ | |
11860 | (?i)^(?>(?(1)\.|())[^\W_](?>[a-z0-9-]*[^\W_])?)+$ | |
11861 | .endd | |
11862 | which permits only letters, digits, and hyphens in components, but they may not | |
11863 | start or end with a hyphen. | |
4964e932 | 11864 | If you set \allow@_utf8@_domains\, you must modify this pattern, or set the |
495ae4b0 PH |
11865 | option to an empty string. |
11866 | ||
11867 | .conf dns@_ipv4@_lookup "domain list$**$" unset | |
11868 | .index IPv6||DNS lookup for AAAA records | |
11869 | .index DNS||IPv6 lookup for AAAA records | |
11870 | When Exim is compiled with IPv6 support, it looks for IPv6 address records | |
11871 | (AAAA and, if configured, A6) as well as IPv4 address records when trying to | |
11872 | find IP addresses for hosts, unless the host's domain matches this list. | |
11873 | ||
11874 | This is a fudge to help with name servers that give big delays or otherwise do | |
11875 | not work for the new IPv6 record types. If Exim is handed an IPv6 address | |
11876 | record as a result of an MX lookup, it always recognizes it, and may as a | |
11877 | result make an outgoing IPv6 connection. All this option does is to make Exim | |
11878 | look only for IPv4-style A records when it needs to find an IP address for a | |
11879 | host name. In due course, when the world's name servers have all been upgraded, | |
11880 | there should be no need for this option. | |
11881 | ||
11882 | .conf dns@_retrans time 0s | |
11883 | .index DNS||resolver options | |
11884 | The options \dns@_retrans\ and \dns@_retry\ can be used to set the | |
11885 | retransmission and retry parameters for DNS lookups. Values of zero (the | |
11886 | defaults) leave the system default settings unchanged. The first value is the | |
11887 | time between retries, and the second is the number of retries. It isn't | |
11888 | totally clear exactly how these settings affect the total time a DNS lookup may | |
11889 | take. I haven't found any documentation about timeouts on DNS lookups; these | |
11890 | parameter values are available in the external resolver interface structure, | |
11891 | but nowhere does it seem to describe how they are used or what you might want | |
11892 | to set in them. | |
11893 | ||
11894 | .conf dns@_retry integer 0 | |
11895 | See \dns@_retrans\ above. | |
11896 | ||
11897 | .conf drop@_cr boolean false | |
4964e932 PH |
11898 | This is an obsolete option that is now a no-op. It used to affect the way Exim |
11899 | handled CR and LF characters in incoming messages. What happens now is | |
495ae4b0 PH |
11900 | described in section ~~SECTlineendings. |
11901 | ||
11902 | .conf envelope@_to@_remove boolean true | |
11903 | .index ::Envelope-to:: header line | |
11904 | Exim's transports have an option for adding an ::Envelope-to:: header to a | |
11905 | message when it is delivered -- in exactly the same way as ::Return-path:: is | |
11906 | handled. ::Envelope-to:: records the original recipient address from the | |
11907 | messages's envelope that caused the delivery to happen. Such headers should not | |
11908 | be present in incoming messages, and this option causes them to be removed at | |
11909 | the time the message is received, to avoid any problems that might occur when a | |
11910 | delivered message is subsequently sent on to some other recipient. | |
11911 | ||
11912 | .conf errors@_copy "string list$**$" unset | |
11913 | .index bounce message||copy to other address | |
11914 | .index copy of bounce message | |
11915 | Setting this option causes Exim to send bcc copies of bounce messages that it | |
11916 | generates to other addresses. \**Note**\: this does not apply to bounce messages | |
11917 | coming from elsewhere. The value of the option is a colon-separated list of | |
11918 | items. Each item consists of a pattern, terminated by white space, followed by | |
11919 | a comma-separated list of email addresses. If a pattern contains spaces, it | |
11920 | must be enclosed in double quotes. | |
11921 | ||
11922 | Each pattern is processed in the same way as a single item in an address list | |
11923 | (see section ~~SECTaddresslist). When a pattern matches the recipient of the | |
11924 | bounce message, the message is copied to the addresses on the list. The items | |
11925 | are scanned in order, and once a matching one is found, no further items are | |
11926 | examined. For example: | |
11927 | .display asis | |
11928 | errors_copy = spqr@mydomain postmaster@mydomain.example :\ | |
11929 | rqps@mydomain hostmaster@mydomain.example,\ | |
11930 | postmaster@mydomain.example | |
11931 | .endd | |
11932 | The address list is expanded before use. The expansion variables | |
11933 | \$local@_part$\ and \$domain$\ are set from the original recipient of the error | |
11934 | message, and if there was any wildcard matching in the pattern, the expansion | |
4964e932 | 11935 | .index numerical variables (\$1$\, \$2$\, etc)||in \errors@_copy\ |
495ae4b0 PH |
11936 | variables \$0$\, \$1$\, etc. are set in the normal way. |
11937 | ||
11938 | .conf errors@_reply@_to string unset | |
11939 | .index bounce message||::Reply-to:: in | |
11940 | Exim's bounce and delivery warning messages contain the header line | |
11941 | .display | |
11942 | From: Mail Delivery System @<Mailer-Daemon@@<<qualify-domain>>@> | |
11943 | .endd | |
4964e932 | 11944 | where <<qualify-domain>> is the value of the \qualify@_domain\ option. |
495ae4b0 PH |
11945 | Experience shows that people reply to bounce messages. If the |
11946 | \errors@_reply@_to\ option is set, a ::Reply-To:: header is added to bounce and | |
11947 | warning messages. For example: | |
11948 | .display asis | |
11949 | errors_reply_to = postmaster@my.domain.example | |
11950 | .endd | |
11951 | The value of the option is not expanded. It must specify a valid RFC 2822 | |
11952 | address. | |
11953 | ||
11954 | .conf exim@_group string "compile-time configured" | |
11955 | .index gid (group id)||Exim's own | |
11956 | .index Exim group | |
11957 | This option changes the gid under which Exim runs when it gives up root | |
11958 | privilege. The default value is compiled into the binary. The value of this | |
11959 | option is used only when \exim@_user\ is also set. Unless it consists entirely | |
11960 | of digits, the string is looked up using \*getgrnam()*\, and failure causes a | |
11961 | configuration error. See chapter ~~CHAPsecurity for a discussion of security | |
11962 | issues. | |
11963 | ||
11964 | .conf exim@_path string "see below" | |
11965 | .index Exim binary, path name | |
11966 | This option specifies the path name of the Exim binary, which is used when Exim | |
11967 | needs to re-exec itself. The default is set up to point to the file \*exim*\ in | |
11968 | the directory configured at compile time by the \\BIN@_DIRECTORY\\ setting. It | |
11969 | is necessary to change \exim@_path\ if, exceptionally, Exim is run from some | |
11970 | other place. | |
4964e932 PH |
11971 | \**Warning**\: Do not use a macro to define the value of this option, because |
11972 | you will break those Exim utilities that scan the configuration file to find | |
11973 | where the binary is. (They then use the \-bP-\ option to extract option | |
495ae4b0 PH |
11974 | settings such as the value of \spool@_directory\.) |
11975 | ||
11976 | .conf exim@_user string "compile-time configured" | |
11977 | .index uid (user id)||Exim's own | |
11978 | .index Exim user | |
11979 | This option changes the uid under which Exim runs when it gives up root | |
11980 | privilege. The default value is compiled into the binary. Ownership of the run | |
11981 | time configuration file and the use of the \-C-\ and \-D-\ command line options | |
11982 | is checked against the values in the binary, not what is set here. | |
11983 | ||
11984 | Unless it consists entirely of digits, the string is looked up using | |
11985 | \*getpwnam()*\, and failure causes a configuration error. If \exim@_group\ is | |
11986 | not also supplied, the gid is taken from the result of \*getpwnam()*\ if it is | |
11987 | used. See chapter ~~CHAPsecurity for a discussion of security issues. | |
11988 | ||
11989 | .conf extra@_local@_interfaces "string list" unset | |
4964e932 PH |
11990 | .index |
11991 | This option defines network interfaces that are to be considered local when | |
11992 | routing, but which are not used for listening by the daemon. See section | |
495ae4b0 PH |
11993 | ~~SECTreclocipadd for details. |
11994 | ||
11995 | .conf extract@_addresses@_remove@_arguments boolean true | |
11996 | .index \-t-\ option | |
11997 | .index command line||addresses with \-t-\ | |
11998 | .index Sendmail compatibility||\-t-\ option | |
11999 | According to some Sendmail documentation (Sun, IRIX, HP-UX), if any addresses | |
12000 | are present on the command line when the \-t-\ option is used to build an | |
12001 | envelope from a message's ::To::, ::Cc:: and ::Bcc:: headers, the command line | |
12002 | addresses are removed from the recipients list. This is also how Smail behaves. | |
12003 | However, other Sendmail documentation (the O'Reilly book) states that command | |
12004 | line addresses are added to those obtained from the header lines. When | |
d43194df | 12005 | \extract__addresses__remove__arguments\ is true (the default), Exim subtracts |
495ae4b0 PH |
12006 | argument headers. If it is set false, Exim adds rather than removes argument |
12007 | addresses. | |
12008 | ||
12009 | .conf finduser@_retries integer 0 | |
12010 | .index NIS, looking up users, retrying | |
12011 | On systems running NIS or other schemes in which user and group information is | |
12012 | distributed from a remote system, there can be times when \*getpwnam()*\ and | |
12013 | related functions fail, even when given valid data, because things time out. | |
12014 | Unfortunately these failures cannot be distinguished from genuine `not found' | |
12015 | errors. If \finduser@_retries\ is set greater than zero, Exim will try that | |
12016 | many extra times to find a user or a group, waiting for one second between | |
12017 | retries. | |
12018 | ||
d43194df PH |
12019 | .index \(/etc/passwd)\, multiple reading of |
12020 | .em | |
12021 | You should not set this option greater than zero if your user information is in | |
12022 | a traditional \(/etc/passwd)\ file, because it will cause Exim needlessly to | |
12023 | search the file multiple times for non-existent users, and also cause delay. | |
12024 | .nem | |
12025 | ||
495ae4b0 PH |
12026 | .conf freeze@_tell "string list, comma separated" unset |
12027 | .index freezing messages||sending a message when freezing | |
12028 | On encountering certain errors, or when configured to do so in a system filter, | |
12029 | or in an ACL, | |
12030 | Exim freezes a message. This means that no further delivery attempts take place | |
12031 | until an administrator (or the \auto@_thaw\ feature) thaws the message. If | |
12032 | \freeze@_tell\ is set, Exim generates a warning message whenever it freezes | |
4964e932 | 12033 | something, unless the message it is freezing is a |
495ae4b0 PH |
12034 | locally-generated |
12035 | bounce message. (Without this exception there is the possibility of looping.) | |
12036 | The warning message is sent to the addresses supplied as the comma-separated | |
12037 | value of this option. If several of the message's addresses cause freezing, | |
4964e932 | 12038 | only a single message is sent. |
495ae4b0 | 12039 | If the freezing was automatic, the reason(s) for freezing can be found in the |
4964e932 | 12040 | message log. If you configure freezing in a filter or ACL, you must arrange for |
495ae4b0 PH |
12041 | any logging that you require. |
12042 | ||
12043 | .conf gecos@_name string$**$ unset | |
12044 | .index HP-UX | |
12045 | .index `gecos' field, parsing | |
12046 | Some operating systems, notably HP-UX, use the `gecos' field in the system | |
12047 | password file to hold other information in addition to users' real names. Exim | |
12048 | looks up this field for use when it is creating ::Sender:: or ::From:: headers. | |
12049 | If either \gecos@_pattern\ or \gecos@_name\ are unset, the contents of the | |
12050 | field are used unchanged, except that, if an ampersand is encountered, it is | |
12051 | replaced by the user's login name with the first character forced to | |
12052 | upper case, since this is a convention that is observed on many systems. | |
12053 | ||
12054 | When these options are set, \gecos@_pattern\ is treated as a regular expression | |
12055 | that is to be applied to the field (again with & replaced by the login name), | |
12056 | and if it matches, \gecos@_name\ is expanded and used as the user's name. | |
4964e932 | 12057 | .index numerical variables (\$1$\, \$2$\, etc)||in \gecos@_name\ |
495ae4b0 PH |
12058 | Numeric variables such as \$1$\, \$2$\, etc. can be used in the expansion to |
12059 | pick up sub-fields that were matched by the pattern. In HP-UX, where the user's | |
12060 | name terminates at the first comma, the following can be used: | |
12061 | .display asis | |
12062 | gecos_pattern = ([^,]*) | |
12063 | gecos_name = $1 | |
12064 | .endd | |
12065 | ||
12066 | .conf gecos@_pattern string unset | |
12067 | See \gecos@_name\ above. | |
12068 | ||
12069 | .conf headers@_charset string "see below" | |
12070 | This option sets a default character set for translating from encoded MIME | |
12071 | `words' in header lines, when referenced by an \$h@_xxx$\ expansion item. The | |
12072 | default is the value of \\HEADERS@_CHARSET\\ in \(Local/Makefile)\. The | |
12073 | ultimate default is ISO-8859-1. For more details see the description of header | |
12074 | insertions in section ~~SECTexpansionitems. | |
12075 | ||
12076 | ||
12077 | .conf header@_maxsize integer "see below" | |
12078 | .index header section||maximum size of | |
12079 | .index limit||size of message header section | |
12080 | This option controls the overall maximum size of a message's header | |
12081 | section. The default is the value of \\HEADER@_MAXSIZE\\ in | |
4964e932 | 12082 | \(Local/Makefile)\; the default for that is 1M. Messages with larger header |
495ae4b0 PH |
12083 | sections are rejected. |
12084 | ||
12085 | .conf header@_line@_maxsize integer 0 | |
4964e932 | 12086 | .index header lines||maximum size of |
495ae4b0 PH |
12087 | .index limit||size of one header line |
12088 | This option limits the length of any individual header line in a message, after | |
12089 | all the continuations have been joined together. Messages with individual | |
12090 | header lines that are longer than the limit are rejected. The default value of | |
12091 | zero means `no limit'. | |
12092 | ||
12093 | ||
12094 | ||
12095 | .conf helo@_accept@_junk@_hosts "host list$**$" unset | |
12096 | .index \\HELO\\||accepting junk data | |
12097 | .index \\EHLO\\||accepting junk data | |
12098 | Exim checks the syntax of \\HELO\\ and \\EHLO\\ commands for incoming SMTP | |
12099 | mail, and gives an error response for invalid data. Unfortunately, there are | |
12100 | some SMTP clients that send syntactic junk. They can be accommodated by setting | |
12101 | this option. Note that this is a syntax check only. See \helo@_verify@_hosts\ | |
12102 | if you want to do semantic checking. | |
4964e932 | 12103 | See also \helo@_allow@_chars\ for a way of extending the permitted character |
495ae4b0 PH |
12104 | set. |
12105 | ||
12106 | .conf helo@_allow@_chars string unset | |
12107 | .index \\HELO\\||underscores in | |
12108 | .index \\EHLO\\||underscores in | |
12109 | .index underscore in \\EHLO\\/\\HELO\\ | |
12110 | This option can be set to a string of rogue characters that are permitted in | |
12111 | all \\EHLO\\ and \\HELO\\ names in addition to the standard letters, digits, | |
12112 | hyphens, and dots. If you really must allow underscores, you can set | |
12113 | .display asis | |
12114 | helo_allow_chars = _ | |
12115 | .endd | |
12116 | Note that the value is one string, not a list. | |
12117 | ||
12118 | .conf helo@_lookup@_domains "domain list$**$" "$tt{@@:@@[]}" | |
12119 | .index \\HELO\\||forcing reverse lookup | |
12120 | .index \\EHLO\\||forcing reverse lookup | |
12121 | If the domain given by a client in a \\HELO\\ or \\EHLO\\ command matches this | |
12122 | list, a reverse lookup is done in order to establish the host's true name. The | |
12123 | default forces a lookup if the client host gives the server's name or any of | |
12124 | its IP addresses (in brackets), something that broken clients have been seen to | |
12125 | do. | |
12126 | ||
12127 | .conf helo@_try@_verify@_hosts "host list$**$" unset | |
12128 | .index \\HELO\\||verifying, optional | |
12129 | .index \\EHLO\\||verifying, optional | |
12130 | The RFCs mandate that a server must not reject a message because it doesn't | |
12131 | like the \\HELO\\ or \\EHLO\\ command. By default, Exim just checks the syntax | |
12132 | of these commands (see \helo__accept__junk__hosts\ and \helo@_allow@_chars\ | |
12133 | above). However, some sites like to be stricter. If the calling host matches | |
12134 | \helo@_try@_verify@_hosts\, Exim checks that the host name given in the \\HELO\\ | |
12135 | or \\EHLO\\ command either: | |
12136 | .numberpars $. | |
12137 | is an IP literal matching the calling address of the host (the RFCs | |
12138 | specifically allow this), or | |
12139 | .nextp | |
12140 | .index DNS||reverse lookup | |
12141 | .index reverse DNS lookup | |
12142 | matches the host name that Exim obtains by doing a reverse lookup of the | |
12143 | calling host address, or | |
12144 | .nextp | |
12145 | when looked up using \*gethostbyname()*\ (or \*getipnodebyname()*\ when | |
12146 | available) yields the calling host address. | |
12147 | .endp | |
4964e932 | 12148 | However, the \\EHLO\\ or \\HELO\\ command is not rejected if any of the checks |
495ae4b0 PH |
12149 | fail. Processing continues, but the result of the check is remembered, and can |
12150 | be detected later in an ACL by the \"verify = helo"\ condition. If you want | |
12151 | verification failure to cause rejection of \\EHLO\\ or \\HELO\\, use | |
12152 | \helo@_verify@_hosts\ instead. | |
12153 | ||
12154 | ||
12155 | .conf helo@_verify@_hosts "host list$**$" unset | |
12156 | .index \\HELO\\||verifying, mandatory | |
12157 | .index \\EHLO\\||verifying, mandatory | |
12158 | For hosts that match this option, Exim checks the host name given in the | |
12159 | \\HELO\\ or \\EHLO\\ in the same way as for \helo@_try@_verify@_hosts\. If the | |
12160 | check fails, the \\HELO\\ or \\EHLO\\ command is rejected with a 550 error, and | |
12161 | entries are written to the main and reject logs. If a \\MAIL\\ command is | |
4964e932 PH |
12162 | received before \\EHLO\\ or \\HELO\\, it is rejected with a |
12163 | 503 | |
495ae4b0 PH |
12164 | error. |
12165 | ||
12166 | .conf hold@_domains "domain list$**$" unset | |
12167 | .index domain||delaying delivery | |
12168 | .index delivery||delaying certain domains | |
12169 | This option allows mail for particular domains to be held on the queue | |
12170 | manually. The option is overridden if a message delivery is forced with the | |
12171 | \-M-\, \-qf-\, \-Rf-\ or \-Sf-\ options, and also while testing or verifying | |
12172 | addresses using \-bt-\ or \-bv-\. Otherwise, if a domain matches an item in | |
12173 | \hold@_domains\, no routing or delivery for that address is done, and it is | |
12174 | deferred every time the message is looked at. | |
12175 | ||
12176 | This option is intended as a temporary operational measure for delaying the | |
12177 | delivery of mail while some problem is being sorted out, or some new | |
12178 | configuration tested. If you just want to delay the processing of some | |
12179 | domains until a queue run occurs, you should use \queue@_domains\ or | |
12180 | \queue@_smtp@_domains\, not \hold@_domains\. | |
12181 | ||
12182 | A setting of \hold@_domains\ does not override Exim's code for removing | |
12183 | messages from the queue if they have been there longer than the longest retry | |
12184 | time in any retry rule. If you want to hold messages for longer than the normal | |
12185 | retry times, insert a dummy retry rule with a long retry time. | |
12186 | ||
12187 | .conf host@_lookup "host list$**$" unset | |
12188 | .index host||name lookup, forcing | |
12189 | Exim does not look up the name of a calling host from its IP address unless it | |
12190 | is required to compare against some host list, or the host matches | |
12191 | \helo@_try@_verify@_hosts\ or \helo@_verify@_hosts\, or the host matches this | |
12192 | option (which normally contains IP addresses rather than host names). The | |
12193 | default configuration file contains | |
12194 | .display asis | |
12195 | host_lookup = * | |
12196 | .endd | |
12197 | which causes a lookup to happen for all hosts. If the expense of these lookups | |
12198 | is felt to be too great, the setting can be changed or removed. | |
12199 | ||
12200 | After a successful reverse lookup, Exim does a forward lookup on the name it | |
12201 | has obtained, to verify that it yields the IP address that it started with. If | |
12202 | this check fails, Exim behaves as if the name lookup failed. | |
12203 | ||
12204 | After any kind of failure, the host name (in \$sender@_host@_name$\) remains | |
12205 | unset, and \$host@_lookup@_failed$\ is set to the string `1'. See also | |
12206 | \dns@_again@_means@_nonexist\, \helo__lookup__domains\, and \"verify = | |
12207 | reverse@_host@_lookup"\ in ACLs. | |
12208 | ||
12209 | .conf host@_lookup@_order "string list" $tt{bydns:byaddr} | |
12210 | This option specifies the order of different lookup methods when Exim is trying | |
4964e932 | 12211 | to find a host name from an IP address. The default is to do a DNS lookup |
495ae4b0 PH |
12212 | first, and then to try a local lookup (using \*gethostbyaddr()*\ or equivalent) |
12213 | if that fails. You can change the order of these lookups, or omit one entirely, | |
12214 | if you want. | |
12215 | ||
12216 | \**Warning**\: the `byaddr' method does not always yield aliases when there are | |
4964e932 | 12217 | multiple PTR records in the DNS and the IP address is not listed in |
495ae4b0 PH |
12218 | \(/etc/hosts)\. Different operating systems give different results in this |
12219 | case. That is why the default tries a DNS lookup first. | |
12220 | ||
12221 | ||
12222 | .conf host@_reject@_connection "host list$**$" unset | |
12223 | .index host||rejecting connections from | |
12224 | If this option is set, incoming SMTP calls from the hosts listed are rejected | |
4964e932 | 12225 | as soon as the connection is made. |
495ae4b0 PH |
12226 | This option is obsolete, and retained only for backward compatibility, because |
12227 | nowadays the ACL specified by \acl@_smtp@_connect\ can also reject incoming | |
12228 | connections immediately. | |
12229 | ||
12230 | The ability to give an immediate rejection (either by this option or using an | |
12231 | ACL) is provided for use in unusual cases. Many hosts will just try again, | |
12232 | sometimes without much delay. Normally, it is better to use an ACL to reject | |
12233 | incoming messages at a later stage, such as after \\RCPT\\ commands. See | |
12234 | chapter ~~CHAPACL. | |
12235 | ||
d43194df PH |
12236 | .em |
12237 | .conf hosts@_connection@_nolog "host list$**$" unset | |
12238 | .index host||not logging connections from | |
12239 | This option defines a list of hosts for which connection logging does not | |
12240 | happen, even though the \smtp@_connection\ log selector is set. For example, | |
12241 | you might want not to log SMTP connections from local processes, or from | |
12242 | 127.0.0.1, or from your local LAN. This option is consulted in the main loop of | |
12243 | the daemon; you should therefore strive to restrict its value to a short inline | |
12244 | list of IP addresses and networks. To disable logging SMTP connections from | |
12245 | local processes, you must create a host list with an empty item. For example: | |
12246 | .display asis | |
12247 | hosts_connection_nolog = : | |
12248 | .endd | |
12249 | If the \smtp@_connection\ log selector is not set, this option has no effect. | |
12250 | .nem | |
12251 | ||
495ae4b0 PH |
12252 | .conf hosts@_treat@_as@_local "domain list$**$" unset |
12253 | .index local host||domains treated as | |
12254 | .index host||treated as local | |
12255 | If this option is set, any host names that match the domain list are treated as | |
12256 | if they were the local host when Exim is scanning host lists obtained from MX | |
12257 | records | |
12258 | or other sources. Note that the value of this option is a domain list, not a | |
12259 | host list, because it is always used to check host names, not IP addresses. | |
12260 | ||
12261 | This option also applies when Exim is matching the special items | |
12262 | \"@@mx@_any"\, \"@@mx@_primary"\, and \"@@mx@_secondary"\ in a domain list (see | |
12263 | section ~~SECTdomainlist), and when checking the \hosts\ option in the \%smtp%\ | |
12264 | transport for the local host (see the \allow@_localhost\ option in that | |
12265 | transport). | |
4964e932 PH |
12266 | See also \local@_interfaces\, \extra@_local@_interfaces\, and chapter |
12267 | ~~CHAPinterfaces, which contains a discussion about local network interfaces | |
495ae4b0 PH |
12268 | and recognising the local host. |
12269 | ||
12270 | .conf ignore@_bounce@_errors@_after time 10w | |
12271 | .index bounce message||discarding | |
12272 | .index discarding bounce message | |
4964e932 PH |
12273 | This option affects the processing of bounce messages that cannot be delivered, |
12274 | that is, those that suffer a permanent delivery failure. (Bounce messages that | |
495ae4b0 PH |
12275 | suffer temporary delivery failures are of course retried in the usual way.) |
12276 | ||
12277 | After a permanent delivery failure, bounce messages are frozen, | |
12278 | because there is no sender to whom they can be returned. When a frozen bounce | |
12279 | message has been on the queue for more than the given time, it is unfrozen at | |
12280 | the next queue run, and a further delivery is attempted. If delivery fails | |
12281 | again, the bounce message is discarded. This makes it possible to keep failed | |
12282 | bounce messages around for a shorter time than the normal maximum retry time | |
12283 | for frozen messages. For example, | |
12284 | .display asis | |
12285 | ignore_bounce_errors_after = 12h | |
12286 | .endd | |
12287 | retries failed bounce message deliveries after 12 hours, discarding any further | |
12288 | failures. If the value of this option is set to a zero time period, bounce | |
12289 | failures are discarded immediately. Setting a very long time (as in the default | |
12290 | value) has the effect of disabling this option. For ways of automatically | |
12291 | dealing with other kinds of frozen message, see \auto@_thaw\ and | |
12292 | \timeout@_frozen@_after\. | |
12293 | ||
12294 | .conf ignore@_fromline@_hosts "host list$**$" unset | |
12295 | .index `From' line | |
12296 | .index UUCP||`From' line | |
12297 | Some broken SMTP clients insist on sending a UUCP-like `From' line before the | |
12298 | headers of a message. By default this is treated as the start of the message's | |
12299 | body, which means that any following headers are not recognized as such. Exim | |
12300 | can be made to ignore it by setting \ignore@_fromline@_hosts\ to match those | |
12301 | hosts that insist on sending it. If the sender is actually a local process | |
12302 | rather than a remote host, and is using \-bs-\ to inject the messages, | |
12303 | \ignore__fromline__local\ must be set to achieve this effect. | |
12304 | ||
12305 | .conf ignore@_fromline@_local boolean false | |
12306 | See \ignore@_fromline@_hosts\ above. | |
12307 | ||
12308 | .conf keep@_malformed time 4d | |
12309 | This option specifies the length of time to keep messages whose spool files | |
12310 | have been corrupted in some way. This should, of course, never happen. At the | |
12311 | next attempt to deliver such a message, it gets removed. The incident is | |
12312 | logged. | |
12313 | ||
12314 | .conf ldap@_default@_servers "string list" unset | |
12315 | .index LDAP||default servers | |
12316 | This option provides a list of LDAP servers which are tried in turn when an | |
12317 | LDAP query does not contain a server. See section ~~SECTforldaque for details | |
12318 | of LDAP queries. This option is available only when Exim has been built with | |
12319 | LDAP support. | |
12320 | ||
12321 | .conf ldap@_version integer unset | |
12322 | .index LDAP||protocol version, forcing | |
12323 | This option can be used to force Exim to set a specific protocol version for | |
12324 | LDAP. If it option is unset, it is shown by the \-bP-\ command line option as | |
12325 | -1. When this is the case, the default is 3 if \\LDAP@_VERSION3\\ is defined in | |
12326 | the LDAP headers; otherwise it is 2. This option is available only when Exim | |
12327 | has been built with LDAP support. | |
12328 | ||
12329 | ||
12330 | .conf local@_from@_check boolean true | |
12331 | .index ::Sender:: header line||disabling addition of | |
12332 | .index ::From:: header line||disabling checking of | |
12333 | When a message is submitted locally (that is, not over a TCP/IP connection) by | |
12334 | an untrusted user, Exim removes any existing ::Sender:: header line, and checks | |
d43194df PH |
12335 | that the ::From:: header line matches |
12336 | .em | |
12337 | the login of the calling user and the domain specified by \qualify@_domain\. | |
12338 | ||
12339 | \**Note**\: An unqualified address (no domain) in the ::From:: header in a | |
12340 | locally submitted message is automatically qualified by Exim, unless the | |
12341 | \-bnq-\ command line option is used. | |
12342 | .nem | |
12343 | ||
12344 | You can use \local@_from@_prefix\ and \local@_from@_suffix\ to permit affixes | |
12345 | on the local part. If the ::From:: header line does not match, Exim adds a | |
12346 | ::Sender:: header with an address constructed from the calling user's login and | |
12347 | the default qualify domain. | |
495ae4b0 PH |
12348 | |
12349 | If \local@_from@_check\ is set false, the ::From:: header check is disabled, | |
12350 | and no ::Sender:: header is ever added. If, in addition, you want to retain | |
12351 | ::Sender:: header lines supplied by untrusted users, you must also set | |
12352 | \local@_sender@_retain\ to be true. | |
12353 | ||
12354 | .index envelope sender | |
12355 | These options affect only the header lines in the message. The envelope sender | |
12356 | is still forced to be the login id at the qualify domain unless | |
12357 | \untrusted@_set@_sender\ permits the user to supply an envelope sender. | |
d43194df PH |
12358 | |
12359 | .em | |
12360 | For messages received over TCP/IP, an ACL can specify `submission mode' to | |
12361 | request similar header line checking. See section ~~SECTthesenhea, which has | |
12362 | more details about ::Sender:: processing. | |
12363 | .nem | |
495ae4b0 PH |
12364 | |
12365 | ||
12366 | .conf local@_from@_prefix string unset | |
12367 | When Exim checks the ::From:: header line of locally submitted messages for | |
12368 | matching the login id (see \local@_from@_check\ above), it can be configured to | |
12369 | ignore certain prefixes and suffixes in the local part of the address. This is | |
12370 | done by setting \local@_from@_prefix\ and/or \local@_from@_suffix\ to | |
12371 | appropriate lists, in the same form as the \local@_part@_prefix\ and | |
12372 | \local@_part@_suffix\ router options (see chapter ~~CHAProutergeneric). For | |
12373 | example, if | |
12374 | .display asis | |
12375 | local_from_prefix = *- | |
12376 | .endd | |
12377 | is set, a ::From:: line containing | |
12378 | .display asis | |
12379 | From: anything-user@your.domain.example | |
12380 | .endd | |
12381 | will not cause a ::Sender:: header to be added if \*user@@your.domain.example*\ | |
12382 | matches the actual sender address that is constructed from the login name and | |
12383 | qualify domain. | |
12384 | ||
12385 | .conf local@_from@_suffix string unset | |
12386 | See \local@_from@_prefix\ above. | |
12387 | ||
12388 | .conf local@_interfaces "string list" "see below" | |
4964e932 PH |
12389 | This option controls which network interfaces are used by the daemon for |
12390 | listening; they are also used to identify the local host when routing. Chapter | |
12391 | ~~CHAPinterfaces contains a full description of this option and the related | |
d43194df PH |
12392 | options |
12393 | .em | |
12394 | \daemon@_smtp@_ports\, \extra@_local@_interfaces\, \hosts@_treat@_as@_local\, | |
12395 | and \tls@_on@_connect@_ports\. | |
12396 | .nem | |
12397 | The default value for \local@_interfaces\ is | |
495ae4b0 PH |
12398 | .display asis |
12399 | local_interfaces = 0.0.0.0 | |
12400 | .endd | |
12401 | when Exim is built without IPv6 support; otherwise it is | |
12402 | .display asis | |
12403 | local_interfaces = <; ::0 ; 0.0.0.0 | |
12404 | .endd | |
12405 | ||
12406 | .conf local@_scan@_timeout time 5m | |
12407 | .index timeout||for \*local@_scan()*\ function | |
12408 | .index \*local@_scan()*\ function||timeout | |
12409 | This timeout applies to the \*local@_scan()*\ function (see chapter | |
12410 | ~~CHAPlocalscan). Zero means `no timeout'. If the timeout is exceeded, the | |
12411 | incoming message is rejected with a temporary error if it is an SMTP message. | |
12412 | For a non-SMTP message, the message is dropped and Exim ends with a non-zero | |
12413 | code. The incident is logged on the main and reject logs. | |
12414 | ||
12415 | ||
12416 | .conf local@_sender@_retain boolean false | |
12417 | .index ::Sender:: header line||retaining from local submission | |
12418 | When a message is submitted locally (that is, not over a TCP/IP connection) by | |
12419 | an untrusted user, Exim removes any existing ::Sender:: header line. If you | |
12420 | do not want this to happen, you must set \local@_sender@_retain\, and you must | |
12421 | also set \local@_from@_check\ to be false (Exim will complain if you do not). | |
12422 | Section ~~SECTthesenhea has more details about ::Sender:: processing. | |
12423 | ||
12424 | ||
12425 | ||
12426 | .conf localhost@_number string$**$ unset | |
12427 | .index host||locally unique number for | |
12428 | .index message||ids, with multiple hosts | |
12429 | Exim's message ids are normally unique only within the local host. If | |
12430 | uniqueness among a set of hosts is required, each host must set a different | |
12431 | value for the \localhost@_number\ option. The string is expanded immediately | |
12432 | after reading the configuration file (so that a number can be computed from the | |
12433 | host name, for example) and the result of the expansion must be a number in the | |
12434 | range 0--16 (or 0--10 on operating systems with case-insensitive file systems). | |
12435 | This is available in subsequent string expansions via the variable | |
12436 | \$localhost@_number$\. When \localhost@_number is set\, the final two | |
12437 | characters of the message id, instead of just being a fractional part of the | |
12438 | time, are computed from the time and the local host number as described in | |
12439 | section ~~SECTmessiden. | |
12440 | ||
12441 | ||
12442 | .conf log@_file@_path "string list$**$" "set at compile time" | |
12443 | .index log||file path for | |
12444 | This option sets the path which is used to determine the names of Exim's log | |
12445 | files, or indicates that logging is to be to syslog, or both. It is expanded | |
12446 | when Exim is entered, so it can, for example, contain a reference to the host | |
12447 | name. If no specific path is set for the log files at compile or run time, they | |
12448 | are written in a sub-directory called \(log)\ in Exim's spool directory. | |
12449 | Chapter ~~CHAPlog contains further details about Exim's logging, and section | |
12450 | ~~SECTwhelogwri describes how the contents of \log@_file@_path\ are used. If | |
12451 | this string is fixed at your installation (contains no expansion variables) it | |
12452 | is recommended that you do not set this option in the configuration file, but | |
12453 | instead supply the path using \\LOG@_FILE@_PATH\\ in \(Local/Makefile)\ so that | |
12454 | it is available to Exim for logging errors detected early on -- in particular, | |
12455 | failure to read the configuration file. | |
12456 | ||
12457 | .conf log@_selector string unset | |
12458 | .index log||selectors | |
12459 | This option can be used to reduce or increase the number of things that Exim | |
12460 | writes to its log files. Its argument is made up of names preceded by plus or | |
12461 | minus characters. For example: | |
12462 | .display asis | |
12463 | log_selector = +arguments -retry_defer | |
12464 | .endd | |
12465 | A list of possible names and what they control is given in the chapter on | |
12466 | logging, in section ~~SECTlogselector. | |
12467 | ||
12468 | .conf log@_timezone boolean false | |
12469 | .index log||timezone for entries | |
12470 | By default, the timestamps on log lines are in local time without the | |
12471 | timezone. This means that if your timezone changes twice a year, the timestamps | |
12472 | in log lines are ambiguous for an hour when the clocks go back. One way of | |
12473 | avoiding this problem is to set the timezone to UTC. An alternative is to set | |
12474 | \log@_timezone\ true. This turns on the addition of the timezone offset to | |
12475 | timestamps in log lines. Turning on this option can add quite a lot to the size | |
12476 | of log files because each line is extended by 6 characters. Note that the | |
12477 | \$tod@_log$\ variable contains the log timestamp without the zone, but there is | |
12478 | another variable called \$tod@_zone$\ that contains just the timezone offset. | |
12479 | ||
12480 | .conf lookup@_open@_max integer 25 | |
12481 | .index too many open files | |
12482 | .index open files, too many | |
12483 | .index file||too many open | |
12484 | .index lookup||maximum open files | |
12485 | .index limit||open files for lookups | |
12486 | This option limits the number of simultaneously open files for single-key | |
12487 | lookups that use regular files (that is, \%lsearch%\, \%dbm%\, and \%cdb%\). Exim | |
12488 | normally keeps these files open during routing, because often the same file is | |
12489 | required several times. If the limit is reached, Exim closes the least recently | |
12490 | used file. Note that if you are using the \*ndbm*\ library, it actually opens | |
12491 | two files for each logical DBM database, though it still counts as one for the | |
12492 | purposes of \lookup@_open@_max\. If you are getting `too many open files' | |
12493 | errors with NDBM, you need to reduce the value of \lookup@_open@_max\. | |
12494 | ||
12495 | .conf max@_username@_length integer 0 | |
12496 | .index length of login name | |
12497 | .index user name||maximum length | |
12498 | .index limit||user name length | |
12499 | Some operating systems are broken in that they truncate long arguments to | |
12500 | \*getpwnam()*\ to eight characters, instead of returning `no such user'. If | |
12501 | this option is set greater than zero, any attempt to call \*getpwnam()*\ with | |
12502 | an argument that is longer behaves as if \*getpwnam()*\ failed. | |
12503 | ||
12504 | ||
12505 | .conf message@_body@_visible integer 500 | |
12506 | .index body of message||visible size | |
12507 | .index message||body, visible size | |
12508 | This option specifies how much of a message's body is to be included in the | |
12509 | \$message@_body$\ and \$message@_body@_end$\ expansion variables. | |
12510 | ||
12511 | .conf message@_id@_header@_domain string$**$ unset | |
12512 | .index ::Message-ID:: header line | |
12513 | If this option is set, the string is expanded and used as the right hand side | |
12514 | (domain) of the ::Message-ID:: header that Exim creates if a | |
12515 | locally-originated incoming message does not have one. `Locally-originated' | |
12516 | means `not received over TCP/IP.' | |
12517 | Otherwise, the primary host name is used. | |
12518 | Only letters, digits, dot and hyphen are accepted; any other characters are | |
12519 | replaced by hyphens. If the expansion is forced to fail, or if the result is an | |
12520 | empty string, the option is ignored. | |
12521 | ||
12522 | .conf message@_id@_header@_text string$**$ unset | |
12523 | If this variable is set, the string is expanded and used to augment the text of | |
12524 | the ::Message-id:: header that Exim creates if a | |
12525 | locally-originated | |
12526 | incoming message does not have one. The text of this header is required by RFC | |
12527 | 2822 to take the form of an address. By default, Exim uses its internal message | |
12528 | id as the local part, and the primary host name as the domain. If this option | |
12529 | is set, it is expanded, and provided the expansion is not forced to fail, and | |
12530 | does not yield an empty string, the result is inserted into the header | |
12531 | immediately before the @@, separated from the internal message id by a dot. Any | |
12532 | characters that are illegal in an address are automatically converted into | |
12533 | hyphens. This means that variables such as \$tod@_log$\ can be used, because | |
12534 | the spaces and colons will become hyphens. | |
12535 | ||
12536 | .conf message@_logs boolean true | |
12537 | .index message||log, disabling | |
12538 | .index log||message log, disabling | |
12539 | If this option is turned off, per-message log files are not created in the | |
12540 | \(msglog)\ spool sub-directory. This reduces the amount of disk I/O required by | |
12541 | Exim, by reducing the number of files involved in handling a message from a | |
12542 | minimum of four (header spool file, body spool file, delivery journal, and | |
12543 | per-message log) to three. The other major I/O activity is Exim's main log, | |
12544 | which is not affected by this option. | |
12545 | ||
12546 | .conf message@_size@_limit string$**$ 50M | |
12547 | .index message||size limit | |
12548 | .index limit||message size | |
12549 | .index size||of message, limit | |
12550 | This option limits the maximum size of message that Exim will process. The | |
4964e932 | 12551 | value is expanded for each incoming |
495ae4b0 PH |
12552 | connection so, for example, it can be made to depend on the IP address of the |
12553 | remote host for messages arriving via TCP/IP. \**Note**\: This limit cannot be | |
12554 | made to depend on a message's sender or any other properties of an individual | |
12555 | message, because it has to be advertised in the server's response to \\EHLO\\. | |
12556 | String expansion failure causes a temporary error. A value of zero means no | |
12557 | limit, but its use is not recommended. See also \bounce@_return@_size@_limit\. | |
12558 | ||
12559 | Incoming SMTP messages are failed with a 552 error if the limit is | |
12560 | exceeded; locally-generated messages either get a stderr message or a delivery | |
12561 | failure message to the sender, depending on the \-oe-\ setting. Rejection of an | |
12562 | oversized message is logged in both the main and the reject logs. See also the | |
12563 | generic transport option \message@_size@_limit\, which limits the size of | |
12564 | message that an individual transport can process. | |
12565 | ||
12566 | .conf move@_frozen@_messages boolean false | |
12567 | .index frozen messages||moving | |
12568 | This option, which is available only if Exim has been built with the setting | |
12569 | .display asis | |
12570 | SUPPORT_MOVE_FROZEN_MESSAGES=yes | |
12571 | .endd | |
12572 | in \(Local/Makefile)\, causes frozen messages and their message logs to be | |
12573 | moved from the \(input)\ and \(msglog)\ directories on the spool to \(Finput)\ | |
12574 | and \(Fmsglog)\, respectively. There is currently no support in Exim or the | |
12575 | standard utilities for handling such moved messages, and they do not show up in | |
12576 | lists generated by \-bp-\ or by the Exim monitor. | |
12577 | ||
d43194df PH |
12578 | .em |
12579 | .conf mua@_wrapper boolean false | |
12580 | Setting this option true causes Exim to run in a very restrictive mode in which | |
12581 | it passes messages synchronously to a smart host. Chapter ~~CHAPnonqueueing | |
12582 | contains a full description of this facility. | |
12583 | .nem | |
12584 | ||
495ae4b0 PH |
12585 | .conf mysql@_servers "string list" unset |
12586 | .index MySQL||server list | |
12587 | This option provides a list of MySQL servers and associated connection data, to | |
12588 | be used in conjunction with \%mysql%\ lookups (see section ~~SECTsql). The | |
12589 | option is available only if Exim has been built with MySQL support. | |
12590 | ||
12591 | .conf never@_users "string list" unset | |
12592 | Local message deliveries are normally run in processes that are setuid to the | |
12593 | recipient, and remote deliveries are normally run under Exim's own uid and gid. | |
12594 | It is usually desirable to prevent any deliveries from running as root, as a | |
12595 | safety precaution. | |
4964e932 PH |
12596 | |
12597 | When Exim is built, an option called \\FIXED@_NEVER@_USERS\\ can be set to a | |
12598 | list of users that must not be used for local deliveries. This list is fixed in | |
12599 | the binary and cannot be overridden by the configuration file. By default, it | |
12600 | contains just the single user name `root'. The \never@_users\ runtime option | |
495ae4b0 PH |
12601 | can be used to add more users to the fixed list. |
12602 | ||
12603 | If a message is to be delivered as one of the users on the fixed list or the | |
12604 | \never@_users\ list, an error occurs, and delivery is deferred. A common | |
12605 | example is | |
12606 | .display | |
12607 | never@_users = root:daemon:bin | |
12608 | .endd | |
12609 | Including root is redundant if it is also on the fixed list, but it does no | |
12610 | harm. | |
12611 | This option overrides the \pipe@_as@_creator\ option of the \%pipe%\ transport | |
12612 | driver. | |
12613 | ||
12614 | .conf oracle@_servers "string list" unset | |
12615 | .index Oracle||server list | |
12616 | This option provides a list of Oracle servers and associated connection data, | |
12617 | to be used in conjunction with \%oracle%\ lookups (see section ~~SECTsql). The | |
12618 | option is available only if Exim has been built with Oracle support. | |
12619 | ||
12620 | .conf percent@_hack@_domains "domain list$**$" unset | |
12621 | .index `percent hack' | |
12622 | .index source routing||in email address | |
12623 | .index address||source-routed | |
12624 | The `percent hack' is the convention whereby a local part containing a percent | |
12625 | sign is re-interpreted as a new email address, with the percent replaced by @@. | |
12626 | This is sometimes called `source routing', though that term is also applied to | |
12627 | RFC 2822 addresses that begin with an @@ character. If this option is set, Exim | |
12628 | implements the percent facility for those domains listed, but no others. This | |
12629 | happens before an incoming SMTP address is tested against an ACL. | |
12630 | ||
12631 | \**Warning**\: The `percent hack' has often been abused by people who are | |
12632 | trying to get round relaying restrictions. For this reason, it is best avoided | |
12633 | if at all possible. Unfortunately, a number of less security-conscious MTAs | |
12634 | implement it unconditionally. If you are running Exim on a gateway host, and | |
12635 | routing mail through to internal MTAs without processing the local parts, it is | |
12636 | a good idea to reject recipient addresses with percent characters in their | |
12637 | local parts. Exim's default configuration does this. | |
12638 | ||
12639 | .conf perl@_at@_start boolean false | |
12640 | This option is available only when Exim is built with an embedded Perl | |
12641 | interpreter. See chapter ~~CHAPperl for details of its use. | |
12642 | ||
12643 | .conf perl@_startup string unset | |
12644 | This option is available only when Exim is built with an embedded Perl | |
12645 | interpreter. See chapter ~~CHAPperl for details of its use. | |
12646 | ||
12647 | .conf pgsql@_servers "string list" unset | |
12648 | .index PostgreSQL lookup type||server list | |
12649 | This option provides a list of PostgreSQL servers and associated connection | |
12650 | data, to be used in conjunction with \%pgsql%\ lookups (see section ~~SECTsql). | |
12651 | The option is available only if Exim has been built with PostgreSQL support. | |
12652 | ||
12653 | .conf pid@_file@_path string$**$ "set at compile time" | |
12654 | .index daemon||pid file path | |
12655 | .index pid file, path for | |
12656 | This option sets the name of the file to which the Exim daemon writes its | |
12657 | process id. The string is expanded, so it can contain, for example, references | |
12658 | to the host name: | |
12659 | .display asis | |
12660 | pid_file_path = /var/log/$primary_hostname/exim.pid | |
12661 | .endd | |
12662 | If no path is set, the pid is written to the file \(exim-daemon.pid)\ in Exim's | |
12663 | spool directory. | |
4964e932 PH |
12664 | The value set by the option can be overridden by the \-oP-\ command line |
12665 | option. A pid file is not written if a `non-standard' daemon is run by means of | |
495ae4b0 PH |
12666 | the \-oX-\ option, unless a path is explicitly supplied by \-oP-\. |
12667 | ||
12668 | .conf pipelining@_advertise@_hosts "host list$**$" $*$ | |
12669 | .index \\PIPELINING\\||advertising, suppressing | |
12670 | This option can be used to suppress the advertisement of the SMTP | |
12671 | \\PIPELINING\\ extension to specific hosts. When \\PIPELINING\\ is not | |
12672 | advertised and \smtp@_enforce@_sync\ is true, an Exim server enforces strict | |
12673 | synchronization for each SMTP command and response. | |
495ae4b0 | 12674 | When \\PIPELINING\\ is advertised, Exim assumes that clients will use it; `out |
4964e932 | 12675 | of order' commands that are `expected' do not count as protocol errors (see |
495ae4b0 | 12676 | \smtp@_max@_synprot@_errors\). |
495ae4b0 PH |
12677 | |
12678 | .conf preserve@_message@_logs boolean false | |
12679 | .index message logs, preserving | |
12680 | If this option is set, message log files are not deleted when messages are | |
12681 | completed. Instead, they are moved to a sub-directory of the spool directory | |
12682 | called \(msglog.OLD)\, where they remain available for statistical or debugging | |
12683 | purposes. This is a dangerous option to set on systems with any appreciable | |
12684 | volume of mail. Use with care! | |
12685 | ||
12686 | .conf primary@_hostname string "see below" | |
12687 | .index name||of local host | |
12688 | .index host||name of local | |
12689 | .index local host||name of | |
495ae4b0 PH |
12690 | This specifies the name of the current host. It is used in the default \\EHLO\\ |
12691 | or \\HELO\\ command for outgoing SMTP messages (changeable via the \helo@_data\ | |
12692 | option in the \%smtp%\ transport), | |
495ae4b0 PH |
12693 | and as the default for \qualify@_domain\. If it is not set, Exim calls |
12694 | \*uname()*\ to find it. If this fails, Exim panics and dies. If the name | |
12695 | returned by \*uname()*\ contains only one component, Exim passes it to | |
12696 | \*gethostbyname()*\ (or \*getipnodebyname()*\ when available) in order to | |
12697 | obtain the fully qualified version. | |
12698 | ||
495ae4b0 PH |
12699 | The value of \$primary@_hostname$\ is also used by default in some SMTP |
12700 | response messages from an Exim server. This can be changed dynamically by | |
12701 | setting \smtp@_active@_hostname\. | |
495ae4b0 PH |
12702 | |
12703 | .conf print@_topbitchars boolean false | |
12704 | .index printing characters | |
12705 | .index 8-bit characters | |
12706 | By default, Exim considers only those characters whose codes lie in the range | |
12707 | 32--126 to be printing characters. In a number of circumstances (for example, | |
12708 | when writing log entries) non-printing characters are converted into escape | |
12709 | sequences, primarily to avoid messing up the layout. If \print@_topbitchars\ is | |
12710 | set, code values of 128 and above are also considered to be printing | |
12711 | characters. | |
12712 | ||
12713 | .conf process@_log@_path string unset | |
12714 | .index process log path | |
4964e932 | 12715 | .index log||process log |
495ae4b0 PH |
12716 | .index \*exiwhat*\ |
12717 | This option sets the name of the file to which an Exim process writes its | |
12718 | `process log' when sent a USR1 signal. This is used by the \*exiwhat*\ utility | |
12719 | script. If this option is unset, the file called \(exim-process.info)\ in | |
12720 | Exim's spool directory is used. The ability to specify the name explicitly can | |
12721 | be useful in environments where two different Exims are running, using | |
12722 | different spool directories. | |
12723 | ||
12724 | .conf prod@_requires@_admin boolean true | |
12725 | .index \-M-\ option | |
12726 | .index \-R-\ option | |
12727 | .index \-q-\ option | |
12728 | The \-M-\, \-R-\, and \-q-\ command-line options require the caller to be an | |
12729 | admin user unless \prod@_requires@_admin\ is set false. See also | |
12730 | \queue@_list@_requires@_admin\. | |
12731 | ||
12732 | .conf qualify@_domain string "see below" | |
12733 | .index domain||for qualifying addresses | |
12734 | .index address||qualification | |
d43194df PH |
12735 | This option specifies the domain name that is added to any envelope sender |
12736 | addresses that do not have a domain qualification. It also applies to | |
12737 | recipient addresses if \qualify@_recipient\ is not set. | |
12738 | .em | |
12739 | Unqualified addresses are accepted by default only for locally-generated | |
12740 | messages. | |
12741 | ||
12742 | Qualification is also applied to addresses in header lines such as ::From:: and | |
12743 | ::To:: for locally-generated messages, unless the \-bnq-\ command line option | |
12744 | is used. | |
12745 | .nem | |
12746 | ||
12747 | Messages from external sources must always contain fully qualified addresses, | |
12748 | unless the sending host matches \sender@_unqualified@_hosts\ or | |
12749 | \recipient@_unqualified@_hosts\ (as appropriate), in which case incoming | |
12750 | addresses are qualified with \qualify@_domain\ or \qualify@_recipient\ as | |
12751 | necessary. Internally, Exim always works with fully qualified envelope | |
12752 | addresses. If \qualify@_domain\ is not set, it defaults to the | |
12753 | \primary@_hostname\ value. | |
495ae4b0 PH |
12754 | |
12755 | .conf qualify@_recipient string "see below" | |
d43194df PH |
12756 | .em |
12757 | This option allows you to specify a different domain for qualifying recipient | |
12758 | addresses to the one that is used for senders. See \qualify@_domain\ above. | |
12759 | .nem | |
495ae4b0 PH |
12760 | |
12761 | .conf queue@_domains "domain list$**$" unset | |
12762 | .index domain||specifying non-immediate delivery | |
12763 | .index queueing incoming messages | |
12764 | .index message||queueing certain domains | |
12765 | This option lists domains for which immediate delivery is not required. | |
12766 | A delivery process is started whenever a message is received, but only those | |
12767 | domains that do not match are processed. All other deliveries wait until the | |
12768 | next queue run. See also \hold@_domains\ and \queue@_smtp@_domains\. | |
12769 | ||
12770 | .conf queue@_list@_requires@_admin boolean true | |
12771 | .index \-bp-\ option | |
12772 | The \-bp-\ command-line option, which lists the messages that are on the queue, | |
12773 | requires the caller to be an admin user unless \queue__list__requires__admin\ | |
12774 | is set false. See also \prod@_requires@_admin\. | |
12775 | ||
12776 | .conf queue@_only boolean false | |
12777 | .index queueing incoming messages | |
12778 | .index message||queueing unconditionally | |
12779 | If \queue@_only\ is set, a delivery process is not automatically started | |
12780 | whenever a message is received. Instead, the message waits on the queue for the | |
12781 | next queue run. Even if \queue@_only\ is false, incoming messages may not get | |
12782 | delivered immediately when certain conditions (such as heavy load) occur. | |
12783 | ||
12784 | The \-odq-\ command line has the same effect as \queue@_only\. The \-odb-\ and | |
12785 | \-odi-\ command line options override \queue@_only\ unless | |
12786 | \queue@_only@_override\ is set false. See also \queue@_only@_file\, | |
12787 | \queue@_only@_load\, and \smtp@_accept@_queue\. | |
12788 | ||
12789 | .conf queue@_only@_file string unset | |
12790 | .index queueing incoming messages | |
12791 | .index message||queueing by file existence | |
12792 | This option can be set to a colon-separated list of absolute path names, each | |
12793 | one optionally preceded by `smtp'. When Exim is receiving a message, | |
12794 | it tests for the existence of each listed path using a call to \*stat()*\. For | |
12795 | each path that exists, the corresponding queuing option is set. | |
12796 | For paths with no prefix, \queue@_only\ is set; for paths prefixed by `smtp', | |
12797 | \queue@_smtp@_domains\ is set to match all domains. So, for example, | |
12798 | .display asis | |
12799 | queue_only_file = smtp/some/file | |
12800 | .endd | |
12801 | causes Exim to behave as if \queue@_smtp@_domains\ were set to `$*$' whenever | |
12802 | \(/some/file)\ exists. | |
12803 | ||
12804 | .conf queue@_only@_load fixed-point unset | |
12805 | .index load average | |
12806 | .index queueing incoming messages | |
12807 | .index message||queueing by load | |
12808 | If the system load average is higher than this value, incoming messages from | |
12809 | all sources are queued, and no automatic deliveries are started. If this | |
12810 | happens during local or remote SMTP input, all subsequent messages on the same | |
12811 | connection are queued. Deliveries will subsequently be performed by queue | |
12812 | runner processes. This option has no effect on ancient operating systems on | |
12813 | which Exim cannot determine the load average. See also | |
12814 | \deliver@_queue@_load@_max\ and \smtp@_load@_reserve\. | |
12815 | ||
12816 | .conf queue@_only@_override boolean true | |
12817 | .index queueing incoming messages | |
12818 | When this option is true, the \-od\*x*\-\ command line options override the | |
12819 | setting of \queue@_only\ or \queue@_only@_file\ in the configuration file. If | |
12820 | \queue@_only@_override\ is set false, the \-od\*x*\-\ options cannot be used to | |
12821 | override; they are accepted, but ignored. | |
12822 | ||
12823 | .conf queue@_run@_in@_order boolean false | |
12824 | .index queue runner||processing messages in order | |
12825 | If this option is set, queue runs happen in order of message arrival instead of | |
12826 | in an arbitrary order. For this to happen, a complete list of the entire queue | |
8408f763 PH |
12827 | must be set up before the deliveries start. When the queue is all held in a |
12828 | single directory (the default), | |
12829 | .em | |
12830 | a single list is created for both the ordered and the non-ordered cases. | |
12831 | However, if \split@_spool@_directory\ is set, a single list is not created when | |
12832 | \queue@_run@_in@_order\ is false. In this case, the sub-directories are | |
12833 | processed one at a time (in a random order), and this avoids setting up one | |
12834 | huge list for the whole queue. Thus, setting \queue@_run@_in@_order\ with | |
12835 | \split@_spool@_directory\ may degrade performance when the queue is large, | |
12836 | because of the extra work in setting up the single, large list. In most | |
12837 | situations, \queue@_run@_in@_order\ should not be set. | |
12838 | .nem | |
495ae4b0 PH |
12839 | |
12840 | .conf queue@_run@_max integer 5 | |
12841 | .index queue runner||maximum number of | |
12842 | This controls the maximum number of queue runner processes that an Exim daemon | |
12843 | can run simultaneously. This does not mean that it starts them all at once, | |
12844 | but rather that if the maximum number are still running when the time comes to | |
12845 | start another one, it refrains from starting another one. This can happen with | |
12846 | very large queues and/or very sluggish deliveries. This option does not, | |
12847 | however, interlock with other processes, so additional queue runners can be | |
12848 | started by other means, or by killing and restarting the daemon. | |
12849 | ||
12850 | .conf queue@_smtp@_domains "domain list$**$" unset | |
12851 | .index queueing incoming messages | |
12852 | .index message||queueing remote deliveries | |
12853 | When this option is set, a delivery process is started whenever a message is | |
12854 | received, routing is performed, and local deliveries take place. | |
12855 | However, if any SMTP deliveries are required for domains that match | |
12856 | \queue@_smtp@_domains\, they are not immediately delivered, but instead the | |
12857 | message waits on the queue for the next queue run. Since routing of the message | |
12858 | has taken place, Exim knows to which remote hosts it must be delivered, and so | |
12859 | when the queue run happens, multiple messages for the same host are delivered | |
12860 | over a single SMTP connection. The \-odqs-\ command line option causes all SMTP | |
12861 | deliveries to be queued in this way, and is equivalent to setting | |
12862 | \queue@_smtp@_domains\ to `$*$'. See also \hold@_domains\ and \queue@_domains\. | |
12863 | ||
12864 | .conf receive@_timeout time 0s | |
12865 | .index timeout||for non-SMTP input | |
12866 | This option sets the timeout for accepting a non-SMTP message, that is, the | |
12867 | maximum time that Exim waits when reading a message on the standard input. If | |
12868 | the value is zero, it will wait for ever. This setting is overridden by the | |
12869 | \-or-\ command line option. The timeout for incoming SMTP messages is | |
12870 | controlled by \smtp@_receive@_timeout\. | |
12871 | ||
12872 | .index customizing|| ::Received:: header | |
12873 | .index ::Received:: header line||customizing | |
12874 | .conf received@_header@_text string$**$ "see below" | |
12875 | This string defines the contents of the ::Received:: message header that is | |
12876 | added to each message, except for the timestamp, which is automatically added | |
12877 | on at the end (preceded by a semicolon). The string is expanded each time it is | |
12878 | used. If the expansion yields an empty string, no ::Received:: header line is | |
12879 | added to the message. Otherwise, the string should start with the text | |
12880 | `Received:' and conform to the RFC 2822 specification for ::Received:: header | |
12881 | lines. The default setting is: | |
12882 | .display asis | |
12883 | received_header_text = Received: \ | |
12884 | ${if def:sender_rcvhost {from $sender_rcvhost\n\t}\ | |
12885 | {${if def:sender_ident {from $sender_ident }}\ | |
12886 | ${if def:sender_helo_name {(helo=$sender_helo_name)\n\t}}}}\ | |
12887 | by $primary_hostname \ | |
12888 | ${if def:received_protocol {with $received_protocol}} \ | |
12889 | ${if def:tls_cipher {($tls_cipher)\n\t}}\ | |
12890 | (Exim $version_number)\n\t\ | |
12891 | id $message_id\ | |
12892 | ${if def:received_for {\n\tfor $received_for}} | |
12893 | .endd | |
12894 | Note the use of quotes, to allow the sequences \"@\n"\ and \"@\t"\ to be used | |
12895 | for newlines and tabs, respectively. The reference to the TLS cipher is omitted | |
12896 | when Exim is built without TLS support. The use of conditional expansions | |
12897 | ensures that this works for both locally generated messages and messages | |
12898 | received from remote hosts, giving header lines such as the following: | |
12899 | .display asis | |
12900 | Received: from scrooge.carol.example ([192.168.12.25] ident=root) | |
12901 | by marley.carol.example with esmtp (Exim 4.00) | |
12902 | id 16IOWa-00019l-00 | |
12903 | for chas@dickens.example; Tue, 25 Dec 2001 14:43:44 +0000 | |
12904 | Received: by scrooge.carol.example with local (Exim 4.00) | |
12905 | id 16IOWW-000083-00; Tue, 25 Dec 2001 14:43:41 +0000 | |
12906 | .endd | |
4964e932 PH |
12907 | Until the body of the message has been received, the timestamp is the time when |
12908 | the message started to be received. Once the body has arrived, and all policy | |
12909 | checks have taken place, the timestamp is updated to the time at which the | |
495ae4b0 | 12910 | message was accepted. |
495ae4b0 PH |
12911 | |
12912 | .conf received@_headers@_max integer 30 | |
12913 | .index loop||prevention | |
12914 | .index mail loop prevention | |
12915 | .index ::Received:: header line||counting | |
12916 | When a message is to be delivered, the number of ::Received:: headers is | |
12917 | counted, and if it is greater than this parameter, a mail loop is assumed to | |
12918 | have occurred, the delivery is abandoned, and an error message is generated. | |
12919 | This applies to both local and remote deliveries. | |
12920 | ||
12921 | .conf recipient@_unqualified@_hosts "host list$**$" unset | |
12922 | .index unqualified addresses | |
12923 | .index host||unqualified addresses from | |
12924 | This option lists those hosts from which Exim is prepared to accept unqualified | |
12925 | recipient addresses in message envelopes. The addresses are made fully | |
12926 | qualified by the addition of the \qualify@_recipient\ value. This option also | |
12927 | affects message header lines. Exim does not reject unqualified recipient | |
12928 | addresses in headers, but it qualifies them only if the message came from a | |
12929 | host that matches \recipient@_unqualified@_hosts\, | |
495ae4b0 PH |
12930 | or if the message was submitted locally (not using TCP/IP), and the \-bnq-\ |
12931 | option was not set. | |
495ae4b0 PH |
12932 | |
12933 | .conf recipients@_max integer 0 | |
12934 | .index limit||number of recipients | |
4964e932 | 12935 | .index recipient||maximum number |
495ae4b0 PH |
12936 | If this option is set greater than zero, it specifies the maximum number of |
12937 | original recipients for any message. Additional recipients that are generated | |
12938 | by aliasing or forwarding do not count. SMTP messages get a 452 response for | |
12939 | all recipients over the limit; earlier recipients are delivered as normal. | |
12940 | Non-SMTP messages with too many recipients are failed, and no deliveries are | |
12941 | done. | |
12942 | .index \\RCPT\\||maximum number of incoming | |
12943 | Note that the RFCs specify that an SMTP server should accept at least 100 | |
12944 | \\RCPT\\ commands in a single message. | |
12945 | ||
12946 | .conf recipients@_max@_reject boolean false | |
12947 | If this option is set true, Exim rejects SMTP messages containing too many | |
12948 | recipients by giving 552 errors to the surplus \\RCPT\\ commands, and a 554 | |
12949 | error to the eventual \\DATA\\ command. Otherwise (the default) it gives a 452 | |
12950 | error to the surplus \\RCPT\\ commands and accepts the message on behalf of the | |
12951 | initial set of recipients. The remote server should then re-send the message | |
12952 | for the remaining recipients at a later time. | |
12953 | ||
12954 | .conf remote@_max@_parallel integer 2 | |
12955 | .index delivery||parallelism for remote | |
12956 | This option controls parallel delivery of one message to a number of remote | |
12957 | hosts. If the value is less than 2, parallel delivery is disabled, and Exim | |
12958 | does all the remote deliveries for a message one by one. Otherwise, if a single | |
12959 | message has to be delivered to more than one remote host, or if several copies | |
12960 | have to be sent to the same remote host, up to \remote@_max@_parallel\ | |
12961 | deliveries are done simultaneously. If more than \remote@_max@_parallel\ | |
12962 | deliveries are required, the maximum number of processes are started, and as | |
12963 | each one finishes, another is begun. The order of starting processes is the | |
12964 | same as if sequential delivery were being done, and can be controlled by the | |
12965 | \remote@_sort@_domains\ option. If parallel delivery takes place while running | |
12966 | with debugging turned on, the debugging output from each delivery process is | |
12967 | tagged with its process id. | |
12968 | ||
12969 | This option controls only the maximum number of parallel deliveries for one | |
12970 | message in one Exim delivery process. Because Exim has no central queue | |
12971 | manager, there is no way of controlling the total number of simultaneous | |
12972 | deliveries if the configuration allows a delivery attempt as soon as a message | |
12973 | is received. | |
12974 | .index number of deliveries | |
12975 | .index delivery||maximum number of | |
12976 | If you want to control the total number of deliveries on the system, you | |
12977 | need to set the \queue@_only\ option. This ensures that all incoming messages | |
12978 | are added to the queue without starting a delivery process. Then set up an Exim | |
12979 | daemon to start queue runner processes at appropriate intervals (probably | |
12980 | fairly often, for example, every minute), and limit the total number of queue | |
12981 | runners by setting the \queue__run__max\ parameter. Because each queue runner | |
12982 | delivers only one message at a time, the maximum number of deliveries that can | |
12983 | then take place at once is \queue@_run@_max\ multiplied by | |
12984 | \remote@_max@_parallel\. | |
12985 | ||
d43194df PH |
12986 | If it is purely remote deliveries you want to control, use |
12987 | \queue@_smtp@_domains\ instead of \queue@_only\. This has the added benefit of | |
12988 | doing the SMTP routing before queuing, so that several messages for the same | |
12989 | host will eventually get delivered down the same connection. | |
495ae4b0 PH |
12990 | |
12991 | .conf remote@_sort@_domains "domain list$**$" unset | |
12992 | .index sorting remote deliveries | |
12993 | .index delivery||sorting remote | |
12994 | When there are a number of remote deliveries for a message, they are sorted by | |
12995 | domain into the order given by this list. For example, | |
12996 | .display asis | |
12997 | remote_sort_domains = *.cam.ac.uk:*.uk | |
12998 | .endd | |
12999 | would attempt to deliver to all addresses in the \*cam.ac.uk*\ domain first, then | |
13000 | to those in the \uk\ domain, then to any others. | |
13001 | ||
13002 | .conf retry@_data@_expire time 7d | |
13003 | .index hints database||data expiry | |
13004 | This option sets a `use before' time on retry information in Exim's hints | |
13005 | database. Any older retry data is ignored. This means that, for example, once a | |
13006 | host has not been tried for 7 days, Exim behaves as if it has no knowledge of | |
13007 | past failures. | |
13008 | ||
13009 | .conf retry@_interval@_max time 24h | |
13010 | .index retry||limit on interval | |
13011 | .index limit||on retry interval | |
13012 | Chapter ~~CHAPretry describes Exim's mechanisms for controlling the intervals | |
13013 | between delivery attempts for messages that cannot be delivered straight away. | |
13014 | This option sets an overall limit to the length of time between retries. | |
13015 | ||
13016 | .conf return@_path@_remove boolean true | |
13017 | .index ::Return-path:: header line||removing | |
13018 | RFC 2821, section 4.4, states that an SMTP server must insert a ::Return-path:: | |
13019 | header line into a message when it makes a `final delivery'. The ::Return-path:: | |
13020 | header preserves the sender address as received in the \\MAIL\\ command. This | |
13021 | description implies that this header should not be present in an incoming | |
13022 | message. If \return@_path@_remove\ is true, any existing ::Return-path:: | |
13023 | headers are removed from messages at the time they are received. Exim's | |
13024 | transports have options for adding ::Return-path:: headers at the time of | |
13025 | delivery. They are normally used only for final local deliveries. | |
13026 | ||
13027 | .conf return@_size@_limit integer 100K | |
13028 | This option is an obsolete synonym for \bounce@_return@_size@_limit\. | |
13029 | ||
13030 | .conf rfc1413@_hosts "host list$**$" $*$ | |
13031 | .index RFC 1413 | |
13032 | .index host||for RFC 1413 calls | |
13033 | RFC 1413 identification calls are made to any client host which matches an item | |
13034 | in the list. | |
13035 | ||
13036 | .conf rfc1413@_query@_timeout time 30s | |
13037 | .index RFC 1413||query timeout | |
13038 | .index timeout||for RFC 1413 call | |
13039 | This sets the timeout on RFC 1413 identification calls. If it is set to zero, | |
13040 | no RFC 1413 calls are ever made. | |
13041 | ||
13042 | .conf sender@_unqualified@_hosts "host list$**$" unset | |
13043 | .index unqualified addresses | |
13044 | .index host||unqualified addresses from | |
13045 | This option lists those hosts from which Exim is prepared to accept unqualified | |
13046 | sender addresses. The addresses are made fully qualified by the addition of | |
13047 | \qualify@_domain\. This option also affects message header lines. Exim does not | |
13048 | reject unqualified addresses in headers that contain sender addresses, but it | |
13049 | qualifies them only if the message came from a host that matches | |
13050 | \sender@_unqualified@_hosts\, | |
495ae4b0 PH |
13051 | or if the message was submitted locally (not using TCP/IP), and the \-bnq-\ |
13052 | option was not set. | |
495ae4b0 PH |
13053 | |
13054 | .conf smtp@_accept@_keepalive boolean true | |
13055 | .index keepalive||on incoming connection | |
13056 | This option controls the setting of the \\SO@_KEEPALIVE\\ option on incoming | |
13057 | TCP/IP socket connections. When set, it causes the kernel to probe idle | |
13058 | connections periodically, by sending packets with `old' sequence numbers. The | |
13059 | other end of the connection should send an acknowledgement if the connection is | |
13060 | still okay or a reset if the connection has been aborted. The reason for doing | |
13061 | this is that it has the beneficial effect of freeing up certain types of | |
13062 | connection that can get stuck when the remote host is disconnected without | |
13063 | tidying up the TCP/IP call properly. The keepalive mechanism takes several | |
13064 | hours to detect unreachable hosts. | |
13065 | ||
13066 | ||
13067 | .conf smtp@_accept@_max integer 20 | |
13068 | .index limit||incoming SMTP connections | |
13069 | .index SMTP||incoming connection count | |
13070 | .index inetd | |
13071 | This option specifies the maximum number of simultaneous incoming SMTP calls | |
13072 | that Exim will accept. It applies only to the listening daemon; there is no | |
13073 | control (in Exim) when incoming SMTP is being handled by \*inetd*\. If the value | |
13074 | is set to zero, no limit is applied. However, it is required to be non-zero if | |
13075 | either \smtp@_accept@_max@_per@_host\ or \smtp@_accept@_queue\ is set. See also | |
13076 | \smtp@_accept@_reserve\. | |
13077 | ||
13078 | ||
13079 | .conf smtp@_accept@_max@_nonmail integer 10 | |
13080 | .index limit||non-mail SMTP commands | |
13081 | .index SMTP||limiting non-mail commands | |
13082 | Exim counts the number of `non-mail' commands in an SMTP session, and drops the | |
13083 | connection if there are too many. This option defines `too many'. The check | |
13084 | catches some denial-of-service attacks, repeated failing \\AUTH\\s, or a mad | |
4964e932 | 13085 | client looping sending \\EHLO\\, for example. The check is applied only if the |
495ae4b0 PH |
13086 | client host matches \smtp@_accept@_max@_nonmail@_hosts\. |
13087 | ||
13088 | When a new message is expected, one occurrence of \\RSET\\ is not counted. This | |
13089 | allows a client to send one \\RSET\\ between messages (this is not necessary, | |
13090 | but some clients do it). Exim also allows one uncounted occurence of \\HELO\\ | |
13091 | or \\EHLO\\, and one occurrence of \\STARTTLS\\ between messages. After | |
13092 | starting up a TLS session, another \\EHLO\\ is expected, and so it too is not | |
13093 | counted. The first occurrence of \\AUTH\\ in a connection, or immediately | |
13094 | following \\STARTTLS\\ is not counted. Otherwise, all commands other than | |
13095 | \\MAIL\\, \\RCPT\\, \\DATA\\, and \\QUIT\\ are counted. | |
13096 | ||
13097 | .conf smtp@_accept@_max@_nonmail@_hosts "host list$**$" $*$ | |
13098 | You can control which hosts are subject to the \smtp@_accept@_max@_nonmail\ | |
13099 | check by setting this option. The default value makes it apply to all hosts. By | |
13100 | changing the value, you can exclude any badly-behaved hosts that you have to | |
13101 | live with. | |
13102 | ||
13103 | ||
13104 | .conf smtp@_accept@_max@_per@_connection integer 1000 | |
13105 | .index SMTP||incoming message count, limiting | |
13106 | .index limit||messages per SMTP connection | |
13107 | The value of this option limits the number of \\MAIL\\ commands that Exim is | |
13108 | prepared to accept over a single SMTP connection, whether or not each command | |
13109 | results in the transfer of a message. After the limit is reached, a 421 | |
13110 | response is given to subsequent \\MAIL\\ commands. This limit is a safety | |
13111 | precaution against a client that goes mad (incidents of this type have been | |
13112 | seen). | |
13113 | ||
13114 | .conf smtp@_accept@_max@_per@_host string$**$ unset | |
13115 | .index limit||SMTP connections from one host | |
13116 | .index host||limiting SMTP connections from | |
13117 | This option restricts the number of simultaneous IP connections from a single | |
13118 | host (strictly, from a single IP address) to the Exim daemon. The option is | |
13119 | expanded, to enable different limits to be applied to different hosts by | |
13120 | reference to \$sender@_host@_address$\. Once the limit is reached, additional | |
13121 | connection attempts from the same host are rejected with error code 421. The | |
13122 | default value of zero imposes no limit. If this option is set, it is required | |
13123 | that \smtp@_accept@_max\ be non-zero. | |
13124 | ||
13125 | \**Warning**\: When setting this option you should not use any expansion | |
13126 | constructions that take an appreciable amount of time. The expansion and test | |
13127 | happen in the main daemon loop, in order to reject additional connections | |
13128 | without forking additional processes (otherwise a denial-of-service attack | |
13129 | could cause a vast number or processes to be created). While the daemon is | |
13130 | doing this processing, it cannot accept any other incoming connections. | |
13131 | ||
13132 | ||
13133 | .conf smtp@_accept@_queue integer 0 | |
13134 | .index SMTP||incoming connection count | |
13135 | .index queueing incoming messages | |
13136 | .index message||queueing by SMTP connection count | |
13137 | If the number of simultaneous incoming SMTP calls handled via the listening | |
13138 | daemon exceeds this value, messages received by SMTP are just placed on the | |
13139 | queue; no delivery processes are started automatically. A value of zero implies | |
13140 | no limit, and clearly any non-zero value is useful only if it is less than the | |
13141 | \smtp@_accept@_max\ value (unless that is zero). See also \queue@_only\, | |
13142 | \queue@_only@_load\, \queue@_smtp@_domains\, and the various \-od-\ command | |
13143 | line options. | |
13144 | ||
13145 | .conf smtp@_accept@_queue@_per@_connection integer 10 | |
13146 | .index queueing incoming messages | |
13147 | .index message||queueing by message count | |
13148 | This option limits the number of delivery processes that Exim starts | |
13149 | automatically when receiving messages via SMTP, whether via the daemon or by | |
13150 | the use of \-bs-\ or \-bS-\. If the value of the option is greater than zero, | |
13151 | and the number of messages received in a single SMTP session exceeds this | |
13152 | number, subsequent messages are placed on the queue, but no delivery processes | |
13153 | are started. This helps to limit the number of Exim processes when a server | |
13154 | restarts after downtime and there is a lot of mail waiting for it on other | |
13155 | systems. On large systems, the default should probably be increased, and on | |
13156 | dial-in client systems it should probably be set to zero (that is, disabled). | |
13157 | ||
13158 | .conf smtp@_accept@_reserve integer 0 | |
13159 | .index SMTP||incoming call count | |
13160 | .index host||reserved | |
13161 | When \smtp@_accept@_max\ is set greater than zero, this option specifies a | |
13162 | number of SMTP connections that are reserved for connections from the hosts | |
13163 | that are specified in \smtp@_reserve@_hosts\. The value set in | |
13164 | \smtp@_accept@_max\ includes this reserve pool. The specified hosts are not | |
13165 | restricted to this number of connections; the option specifies a minimum number | |
13166 | of connection slots for them, not a maximum. It is a guarantee that that group | |
13167 | of hosts can always get at least \smtp@_accept@_reserve\ connections. | |
13168 | ||
13169 | For example, if \smtp@_accept@_max\ is set to 50 and \smtp@_accept@_reserve\ is | |
13170 | set to 5, once there are 45 active connections (from any hosts), new | |
13171 | connections are accepted only from hosts listed in \smtp@_reserve@_hosts\. | |
13172 | See also \smtp@_accept@_max@_per@_host\. | |
13173 | ||
495ae4b0 PH |
13174 | .conf smtp@_active@_hostname string$**$ unset |
13175 | .index host||name in SMTP responses | |
13176 | .index SMTP||host name in responses | |
13177 | This option is provided for multi-homed servers that want to masquerade as | |
13178 | several different hosts. At the start of an SMTP connection, its value is | |
13179 | expanded and used instead of the value of \$primary@_hostname$\ in SMTP | |
13180 | responses. For example, it is used as domain name in the response to an | |
d43194df PH |
13181 | incoming \\HELO\\ or \\EHLO\\ command. |
13182 | .em | |
8408f763 | 13183 | It is also used in \\HELO\\ commands for callout verification. |
d43194df PH |
13184 | The active hostname is placed in the \$smtp__active__hostname$\ variable, which |
13185 | is saved with any messages that are received. It is therefore available for use | |
13186 | in routers and transports when the message is later delivered. | |
13187 | .nem | |
13188 | ||
13189 | If this option is unset, or if its expansion is forced to fail, or if the | |
13190 | expansion results in an empty string, the value of \$primary@_hostname$\ is | |
13191 | used. Other expansion failures cause a message to be written to the main and | |
13192 | panic logs, and the SMTP command receives a temporary error. Typically, the | |
13193 | value of \smtp@_active@_hostname\ depends on the incoming interface address. | |
13194 | For example: | |
495ae4b0 PH |
13195 | .display asis |
13196 | smtp_active_hostname = ${if eq{$interface_address}{10.0.0.1}\ | |
13197 | {cox.mydomain}{box.mydomain}} | |
13198 | .endd | |
495ae4b0 PH |
13199 | |
13200 | .conf smtp@_banner string$**$ "see below" | |
13201 | .index SMTP||welcome banner | |
13202 | .index banner for SMTP | |
13203 | .index welcome banner for SMTP | |
13204 | .index customizing||SMTP banner | |
13205 | This string, which is expanded every time it is used, is output as the initial | |
13206 | positive response to an SMTP connection. The default setting is: | |
13207 | .display asis | |
d43194df PH |
13208 | .em |
13209 | smtp_banner = $smtp_active_hostname ESMTP Exim \ | |
13210 | $version_number $tod_full | |
13211 | .nem | |
495ae4b0 PH |
13212 | .endd |
13213 | Failure to expand the string causes a panic error. If you want to create a | |
13214 | multiline response to the initial SMTP connection, use `@\n' in the string at | |
13215 | appropriate points, but not at the end. Note that the 220 code is not included | |
13216 | in this string. Exim adds it automatically (several times in the case of a | |
13217 | multiline response). | |
13218 | ||
13219 | .conf smtp@_check@_spool@_space boolean true | |
13220 | .index checking disk space | |
13221 | .index disk space, checking | |
13222 | .index spool directory||checking space | |
13223 | When this option is set, if an incoming SMTP session encounters the \\SIZE\\ | |
13224 | option on a \\MAIL\\ command, it checks that there is enough space in the | |
13225 | spool directory's partition to accept a message of that size, while still | |
13226 | leaving free the amount specified by \check@_spool@_space\ (even if that value | |
13227 | is zero). If there isn't enough space, a temporary error code is returned. | |
13228 | ||
13229 | .conf smtp@_connect@_backlog integer 20 | |
13230 | .index connection backlog | |
13231 | .index SMTP||connection backlog | |
13232 | .index backlog of connections | |
13233 | This option specifies a maximum number of waiting SMTP connections. Exim passes | |
13234 | this value to the TCP/IP system when it sets up its listener. Once this number | |
13235 | of connections are waiting for the daemon's attention, subsequent connection | |
13236 | attempts are refused at the TCP/IP level. At least, that is what the manuals | |
13237 | say; in some circumstances such connection attempts have been observed to time | |
13238 | out instead. For large systems it is probably a good idea to increase the | |
13239 | value (to 50, say). It also gives some protection against denial-of-service | |
13240 | attacks by SYN flooding. | |
13241 | ||
13242 | .conf smtp@_enforce@_sync boolean true | |
13243 | .index SMTP||synchronization checking | |
13244 | .index synchronization checking in SMTP | |
13245 | The SMTP protocol specification requires the client to wait for a response from | |
13246 | the server at certain points in the dialogue. Without \\PIPELINING\\ these | |
13247 | synchronization points are after every command; with \\PIPELINING\\ they are | |
d43194df PH |
13248 | fewer, but they still exist. |
13249 | ||
13250 | Some spamming sites send out a complete set of SMTP commands without waiting | |
13251 | for any response. Exim protects against this by rejecting a message if the | |
13252 | client has sent further input when it should not have. The error response `554 | |
13253 | SMTP synchronization error' is sent, and the connection is dropped. Testing for | |
13254 | this error cannot be perfect because of transmission delays (unexpected input | |
13255 | may be on its way but not yet received when Exim checks). However, it does | |
13256 | detect many instances. | |
13257 | ||
13258 | .em | |
13259 | The check can be globally disabled by setting \smtp@_enforce@_sync\ false. | |
13260 | If you want to disable the check selectively (for example, only for certain | |
13261 | hosts), you can do so by an appropriate use of a \control\ modifier in an ACL | |
13262 | (see section ~~SECTcontrols). See also \pipelining@_advertise@_hosts\. | |
13263 | .nem | |
495ae4b0 PH |
13264 | |
13265 | .conf smtp@_etrn@_command string$**$ unset | |
13266 | .index \\ETRN\\||command to be run | |
13267 | If this option is set, the given command is run whenever an SMTP \\ETRN\\ | |
13268 | command is received from a host that is permitted to issue such commands (see | |
13269 | chapter ~~CHAPACL). The string is split up into separate arguments which are | |
13270 | independently expanded. The expansion variable \$domain$\ is set to the | |
13271 | argument of the \\ETRN\\ command, and no syntax checking is done on it. For | |
13272 | example: | |
13273 | .display asis | |
13274 | smtp_etrn_command = /etc/etrn_command $domain $sender_host_address | |
13275 | .endd | |
13276 | A new process is created to run the command, but Exim does not wait for it to | |
13277 | complete. Consequently, its status cannot be checked. If the command cannot be | |
13278 | run, a line is written to the panic log, but the \\ETRN\\ caller still receives | |
13279 | a 250 success response. Exim is normally running under its own uid when | |
13280 | receiving SMTP, so it is not possible for it to change the uid before running | |
13281 | the command. | |
13282 | ||
13283 | .conf smtp@_etrn@_serialize boolean true | |
13284 | .index \\ETRN\\||serializing | |
13285 | When this option is set, it prevents the simultaneous execution of more than | |
13286 | one identical command as a result of \\ETRN\\ in an SMTP connection. See | |
13287 | section ~~SECTETRN for details. | |
13288 | ||
13289 | .conf smtp@_load@_reserve fixed-point unset | |
13290 | .index load average | |
13291 | If the system load average ever gets higher than this, incoming SMTP calls are | |
13292 | accepted only from those hosts that match an entry in \smtp@_reserve@_hosts\. | |
13293 | If \smtp@_reserve@_hosts\ is not set, no incoming SMTP calls are accepted when | |
13294 | the load is over the limit. The option has no effect on ancient operating | |
13295 | systems on which Exim cannot determine the load average. See also | |
13296 | \deliver@_queue@_load@_max\ and \queue@_only@_load\. | |
13297 | ||
13298 | ||
13299 | .conf smtp@_max@_synprot@_errors integer 3 | |
13300 | .index SMTP||limiting syntax and protocol errors | |
13301 | .index limit||SMTP syntax and protocol errors | |
4964e932 | 13302 | Exim rejects SMTP commands that contain syntax or protocol errors. In |
495ae4b0 PH |
13303 | particular, a syntactically invalid email address, as in this command: |
13304 | .display asis | |
13305 | RCPT TO:<abc xyz@a.b.c> | |
13306 | .endd | |
13307 | causes immediate rejection of the command, before any other tests are done. | |
13308 | (The ACL cannot be run if there is no valid address to set up for it.) An | |
13309 | example of a protocol error is receiving \\RCPT\\ before \\MAIL\\. If there are | |
13310 | too many syntax or protocol errors in one SMTP session, the connection is | |
13311 | dropped. The limit is set by this option. | |
13312 | ||
495ae4b0 | 13313 | .index \\PIPELINING\\||expected errors |
4964e932 PH |
13314 | When the \\PIPELINING\\ extension to SMTP is in use, some protocol errors are |
13315 | `expected', for instance, a \\RCPT\\ command after a rejected \\MAIL\\ command. | |
13316 | Exim assumes that \\PIPELINING\\ will be used if it advertises it (see | |
13317 | \pipelining@_advertise@_hosts\), and in this situation, `expected' errors do | |
495ae4b0 | 13318 | not count towards the limit. |
495ae4b0 PH |
13319 | |
13320 | ||
13321 | .conf smtp@_max@_unknown@_commands integer 3 | |
13322 | .index SMTP||limiting unknown commands | |
13323 | .index limit||unknown SMTP commands | |
4964e932 PH |
13324 | If there are too many unrecognized commands in an incoming SMTP session, an |
13325 | Exim server drops the connection. This is a defence against some kinds of abuse | |
13326 | that subvert web | |
13327 | clients | |
495ae4b0 PH |
13328 | into making connections to SMTP ports; in these circumstances, a number of |
13329 | non-SMTP command lines are sent first. | |
13330 | ||
13331 | ||
13332 | .conf smtp@_ratelimit@_hosts "host list$**$" unset | |
13333 | .index SMTP||rate limiting | |
13334 | .index limit||rate of message arrival | |
13335 | .index \\RCPT\\||rate limiting | |
13336 | Some sites find it helpful to be able to limit the rate at which certain hosts | |
13337 | can send them messages, and the rate at which an individual message can specify | |
13338 | recipients. When a host matches \smtp@_ratelimit@_hosts\, the values of | |
13339 | \smtp@_ratelimit@_mail\ and \smtp@_ratelimit@_rcpt\ are used to control the | |
13340 | rate of acceptance of \\MAIL\\ and \\RCPT\\ commands in a single SMTP session, | |
13341 | respectively. Each option, if set, must contain a set of four comma-separated | |
13342 | values: | |
13343 | .numberpars $. | |
13344 | A threshold, before which there is no rate limiting. | |
13345 | .nextp | |
13346 | An initial time delay. Unlike other times in Exim, numbers with decimal | |
13347 | fractional parts are allowed here. | |
13348 | .nextp | |
13349 | A factor by which to increase the delay each time. | |
13350 | .nextp | |
13351 | A maximum value for the delay. This should normally be less than 5 minutes, | |
13352 | because after that time, the client is liable to timeout the SMTP command. | |
13353 | .endp | |
13354 | For example, these settings have been used successfully at the site which | |
13355 | first suggested this feature, for controlling mail from their customers: | |
13356 | .display asis | |
13357 | smtp_ratelimit_mail = 2,0.5s,1.05,4m | |
13358 | smtp_ratelimit_rcpt = 4,0.25s,1.015,4m | |
13359 | .endd | |
13360 | The first setting specifies delays that are applied to \\MAIL\\ commands after | |
13361 | two have been received over a single connection. The initial delay is 0.5 | |
13362 | seconds, increasing by a factor of 1.05 each time. The second setting applies | |
13363 | delays to \\RCPT\\ commands when more than four occur in a single message. | |
13364 | ||
4964e932 | 13365 | It is also possible to configure delays explicitly in ACLs. See section |
495ae4b0 PH |
13366 | ~~SECTACLmodi for details. |
13367 | ||
13368 | ||
13369 | .conf smtp@_ratelimit@_mail string unset | |
13370 | See \smtp@_ratelimit@_hosts\ above. | |
13371 | ||
13372 | .conf smtp@_ratelimit@_rcpt string unset | |
13373 | See \smtp@_ratelimit@_hosts\ above. | |
13374 | ||
13375 | .conf smtp@_receive@_timeout time 5m | |
13376 | .index timeout||for SMTP input | |
13377 | .index SMTP||timeout, input | |
13378 | This sets a timeout value for SMTP reception. It applies to all forms of SMTP | |
13379 | input, including batch SMTP. If a line of input (either an SMTP command or a | |
13380 | data line) is not received within this time, the SMTP connection is dropped and | |
4964e932 | 13381 | the message is abandoned. |
495ae4b0 PH |
13382 | A line is written to the log containing one of the following messages: |
13383 | .display asis | |
13384 | SMTP command timeout on connection from... | |
13385 | SMTP data timeout on connection from... | |
13386 | .endd | |
4964e932 | 13387 | The former means that Exim was expecting to read an SMTP command; the latter |
495ae4b0 PH |
13388 | means that it was in the \\DATA\\ phase, reading the contents of a message. |
13389 | ||
13390 | ||
13391 | .index \-os-\ option | |
13392 | The value set by this option can be overridden by the | |
13393 | \-os-\ command-line option. A setting of zero time disables the timeout, but | |
13394 | this should never be used for SMTP over TCP/IP. (It can be useful in some cases | |
13395 | of local input using \-bs-\ or \-bS-\.) For non-SMTP input, the reception | |
13396 | timeout is controlled by \receive@_timeout\ and \-or-\. | |
13397 | ||
13398 | .conf smtp@_reserve@_hosts "host list$**$" unset | |
13399 | This option defines hosts for which SMTP connections are reserved; see | |
13400 | \smtp@_accept@_reserve\ and \smtp@_load@_reserve\ above. | |
13401 | ||
13402 | .conf smtp@_return@_error@_details boolean false | |
13403 | .index SMTP||details policy failures | |
13404 | .index policy control||rejection, returning details | |
13405 | In the default state, Exim uses bland messages such as | |
13406 | `Administrative prohibition' when it rejects SMTP commands for policy | |
13407 | reasons. Many sysadmins like this because it gives away little information | |
13408 | to spammers. However, some other syadmins who are applying strict checking | |
13409 | policies want to give out much fuller information about failures. Setting | |
13410 | \smtp@_return@_error@_details\ true causes Exim to be more forthcoming. For | |
13411 | example, instead of `Administrative prohibition', it might give: | |
13412 | .display asis | |
13413 | 550-Rejected after DATA: '>' missing at end of address: | |
13414 | 550 failing address in "From" header is: <user@dom.ain | |
13415 | .endd | |
13416 | ||
d43194df PH |
13417 | .em |
13418 | .conf spamd@_address string "$tt{127.0.0.1 783}" | |
13419 | This option is available when Exim is compiled with the content-scanning | |
13420 | extension. It specifies how Exim connects to SpamAssassin's \spamd\ daemon. See | |
13421 | section ~~SECTscanspamass for more details. | |
13422 | .nem | |
13423 | ||
495ae4b0 PH |
13424 | .conf split@_spool@_directory boolean false |
13425 | .index multiple spool directories | |
13426 | .index spool directory||split | |
13427 | .index directories, multiple | |
13428 | If this option is set, it causes Exim to split its input directory into 62 | |
13429 | subdirectories, each with a single alphanumeric character as its name. The | |
13430 | sixth character of the message id is used to allocate messages to | |
13431 | subdirectories; this is the least significant base-62 digit of the time of | |
13432 | arrival of the message. | |
13433 | ||
13434 | Splitting up the spool in this way may provide better performance on systems | |
13435 | where there are long mail queues, by reducing the number of files in any one | |
13436 | directory. The msglog directory is also split up in a similar way to the input | |
13437 | directory; however, if \preserve@_message@_logs\ is set, all old msglog files | |
13438 | are still placed in the single directory \(msglog.OLD)\. | |
13439 | ||
13440 | It is not necessary to take any special action for existing messages when | |
13441 | changing \split@_spool@_directory\. Exim notices messages that are in the | |
13442 | `wrong' place, and continues to process them. If the option is turned off after | |
13443 | a period of being on, the subdirectories will eventually empty and be | |
13444 | automatically deleted. | |
13445 | ||
13446 | When \split@_spool@_directory\ is set, the behaviour of queue runner processes | |
13447 | changes. Instead of creating a list of all messages in the queue, and then | |
13448 | trying to deliver each one in turn, it constructs a list of those in one | |
13449 | sub-directory and tries to deliver them, before moving on to the next | |
13450 | sub-directory. The sub-directories are processed in a random order. This | |
13451 | spreads out the scanning of the input directories, and uses less memory. It is | |
13452 | particularly beneficial when there are lots of messages on the queue. However, | |
13453 | if \queue@_run@_in@_order\ is set, none of this new processing happens. The | |
13454 | entire queue has to be scanned and sorted before any deliveries can start. | |
13455 | ||
13456 | .conf spool@_directory string$**$ "set at compile time" | |
13457 | .index spool directory||path to | |
13458 | This defines the directory in which Exim keeps its spool, that is, the messages | |
13459 | it is waiting to deliver. The default value is taken from the compile-time | |
13460 | configuration setting, if there is one. If not, this option must be set. The | |
13461 | string is expanded, so it can contain, for example, a reference to | |
13462 | \$primary@_hostname$\. | |
13463 | ||
13464 | If the spool directory name is fixed on your installation, it is recommended | |
13465 | that you set it at build time rather than from this option, particularly if the | |
13466 | log files are being written to the spool directory (see \log@_file@_path\). | |
13467 | Otherwise log files cannot be used for errors that are detected early on, such | |
13468 | as failures in the configuration file. | |
13469 | ||
13470 | By using this option to override the compiled-in path, it is possible to run | |
13471 | tests of Exim without using the standard spool. | |
13472 | ||
13473 | .conf strip@_excess@_angle@_brackets boolean false | |
13474 | .index angle brackets, excess | |
13475 | If this option is set, redundant pairs of angle brackets round `route-addr' | |
13476 | items in addresses are stripped. For example, \*@<@<xxx@@a.b.c.d@>@>*\ is treated | |
13477 | as \*@<xxx@@a.b.c.d@>*\. If this is in the envelope and the message is passed on | |
13478 | to another MTA, the excess angle brackets are not passed on. If this option is | |
13479 | not set, multiple pairs of angle brackets cause a syntax error. | |
13480 | ||
13481 | .conf strip@_trailing@_dot boolean false | |
13482 | .index trailing dot on domain | |
13483 | .index dot||trailing on domain | |
13484 | If this option is set, a trailing dot at the end of a domain in an address is | |
13485 | ignored. If this is in the envelope and the message is passed on to another | |
13486 | MTA, the dot is not passed on. If this option is not set, a dot at the end of a | |
13487 | domain causes a syntax error. | |
4964e932 | 13488 | However, addresses in header lines are checked only when an ACL requests header |
495ae4b0 | 13489 | syntax checking. |
495ae4b0 PH |
13490 | |
13491 | .conf syslog@_duplication boolean true | |
13492 | .index syslog||duplicate log lines, suppressing | |
13493 | When Exim is logging to syslog, it writes the log lines for its three | |
13494 | separate logs at different syslog priorities so that they can in principle | |
13495 | be separated on the logging hosts. Some installations do not require this | |
13496 | separation, and in those cases, the duplication of certain log lines is a | |
13497 | nuisance. If \syslog@_duplication\ is set false, only one copy of any | |
13498 | particular log line is written to syslog. For lines that normally go to | |
13499 | both the main log and the reject log, the reject log version (possibly | |
13500 | containing message header lines) is written, at \\LOG@_NOTICE\\ priority. | |
13501 | Lines that normally go to both the main and the panic log are written at | |
13502 | the \\LOG@_ALERT\\ priority. | |
13503 | ||
13504 | .conf syslog@_facility string unset | |
13505 | .index syslog||facility, setting | |
4964e932 | 13506 | This option sets the syslog `facility' name, used when Exim is logging to |
495ae4b0 | 13507 | syslog. The value must be one of the strings `mail', `user', `news', `uucp', |
4964e932 | 13508 | `daemon', or `local\*x*\' where \*x*\ is a digit between 0 and 7. If this |
495ae4b0 PH |
13509 | option is unset, `mail' is used. See chapter ~~CHAPlog for details of Exim's |
13510 | logging. | |
13511 | ||
13512 | ||
13513 | .conf syslog@_processname string "$tt{exim}" | |
13514 | .index syslog||process name, setting | |
13515 | This option sets the syslog `ident' name, used when Exim is logging to syslog. | |
13516 | The value must be no longer than 32 characters. See chapter ~~CHAPlog for | |
13517 | details of Exim's logging. | |
13518 | ||
13519 | ||
13520 | .conf syslog@_timestamp boolean true | |
13521 | .index syslog||timestamps | |
13522 | If \syslog@_timestamp\ is set false, the timestamps on Exim's log lines are | |
13523 | omitted when these lines are sent to syslog. See chapter ~~CHAPlog for | |
13524 | details of Exim's logging. | |
13525 | ||
13526 | .conf system@_filter string$**$ unset | |
13527 | .index filter||system filter | |
13528 | .index system filter||specifying | |
13529 | .index Sieve filter||not available for system filter | |
13530 | This option specifies an Exim filter file that is applied to all messages at | |
13531 | the start of each delivery attempt, before any routing is done. System filters | |
13532 | must be Exim filters; they cannot be Sieve filters. If the system filter | |
13533 | generates any deliveries to files or pipes, or any new mail messages, the | |
13534 | appropriate \system@_filter@_...@_transport\ option(s) must be set, to define | |
13535 | which transports are to be used. Details of this facility are given in chapter | |
13536 | ~~CHAPsystemfilter. | |
13537 | ||
13538 | .conf system@_filter@_directory@_transport string$**$ unset | |
13539 | This sets the name of the transport driver that is to be used when the | |
13540 | \save\ command in a system message filter specifies a path ending in `/', | |
13541 | implying delivery of each message into a separate file in some directory. | |
13542 | During the delivery, the variable \$address@_file$\ contains the path name. | |
13543 | ||
13544 | .conf system@_filter@_file@_transport string$**$ unset | |
13545 | .index file||transport for system filter | |
13546 | This sets the name of the transport driver that is to be used when the \save\ | |
13547 | command in a system message filter specifies a path not ending in `/'. During | |
13548 | the delivery, the variable \$address@_file$\ contains the path name. | |
13549 | ||
13550 | .index gid (group id)||system filter | |
13551 | .conf system@_filter@_group string unset | |
13552 | This option is used only when \system@_filter@_user\ is also set. It sets the | |
13553 | gid under which the system filter is run, overriding any gid that is associated | |
13554 | with the user. The value may be numerical or symbolic. | |
13555 | ||
13556 | .conf system@_filter@_pipe@_transport string$**$ unset 7 | |
13557 | .index \%pipe%\ transport||for system filter | |
13558 | This specifies the transport driver that is to be used when a \pipe\ command is | |
13559 | used in a system filter. During the delivery, the variable \$address@_pipe$\ | |
13560 | contains the pipe command. | |
13561 | ||
13562 | .conf system@_filter@_reply@_transport string$**$ unset | |
13563 | .index \%autoreply%\ transport||for system filter | |
13564 | This specifies the transport driver that is to be used when a \mail\ command is | |
13565 | used in a system filter. | |
13566 | ||
13567 | .index uid (user id)||system filter | |
13568 | .conf system@_filter@_user string unset | |
13569 | If this option is not set, the system filter is run in the main Exim delivery | |
13570 | process, as root. When the option is set, the system filter runs in a separate | |
13571 | process, as the given user. Unless the string consists entirely of digits, it | |
13572 | is looked up in the password data. Failure to find the named user causes a | |
13573 | configuration error. The gid is either taken from the password data, or | |
13574 | specified by \system@_filter@_group\. When the uid is specified numerically, | |
13575 | \system@_filter@_group\ is required to be set. | |
13576 | ||
13577 | If the system filter generates any pipe, file, or reply deliveries, the uid | |
13578 | under which the filter is run is used when transporting them, unless a | |
13579 | transport option overrides. | |
13580 | Normally you should set \system@_filter@_user\ if your system filter generates | |
13581 | these kinds of delivery. | |
13582 | ||
13583 | .conf tcp@_nodelay boolean true | |
13584 | .index daemon||\\TCP@_NODELAY\\ on sockets | |
13585 | .index Nagle algorithm | |
13586 | .index \\TCP@_NODELAY\\ on listening sockets | |
13587 | If this option is set false, it stops the Exim daemon setting the | |
13588 | \\TCP@_NODELAY\\ option on its listening sockets. Setting \\TCP@_NODELAY\\ | |
13589 | turns off the `Nagle algorithm', which is a way of improving network | |
13590 | performance in interactive (character-by-character) situations. Turning it off | |
13591 | should improve Exim's performance a bit, so that is what happens by default. | |
13592 | However, it appears that some broken clients cannot cope, and time out. Hence | |
13593 | this option. It affects only those sockets that are set up for listening by the | |
13594 | daemon. Sockets created by the smtp transport for delivering mail always set | |
13595 | \\TCP@_NODELAY\\. | |
13596 | ||
13597 | .conf timeout@_frozen@_after time 0s | |
13598 | .index frozen messages||timing out | |
13599 | .index timeout||frozen messages | |
13600 | If \timeout@_frozen@_after\ is set to a time greater than zero, a frozen | |
13601 | message of any kind that has been on the queue for longer than the given | |
13602 | time is automatically cancelled at the next queue run. If it is a bounce | |
13603 | message, it is just discarded; otherwise, a bounce is sent to the sender, in a | |
13604 | similar manner to cancellation by the \-Mg-\ command line option. If you want | |
13605 | to timeout frozen bounce messages earlier than other kinds of frozen message, | |
13606 | see \ignore@_bounce@_errors@_after\. | |
13607 | ||
13608 | .conf timezone string unset | |
13609 | .index timezone, setting | |
13610 | The value of \timezone\ is used to set the environment variable \\TZ\\ while | |
13611 | running Exim (if it is different on entry). This ensures that all timestamps | |
13612 | created by Exim are in the required timezone. If you want all your timestamps | |
13613 | to be in UTC (aka GMT) you should set | |
13614 | .display asis | |
13615 | timezone = UTC | |
13616 | .endd | |
13617 | The default value is taken from \\TIMEZONE@_DEFAULT\\ in \(Local/Makefile)\, | |
13618 | or, if that is not set, from the value of the TZ environment variable when Exim | |
13619 | is built. If \timezone\ is set to the empty string, either at build or run | |
13620 | time, any existing \\TZ\\ variable is removed from the environment when Exim | |
13621 | runs. This is appropriate behaviour for obtaining wall-clock time on some, but | |
13622 | unfortunately not all, operating systems. | |
13623 | ||
13624 | .conf tls@_advertise@_hosts "host list$**$" unset | |
13625 | .index TLS||advertising | |
13626 | .index encryption||on SMTP connection | |
13627 | .index SMTP||encrypted connection | |
13628 | When Exim is built with support for TLS encrypted connections, the availability | |
13629 | of the \\STARTTLS\\ command to set up an encrypted session is advertised in | |
13630 | response to \\EHLO\\ only to those client hosts that match this option. See | |
13631 | chapter ~~CHAPTLS for details of Exim's support for TLS. | |
13632 | ||
13633 | .conf tls@_certificate string$**$ unset | |
13634 | .index TLS||server certificate, location of | |
13635 | .index certificate||for server, location of | |
13636 | The value of this option is expanded, and must then be the absolute path to a | |
13637 | file which contains the server's certificates. The server's private key is also | |
13638 | assumed to be in this file if \tls@_privatekey\ is unset. See chapter ~~CHAPTLS | |
13639 | for further details. | |
13640 | ||
4964e932 | 13641 | \**Note**\: The certificates defined by this option are used only when Exim is |
495ae4b0 PH |
13642 | receiving incoming messages as a server. If you want to supply certificates for |
13643 | use when sending messages as a client, you must set the \tls@_certificate\ | |
13644 | option in the relevant \%smtp%\ transport. | |
13645 | ||
495ae4b0 PH |
13646 | .conf tls@_crl string$**$ unset |
13647 | .index TLS||server certificate revocation list | |
13648 | .index certificate||revocation list for server | |
13649 | This option specifies a certificate revocation list. The expanded value must | |
13650 | be the name of a file that contains a CRL in PEM format. | |
495ae4b0 PH |
13651 | |
13652 | .conf tls@_dhparam string$**$ unset | |
13653 | .index TLS||D-H parameters for server | |
13654 | The value of this option is expanded, and must then be the absolute path to | |
13655 | a file which contains the server's DH parameter values. | |
4964e932 | 13656 | This is used only for OpenSSL. When Exim is linked with GnuTLS, this option is |
495ae4b0 PH |
13657 | ignored. See section ~~SECTopenvsgnu for further details. |
13658 | ||
d43194df PH |
13659 | .em |
13660 | .conf tls@_on@_connect@_ports "string list" unset | |
8408f763 PH |
13661 | This option specifies a list of incoming SSMTP (aka SMTPS) ports that should |
13662 | operate the obsolete SSMTP (SMTPS) protocol, where a TLS session is immediately | |
13663 | set up without waiting for the client to issue a \\STARTTLS\\ command. For | |
13664 | further details, see section ~~SECTsupobssmt. | |
d43194df PH |
13665 | .nem |
13666 | ||
495ae4b0 PH |
13667 | .conf tls@_privatekey string$**$ unset |
13668 | .index TLS||server private key, location of | |
d43194df PH |
13669 | The value of this option is expanded, and must then be the absolute path to a |
13670 | file which contains the server's private key. If this option is unset, the | |
13671 | private key is assumed to be in the same file as the server's certificates. See | |
13672 | chapter ~~CHAPTLS for further details. | |
495ae4b0 PH |
13673 | |
13674 | .conf tls@_remember@_esmtp boolean false | |
13675 | .index TLS||esmtp state, remembering | |
13676 | .index TLS||broken clients | |
13677 | If this option is set true, Exim violates the RFCs by remembering that it is in | |
13678 | `esmtp' state after successfully negotiating a TLS session. This provides | |
13679 | support for broken clients that fail to send a new \\EHLO\\ after starting a | |
13680 | TLS session. | |
13681 | ||
495ae4b0 PH |
13682 | .conf tls@_require@_ciphers string$**$ unset |
13683 | .index TLS||requiring specific ciphers | |
13684 | .index cipher||requiring specific | |
13685 | This option controls which ciphers can be used for incoming TLS connections. | |
d43194df PH |
13686 | The \%smtp%\ transport has an option of the same name for controlling outgoing |
13687 | connections. This option is expanded for each connection, so can be varied for | |
495ae4b0 PH |
13688 | different clients if required. The value of this option must be a list of |
13689 | permitted cipher suites. The OpenSSL and GnuTLS libraries handle cipher control | |
d43194df PH |
13690 | in somewhat different ways. |
13691 | .em | |
13692 | If GnuTLS is being used, the client controls the preference order of the | |
13693 | available ciphers. | |
13694 | .nem | |
13695 | Details are given in sections ~~SECTreqciphssl and ~~SECTreqciphgnu. | |
495ae4b0 PH |
13696 | |
13697 | .conf tls@_try@_verify@_hosts "host list$**$" unset | |
13698 | .index TLS||client certificate verification | |
13699 | .index certificate||verification of client | |
13700 | See \tls@_verify@_hosts\ below. | |
13701 | ||
13702 | .conf tls@_verify@_certificates string$**$ unset | |
13703 | .index TLS||client certificate verification | |
13704 | .index certificate||verification of client | |
13705 | The value of this option is expanded, and must then be the absolute path to | |
13706 | a file containing permitted certificates for clients that | |
13707 | match \tls@_verify@_hosts\ or \tls@_try@_verify@_hosts\. Alternatively, if you | |
13708 | are using OpenSSL, you can set \tls@_verify@_certificates\ to the name of a | |
13709 | directory containing certificate files. This does not work with GnuTLS; the | |
13710 | option must be set to the name of a single file if you are using GnuTLS. | |
13711 | ||
13712 | .conf tls@_verify@_hosts "host list$**$" unset | |
13713 | .index TLS||client certificate verification | |
13714 | .index certificate||verification of client | |
13715 | This option, along with \tls@_try@_verify@_hosts\, controls the checking of | |
4964e932 PH |
13716 | certificates from clients. |
13717 | The expected certificates are defined by \tls@_verify@_certificates\, which | |
13718 | must be set. A configuration error occurs if either \tls@_verify@_hosts\ or | |
495ae4b0 PH |
13719 | \tls@_try@_verify@_hosts\ is set and \tls@_verify@_certificates\ is not set. |
13720 | ||
13721 | Any client that matches \tls@_verify@_hosts\ is constrained by | |
13722 | \tls@_verify@_certificates\. The client must present one of the listed | |
13723 | certificates. If it does not, the connection is aborted. | |
13724 | ||
13725 | A weaker form of checking is provided by \tls@_try@_verify@_hosts\. If a client | |
13726 | matches this option (but not \tls@_verify@_hosts\), Exim requests a | |
13727 | certificate and checks it against \tls@_verify@_certificates\, but does not | |
13728 | abort the connection if there is no certificate or if it does not match. This | |
13729 | state can be detected in an ACL, which makes it possible to implement policies | |
13730 | such as `accept for relay only if a verified certificate has been received, but | |
13731 | accept for local delivery if encrypted, even without a verified certificate'. | |
13732 | ||
13733 | Client hosts that match neither of these lists are not asked to present | |
13734 | certificates. | |
13735 | ||
13736 | .conf trusted@_groups "string list" unset | |
13737 | .index trusted group | |
13738 | .index group||trusted | |
13739 | If this option is set, any process that is running in one of the listed groups, | |
4964e932 | 13740 | or which has one of them as a supplementary group, is trusted. |
495ae4b0 PH |
13741 | The groups can be specified numerically or by name. |
13742 | See section ~~SECTtrustedadmin for details of what trusted callers are | |
13743 | permitted to do. If neither \trusted@_groups\ nor \trusted@_users\ is set, only | |
13744 | root and the Exim user are trusted. | |
13745 | ||
13746 | .conf trusted@_users "string list" unset | |
13747 | .index trusted user | |
13748 | .index user||trusted | |
13749 | If this option is set, any process that is running as one of the listed users | |
4964e932 | 13750 | is trusted. |
495ae4b0 PH |
13751 | The users can be specified numerically or by name. |
13752 | See section ~~SECTtrustedadmin for details of what trusted callers are | |
13753 | permitted to do. If neither \trusted@_groups\ nor \trusted@_users\ is set, only | |
13754 | root and the Exim user are trusted. | |
13755 | ||
13756 | .index uid (user id)||unknown caller | |
13757 | .conf unknown@_login string$**$ unset | |
13758 | This is a specialized feature for use in unusual configurations. By default, if | |
13759 | the uid of the caller of Exim cannot be looked up using \*getpwuid()*\, Exim | |
13760 | gives up. The \unknown@_login\ option can be used to set a login name to be | |
13761 | used in this circumstance. It is expanded, so values like \user@$caller@_uid\ | |
13762 | can be set. When \unknown@_login\ is used, the value of \unknown@_username\ is | |
13763 | used for the user's real name (gecos field), unless this has been set by the | |
13764 | \-F-\ option. | |
13765 | ||
13766 | .conf unknown@_username string unset | |
13767 | See \unknown@_login\. | |
13768 | ||
13769 | .conf untrusted@_set@_sender "address list$**$" unset | |
13770 | .index trusted user | |
13771 | .index sender||setting by untrusted user | |
13772 | .index untrusted user, setting sender | |
13773 | .index user||untrusted setting sender | |
13774 | .index envelope sender | |
13775 | When an untrusted user submits a message to Exim using the standard input, Exim | |
13776 | normally creates an envelope sender address from the user's login and the | |
13777 | default qualification domain. Data from the \-f-\ option (for setting envelope | |
13778 | senders on non-SMTP messages) or the SMTP \\MAIL\\ command (if \-bs-\ or \-bS-\ | |
13779 | is used) is ignored. | |
13780 | ||
13781 | However, untrusted users are permitted to set an empty envelope sender address, | |
13782 | to declare that a message should never generate any bounces. For example: | |
13783 | .display asis | |
13784 | exim -f '<>' user@domain.example | |
13785 | .endd | |
13786 | The \untrusted@_set@_sender\ option allows you to permit untrusted users to set | |
13787 | other envelope sender addresses in a controlled way. When it is set, untrusted | |
13788 | users are allowed to set envelope sender addresses that match any of the | |
13789 | patterns in the list. Like all address lists, the string is expanded. The | |
13790 | identity of the user is in \$sender@_ident$\, so you can, for example, restrict | |
4964e932 | 13791 | users to setting senders that start with their login ids |
495ae4b0 PH |
13792 | followed by a hyphen |
13793 | by a setting like this: | |
13794 | .display asis | |
13795 | untrusted_set_sender = ^$sender_ident- | |
13796 | .endd | |
13797 | If you want to allow untrusted users to set envelope sender addresses without | |
13798 | restriction, you can use | |
13799 | .display asis | |
13800 | untrusted_set_sender = * | |
13801 | .endd | |
13802 | The \untrusted@_set@_sender\ option applies to all forms of local input, but | |
13803 | only to the setting of the envelope sender. It does not permit untrusted users | |
13804 | to use the other options which trusted user can use to override message | |
13805 | parameters. Furthermore, it does not stop Exim from removing an existing | |
13806 | ::Sender:: header in the message, or from adding a ::Sender:: header if | |
13807 | necessary. See \local__sender__retain\ and \local@_from@_check\ for ways of | |
13808 | overriding these actions. The handling of the ::Sender:: header is also | |
13809 | described in section ~~SECTthesenhea. | |
13810 | ||
13811 | The log line for a message's arrival shows the envelope sender following `<='. | |
13812 | For local messages, the user's login always follows, after `U='. In \-bp-\ | |
13813 | displays, and in the Exim monitor, if an untrusted user sets an envelope sender | |
13814 | address, the user's login is shown in parentheses after the sender address. | |
13815 | ||
13816 | .conf uucp@_from@_pattern string "see below" | |
13817 | .index `From' line | |
13818 | .index UUCP||`From' line | |
13819 | Some applications that pass messages to an MTA via a command line interface use | |
13820 | an initial line starting with `From' to pass the envelope sender. In | |
13821 | particular, this is used by UUCP software. Exim recognizes such a line by means | |
13822 | of a regular expression that is set in \uucp@_from@_pattern\. When the pattern | |
13823 | matches, the sender address is constructed by expanding the contents of | |
13824 | \uucp@_from@_sender\, provided that the caller of Exim is a trusted user. The | |
13825 | default pattern recognizes lines in the following two forms: | |
13826 | .display asis | |
13827 | From ph10 Fri Jan 5 12:35 GMT 1996 | |
13828 | From ph10 Fri, 7 Jan 97 14:00:00 GMT | |
13829 | .endd | |
13830 | The pattern can be seen by running | |
13831 | .display asis | |
13832 | exim -bP uucp_from_pattern | |
13833 | .endd | |
13834 | It checks only up to the hours and minutes, and allows for a 2-digit or 4-digit | |
13835 | year in the second case. The first word after `From' is matched in the regular | |
13836 | expression by a parenthesized subpattern. The default value for | |
13837 | \uucp@_from@_sender\ is `$1', which therefore just uses this first word (`ph10' | |
13838 | in the example above) as the message's sender. See also | |
13839 | \ignore@_fromline@_hosts\. | |
13840 | ||
13841 | .conf uucp@_from@_sender string$**$ "$tt{@$1}" | |
13842 | See \uucp@_from@_pattern\ above. | |
13843 | ||
13844 | .conf warn@_message@_file string unset | |
13845 | .index warning of delay||customizing the message | |
13846 | .index customizing||warning message | |
13847 | This option defines a template file containing paragraphs of text to be used | |
13848 | for constructing the warning message which is sent by Exim when a message has | |
13849 | been on the queue for a specified amount of time, as specified by | |
13850 | \delay@_warning\. Details of the file's contents are given in chapter | |
13851 | ~~CHAPemsgcust. See also \bounce@_message@_file\. | |
13852 | ||
495ae4b0 PH |
13853 | .conf write@_rejectlog boolean true |
13854 | .index reject log||disabling | |
13855 | If this option is set false, Exim no longer writes anything to the reject log. | |
13856 | See chapter ~~CHAPlog for details of what Exim writes to its logs. | |
495ae4b0 PH |
13857 | |
13858 | .endconf | |
13859 | ||
13860 | ||
13861 | ||
13862 | . | |
13863 | . | |
13864 | . | |
13865 | . | |
13866 | . ============================================================================ | |
13867 | .chapter Generic options for routers | |
13868 | .rset CHAProutergeneric "~~chapter" | |
13869 | .set runningfoot "generic router options" | |
13870 | .index options||generic, for routers | |
13871 | .index generic options||router | |
13872 | ||
4964e932 | 13873 | This chapter describes the generic options that apply to all routers, |
495ae4b0 | 13874 | identifying those that are preconditions. For a general description of how a |
d43194df PH |
13875 | router operates, see sections ~~SECTrunindrou and ~~SECTrouprecon. The latter |
13876 | specifies the order in which the preconditions are tested. The order of | |
13877 | expansion of the options that provide data for a transport is: \errors@_to\, | |
13878 | \headers@_add\, \headers@_remove\, \transport\. | |
495ae4b0 | 13879 | |
d43194df | 13880 | .startconf routers |
495ae4b0 PH |
13881 | |
13882 | .conf address@_data string$**$ unset | |
13883 | .index router||data attached to address | |
13884 | The string is expanded just before the router is run, that is, after all the | |
13885 | precondition tests have succeeded. If the expansion is forced to fail, the | |
13886 | router declines. Other expansion failures cause delivery of the address to be | |
13887 | deferred. | |
13888 | ||
13889 | When the expansion succeeds, the value is retained with the address, and can be | |
13890 | accessed using the variable \$address@_data$\ in the current router, subsequent | |
4964e932 | 13891 | routers, and the eventual transport. |
495ae4b0 | 13892 | |
4964e932 | 13893 | \**Warning**\: if the current or any subsequent router is a \%redirect%\ router |
495ae4b0 PH |
13894 | that runs a user's filter file, the contents of \$address@_data$\ are |
13895 | accessible in the filter. This is not normally a problem, because such data is | |
4964e932 PH |
13896 | usually either not confidential or it `belongs' to the current user, but if you |
13897 | do put confidential data into \$address@_data$\ you need to remember this | |
495ae4b0 PH |
13898 | point. |
13899 | ||
13900 | Even if the router declines or passes, the value of \$address@_data$\ remains | |
13901 | with the address, though it can be changed by another \address@_data\ setting | |
13902 | on a subsequent router. If a router generates child addresses, the value of | |
13903 | \$address@_data$\ propagates to them. This also applies to the special kind of | |
13904 | `child' that is generated by a router with the \unseen\ option. | |
13905 | ||
13906 | The idea of \address@_data\ is that you can use it to look up a lot of data for | |
13907 | the address once, and then pick out parts of the data later. For example, you | |
13908 | could use a single LDAP lookup to return a string of the form | |
13909 | .display asis | |
13910 | uid=1234 gid=5678 mailbox=/mail/xyz forward=/home/xyz/.forward | |
13911 | .endd | |
13912 | In the transport you could pick out the mailbox by a setting such as | |
13913 | .display asis | |
13914 | file = ${extract{mailbox}{$address_data}} | |
13915 | .endd | |
13916 | This makes the configuration file less messy, and also reduces the number of | |
d43194df | 13917 | lookups (though Exim does cache lookups). |
495ae4b0 | 13918 | |
4964e932 | 13919 | The \address@_data\ facility is also useful as a means of passing information |
d43194df PH |
13920 | from one router to another, and from a router to a transport. In addition, if |
13921 | .em | |
13922 | \$address@_data$\ is set by a router when verifying a recipient address from an | |
13923 | ACL, it remains available for use in the rest of the ACL statement. After | |
13924 | verifying a sender, the value is transferred to \$sender@_address@_data$\. | |
13925 | .nem | |
495ae4b0 PH |
13926 | |
13927 | ||
13928 | .conf address@_test "boolean (precondition)" true | |
13929 | .index \-bt-\ option | |
13930 | .index router||skipping when address testing | |
13931 | If this option is set false, the router is skipped when routing is being tested | |
13932 | by means of the \-bt-\ command line option. This can be a convenience when your | |
4964e932 PH |
13933 | first router sends messages to an external scanner, because it saves you |
13934 | having to set the `already scanned' indicator when testing real address | |
495ae4b0 PH |
13935 | routing. |
13936 | ||
13937 | ||
13938 | .conf cannot@_route@_message string$**$ unset | |
13939 | .index router||customizing `cannot route' message | |
13940 | .index customizing||`cannot route' message | |
13941 | This option specifies a text message that is used when an address cannot be | |
13942 | routed because Exim has run out of routers. The default message is `Unrouteable | |
13943 | address'. This option is useful only on routers that have \more\ set false, or | |
13944 | on the very last router in a configuration, because the value that is used is | |
13945 | taken from the last router that inspects an address. For example, using the | |
13946 | default configuration, you could put: | |
13947 | .display asis | |
13948 | cannot_route_message = Remote domain not found in DNS | |
13949 | .endd | |
13950 | on the first (\%dnslookup%\) router, and | |
13951 | .display asis | |
13952 | cannot_route_message = Unknown local user | |
13953 | .endd | |
4964e932 | 13954 | on the final router that checks for local users. If string expansion fails, the |
495ae4b0 PH |
13955 | default message is used. |
13956 | Unless the expansion failure was explicitly forced, a message about the failure | |
13957 | is written to the main and panic logs, in addition to the normal message about | |
13958 | the routing failure. | |
13959 | ||
13960 | .conf caseful@_local@_part boolean false | |
13961 | .index case of local parts | |
13962 | .index router||case of local parts | |
13963 | By default, routers handle the local parts of addresses in a case-insensitive | |
13964 | manner, though the actual case is preserved for transmission with the message. | |
13965 | If you want the case of letters to be significant in a router, you must set | |
13966 | this option true. For individual router options that contain address or local | |
13967 | part lists (for example, \local@_parts\), case-sensitive matching can be turned | |
13968 | on by `+caseful' as a list item. See section ~~SECTcasletadd for more details. | |
13969 | ||
d43194df PH |
13970 | .em |
13971 | The value of the \$local@_part$\ variable is forced to lower case while a | |
13972 | router is running unless \caseful@_local@_part\ is set. When a router assigns | |
13973 | an address to a transport, the value of \$local@_part$\ when the transport runs | |
13974 | is the same as it was in the router. Similarly, when a router generates child | |
13975 | addresses by aliasing or forwarding, the values of \$original@_local@_part$\ | |
13976 | and \$parent@_local@_part$\ are those that were used by the redirecting router. | |
13977 | ||
13978 | This option applies to the processing of an address by a router. When a | |
13979 | recipient address is being processed in an ACL, there is a separate \control\ | |
13980 | modifier that can be used to specify case-sensitive processing within the ACL | |
13981 | (see section ~~SECTcontrols). | |
13982 | .nem | |
495ae4b0 PH |
13983 | |
13984 | .conf check@_local@_user "boolean (precondition)" false | |
13985 | .index local user, checking in router | |
13986 | .index router||checking for local user | |
d43194df | 13987 | .index \(/etc/passwd)\ |
495ae4b0 PH |
13988 | When this option is true, Exim checks that the local part of the recipient |
13989 | address (with affixes removed if relevant) is the name of an account on the | |
13990 | local system. The check is done by calling the \*getpwnam()*\ function rather | |
13991 | than trying to read \(/etc/passwd)\ directly. This means that other methods of | |
13992 | holding password data (such as NIS) are supported. If the local part is a local | |
13993 | user, \$home$\ is set from the password data, and can be tested in other | |
d43194df PH |
13994 | preconditions that are evaluated after this one (the order of evaluation is |
13995 | given in section ~~SECTrouprecon). However, the value of \$home$\ can be | |
13996 | overridden by \router@_home@_directory\. If the local part is not a local user, | |
13997 | the router is skipped. | |
495ae4b0 PH |
13998 | |
13999 | If you want to check that the local part is either the name of a local user | |
4964e932 PH |
14000 | or matches something else, you cannot combine \check@_local@_user\ with a |
14001 | setting of \local@_parts\, because that specifies the logical \*and*\ of the | |
14002 | two conditions. However, you can use a \%passwd%\ lookup in a \local@_parts\ | |
495ae4b0 PH |
14003 | setting to achieve this. For example: |
14004 | .display asis | |
14005 | local_parts = passwd;$local_part : lsearch;/etc/other/users | |
14006 | .endd | |
14007 | Note, however, that the side effects of \check@_local@_user\ (such as setting | |
14008 | up a home directory) do not occur when a \%passwd%\ lookup is used in a | |
14009 | \local@_parts\ (or any other) precondition. | |
14010 | ||
d43194df | 14011 | |
495ae4b0 PH |
14012 | .conf condition "string$**$ (precondition)" unset |
14013 | .index router||customized precondition | |
14014 | This option specifies a general precondition test that has to succeed for the | |
d43194df PH |
14015 | router to be called. The \condition\ option is the last precondition to be |
14016 | evaluated (see section ~~SECTrouprecon). The string is expanded, and if the | |
14017 | result is a forced failure, or an empty string, or one of the strings `0' or | |
14018 | `no' or `false' (checked without regard to the case of the letters), the router | |
14019 | is skipped, and the address is offered to the next one. | |
14020 | .em | |
14021 | If the result is any other value, the router is run (as this is the last | |
14022 | precondition to be evaluated, all the other preconditions must be true). | |
14023 | ||
14024 | The \condition\ option provides a means of applying custom conditions to the | |
14025 | running of routers. Note that in the case of a simple conditional expansion, | |
14026 | the default expansion values are exactly what is wanted. For example: | |
14027 | .display asis | |
14028 | condition = ${if >{$message_age}{600}} | |
14029 | .endd | |
14030 | Because of the default behaviour of the string expansion, this is equivalent to | |
14031 | .display asis | |
14032 | condition = ${if >{$message_age}{600}{true}{}} | |
14033 | .endd | |
14034 | .nem | |
495ae4b0 PH |
14035 | |
14036 | If the expansion fails (other than forced failure) delivery is deferred. Some | |
d43194df PH |
14037 | of the other precondition options are common special cases that could in fact |
14038 | be specified using \condition\. | |
495ae4b0 PH |
14039 | |
14040 | ||
14041 | .conf debug@_print string$**$ unset | |
14042 | .index testing||variables in drivers | |
14043 | If this option is set and debugging is enabled (see the \-d-\ command line | |
4964e932 PH |
14044 | option), the string is expanded and included in the debugging output. |
14045 | If expansion of the string fails, the error message is written to the debugging | |
495ae4b0 PH |
14046 | output, and Exim carries on processing. |
14047 | This option is provided to help with checking out the values of variables and | |
14048 | so on when debugging router configurations. For example, if a \condition\ | |
14049 | option appears not to be working, \debug@_print\ can be used to output the | |
14050 | variables it references. The output happens after checks for \domains\, | |
14051 | \local@_parts\, and \check@_local@_user\ but before any other preconditions are | |
14052 | tested. A newline is added to the text if it does not end with one. | |
14053 | ||
14054 | ||
14055 | .conf disable@_logging boolean false | |
14056 | If this option is set true, nothing is logged for any routing errors | |
495ae4b0 PH |
14057 | or for any deliveries caused by this router. You should not set this option |
14058 | unless you really, really know what you are doing. See also the generic | |
14059 | transport option of the same name. | |
495ae4b0 PH |
14060 | |
14061 | .conf domains "domain list$**$ (precondition)" unset | |
14062 | .index router||restricting to specific domains | |
14063 | If this option is set, the router is skipped unless the current domain matches | |
14064 | the list. If the match is achieved by means of a file lookup, the data that the | |
14065 | lookup returned for the domain is placed in \$domain@_data$\ for use in string | |
14066 | expansions of the driver's private options. | |
4964e932 | 14067 | See section ~~SECTrouprecon for a list of the order in which preconditions |
495ae4b0 PH |
14068 | are evaluated. |
14069 | ||
14070 | ||
14071 | .conf driver string unset | |
14072 | This option must always be set. It specifies which of the available routers is | |
14073 | to be used. | |
14074 | ||
14075 | ||
14076 | .conf errors@_to string$**$ unset | |
14077 | .index envelope sender | |
14078 | .index router||changing address for errors | |
14079 | If a router successfully handles an address, it may queue the address for | |
14080 | delivery or it may generate child addresses. In both cases, if there is a | |
14081 | delivery problem during later processing, the resulting bounce message is sent | |
14082 | to the address that results from expanding this string, provided that the | |
4964e932 PH |
14083 | address verifies successfully. |
14084 | \errors@_to\ is expanded before \headers@_add\, \headers@_remove\, and | |
495ae4b0 PH |
14085 | \transport\. |
14086 | ||
14087 | If the option is unset, or the expansion is forced to fail, or the result of | |
14088 | the expansion fails to verify, the errors address associated with the incoming | |
14089 | address is used. At top level, this is the envelope sender. A non-forced | |
14090 | expansion failure causes delivery to be deferred. | |
14091 | ||
14092 | If an address for which \errors@_to\ has been set ends up being delivered over | |
14093 | SMTP, the envelope sender for that delivery is the \errors@_to\ value, so that | |
14094 | any bounces that are generated by other MTAs on the delivery route are also | |
14095 | sent there. The most common use of \errors@_to\ is probably to direct mailing | |
14096 | list bounces to the manager of the list, as described in section | |
14097 | ~~SECTmailinglists. | |
14098 | ||
14099 | The \errors@_to\ setting associated with an address can be overridden if it | |
14100 | subsequently passes through other routers that have their own \errors@_to\ | |
14101 | settings, | |
14102 | or if it is delivered by a transport with a \return@_path\ setting. | |
14103 | ||
14104 | You can set \errors@_to\ to the empty string by either of these settings: | |
14105 | .display asis | |
14106 | errors_to = | |
14107 | errors_to = "" | |
14108 | .endd | |
14109 | An expansion item that yields an empty string has the same effect. If you do | |
14110 | this, a locally detected delivery error for addresses processed by this router | |
14111 | no longer gives rise to a bounce message; the error is discarded. If the | |
14112 | address is delivered to a remote host, the return path is set to \"<>"\, unless | |
14113 | overridden by the \return@_path\ option on the transport. | |
14114 | ||
14115 | If for some reason you want to discard local errors, but use a non-empty | |
14116 | \\MAIL\\ command for remote delivery, you can preserve the original return | |
14117 | path in \$address@_data$\ in the router, and reinstate it in the transport by | |
14118 | setting \return@_path\. | |
14119 | ||
14120 | ||
14121 | .conf expn "boolean (precondition)" true | |
14122 | .index address||testing | |
14123 | .index testing||addresses | |
14124 | .index \\EXPN\\||router skipping | |
14125 | .index router||skipping for \\EXPN\\ | |
14126 | If this option is turned off, the router is skipped when testing an address | |
14127 | as a result of processing an SMTP \\EXPN\\ command. You might, for example, | |
14128 | want to turn it off on a router for users' \(.forward)\ files, while leaving it | |
4964e932 PH |
14129 | on for the system alias file. |
14130 | See section ~~SECTrouprecon for a list of the order in which preconditions | |
495ae4b0 PH |
14131 | are evaluated. |
14132 | ||
14133 | The use of the SMTP \\EXPN\\ command is controlled by an ACL (see chapter | |
14134 | ~~CHAPACL). When Exim is running an \\EXPN\\ command, it is similar to testing | |
14135 | an address with \-bt-\. Compare \\VRFY\\, whose counterpart is \-bv-\. | |
14136 | ||
14137 | ||
14138 | .conf fail@_verify boolean false | |
14139 | .index router||forcing verification failure | |
14140 | Setting this option has the effect of setting both \fail@_verify@_sender\ and | |
14141 | \fail@_verify@_recipient\ to the same value. | |
14142 | ||
14143 | ||
14144 | .conf fail@_verify@_recipient boolean false | |
14145 | If this option is true and an address is accepted by this router when | |
14146 | verifying a recipient, verification fails. | |
14147 | ||
14148 | ||
14149 | .conf fail@_verify@_sender boolean false | |
14150 | If this option is true and an address is accepted by this router when | |
14151 | verifying a sender, verification fails. | |
14152 | ||
14153 | ||
14154 | .conf fallback@_hosts "string list" unset | |
14155 | .index router||fallback hosts | |
14156 | .index fallback||hosts specified on router | |
14157 | String expansion is not applied to this option. The argument must be a | |
14158 | colon-separated list of host names or IP addresses. If a router queues an | |
14159 | address for a remote transport, this host list is associated with the address, | |
14160 | and used instead of the transport's fallback host list. If \hosts@_randomize\ | |
14161 | is set on the transport, the order of the list is randomized for each use. See | |
14162 | the \fallback@_hosts\ option of the \%smtp%\ transport for further details. | |
14163 | ||
14164 | .conf group string$**$ "see below" | |
14165 | .index gid (group id)||local delivery | |
14166 | .index local transports||uid and gid | |
14167 | .index transport||local | |
14168 | .index router||setting group | |
14169 | When a router queues an address for a transport, and the transport does not | |
14170 | specify a group, the group given here is used when running the delivery | |
4964e932 PH |
14171 | process. |
14172 | The group may be specified numerically or by name. If expansion fails, the | |
495ae4b0 PH |
14173 | error is logged and delivery is deferred. |
14174 | The default is unset, unless \check@_local@_user\ is set, when the default | |
14175 | is taken from the password information. See also \initgroups\ and \user\ and | |
14176 | the discussion in chapter ~~CHAPenvironment. | |
14177 | ||
14178 | ||
14179 | .conf headers@_add string$**$ unset | |
14180 | .index header lines||adding | |
14181 | .index router||adding header lines | |
d43194df | 14182 | .em |
495ae4b0 | 14183 | This option specifies a string of text that is expanded at routing time, and |
d43194df PH |
14184 | associated with any addresses that are accepted by the router. However, this |
14185 | option has no effect when an address is just being verified. The way in which | |
14186 | the text is used to add header lines at transport time is described in section | |
14187 | ~~SECTheadersaddrem. | |
495ae4b0 PH |
14188 | |
14189 | The \headers@_add\ option is expanded after \errors@_to\, but before | |
d43194df PH |
14190 | \headers@_remove\ and \transport\. If the expanded string is empty, or if the |
14191 | expansion is forced to fail, the option has no effect. Other expansion failures | |
14192 | are treated as configuration errors. | |
495ae4b0 | 14193 | |
d43194df PH |
14194 | \**Warning**\: The \headers@_add\ option cannot be used for a \%redirect%\ |
14195 | router that has the \one@_time\ option set. | |
14196 | .nem | |
495ae4b0 PH |
14197 | |
14198 | ||
14199 | .conf headers@_remove string$**$ unset | |
14200 | .index header lines||removing | |
14201 | .index router||removing header lines | |
d43194df PH |
14202 | .em |
14203 | This option specifies a string of text that is expanded at routing time, and | |
14204 | associated with any addresses that are accepted by the router. However, this | |
14205 | option has no effect when an address is just being verified. The way in which | |
14206 | the text is used to remove header lines at transport time is described in | |
14207 | section ~~SECTheadersaddrem. | |
14208 | ||
14209 | The \headers@_remove\ option is expanded after \errors@_to\ and \headers@_add\, | |
14210 | but before \transport\. If the expansion is forced to fail, the option has no | |
14211 | effect. Other expansion failures are treated as configuration errors. | |
14212 | ||
14213 | \**Warning**\: The \headers@_remove\ option cannot be used for a \%redirect%\ | |
14214 | router that has the \one@_time\ option set. | |
14215 | .nem | |
14216 | ||
495ae4b0 PH |
14217 | |
14218 | .conf ignore@_target@_hosts "host list$**$" unset | |
14219 | .index IP address||discarding | |
14220 | .index router||discarding IP addresses | |
14221 | Although this option is a host list, it should normally contain IP address | |
14222 | entries rather than names. If any host that is looked up by the router has an | |
14223 | IP address that matches an item in this list, Exim behaves as if that IP | |
14224 | address did not exist. This option allows you to cope with rogue DNS entries | |
14225 | like | |
14226 | .display asis | |
14227 | remote.domain.example. A 127.0.0.1 | |
14228 | .endd | |
14229 | by setting | |
14230 | .display asis | |
14231 | ignore_target_hosts = 127.0.0.1 | |
14232 | .endd | |
d43194df PH |
14233 | on the relevant router. If all the hosts found by a \%dnslookup%\ router are |
14234 | discarded in this way, the router declines. In a conventional configuration, an | |
14235 | attempt to mail to such a domain would normally provoke the `unrouteable | |
14236 | domain' error, and an attempt to verify an address in the domain would fail. | |
495ae4b0 PH |
14237 | |
14238 | Similarly, if \ignore@_target@_hosts\ is set on an \%ipliteral%\ router, the | |
14239 | router declines if presented with one of the listed addresses. | |
495ae4b0 PH |
14240 | |
14241 | This option may also be useful for ignoring link-local and site-local IPv6 | |
14242 | addresses. Because, like all host lists, the value of \ignore@_target@_hosts\ | |
14243 | is expanded before use as a list, it is possible to make it dependent on the | |
14244 | domain that is being routed. | |
d43194df PH |
14245 | .em |
14246 | During its expansion, \$host@_address$\ is set to the IP address that is being | |
14247 | checked. | |
14248 | .nem | |
495ae4b0 PH |
14249 | |
14250 | ||
14251 | ||
14252 | .index additional groups | |
14253 | .index groups, additional | |
14254 | .index local transports||uid and gid | |
14255 | .index transport||local | |
14256 | .conf initgroups boolean false | |
14257 | If the router queues an address for a transport, and this option is true, and | |
14258 | the uid supplied by the router is not overridden by the transport, the | |
14259 | \*initgroups()*\ function is called when running the transport to ensure that | |
14260 | any additional groups associated with the uid are set up. See also \group\ and | |
14261 | \user\ and the discussion in chapter ~~CHAPenvironment. | |
14262 | ||
14263 | ||
14264 | .conf local@_part@_prefix "string list (precondition)" unset | |
14265 | .index router||prefix for local part | |
14266 | .index prefix||for local part, used in router | |
14267 | If this option is set, the router is skipped unless the local part | |
14268 | starts with one of the given strings, or \local@_part@_prefix@_optional\ is | |
14269 | true. | |
14270 | See section ~~SECTrouprecon for a list of the order in which preconditions | |
14271 | are evaluated. | |
14272 | ||
14273 | The list is scanned from left to right, and the first prefix that matches is | |
14274 | used. A limited form of wildcard is available; if the prefix begins with an | |
14275 | asterisk, it matches the longest possible sequence of arbitrary characters at | |
14276 | the start of the local part. An asterisk should therefore always be followed by | |
14277 | some character that does not occur in normal local parts. | |
14278 | .index multiple mailboxes | |
14279 | .index mailbox||multiple | |
14280 | Wildcarding can be used to set up multiple user mailboxes, as described in | |
14281 | section ~~SECTmulbox. | |
14282 | ||
14283 | During the testing of the \local@_parts\ option, and while the router is | |
14284 | running, the prefix is removed from the local part, and is available in the | |
14285 | expansion variable \$local@_part@_prefix$\. If the router accepts the address, | |
14286 | this remains true during subsequent delivery. | |
4964e932 PH |
14287 | In particular, the local part that is transmitted in the \\RCPT\\ command |
14288 | for LMTP, SMTP, and BSMTP deliveries has the prefix removed by default. This | |
14289 | behaviour can be overridden by setting \rcpt@_include@_affixes\ true on the | |
495ae4b0 PH |
14290 | relevant transport. |
14291 | ||
14292 | The prefix facility is commonly used to handle local parts of the form | |
14293 | \owner-something\. Another common use is to support local parts of the form | |
14294 | \real-username\ to bypass a user's \(.forward)\ file -- helpful when trying to | |
14295 | tell a user their forwarding is broken -- by placing a router like this one | |
14296 | immediately before the router that handles \(.forward)\ files: | |
14297 | .display asis | |
14298 | real_localuser: | |
14299 | driver = accept | |
14300 | local_part_prefix = real- | |
14301 | check_local_user | |
14302 | transport = local_delivery | |
14303 | .endd | |
14304 | If both \local@_part@_prefix\ and \local@_part@_suffix\ are set for a router, | |
14305 | both conditions must be met if not optional. Care must be taken if wildcards | |
14306 | are used in both a prefix and a suffix on the same router. Different | |
14307 | separator characters must be used to avoid ambiguity. | |
14308 | ||
14309 | .conf local@_part@_prefix@_optional boolean false | |
14310 | See \local@_part@_prefix\ above. | |
14311 | ||
14312 | ||
14313 | .conf local@_part@_suffix "string list (precondition)" unset | |
14314 | .index router||suffix for local part | |
14315 | .index suffix for local part, used in router | |
14316 | This option operates in the same way as \local@_part@_prefix\, except that the | |
14317 | local part must end (rather than start) with the given string, the | |
14318 | \local@_part@_suffix@_optional\ option determines whether the suffix is | |
14319 | mandatory, and the wildcard $*$ character, if present, must be the last | |
14320 | character of the suffix. This option facility is commonly used to handle local | |
14321 | parts of the form \something-request\ and multiple user mailboxes of the form | |
14322 | \username-foo\. | |
14323 | ||
14324 | .conf local@_part@_suffix@_optional boolean false | |
14325 | See \local@_part@_suffix\ above. | |
14326 | ||
14327 | ||
14328 | .conf local@_parts "local part list$**$ (precondition)" unset | |
14329 | .index router||restricting to specific local parts | |
14330 | .index local part||checking in router | |
14331 | The router is run only if the local part of the address matches the list. | |
4964e932 | 14332 | See section ~~SECTrouprecon for a list of the order in which preconditions |
495ae4b0 PH |
14333 | are evaluated, and |
14334 | section ~~SECTlocparlis for a discussion of local part lists. Because the | |
14335 | string is expanded, it is possible to make it depend on the domain, for | |
14336 | example: | |
14337 | .display asis | |
14338 | local_parts = dbm;/usr/local/specials/$domain | |
14339 | .endd | |
14340 | If the match is achieved by a lookup, the data that the lookup returned | |
14341 | for the local part is placed in the variable \$local@_part@_data$\ for use in | |
14342 | expansions of the router's private options. You might use this option, for | |
14343 | example, if you have a large number of local virtual domains, and you want to | |
14344 | send all postmaster mail to the same place without having to set up an alias in | |
14345 | each virtual domain: | |
14346 | .display asis | |
14347 | postmaster: | |
14348 | driver = redirect | |
14349 | local_parts = postmaster | |
14350 | data = postmaster@real.domain.example | |
14351 | .endd | |
14352 | ||
14353 | ||
14354 | .conf log@_as@_local boolean "see below" | |
14355 | .index log||delivery line | |
14356 | .index delivery||log line format | |
14357 | Exim has two logging styles for delivery, the idea being to make local | |
14358 | deliveries stand out more visibly from remote ones. In the `local' style, the | |
14359 | recipient address is given just as the local part, without a domain. The use of | |
14360 | this style is controlled by this option. It defaults to true for the \%accept%\ | |
14361 | router, and false for all the others. | |
14362 | ||
14363 | ||
14364 | .conf more boolean$**$ true | |
14365 | The result of string expansion for this option must be a valid boolean value, | |
14366 | that is, one of the strings `yes', `no', `true', or `false'. Any other result | |
14367 | causes an error, and delivery is deferred. If the expansion is forced to fail, | |
14368 | the default value for the option (true) is used. Other failures cause delivery | |
14369 | to be deferred. | |
14370 | ||
14371 | If this option is set false, and the router is run, but declines to handle the | |
14372 | address, no further routers are tried, routing fails, and the address is | |
14373 | bounced. | |
14374 | .index \self\ option | |
14375 | However, if the router explicitly passes an address to the following router by | |
14376 | means of the setting | |
14377 | .display asis | |
14378 | self = pass | |
14379 | .endd | |
14380 | or otherwise, the setting of \more\ is ignored. Also, the setting of \more\ | |
14381 | does not affect the behaviour if one of the precondition tests fails. In that | |
14382 | case, the address is always passed to the next router. | |
14383 | ||
14384 | ||
14385 | .conf pass@_on@_timeout boolean false | |
14386 | .index timeout||of router | |
14387 | .index router||timeout | |
14388 | If a router times out during a host lookup, it normally causes deferral of the | |
14389 | address. If \pass@_on@_timeout\ is set, the address is passed on to the next | |
14390 | router, overriding \no@_more\. This may be helpful for systems that are | |
14391 | intermittently connected to the Internet, or those that want to pass to a smart | |
14392 | host any messages that cannot immediately be delivered. | |
14393 | ||
14394 | There are occasional other temporary errors that can occur while doing DNS | |
14395 | lookups. They are treated in the same way as a timeout, and this option | |
14396 | applies to all of them. | |
14397 | ||
14398 | ||
14399 | .conf pass@_router string unset | |
14400 | .index router||go to after `pass' | |
14401 | When a router returns `pass', the address is normally handed on to the next | |
14402 | router in sequence. This can be changed by setting \pass@_router\ to the name | |
14403 | of another router. However (unlike \redirect@_router\) the named router must be | |
14404 | below the current router, to avoid loops. Note that this option applies only to | |
14405 | the special case of `pass'. It does not apply when a router returns `decline'. | |
14406 | ||
14407 | ||
14408 | .conf redirect@_router string unset | |
14409 | .index router||start at after redirection | |
14410 | Sometimes an administrator knows that it is pointless to reprocess addresses | |
14411 | generated from alias or forward files with the same router again. For | |
14412 | example, if an alias file translates real names into login ids there is no | |
14413 | point searching the alias file a second time, especially if it is a large file. | |
14414 | ||
14415 | The \redirect@_router\ option can be set to the name of any router instance. It | |
14416 | causes the routing of any generated addresses to start at the named router | |
14417 | instead of at the first router. This option has no effect if the router in | |
14418 | which it is set does not generate new addresses. | |
14419 | ||
14420 | ||
14421 | .conf require@_files "string list$**$ (precondition)" unset | |
14422 | .index file||requiring for router | |
14423 | .index router||requiring file existence | |
14424 | This option provides a general mechanism for predicating the running of a | |
14425 | router on the existence or non-existence of certain files or directories. | |
14426 | Before running a router, as one of its precondition tests, Exim works its way | |
4964e932 | 14427 | through the \require@_files\ list, expanding each item separately. |
495ae4b0 PH |
14428 | |
14429 | Because the list is split before expansion, any colons in expansion items must | |
14430 | be doubled, or the facility for using a different list separator must be used. | |
4964e932 | 14431 | If any expansion is forced to fail, the item is ignored. Other expansion |
495ae4b0 PH |
14432 | failures cause routing of the address to be deferred. |
14433 | ||
14434 | If any expanded string is empty, it is ignored. Otherwise, except as described | |
14435 | below, each string must be a fully qualified file path, optionally preceded by | |
14436 | `!'. The paths are passed to the \*stat()*\ function to test for the existence | |
14437 | of the files or directories. The router is skipped if any paths not preceded by | |
14438 | `!' do not exist, or if any paths preceded by `!' do exist. | |
14439 | ||
14440 | .index NFS | |
14441 | If \*stat()*\ cannot determine whether a file exists or not, delivery of | |
14442 | the message is deferred. This can happen when NFS-mounted filesystems are | |
14443 | unavailable. | |
14444 | ||
14445 | This option is checked after the \domains\, \local@_parts\, and \senders\ | |
14446 | options, so you cannot use it to check for the existence of a file in which to | |
14447 | look up a domain, local part, or sender. (See section ~~SECTrouprecon for a | |
14448 | full list of the order in which preconditions are evaluated.) However, as | |
14449 | these options are all expanded, you can use the \exists\ expansion condition to | |
14450 | make such tests. The \require@_files\ option is intended for checking files | |
14451 | that the router may be going to use internally, or which are needed by a | |
14452 | transport (for example \(.procmailrc)\). | |
14453 | ||
14454 | During delivery, the \*stat()*\ function is run as root, but there is a | |
4964e932 | 14455 | facility for some checking of the accessibility of a file by another user. |
495ae4b0 PH |
14456 | This is not a proper permissions check, but just a `rough' check that |
14457 | operates as follows: | |
14458 | ||
14459 | If an item in a \require@_files\ list does not contain any forward slash | |
14460 | characters, it is taken to be the user (and optional group, separated by a | |
14461 | comma) to be checked for subsequent files in the list. If no group is specified | |
14462 | but the user is specified symbolically, the gid associated with the uid is | |
14463 | used. For example: | |
14464 | .display asis | |
14465 | require_files = mail:/some/file | |
14466 | require_files = $local_part:$home/.procmailrc | |
14467 | .endd | |
14468 | If a user or group name in a \require@_files\ list does not exist, the | |
14469 | \require@_files\ condition fails. | |
14470 | ||
14471 | Exim performs the check by scanning along the components of the file path, and | |
14472 | checking the access for the given uid and gid. It checks for `x' access on | |
14473 | directories, and `r' access on the final file. Note that this means that file | |
14474 | access control lists, if the operating system has them, are ignored. | |
14475 | ||
14476 | \**Warning 1**\: When the router is being run to verify addresses for an | |
14477 | incoming SMTP message, Exim is not running as root, but under its own uid. This | |
14478 | may affect the result of a \require@_files\ check. In particular, \*stat()*\ | |
14479 | may yield the error \\EACCES\\ (`Permission denied'). This means that the Exim | |
14480 | user is not permitted to read one of the directories on the file's path. | |
14481 | ||
4964e932 | 14482 | \**Warning 2**\: Even when Exim is running as root while delivering a message, |
d43194df | 14483 | \*stat()*\ can yield \\EACCES\\ for a file in an NFS directory that is mounted |
495ae4b0 | 14484 | without root access. |
d43194df PH |
14485 | .em |
14486 | In this case, if a check for access by a particular user is requested, Exim | |
14487 | creates a subprocess that runs as that user, and tries the check again in that | |
14488 | process. | |
495ae4b0 | 14489 | |
d43194df PH |
14490 | The default action for handling an unresolved \\EACCES\\ is to consider it to |
14491 | be caused by a configuration error, | |
14492 | .nem | |
14493 | and routing is deferred because the existence or non-existence of the file | |
14494 | cannot be determined. However, in some circumstances it may be desirable to | |
14495 | treat this condition as if the file did not exist. If the file name (or the | |
14496 | exclamation mark that precedes the file name for non-existence) is preceded by | |
14497 | a plus sign, the \\EACCES\\ error is treated as if the file did not exist. For | |
14498 | example: | |
495ae4b0 PH |
14499 | .display asis |
14500 | require_files = +/some/file | |
14501 | .endd | |
14502 | If the router is not an essential part of verification (for example, it | |
4964e932 | 14503 | handles users' \(.forward)\ files), another solution is to set the \verify\ |
495ae4b0 PH |
14504 | option false so that the router is skipped when verifying. |
14505 | ||
14506 | ||
14507 | .conf retry@_use@_local@_part boolean "see below" | |
14508 | .index hints database||retry keys | |
14509 | .index local part||in retry keys | |
14510 | When a delivery suffers a temporary routing failure, a retry record is created | |
14511 | in Exim's hints database. For addresses whose routing depends only on the | |
14512 | domain, the key for the retry record should not involve the local part, but for | |
14513 | other addresses, both the domain and the local part should be included. | |
14514 | Usually, remote routing is of the former kind, and local routing is of the | |
14515 | latter kind. | |
14516 | ||
14517 | This option controls whether the local part is used to form the key for retry | |
14518 | hints for addresses that suffer temporary errors while being handled by this | |
14519 | router. The default value is true for any router that has \check@_local@_user\ | |
14520 | set, and false otherwise. Note that this option does not apply to hints keys | |
14521 | for transport delays; they are controlled by a generic transport option of the | |
14522 | same name. | |
14523 | ||
4964e932 PH |
14524 | The setting of \retry@_use@_local@_part\ applies only to the router on which it |
14525 | appears. If the router generates child addresses, they are routed | |
495ae4b0 | 14526 | independently; this setting does not become attached to them. |
495ae4b0 PH |
14527 | |
14528 | ||
14529 | .conf router@_home@_directory string$**$ unset | |
14530 | .index router||home directory for | |
14531 | .index home directory||for router | |
14532 | This option sets a home directory for use while the router is running. (Compare | |
14533 | \transport__home@_directory\, which sets a home directory for later | |
14534 | transporting.) In particular, if used on a \%redirect%\ router, this option | |
14535 | sets a value for \$home$\ while a filter is running. The value is expanded; | |
14536 | forced expansion failure causes the option to be ignored -- other failures | |
14537 | cause the router to defer. | |
14538 | ||
14539 | Expansion of \router@_home@_directory\ happens immediately after the | |
14540 | \check@_local@_user\ test (if configured), before any further expansions take | |
4964e932 | 14541 | place. |
495ae4b0 PH |
14542 | (See section ~~SECTrouprecon for a list of the order in which preconditions |
14543 | are evaluated.) | |
14544 | While the router is running, \router__home@_directory\ overrides the value of | |
14545 | \$home$\ that came from \check@_local@_user\. | |
14546 | ||
14547 | When a router accepts an address and routes it to a transport (including the | |
14548 | cases when a redirect router generates a pipe, file, or autoreply delivery), | |
14549 | the home directory setting for the transport is taken from the first of these | |
14550 | values that is set: | |
14551 | .numberpars $. | |
14552 | The \home@_directory\ option on the transport; | |
14553 | .nextp | |
14554 | The \transport@_home@_directory\ option on the router; | |
14555 | .nextp | |
14556 | The password data if \check@_local@_user\ is set on the router; | |
14557 | .nextp | |
14558 | The \router@_home@_directory\ option on the router. | |
14559 | .endp | |
14560 | In other words, \router@_home@_directory\ overrides the password data for the | |
14561 | router, but not for the transport. | |
14562 | ||
14563 | ||
14564 | .conf self string "freeze" | |
14565 | .index MX record||pointing to local host | |
14566 | .index local host||MX pointing to | |
14567 | This option applies to those routers that use a recipient address to find a | |
14568 | list of remote hosts. Currently, these are the \%dnslookup%\, \%ipliteral%\, | |
4964e932 | 14569 | and \%manualroute%\ routers. |
495ae4b0 PH |
14570 | Certain configurations of the \%queryprogram%\ router can also specify a list |
14571 | of remote hosts. | |
14572 | Usually such routers are configured to send the message to a remote host via an | |
14573 | \%smtp%\ transport. The \self\ option specifies what happens when the first | |
14574 | host on the list turns out to be the local host. | |
14575 | The way in which Exim checks for the local host is described in section | |
14576 | ~~SECTreclocipadd. | |
14577 | ||
14578 | Normally this situation indicates either an error in Exim's configuration (for | |
14579 | example, the router should be configured not to process this domain), or an | |
14580 | error in the DNS (for example, the MX should not point to this host). For this | |
14581 | reason, the default action is to log the incident, defer the address, and | |
14582 | freeze the message. The following alternatives are provided for use in special | |
14583 | cases: | |
14584 | .numberpars $. | |
14585 | \defer\ | |
14586 | .newline | |
14587 | Delivery of the message is tried again later, but the message is not frozen. | |
14588 | .nextp | |
14589 | \reroute: <<domain>>\ | |
14590 | .newline | |
14591 | The domain is changed to the given domain, and the address is passed back to | |
14592 | be reprocessed by the routers. No rewriting of headers takes place. This | |
14593 | behaviour is essentially a redirection. | |
14594 | .nextp | |
14595 | \reroute: rewrite: <<domain>>\ | |
14596 | .newline | |
14597 | The domain is changed to the given domain, and the address is passed back to be | |
14598 | reprocessed by the routers. Any headers that contain the original domain are | |
14599 | rewritten. | |
14600 | .nextp | |
14601 | \pass\ | |
14602 | .newline | |
14603 | The router passes the address to the next router, or to the router named in the | |
14604 | \pass@_router\ option if it is set. | |
14605 | .index \more\ option | |
14606 | This overrides \no@_more\. | |
14607 | ||
14608 | During subsequent routing and delivery, the variable | |
14609 | \$self@_hostname$\ contains the name of the local host that the router | |
14610 | encountered. This can be used to distinguish between different cases for hosts | |
14611 | with multiple names. The combination | |
14612 | .display asis | |
14613 | self = pass | |
14614 | no_more | |
14615 | .endd | |
14616 | ensures that only those addresses that routed to the local host are passed on. | |
14617 | Without \no@_more\, addresses that were declined for other reasons would also | |
14618 | be passed to the next router. | |
14619 | .nextp | |
14620 | \fail\ | |
14621 | .newline | |
14622 | Delivery fails and an error report is generated. | |
14623 | .nextp | |
14624 | \send\ | |
14625 | .newline | |
14626 | .index local host||sending to | |
14627 | The anomaly is ignored and the address is queued for the transport. This | |
14628 | setting should be used with extreme caution. For an \%smtp%\ transport, it makes | |
14629 | sense only in cases where the program that is listening on the SMTP port is not | |
14630 | this version of Exim. That is, it must be some other MTA, or Exim with a | |
14631 | different configuration file that handles the domain in another way. | |
14632 | .endp | |
14633 | ||
14634 | .conf senders "address list$**$ (precondition)" unset | |
14635 | .index router||checking senders | |
14636 | If this option is set, the router is skipped unless the message's sender | |
4964e932 PH |
14637 | address matches something on the list. |
14638 | See section ~~SECTrouprecon for a list of the order in which preconditions | |
495ae4b0 PH |
14639 | are evaluated. |
14640 | ||
14641 | There are issues concerning verification when the running of routers is | |
14642 | dependent on the sender. When Exim is verifying the address in an \errors@_to\ | |
14643 | setting, it sets the sender to the null string. When using the \-bt-\ option to | |
14644 | check a configuration file, it is necessary also to use the \-f-\ option to set | |
14645 | an appropriate sender. For incoming mail, the sender is unset when verifying | |
14646 | the sender, but is available when verifying any recipients. If the SMTP | |
14647 | \\VRFY\\ command is enabled, it must be used after \\MAIL\\ if the sender | |
14648 | address matters. | |
14649 | ||
14650 | .conf translate@_ip@_address string$**$ unset | |
14651 | .index IP address||translating | |
14652 | .index packet radio | |
14653 | .index router||IP address translation | |
14654 | There exist some rare networking situations (for example, packet radio) where | |
14655 | it is helpful to be able to translate IP addresses generated by normal routing | |
14656 | mechanisms into other IP addresses, thus performing a kind of manual IP | |
14657 | routing. This should be done only if the normal IP routing of the TCP/IP stack | |
14658 | is inadequate or broken. Because this is an extremely uncommon requirement, the | |
14659 | code to support this option is not included in the Exim binary unless | |
14660 | \\SUPPORT__TRANSLATE__IP__ADDRESS\\=yes is set in \(Local/Makefile)\. | |
14661 | ||
14662 | The \translate@_ip@_address\ string is expanded for every IP address generated | |
14663 | by the router, with the generated address set in \$host@_address$\. If the | |
4964e932 | 14664 | expansion is forced to fail, no action is taken. |
495ae4b0 PH |
14665 | For any other expansion error, delivery of the message is deferred. |
14666 | If the result of the expansion is an IP address, that replaces the original | |
14667 | address; otherwise the result is assumed to be a host name -- this is looked up | |
14668 | using \*gethostbyname()*\ (or \*getipnodebyname()*\ when available) to produce | |
14669 | one or more replacement IP addresses. For example, to subvert all IP addresses | |
14670 | in some specific networks, this could be added to a router: | |
14671 | .display | |
14672 | $smc{translate@_ip@_address = @\ | |
14673 | @$@{lookup@{@$@{mask:@$host@_address/26@}@}lsearch@{/some/file@}@{@$value@}fail@}} | |
14674 | .endd | |
14675 | The file would contain lines like | |
14676 | .display asis | |
14677 | 10.2.3.128/26 some.host | |
14678 | 10.8.4.34/26 10.44.8.15 | |
14679 | .endd | |
14680 | You should not make use of this facility unless you really understand what you | |
14681 | are doing. | |
14682 | ||
14683 | ||
14684 | .conf transport string$**$ unset | |
14685 | This option specifies the transport to be used when a router accepts an address | |
14686 | and sets it up for delivery. A transport is never needed if a router is used | |
4964e932 | 14687 | only for verification. The value of the option is expanded at routing time, |
d43194df PH |
14688 | after the expansion of \errors@_to\, \headers@_add\, and \headers@_remove\, and |
14689 | result must be the name of one of the configured transports. If it is not, | |
14690 | delivery is deferred. | |
495ae4b0 PH |
14691 | |
14692 | The \transport\ option is not used by the \%redirect%\ router, but it does have | |
14693 | some private options that set up transports for pipe and file deliveries (see | |
14694 | chapter ~~CHAPredirect). | |
14695 | ||
14696 | ||
14697 | .conf transport@_current@_directory string$**$ unset | |
14698 | .index current directory for local transport | |
14699 | This option associates a current directory with any address that is routed | |
14700 | to a local transport. This can happen either because a transport is | |
14701 | explicitly configured for the router, or because it generates a delivery to a | |
14702 | file or a pipe. During the delivery process (that is, at transport time), this | |
14703 | option string is expanded and is set as the current directory, unless | |
14704 | overridden by a setting on the transport. | |
14705 | If the expansion fails for any reason, including forced failure, an error is | |
14706 | logged, and delivery is deferred. | |
14707 | See chapter ~~CHAPenvironment for details of the local delivery environment. | |
14708 | ||
14709 | ||
14710 | ||
14711 | .conf transport@_home@_directory string$**$ "see below" | |
14712 | .index home directory||for local transport | |
14713 | This option associates a home directory with any address that is routed to a | |
14714 | local transport. This can happen either because a transport is explicitly | |
14715 | configured for the router, or because it generates a delivery to a file or a | |
14716 | pipe. During the delivery process (that is, at transport time), the option | |
14717 | string is expanded and is set as the home directory, unless overridden by a | |
14718 | setting of \home@_directory\ on the transport. | |
14719 | If the expansion fails for any reason, including forced failure, an error is | |
14720 | logged, and delivery is deferred. | |
14721 | ||
14722 | If the transport does not specify a home directory, and | |
14723 | \transport@_home@_directory\ is not set for the router, the home directory for | |
14724 | the tranport is taken from the password data if \check@_local@_user\ is set for | |
14725 | the router. Otherwise it is taken from \router@_home@_directory\ if that option | |
4964e932 | 14726 | is set; if not, no home directory is set for the transport. |
495ae4b0 PH |
14727 | |
14728 | See chapter ~~CHAPenvironment for further details of the local delivery | |
14729 | environment. | |
14730 | ||
14731 | ||
14732 | ||
14733 | .conf unseen boolean$**$ false | |
14734 | .index router||carrying on after success | |
14735 | The result of string expansion for this option must be a valid boolean value, | |
14736 | that is, one of the strings `yes', `no', `true', or `false'. Any other result | |
14737 | causes an error, and delivery is deferred. If the expansion is forced to fail, | |
14738 | the default value for the option (false) is used. Other failures cause delivery | |
14739 | to be deferred. | |
14740 | ||
14741 | When this option is set true, routing does not cease if the router accepts the | |
14742 | address. Instead, a copy of the incoming address is passed to the next router, | |
4964e932 PH |
14743 | overriding a false setting of \more\. There is little point in setting \more\ |
14744 | false if \unseen\ is always true, but it may be useful in cases when the value | |
495ae4b0 PH |
14745 | of \unseen\ contains expansion items (and therefore, presumably, is sometimes |
14746 | true and sometimes false). | |
14747 | ||
14748 | The \unseen\ option can be used to cause | |
14749 | .index copy of message (\unseen\ option) | |
14750 | copies of messages to be delivered to some other destination, while also | |
4964e932 PH |
14751 | carrying out a normal delivery. In effect, the current address is made into a |
14752 | `parent' that has two children -- one that is delivered as specified by this | |
495ae4b0 PH |
14753 | router, and a clone that goes on to be routed further. |
14754 | ||
14755 | Header lines added to the address (or specified for removal) by this router or | |
14756 | by previous routers affect the `unseen' copy of the message only. The clone | |
4964e932 | 14757 | that continues to be processed by further routers starts with no added headers |
495ae4b0 PH |
14758 | and none specified for removal. |
14759 | ||
14760 | However, any data that was set by the \address@_data\ option in the current or | |
14761 | previous routers is passed on. Setting this option has a similar effect to the | |
14762 | \unseen\ command qualifier in filter files. | |
14763 | ||
14764 | ||
14765 | .conf user string$**$ "see below" | |
14766 | .index uid (user id)||local delivery | |
14767 | .index local transports||uid and gid | |
14768 | .index transport||local | |
14769 | .index router||user for filter processing | |
14770 | .index filter||user for processing | |
14771 | When a router queues an address for a transport, and the transport does not | |
14772 | specify a user, the user given here is used when running the delivery process. | |
4964e932 | 14773 | The user may be specified numerically or by name. If expansion fails, the |
495ae4b0 PH |
14774 | error is logged and delivery is deferred. |
14775 | This user is also used by the \%redirect%\ router when running a filter file. | |
14776 | The default is unset, except when \check@_local@_user\ is set. In this case, | |
14777 | the default is taken from the password information. If the user is specified as | |
14778 | a name, and \group\ is not set, the group associated with the user is used. See | |
14779 | also \initgroups\ and \group\ and the discussion in chapter ~~CHAPenvironment. | |
14780 | ||
14781 | ||
14782 | .conf verify "boolean (precondition)" true | |
14783 | Setting this option has the effect of setting \verify@_sender\ and | |
14784 | \verify@_recipient\ to the same value. | |
14785 | ||
14786 | .conf verify@_only "boolean (precondition)" false | |
14787 | .index \\EXPN\\||with \verify@_only\ | |
14788 | .index \-bv-\ option | |
14789 | .index router||used only when verifying | |
14790 | If this option is set, the router is used only when verifying an address or | |
14791 | testing with the \-bv-\ option, not when actually doing a delivery, testing | |
14792 | with the \-bt-\ option, or running the SMTP \\EXPN\\ command. It can be further | |
14793 | restricted to verifying only senders or recipients by means of \verify@_sender\ | |
14794 | and \verify@_recipient\. | |
14795 | ||
14796 | \**Warning**\: When the router is being run to verify addresses for an incoming | |
4964e932 PH |
14797 | SMTP message, Exim is not running as root, but under its own uid. If the router |
14798 | accesses any files, you need to make sure that they are accessible to the Exim | |
495ae4b0 PH |
14799 | user or group. |
14800 | ||
14801 | .conf verify@_recipient "boolean (precondition)" true | |
14802 | If this option is false, the router is skipped when verifying recipient | |
14803 | addresses | |
14804 | or testing recipient verification using \-bv-\. | |
4964e932 | 14805 | See section ~~SECTrouprecon for a list of the order in which preconditions |
495ae4b0 PH |
14806 | are evaluated. |
14807 | ||
14808 | .conf verify@_sender "boolean (precondition)" true | |
14809 | If this option is false, the router is skipped when verifying sender addresses | |
14810 | or testing sender verification using \-bvs-\. | |
4964e932 | 14811 | See section ~~SECTrouprecon for a list of the order in which preconditions |
495ae4b0 PH |
14812 | are evaluated. |
14813 | ||
14814 | .endconf | |
14815 | ||
14816 | ||
14817 | ||
14818 | ||
14819 | ||
14820 | . | |
14821 | . | |
14822 | . | |
14823 | . | |
14824 | . ============================================================================ | |
14825 | .chapter The accept router | |
14826 | .set runningfoot "accept router" | |
14827 | .index \%accept%\ router | |
14828 | .index routers||\%accept%\ | |
14829 | The \%accept%\ router has no private options of its own. Unless it is being used | |
14830 | purely for verification (see \verify@_only\) a transport is required to be | |
14831 | defined by the generic \transport\ option. If the preconditions that are | |
14832 | specified by generic options are met, the router accepts the address and queues | |
14833 | it for the given transport. The most common use of this router is for setting | |
14834 | up deliveries to local mailboxes. For example: | |
14835 | .display asis | |
14836 | localusers: | |
14837 | driver = accept | |
14838 | domains = mydomain.example | |
14839 | check_local_user | |
14840 | transport = local_delivery | |
14841 | .endd | |
14842 | The \domains\ condition in this example checks the domain of the address, and | |
14843 | \check@_local@_user\ checks that the local part is the login of a local user. | |
14844 | When both preconditions are met, the \%accept%\ router runs, and queues the | |
14845 | address for the \%local@_delivery%\ transport. | |
14846 | ||
14847 | ||
14848 | ||
14849 | ||
14850 | ||
14851 | ||
14852 | . | |
14853 | . | |
14854 | . | |
14855 | . | |
14856 | . ============================================================================ | |
14857 | .chapter The dnslookup router | |
14858 | .rset CHAPdnslookup "~~chapter" | |
14859 | .set runningfoot "dnslookup router" | |
14860 | .index \%dnslookup%\ router | |
14861 | .index routers||\%dnslookup%\ | |
d43194df PH |
14862 | The \%dnslookup%\ router looks up the hosts that handle mail for the |
14863 | recipient's domain in the DNS. A transport must always be set for this router, | |
14864 | unless \verify@_only\ is set. | |
495ae4b0 | 14865 | |
4964e932 | 14866 | If SRV support is configured (see \check@_srv\ below), Exim first searches for |
495ae4b0 PH |
14867 | SRV records. If none are found, or if SRV support is not configured, |
14868 | MX records are looked up. If no MX records exist, address records are sought. | |
14869 | However, \mx@_domains\ can be set to disable the direct use of address records. | |
14870 | ||
14871 | MX records of equal priority are sorted by Exim into a random order. Exim then | |
14872 | looks for address records for the host names obtained from MX or SRV records. | |
14873 | When a host has more than one IP address, they are sorted into a random order, | |
14874 | except that IPv6 addresses are always sorted before IPv4 addresses. If all the | |
14875 | IP addresses found are discarded by a setting of the \ignore@_target@_hosts\ | |
14876 | generic option, the router declines. | |
14877 | ||
14878 | Unless they have the highest priority (lowest MX value), MX records that point | |
14879 | to the local host, or to any host name that matches \hosts__treat__as__local\, | |
14880 | are discarded, together with any other MX records of equal or lower priority. | |
495ae4b0 PH |
14881 | |
14882 | .index MX record||pointing to local host | |
14883 | .index local host||MX pointing to | |
14884 | .index \self\ option||in \%dnslookup%\ router | |
14885 | If the host pointed to by the highest priority MX record, or looked up as an | |
14886 | address record, is the local host, or matches \hosts__treat__as__local\, what | |
14887 | happens is controlled by the generic \self\ option. | |
14888 | ||
d43194df PH |
14889 | .em |
14890 | .section Problems with DNS lookups | |
14891 | .rset SECTprowitdnsloo "~~chapter.~~section" | |
14892 | There have been problems with DNS servers when SRV records are looked up. | |
14893 | Some mis-behaving servers return a DNS error or timeout when a non-existent | |
14894 | SRV record is sought. Similar problems have in the past been reported for | |
14895 | MX records. The global \dns@_again@_means@_nonexist\ option can help with this | |
14896 | problem, but it is heavy-handed because it is a global option. | |
14897 | ||
14898 | For this reason, there are two options, \srv@_fail@_domains\ and | |
14899 | \mx@_fail@_domains\, that control what happens when a DNS lookup in a | |
14900 | \%dnslookup%\ router results in a DNS failure or a `try again' response. If an | |
14901 | attempt to look up an SRV or MX record causes one of these results, and the | |
14902 | domain matches the relevant list, Exim behaves as if the DNS had responded `no | |
14903 | such record'. In the case of an SRV lookup, this means that the router proceeds | |
14904 | to look for MX records; in the case of an MX lookup, it proceeds to look for A | |
14905 | or AAAA records, unless the domain matches \mx@_domains\, in which case routing | |
14906 | fails. | |
14907 | .nem | |
14908 | ||
495ae4b0 | 14909 | |
d43194df PH |
14910 | .section Private options for dnslookup |
14911 | The private options for the \%dnslookup%\ router are as follows: | |
14912 | ||
14913 | ||
14914 | .startconf dnslookup | |
495ae4b0 | 14915 | |
495ae4b0 PH |
14916 | .index options||\%dnslookup%\ router |
14917 | .conf check@_secondary@_mx boolean false | |
14918 | .index MX record||checking for secondary | |
14919 | If this option is set, the router declines unless the local host is found in | |
14920 | (and removed from) the list of hosts obtained by MX lookup. This can be used to | |
14921 | process domains for which the local host is a secondary mail exchanger | |
14922 | differently to other domains. The way in which Exim decides whether a host is | |
14923 | the local host is described in section ~~SECTreclocipadd. | |
14924 | ||
495ae4b0 PH |
14925 | .conf check@_srv string$**$ unset |
14926 | .index SRV record||enabling use of | |
d43194df | 14927 | The \%dnslookup%\ router supports the use of SRV records (see RFC 2782) in |
495ae4b0 PH |
14928 | addition to MX and address records. The support is disabled by default. To |
14929 | enable SRV support, set the \check@_srv\ option to the name of the service | |
14930 | required. For example, | |
14931 | .display asis | |
14932 | check_srv = smtp | |
14933 | .endd | |
14934 | looks for SRV records that refer to the normal smtp service. The option is | |
14935 | expanded, so the service name can vary from message to message or address | |
14936 | to address. This might be helpful if SRV records are being used for a | |
14937 | submission service. If the expansion is forced to fail, the \check@_srv\ | |
14938 | option is ignored, and the router proceeds to look for MX records in the | |
14939 | normal way. | |
14940 | ||
14941 | When the expansion succeeds, the router searches first for SRV records for | |
d43194df PH |
14942 | the given service (it assumes TCP protocol). A single SRV record with a |
14943 | host name that consists of just a single dot indicates `no such service for | |
14944 | this domain'; if this is encountered, the router declines. If other kinds of | |
14945 | SRV record are found, they are used to construct a host list for delivery | |
14946 | according to the rules of RFC 2782. MX records are not sought in this case. | |
14947 | ||
14948 | When no SRV records are found, MX records (and address records) are sought in | |
14949 | the traditional way. In other words, SRV records take precedence over MX | |
14950 | records, just as MX records take precedence over address records. Note that | |
14951 | this behaviour is not sanctioned by RFC 2782, though a previous draft RFC | |
14952 | defined it. It is apparently believed that MX records are sufficient for email | |
14953 | and that SRV records should not be used for this purpose. However, SRV records | |
14954 | have an additional `weight' feature which some people might find useful when | |
14955 | trying to split an SMTP load between hosts of different power. | |
14956 | ||
14957 | .em | |
14958 | See section ~~SECTprowitdnsloo above for a discussion of Exim's behaviour when | |
14959 | there is a DNS lookup error. | |
14960 | .nem | |
495ae4b0 PH |
14961 | |
14962 | .conf mx@_domains "domain list$**$" unset | |
14963 | .index MX record||required to exist | |
14964 | .index SRV record||required to exist | |
495ae4b0 PH |
14965 | A domain that matches \mx@_domains\ is required to have either an MX or an SRV |
14966 | record in order to be recognised. (The name of this option could be improved.) | |
495ae4b0 PH |
14967 | For example, if all the mail hosts in \*fict.example*\ are known to have MX |
14968 | records, except for those in \*discworld.fict.example*\, you could use this | |
14969 | setting: | |
14970 | .display asis | |
14971 | mx_domains = ! *.discworld.fict.example : *.fict.example | |
14972 | .endd | |
14973 | This specifies that messages addressed to a domain that matches the list but | |
14974 | has no MX record should be bounced immediately instead of being routed using | |
14975 | the address record. | |
14976 | ||
d43194df PH |
14977 | .em |
14978 | .conf mx@_fail@_domains "domain list$**$" unset | |
14979 | If the DNS lookup for MX records for one of the domains in this list causes a | |
14980 | DNS lookup error, Exim behaves as if no MX records were found. See section | |
14981 | ~~SECTprowitdnsloo for more discussion. | |
14982 | .nem | |
14983 | ||
14984 | ||
495ae4b0 PH |
14985 | .conf qualify@_single boolean true |
14986 | .index DNS||resolver options | |
14987 | .index DNS||qualifying single-component names | |
14988 | When this option is true, the resolver option \\RES@_DEFNAMES\\ is set for DNS | |
14989 | lookups. Typically, but not standardly, this causes the resolver to qualify | |
14990 | single-component names with the default domain. For example, on a machine | |
14991 | called \*dictionary.ref.example*\, the domain \*thesaurus*\ would be changed to | |
14992 | \*thesaurus.ref.example*\ inside the resolver. For details of what your resolver | |
14993 | actually does, consult your man pages for \*resolver*\ and \*resolv.conf*\. | |
14994 | ||
14995 | ||
14996 | .conf rewrite@_headers boolean true | |
14997 | .index rewriting||header lines | |
14998 | .index header lines||rewriting | |
14999 | If the domain name in the address that is being processed is not fully | |
15000 | qualified, it may be expanded to its full form by a DNS lookup. For example, if | |
15001 | an address is specified as \*dormouse@@teaparty*\, the domain might be | |
15002 | expanded to \*teaparty.wonderland.fict.example*\. Domain expansion can also | |
15003 | occur as a result of setting the \widen@_domains\ option. If \rewrite@_headers\ | |
15004 | is true, all occurrences of the abbreviated domain name in any ::Bcc::, ::Cc::, | |
15005 | ::From::, ::Reply-to::, ::Sender::, and ::To:: header lines of the message are | |
15006 | rewritten with the full domain name. | |
15007 | ||
15008 | This option should be turned off only when it is known that no message is | |
15009 | ever going to be sent outside an environment where the abbreviation makes | |
15010 | sense. | |
15011 | ||
15012 | When an MX record is looked up in the DNS and matches a wildcard record, name | |
15013 | servers normally return a record containing the name that has been looked up, | |
15014 | making it impossible to detect whether a wildcard was present or not. However, | |
15015 | some name servers have recently been seen to return the wildcard entry. If the | |
15016 | name returned by a DNS lookup begins with an asterisk, it is not used for | |
15017 | header rewriting. | |
15018 | ||
15019 | .conf same@_domain@_copy@_routing boolean false | |
15020 | .index address||copying routing | |
15021 | Addresses with the same domain are normally routed by the \%dnslookup%\ router | |
15022 | to the same list of hosts. However, this cannot be presumed, because the router | |
15023 | options and preconditions may refer to the local part of the address. By | |
15024 | default, therefore, Exim routes each address in a message independently. DNS | |
15025 | servers run caches, so repeated DNS lookups are not normally expensive, and in | |
15026 | any case, personal messages rarely have more than a few recipients. | |
15027 | ||
15028 | If you are running mailing lists with large numbers of subscribers at the same | |
15029 | domain, and you are using a \%dnslookup%\ router which is independent of the | |
15030 | local part, you can set \same__domain__copy@_routing\ to bypass repeated DNS | |
15031 | lookups for identical domains in one message. In this case, when \%dnslookup%\ | |
15032 | routes an address to a remote transport, any other unrouted addresses in the | |
15033 | message that have the same domain are automatically given the same routing | |
15034 | without processing them independently, | |
15035 | provided the following conditions are met: | |
15036 | .numberpars $. | |
4964e932 | 15037 | No router that processed the address specified \headers@_add\ or |
495ae4b0 PH |
15038 | \headers@_remove\. |
15039 | .nextp | |
4964e932 | 15040 | The router did not change the address in any way, for example, by `widening' |
495ae4b0 PH |
15041 | the domain. |
15042 | .endp | |
15043 | ||
15044 | ||
15045 | .conf search@_parents boolean false | |
15046 | .index DNS||resolver options | |
15047 | When this option is true, the resolver option \\RES@_DNSRCH\\ is set for DNS | |
15048 | lookups. This is different from the \qualify@_single\ option in that it applies | |
15049 | to domains containing dots. Typically, but not standardly, it causes the | |
15050 | resolver to search for the name in the current domain and in parent domains. | |
15051 | For example, on a machine in the \*fict.example*\ domain, if looking up | |
15052 | \*teaparty.wonderland*\ failed, the resolver would try | |
15053 | \*teaparty.wonderland.fict.example*\. For details of what your resolver | |
15054 | actually does, consult your man pages for \*resolver*\ and \*resolv.conf*\. | |
15055 | ||
15056 | Setting this option true can cause problems in domains that have a wildcard MX | |
15057 | record, because any domain that does not have its own MX record matches the | |
15058 | local wildcard. | |
15059 | ||
d43194df PH |
15060 | |
15061 | .em | |
15062 | .conf srv@_fail@_domains "domain list$**$" unset | |
15063 | If the DNS lookup for SRV records for one of the domains in this list causes a | |
15064 | DNS lookup error, Exim behaves as if no SRV records were found. See section | |
15065 | ~~SECTprowitdnsloo for more discussion. | |
15066 | .nem | |
15067 | ||
15068 | ||
495ae4b0 PH |
15069 | .conf widen@_domains "string list" unset |
15070 | .index domain||partial, widening | |
15071 | If a DNS lookup fails and this option is set, each of its strings in turn is | |
15072 | added onto the end of the domain, and the lookup is tried again. For example, | |
15073 | if | |
15074 | .display asis | |
15075 | widen_domains = fict.example:ref.example | |
15076 | .endd | |
15077 | is set and a lookup of \*klingon.dictionary*\ fails, | |
15078 | \*klingon.dictionary.fict.example*\ is looked up, and if this fails, | |
15079 | \*klingon.dictionary.ref.example*\ is tried. Note that the \qualify@_single\ | |
15080 | and \search@_parents\ options can cause some widening to be undertaken inside | |
15081 | the DNS resolver. | |
15082 | ||
15083 | .endconf | |
15084 | ||
495ae4b0 | 15085 | .section Effect of qualify@_single and search@_parents |
4964e932 | 15086 | When a domain from an envelope recipient is changed by the resolver as a result |
495ae4b0 PH |
15087 | of the \qualify@_single\ or \search@_parents\ options, Exim rewrites the |
15088 | corresponding address in the message's header lines unless \rewrite@_headers\ | |
15089 | is set false. Exim then re-routes the address, using the full domain. | |
15090 | ||
15091 | These two options affect only the DNS lookup that takes place inside the router | |
15092 | for the domain of the address that is being routed. They do not affect lookups | |
15093 | such as that implied by | |
15094 | .display asis | |
15095 | domains = @mx_any | |
15096 | .endd | |
15097 | that may happen while processing a router precondition before the router is | |
15098 | entered. No widening ever takes place for these lookups. | |
495ae4b0 PH |
15099 | |
15100 | ||
15101 | ||
15102 | ||
15103 | ||
15104 | ||
15105 | ||
15106 | ||
15107 | ||
15108 | . | |
15109 | . | |
15110 | . | |
15111 | . | |
15112 | . ============================================================================ | |
15113 | .chapter The ipliteral router | |
15114 | .set runningfoot "ipliteral router" | |
15115 | .index \%ipliteral%\ router | |
4964e932 | 15116 | .index domain literal||routing |
495ae4b0 PH |
15117 | .index routers||\%ipliteral%\ |
15118 | This router has no private options. Unless it is being used purely for | |
15119 | verification (see \verify@_only\) a transport is required to be defined by the | |
15120 | generic \transport\ option. The router accepts the address if its domain part | |
15121 | takes the form of an RFC 2822 domain literal, that is, an IP address enclosed | |
15122 | in square brackets. For example, this router handles the address | |
15123 | .display asis | |
15124 | root@[192.168.1.1] | |
15125 | .endd | |
4964e932 | 15126 | by setting up delivery to the host with that IP address. |
495ae4b0 | 15127 | |
4964e932 | 15128 | If the IP address matches something in \ignore@_target@_hosts\, the router |
495ae4b0 | 15129 | declines. |
495ae4b0 PH |
15130 | .index \self\ option||in \%ipliteral%\ router |
15131 | If an IP literal turns out to refer to the local host, the generic \self\ | |
4964e932 | 15132 | option determines what happens. |
495ae4b0 PH |
15133 | |
15134 | The RFCs require support for domain literals; however, their use is | |
15135 | controversial in today's Internet. If you want to use this router, you must | |
15136 | also set the main configuration option \allow@_domain@_literals\. Otherwise, | |
15137 | Exim will not recognize the domain literal syntax in addresses. | |
15138 | ||
15139 | ||
15140 | ||
15141 | . | |
15142 | . | |
15143 | . | |
15144 | . | |
15145 | . ============================================================================ | |
15146 | .chapter The iplookup router | |
15147 | .set runningfoot "iplookup router" | |
15148 | .index \%iplookup%\ router | |
15149 | .index routers||\%iplookup%\ | |
15150 | The \%iplookup%\ router was written to fulfil a specific requirement in | |
d43194df PH |
15151 | Cambridge University (which in fact no longer exists). For this reason, it is |
15152 | not included in the binary of Exim by default. If you want to include it, you | |
15153 | must set | |
495ae4b0 PH |
15154 | .display asis |
15155 | ROUTER_IPLOOKUP=yes | |
15156 | .endd | |
15157 | in your \(Local/Makefile)\ configuration file. | |
15158 | ||
15159 | The \%iplookup%\ router routes an address by sending it over a TCP or UDP | |
15160 | connection to one or more specific hosts. The host can then return the same or | |
15161 | a different address -- in effect rewriting the recipient address in the | |
15162 | message's envelope. The new address is then passed on to subsequent routers. | |
15163 | ||
15164 | ||
15165 | If this process fails, the address can be passed on to | |
15166 | other routers, or delivery can be deferred. | |
15167 | ||
15168 | Background, for those that are interested: We have an Oracle database of all | |
15169 | Cambridge users, and one of the items of data it maintains for each user is | |
15170 | where to send mail addressed to \*user@@cam.ac.uk*\. The MX records for | |
15171 | \*cam.ac.uk*\ point to a central machine that has a large alias list that is | |
15172 | abstracted from the database. Mail from outside is switched by this system, and | |
15173 | originally internal mail was also done this way. However, this resulted in a | |
15174 | fair number of messages travelling from some of our larger systems to the | |
15175 | switch and back again. The Oracle machine now runs a UDP service that can be | |
15176 | called by the \%iplookup%\ router in Exim to find out where \*user@@cam.ac.uk*\ | |
15177 | addresses really have to go; this saves passing through the central switch, and | |
15178 | in many cases saves doing any remote delivery at all. | |
15179 | ||
15180 | Since \%iplookup%\ is just a rewriting router, a transport must not be | |
15181 | specified for it. | |
15182 | ||
d43194df | 15183 | .startconf iplookup |
495ae4b0 PH |
15184 | .index options||\%iplookup%\ router |
15185 | ||
15186 | .conf hosts string unset | |
15187 | This option must be supplied. Its value is a colon-separated list of host | |
4964e932 | 15188 | names. The hosts are looked up using \*gethostbyname()*\ |
495ae4b0 PH |
15189 | (or \*getipnodebyname()*\ when available) |
15190 | and are tried in order until one responds to the query. If none respond, what | |
15191 | happens is controlled by \optional\. | |
15192 | ||
15193 | .conf optional boolean false | |
15194 | If \optional\ is true, if no response is obtained from any host, the address is | |
15195 | passed to the next router, overriding \no@_more\. If \optional\ is false, | |
15196 | delivery to the address is deferred. | |
15197 | ||
15198 | .conf port integer 0 | |
15199 | .index port||\%iplookup%\ router | |
15200 | This option must be supplied. It specifies the port number for the TCP or UDP | |
15201 | call. | |
15202 | ||
15203 | .conf protocol string "udp" | |
15204 | This option can be set to `udp' or `tcp' to specify which of the two protocols | |
15205 | is to be used. | |
15206 | ||
15207 | .conf query string$**$ "$tt{@$local@_part@@@$domain @$local@_part@@@$domain}" | |
15208 | This defines the content of the query that is sent to the remote hosts. The | |
15209 | repetition serves as a way of checking that a response is to the correct query | |
15210 | in the default case (see \response@_pattern\ below). | |
15211 | ||
15212 | .conf reroute string$**$ unset | |
15213 | If this option is not set, the rerouted address is precisely the byte string | |
15214 | returned by the remote host, up to the first white space, if any. If set, the | |
15215 | string is expanded to form the rerouted address. It can include parts matched | |
15216 | in the response by \response@_pattern\ by means of numeric variables such as | |
15217 | \$1$\, \$2$\, etc. The variable \$0$\ refers to the entire input string, | |
15218 | whether or not a pattern is in use. In all cases, the rerouted address must end | |
15219 | up in the form \*local@_part@@domain*\. | |
15220 | ||
15221 | .conf response@_pattern string unset | |
15222 | This option can be set to a regular expression that is applied to the string | |
15223 | returned from the remote host. If the pattern does not match the response, the | |
15224 | router declines. If \response@_pattern\ is not set, no checking of the response | |
15225 | is done, unless the query was defaulted, in which case there is a check that | |
15226 | the text returned after the first white space is the original address. This | |
15227 | checks that the answer that has been received is in response to the correct | |
15228 | question. For example, if the response is just a new domain, the following | |
15229 | could be used: | |
15230 | .display asis | |
15231 | response_pattern = ^([^@]+)$ | |
15232 | reroute = $local_part@$1 | |
15233 | .endd | |
15234 | ||
15235 | .conf timeout time 5s | |
15236 | This specifies the amount of time to wait for a response from the remote | |
15237 | machine. The same timeout is used for the \*connect()*\ function for a TCP | |
15238 | call. It does not apply to UDP. | |
15239 | ||
15240 | .endconf | |
15241 | ||
15242 | ||
15243 | ||
15244 | ||
15245 | . | |
15246 | . | |
15247 | . | |
15248 | . | |
15249 | . ============================================================================ | |
15250 | .chapter The manualroute router | |
15251 | .set runningfoot "manualroute router" | |
15252 | .index \%manualroute%\ router | |
15253 | .index routers||\%manualroute%\ | |
15254 | .index domain||manually routing | |
15255 | The \%manualroute%\ router is so-called because it provides a way of manually | |
15256 | routing an address according to its domain. It is mainly used when you want to | |
15257 | route addresses to remote hosts according to your own rules, bypassing the | |
15258 | normal DNS routing that looks up MX records. However, \%manualroute%\ can also | |
15259 | route to local transports, a facility that may be useful if you want to save | |
15260 | messages for dial-in hosts in local files. | |
15261 | ||
15262 | The \%manualroute%\ router compares a list of domain patterns with the domain it | |
15263 | is trying to route. If there is no match, the router declines. Each pattern has | |
15264 | associated with it a list of hosts and some other optional data, which may | |
15265 | include a transport. The combination of a pattern and its data is called a | |
15266 | `routing rule'. For patterns that do not have an associated transport, the | |
15267 | generic \transport\ option must specify a transport, unless the router is being | |
15268 | used purely for verification (see \verify@_only\). | |
15269 | ||
15270 | In the case of verification, matching the domain pattern is sufficient for the | |
15271 | router to accept the address. When actually routing an address for delivery, | |
15272 | an address that matches a domain pattern is queued for the associated | |
15273 | transport. If the transport is not a local one, a host list must be associated | |
15274 | with the pattern; IP addresses are looked up for the hosts, and these are | |
15275 | passed to the transport along with the mail address. For local transports, a | |
15276 | host list is optional. If it is present, it is passed in \$host$\ as a single | |
15277 | text string. | |
15278 | ||
15279 | The list of routing rules can be provided as an inline string in \route@_list\, | |
15280 | or the data can be obtained by looking up the domain in a file or database by | |
15281 | setting \route@_data\. Only one of these settings may appear in any one | |
15282 | instance of \%manualroute%\. The format of routing rules is described below, | |
15283 | following the list of private options. | |
15284 | ||
15285 | .section Private options for manualroute | |
15286 | .rset SECTprioptman "~~chapter.~~section" | |
15287 | ||
15288 | The private options for the \%manualroute%\ router are as follows: | |
15289 | ||
d43194df | 15290 | .startconf manualroute |
495ae4b0 PH |
15291 | .index options||\%manualroute%\ router |
15292 | ||
15293 | .conf host@_find@_failed string "freeze" | |
15294 | This option controls what happens when \%manualroute%\ tries to find an IP | |
15295 | address for a host, and the host does not exist. The option can be set to one | |
15296 | of | |
15297 | .display asis | |
15298 | decline | |
15299 | defer | |
15300 | fail | |
15301 | freeze | |
15302 | pass | |
15303 | .endd | |
15304 | The default assumes that this state is a serious configuration error. The | |
15305 | difference between `pass' and `decline' is that the former forces the address | |
15306 | to be passed to the next router (or the router defined by \pass@_router\), | |
15307 | .index \more\ option | |
15308 | overriding \no@_more\, whereas the latter passes the address to the next router | |
15309 | only if \more\ is true. | |
15310 | ||
15311 | This option applies only to a definite `does not exist' state; if a host lookup | |
15312 | gets a temporary error, delivery is deferred unless the generic | |
15313 | \pass@_on@_timeout\ option is set. | |
15314 | ||
15315 | .conf hosts@_randomize boolean false | |
15316 | .index randomized host list | |
15317 | .index host||list of, randomized | |
15318 | If this option is set, the order of the items in a host list in a routing rule | |
15319 | is randomized each time the list is used, unless an option in the routing rule | |
15320 | overrides (see below). Randomizing the order of a host list can be used to do | |
15321 | crude load sharing. However, if more than one mail address is routed by the | |
15322 | same router to the same host list, the host lists are considered to be the same | |
15323 | (even though they may be randomized into different orders) for the purpose of | |
15324 | deciding whether to batch the deliveries into a single SMTP transaction. | |
15325 | ||
15326 | When \hosts@_randomize\ is true, a host list may be split | |
15327 | into groups whose order is separately randomized. This makes it possible to | |
15328 | set up MX-like behaviour. The boundaries between groups are indicated by an | |
15329 | item that is just \"+"\ in the host list. For example: | |
15330 | .display asis | |
15331 | route_list = * host1:host2:host3:+:host4:host5 | |
15332 | .endd | |
15333 | The order of the first three hosts and the order of the last two hosts is | |
15334 | randomized for each use, but the first three always end up before the last two. | |
15335 | If \hosts@_randomize\ is not set, a \"+"\ item in the list is ignored. If a | |
15336 | randomized host list is passed to an \%smtp%\ transport that also has | |
15337 | \hosts@_randomize set\, the list is not re-randomized. | |
15338 | ||
15339 | .conf route@_data string$**$ unset | |
15340 | If this option is set, it must expand to yield the data part of a routing rule. | |
15341 | Typically, the expansion string includes a lookup based on the domain. For | |
15342 | example: | |
15343 | .display asis | |
15344 | route_data = ${lookup{$domain}dbm{/etc/routes}} | |
15345 | .endd | |
15346 | If the expansion is forced to fail, or the result is an empty string, the | |
15347 | router declines. Other kinds of expansion failure cause delivery to be | |
15348 | deferred. | |
15349 | ||
15350 | .conf route@_list "string list, semicolon-separated" unset | |
15351 | This string is a list of routing rules, in the form defined below. Note that, | |
15352 | unlike most string lists, the items are separated by semicolons. This is so | |
15353 | that they may contain colon-separated host lists. | |
15354 | ||
15355 | .conf same@_domain@_copy@_routing boolean false | |
15356 | .index address||copying routing | |
15357 | Addresses with the same domain are normally routed by the \%manualroute%\ router | |
15358 | to the same list of hosts. However, this cannot be presumed, because the router | |
15359 | options and preconditions may refer to the local part of the address. By | |
15360 | default, therefore, Exim routes each address in a message independently. DNS | |
15361 | servers run caches, so repeated DNS lookups are not normally expensive, and in | |
15362 | any case, personal messages rarely have more than a few recipients. | |
15363 | ||
15364 | If you are running mailing lists with large numbers of subscribers at the same | |
15365 | domain, and you are using a \%manualroute%\ router which is independent of the | |
15366 | local part, you can set \same@_domain@_copy@_routing\ to bypass repeated DNS | |
15367 | lookups for identical domains in one message. In this case, when \%manualroute%\ | |
15368 | routes an address to a remote transport, any other unrouted addresses in the | |
15369 | message that have the same domain are automatically given the same routing | |
15370 | without processing them independently. However, this is only done if | |
15371 | \headers@_add\ and \headers@_remove\ are unset. | |
15372 | ||
15373 | .endconf | |
15374 | ||
15375 | ||
15376 | .section Routing rules in route@_list | |
15377 | The value of \route@_list\ is a string consisting of a sequence of routing | |
15378 | rules, separated by semicolons. If a semicolon is needed in a rule, it can be | |
15379 | entered as two semicolons. Empty rules are ignored. The format of each rule is | |
15380 | .display | |
15381 | <<domain pattern>> <<list of hosts>> <<options>> | |
15382 | .endd | |
15383 | The following example contains two rules, each with a simple domain pattern and | |
15384 | no options: | |
15385 | .display asis | |
15386 | route_list = \ | |
15387 | dict.ref.example mail-1.ref.example:mail-2.ref.example ; \ | |
15388 | thes.ref.example mail-3.ref.example:mail-4.ref.example | |
15389 | .endd | |
4964e932 | 15390 | The three parts of a rule are separated by white space. The pattern and the |
495ae4b0 PH |
15391 | list of hosts can be enclosed in quotes if necessary, and if they are, the |
15392 | usual quoting rules apply. Each rule in a \route@_list\ must start with a | |
15393 | single domain pattern, which is the only mandatory item in the rule. The | |
15394 | pattern is in the same format as one item in a domain list (see section | |
4964e932 | 15395 | ~~SECTdomainlist), |
495ae4b0 PH |
15396 | except that it may not be the name of an interpolated file. |
15397 | That is, it may be wildcarded, or a regular expression, or a file or database | |
15398 | lookup (with semicolons doubled, because of the use of semicolon as a separator | |
15399 | in a \route@_list\). | |
15400 | ||
15401 | The rules in \route@_list\ are searched in order until one of the patterns | |
15402 | matches the domain that is being routed. The list of hosts and then options are | |
15403 | then used as described below. If there is no match, the router declines. When | |
15404 | \route@_list\ is set, \route@_data\ must not be set. | |
15405 | ||
15406 | ||
15407 | .section Routing rules in route@_data | |
15408 | The use of \route@_list\ is convenient when there are only a small number of | |
15409 | routing rules. For larger numbers, it is easier to use a file or database to | |
15410 | hold the routing information, and use the \route@_data\ option instead. | |
15411 | The value of \route@_data\ is a list of hosts, followed by (optional) options. | |
15412 | Most commonly, \route@_data\ is set as a string that contains an | |
15413 | expansion lookup. For example, suppose we place two routing rules in a file | |
15414 | like this: | |
15415 | .display asis | |
15416 | dict.ref.example: mail-1.ref.example:mail-2.ref.example | |
15417 | thes.ref.example: mail-3.ref.example:mail-4.ref.example | |
15418 | .endd | |
15419 | This data can be accessed by setting | |
15420 | .display asis | |
15421 | route_data = ${lookup{$domain}lsearch{/the/file/name}} | |
15422 | .endd | |
15423 | Failure of the lookup results in an empty string, causing the router to | |
15424 | decline. However, you do not have to use a lookup in \route@_data\. The only | |
15425 | requirement is that the result of expanding the string is a list of hosts, | |
15426 | possibly followed by options, separated by white space. The list of hosts must | |
15427 | be enclosed in quotes if it contains white space. | |
15428 | ||
15429 | ||
15430 | ||
15431 | .section Format of the list of hosts | |
15432 | A list of hosts, whether obtained via \route@_data\ or \route@_list\, is always | |
15433 | separately expanded before use. If the expansion fails, the router declines. | |
15434 | The result of the expansion must be a colon-separated list of names and/or | |
15435 | IP addresses. IP addresses are not enclosed in brackets. | |
15436 | ||
15437 | If the list of hosts was obtained from a \route@_list\ item, the following | |
15438 | variables are set during its expansion: | |
15439 | .index numerical variables (\$1$\, \$2$\, etc)||in \%manualroute%\ router | |
15440 | .numberpars $. | |
15441 | If the domain was matched against a regular expression, the numeric variables | |
15442 | \$1$\, \$2$\, etc. may be set. | |
15443 | .nextp | |
15444 | \$0$\ is always set to the entire domain. | |
15445 | .nextp | |
15446 | \$1$\ is also set when partial matching is done in a file lookup. | |
15447 | .nextp | |
15448 | .index \$value$\ | |
15449 | If the pattern that matched the domain was a lookup item, the data that was | |
15450 | looked up is available in the expansion variable \$value$\. | |
15451 | .endp | |
15452 | ||
15453 | ||
495ae4b0 | 15454 | .section How the list of hosts is used |
4964e932 | 15455 | When an address is routed to an \%smtp%\ transport by \%manualroute%\, each of |
495ae4b0 PH |
15456 | the hosts is tried, in the order specified, when carrying out the SMTP |
15457 | delivery. However, the order can be changed by setting the \hosts@_randomize\ | |
15458 | option, either on the router (see section ~~SECTprioptman above), or on the | |
15459 | transport. | |
15460 | ||
15461 | Hosts may be listed by name or by IP address. An unadorned name in the list of | |
15462 | hosts is interpreted as a host name. A name that is followed by \"/MX"\ is | |
15463 | interpreted as an indirection to a sublist of hosts obtained by looking up MX | |
15464 | records in the DNS. For example: | |
15465 | .display asis | |
15466 | route_list = * x.y.z:p.q.r/MX:e.f.g | |
15467 | .endd | |
15468 | If the \hosts@_randomize\ option is set, the order of the items in the list is | |
4964e932 PH |
15469 | randomized before any lookups are done. Exim then scans the list; for any name |
15470 | that is not followed by \"/MX"\ it looks up an IP address. If this turns out to | |
495ae4b0 PH |
15471 | be an interface on the local host and the item is not the first in the list, |
15472 | Exim discards it and any subsequent items. If it is the first item, what | |
4964e932 | 15473 | happens is controlled by the |
495ae4b0 PH |
15474 | .index \self\ option||in \%manualroute%\ router |
15475 | \self\ option of the router. | |
15476 | ||
15477 | A name on the list that is followed by \"/MX"\ is replaced with the list of | |
15478 | hosts obtained by looking up MX records for the name. This is always a DNS | |
15479 | lookup; the \bydns\ and \byname\ options (see section ~~SECThowoptused below) | |
15480 | are not relevant here. The order of these hosts is determined by the preference | |
15481 | values in the MX records, according to the usual rules. Because randomizing | |
15482 | happens before the MX lookup, it does not affect the order that is defined by | |
15483 | MX preferences. | |
495ae4b0 PH |
15484 | |
15485 | If the local host is present in the sublist obtained from MX records, but is | |
15486 | not the most preferred host in that list, it and any equally or less | |
15487 | preferred hosts are removed before the sublist is inserted into the main list. | |
15488 | ||
15489 | If the local host is the most preferred host in the MX list, what happens | |
15490 | depends on where in the original list of hosts the \"/MX"\ item appears. If it | |
15491 | is not the first item (that is, there are previous hosts in the main list), | |
15492 | Exim discards this name and any subsequent items in the main list. | |
15493 | ||
15494 | If the MX item is first in the list of hosts, and the local host is the | |
15495 | most preferred host, what happens is controlled by the \self\ option of the | |
15496 | router. | |
15497 | ||
15498 | DNS failures when lookup up the MX records are treated in the same way as DNS | |
15499 | failures when looking up IP addresses: \pass@_on@_timeout\ and | |
15500 | \host@_find@_failed\ are used when relevant. | |
15501 | ||
495ae4b0 PH |
15502 | The generic \ignore@_target@_hosts\ option applies to all hosts in the list, |
15503 | whether obtained from an MX lookup or not. | |
495ae4b0 PH |
15504 | |
15505 | ||
15506 | .section How the options are used | |
15507 | .rset SECThowoptused "~~chapter.~~section" | |
15508 | The options are a sequence of words; in practice no more than three are ever | |
15509 | present. One of the words can be the name of a transport; this overrides the | |
15510 | \transport\ option on the router for this particular routing rule only. The | |
15511 | other words (if present) control randomization of the list of hosts on a | |
15512 | per-rule basis, and how the IP addresses of the hosts are to be found when | |
15513 | routing to a remote transport. These options are as follows: | |
15514 | .numberpars $. | |
4964e932 | 15515 | \randomize\: randomize the order of the hosts in this list, overriding the |
495ae4b0 PH |
15516 | setting of \hosts@_randomize\ for this routing rule only. |
15517 | .nextp | |
15518 | \no@_randomize\: do not randomize the order of the hosts in this list, | |
15519 | overriding the setting of \hosts@_randomize\ for this routing rule only. | |
15520 | .nextp | |
15521 | \byname\: use \*getipnodebyname()*\ (\*gethostbyname()*\ on older systems) to | |
15522 | find IP addresses. This function may ultimately cause a DNS lookup, but it may | |
15523 | also look in \(/etc/hosts)\ or other sources of information. | |
15524 | .nextp | |
15525 | \bydns\: look up address records for the hosts directly in the DNS; fail if | |
4964e932 PH |
15526 | no address records are found. If there is a temporary DNS error (such as a |
15527 | timeout), delivery is deferred. | |
495ae4b0 PH |
15528 | .endp |
15529 | For example: | |
15530 | .display asis | |
15531 | route_list = domain1 host1:host2:host3 randomize bydns;\ | |
15532 | domain2 host4:host5 | |
15533 | .endd | |
15534 | If neither \byname\ nor \bydns\ is given, Exim behaves as follows: First, a DNS | |
15535 | lookup is done. If this yields anything other than \\HOST@_NOT@_FOUND\\, that | |
15536 | result is used. Otherwise, Exim goes on to try a call to \*getipnodebyname()*\ | |
15537 | or \*gethostbyname()*\, and the result of the lookup is the result of that | |
15538 | call. | |
15539 | ||
15540 | \**Warning**\: It has been discovered that on some systems, if a DNS lookup | |
15541 | called via \*getipnodebyname()*\ times out, \\HOST@_NOT@_FOUND\\ is returned | |
15542 | instead of \\TRY@_AGAIN\\. That is why the default action is to try a DNS | |
15543 | lookup first. Only if that gives a definite `no such host' is the local | |
15544 | function called. | |
15545 | ||
15546 | ||
15547 | ||
15548 | If no IP address for a host can be found, what happens is controlled by the | |
15549 | \host@_find@_failed\ option. | |
15550 | ||
15551 | When an address is routed to a local transport, IP addresses are not looked up. | |
15552 | The host list is passed to the transport in the \$host$\ variable. | |
15553 | ||
15554 | ||
15555 | .section Manualroute examples | |
15556 | In some of the examples that follow, the presence of the \remote@_smtp\ | |
15557 | transport, as defined in the default configuration file, is assumed: | |
15558 | ||
15559 | .numberpars $. | |
15560 | .index smart host||example router | |
15561 | The \%manualroute%\ router can be used to forward all external mail to a | |
15562 | \*smart host*\. If you have set up, in the main part of the configuration, a | |
15563 | named domain list that contains your local domains, for example, | |
15564 | .display asis | |
15565 | domainlist local_domains = my.domain.example | |
15566 | .endd | |
15567 | you can arrange for all other domains to be routed to a smart host by making | |
15568 | your first router something like this: | |
15569 | .display asis | |
15570 | smart_route: | |
15571 | driver = manualroute | |
15572 | domains = !+local_domains | |
15573 | transport = remote_smtp | |
15574 | route_list = * smarthost.ref.example | |
15575 | .endd | |
15576 | This causes all non-local addresses to be sent to the single host | |
15577 | \*smarthost.ref.example*\. If a colon-separated list of smart hosts is given, | |
15578 | they are tried in order | |
15579 | (but you can use \hosts@_randomize\ to vary the order each time). | |
15580 | Another way of configuring the same thing is this: | |
15581 | .display asis | |
15582 | smart_route: | |
15583 | driver = manualroute | |
15584 | transport = remote_smtp | |
15585 | route_list = !+local_domains smarthost.ref.example | |
15586 | .endd | |
15587 | There is no difference in behaviour between these two routers as they stand. | |
15588 | However, they behave differently if \no@_more\ is added to them. In the first | |
15589 | example, the router is skipped if the domain does not match the \domains\ | |
15590 | precondition; the following router is always tried. If the router runs, it | |
15591 | always matches the domain and so can never decline. Therefore, \no@_more\ would | |
15592 | have no effect. In the second case, the router is never skipped; it always | |
15593 | runs. However, if it doesn't match the domain, it declines. In this case | |
15594 | \no@_more\ would prevent subsequent routers from running. | |
15595 | ||
15596 | .nextp | |
15597 | .index mail hub example | |
15598 | A \*mail hub*\ is a host which receives mail for a number of domains via MX | |
15599 | records in the DNS and delivers it via its own private routing mechanism. Often | |
15600 | the final destinations are behind a firewall, with the mail hub being the one | |
15601 | machine that can connect to machines both inside and outside the firewall. The | |
15602 | \%manualroute%\ router is usually used on a mail hub to route incoming messages | |
15603 | to the correct hosts. For a small number of domains, the routing can be inline, | |
15604 | using the \route@_list\ option, but for a larger number a file or database | |
15605 | lookup is easier to manage. | |
15606 | ||
15607 | If the domain names are in fact the names of the machines to which the mail is | |
15608 | to be sent by the mail hub, the configuration can be quite simple. For | |
15609 | example, | |
15610 | .display asis | |
15611 | hub_route: | |
15612 | driver = manualroute | |
15613 | transport = remote_smtp | |
15614 | route_list = *.rhodes.tvs.example $domain | |
15615 | .endd | |
15616 | This configuration routes domains that match \"*.rhodes.tvs.example"\ to hosts | |
15617 | whose names are the same as the mail domains. A similar approach can be taken | |
15618 | if the host name can be obtained from the domain name by a string manipulation | |
15619 | that the expansion facilities can handle. Otherwise, a lookup based on the | |
15620 | domain can be used to find the host: | |
15621 | .display asis | |
15622 | through_firewall: | |
15623 | driver = manualroute | |
15624 | transport = remote_smtp | |
15625 | route_data = ${lookup {$domain} cdb {/internal/host/routes}} | |
15626 | .endd | |
15627 | The result of the lookup must be the name or IP address of the host (or | |
15628 | hosts) to which the address is to be routed. If the lookup fails, the route | |
15629 | data is empty, causing the router to decline. The address then passes to the | |
15630 | next router. | |
15631 | ||
15632 | .nextp | |
15633 | .index batched SMTP output example | |
15634 | .index SMTP||batched outgoing, example | |
15635 | You can use \%manualroute%\ to deliver messages to pipes or files in batched | |
15636 | SMTP format for onward transportation by some other means. This is one way of | |
15637 | storing mail for a dial-up host when it is not connected. The route list entry | |
15638 | can be as simple as a single domain name in a configuration like this: | |
15639 | .display asis | |
15640 | save_in_file: | |
15641 | driver = manualroute | |
15642 | transport = batchsmtp_appendfile | |
15643 | route_list = saved.domain.example | |
15644 | .endd | |
15645 | though often a pattern is used to pick up more than one domain. If there are | |
15646 | several domains or groups of domains with different transport requirements, | |
15647 | different transports can be listed in the routing information: | |
15648 | .display asis | |
15649 | save_in_file: | |
15650 | driver = manualroute | |
15651 | route_list = \ | |
15652 | *.saved.domain1.example $domain batch_appendfile; \ | |
15653 | *.saved.domain2.example \ | |
15654 | ${lookup{$domain}dbm{/domain2/hosts}{$value}fail} \ | |
15655 | batch_pipe | |
15656 | .endd | |
15657 | The first of these just passes the domain in the \$host$\ variable, which | |
15658 | doesn't achieve much (since it is also in \$domain$\), but the second does a | |
15659 | file lookup to find a value to pass, causing the router to decline to handle | |
15660 | the address if the lookup fails. | |
15661 | .nextp | |
15662 | .index UUCP||example of router for | |
15663 | Routing mail directly to UUCP software is a specific case of the use of | |
15664 | \%manualroute%\ in a gateway to another mail environment. This is an example of | |
15665 | one way it can be done: | |
15666 | .display asis | |
15667 | # Transport | |
15668 | uucp: | |
15669 | driver = pipe | |
15670 | user = nobody | |
15671 | command = /usr/local/bin/uux -r - \ | |
15672 | ${substr_-5:$host}!rmail ${local_part} | |
15673 | return_fail_output = true | |
15674 | .endd | |
15675 | .display asis | |
15676 | # Router | |
15677 | uucphost: | |
15678 | transport = uucp | |
15679 | driver = manualroute | |
15680 | route_data = \ | |
15681 | ${lookup{$domain}lsearch{/usr/local/exim/uucphosts}} | |
15682 | .endd | |
15683 | The file \(/usr/local/exim/uucphosts)\ contains entries like | |
15684 | .display asis | |
15685 | darksite.ethereal.example: darksite.UUCP | |
15686 | .endd | |
15687 | It can be set up more simply without adding and removing `.UUCP' but this way | |
15688 | makes clear the distinction between the domain name | |
15689 | \*darksite.ethereal.example*\ and the UUCP host name \*darksite*\. | |
15690 | .endp | |
15691 | ||
15692 | ||
15693 | ||
15694 | ||
15695 | ||
15696 | ||
15697 | . | |
15698 | . | |
15699 | . | |
15700 | . | |
15701 | . ============================================================================ | |
15702 | .chapter The queryprogram router | |
15703 | .set runningfoot "queryprogram router" | |
15704 | .rset CHAPdriverlast "~~chapter" | |
15705 | .index \%queryprogram%\ router | |
15706 | .index routers||\%queryprogram%\ | |
15707 | .index routing||by external program | |
15708 | The \%queryprogram%\ router routes an address by running an external command and | |
15709 | acting on its output. This is an expensive way to route, and is intended mainly | |
15710 | for use in lightly-loaded systems, or for performing experiments. However, if | |
15711 | it is possible to use the precondition options (\domains\, \local@_parts\, | |
15712 | etc) to skip this router for most addresses, it could sensibly be used in | |
15713 | special cases, even on a busy host. There are the following private options: | |
15714 | ||
d43194df | 15715 | .startconf queryprogram |
495ae4b0 PH |
15716 | .index options||\%queryprogram%\ router |
15717 | .conf command string$**$ unset | |
15718 | This option must be set. It specifies the command that is to be run. The | |
15719 | command is split up into a command name and arguments, and then each is | |
15720 | expanded separately (exactly as for a \%pipe%\ transport, described in chapter | |
15721 | ~~CHAPpipetransport). | |
15722 | ||
15723 | .conf command@_group string unset | |
15724 | .index gid (group id)||in \%queryprogram%\ router | |
15725 | This option specifies a gid to be set when running the command. It must be set | |
15726 | if \command@_user\ specifies a numerical uid. If it begins with a digit, it is | |
15727 | interpreted as the numerical value of the gid. Otherwise it is looked up using | |
15728 | \*getgrnam()*\. | |
15729 | ||
15730 | .conf command@_user string unset | |
15731 | .index uid (user id)||for \%queryprogram%\ | |
15732 | This option must be set. It specifies the uid which is set when running the | |
15733 | command. If it begins with a digit it is interpreted as the numerical value of | |
15734 | the uid. Otherwise, it is looked up using \*getpwnam()*\ to obtain a value for | |
15735 | the uid and, if \command@_group\ is not set, a value for the gid also. | |
15736 | ||
15737 | .conf current@_directory string / | |
15738 | This option specifies an absolute path which is made the current directory | |
15739 | before running the command. | |
15740 | ||
15741 | .conf timeout time 1h | |
15742 | If the command does not complete within the timeout period, its process group | |
15743 | is killed and the message is frozen. A value of zero time specifies no | |
15744 | timeout. | |
15745 | ||
15746 | .endconf | |
15747 | ||
15748 | The standard output of the command is connected to a pipe, which is read when | |
15749 | the command terminates. It should consist of a single line of output, | |
d43194df PH |
15750 | containing up to five fields, separated by white space. |
15751 | .em | |
15752 | The maximum length of the line is 1023 characters. Longer lines are silently | |
15753 | truncated. | |
15754 | .nem | |
15755 | The first field is one of the following words (case-insensitive): | |
495ae4b0 PH |
15756 | .numberpars $. |
15757 | \*Accept*\: routing succeeded; the remaining fields specify what to do (see | |
15758 | below). | |
15759 | .nextp | |
15760 | \*Decline*\: the router declines; pass the address to the next router, unless | |
15761 | \no@_more\ is set. | |
15762 | .nextp | |
15763 | \*Fail*\: routing failed; do not pass the address to any more routers. Any | |
15764 | subsequent text on the line is an error message. If the router is run as part | |
15765 | of address verification during an incoming SMTP message, the message is | |
15766 | included in the SMTP response. | |
15767 | .nextp | |
15768 | \*Defer*\: routing could not be completed at this time; try again later. Any | |
15769 | subsequent text on the line is an error message which is logged. It is not | |
15770 | included in any SMTP response. | |
15771 | .nextp | |
15772 | \*Freeze*\: the same as \*defer*\, except that the message is frozen. | |
15773 | .nextp | |
15774 | \*Pass*\: pass the address to the next router (or the router specified by | |
15775 | \pass@_router\), overriding \no@_more\. | |
15776 | .nextp | |
15777 | \*Redirect*\: the message is redirected. The remainder of the line is a list of | |
15778 | new addresses, which are routed independently, starting with the first router, | |
15779 | or the router specified by \redirect@_router\, if set. | |
15780 | .endp | |
15781 | When the first word is \*accept*\, the remainder of the line consists of a | |
15782 | number of keyed data values, as follows (split into two lines here, to fit on | |
15783 | the page): | |
15784 | .display | |
15785 | ACCEPT TRANSPORT=<<transport>> HOSTS=<<list of hosts>> | |
15786 | LOOKUP=byname|bydns DATA=<<text>> | |
15787 | .endd | |
15788 | The data items can be given in any order, and all are optional. If no transport | |
15789 | is included, the transport specified by the generic \transport\ option is used. | |
15790 | The list of hosts and the lookup type are needed only if the transport is an | |
15791 | \%smtp%\ transport that does not itself supply a list of hosts. | |
15792 | ||
4964e932 | 15793 | The format of the list of hosts is the same as for the \%manualroute%\ router. |
495ae4b0 PH |
15794 | As well as host names and IP addresses, it may contain names followed by |
15795 | \"/MX"\ to specify sublists of hosts that are obtained by looking up MX | |
15796 | records. | |
15797 | ||
4964e932 | 15798 | If the lookup type is not specified, Exim behaves as follows when trying to |
495ae4b0 PH |
15799 | find an IP address for each host: First, a DNS lookup is done. If this yields |
15800 | anything other than \\HOST@_NOT@_FOUND\\, that result is used. Otherwise, Exim | |
15801 | goes on to try a call to \*getipnodebyname()*\ or \*gethostbyname()*\, and the | |
15802 | result of the lookup is the result of that call. | |
15803 | ||
15804 | If the DATA field is set, its value is placed in the \$address@_data$\ | |
15805 | variable. For example, this return line | |
15806 | .display asis | |
15807 | accept hosts=x1.y.example:x2.y.example data="rule1" | |
15808 | .endd | |
d43194df PH |
15809 | routes the address to the default transport, passing a list of two hosts. When |
15810 | the transport runs, the string `rule1' is in \$address@_data$\. | |
495ae4b0 PH |
15811 | |
15812 | ||
15813 | ||
15814 | . | |
15815 | . | |
15816 | . | |
15817 | . | |
15818 | . ============================================================================ | |
15819 | .chapter The redirect router | |
15820 | .set runningfoot "redirect router" | |
15821 | .rset CHAPredirect "~~chapter" | |
15822 | .index \%redirect%\ router | |
15823 | .index routers||\%redirect%\ | |
15824 | .index alias file||in a \%redirect%\ router | |
15825 | .index address redirection||\%redirect%\ router | |
15826 | The \%redirect%\ router handles several kinds of address redirection. Its most | |
15827 | common uses are for resolving local part aliases from a central alias file | |
15828 | (usually called \(/etc/aliases)\) and for handling users' personal \(.forward)\ | |
15829 | files, but it has many other potential uses. The incoming address can be | |
15830 | redirected in several different ways: | |
15831 | .numberpars $. | |
15832 | It can be replaced by one or more new addresses which are themselves routed | |
15833 | independently. | |
15834 | .nextp | |
15835 | It can be routed to be delivered to a given file or directory. | |
15836 | .nextp | |
15837 | It can be routed to be delivered to a specified pipe command. | |
15838 | .nextp | |
15839 | It can cause an automatic reply to be generated. | |
15840 | .nextp | |
15841 | It can be forced to fail, with a custom error message. | |
15842 | .nextp | |
15843 | It can be temporarily deferred. | |
15844 | .nextp | |
15845 | It can be discarded. | |
15846 | .endp | |
15847 | The generic \transport\ option must not be set for \%redirect%\ routers. | |
15848 | However, there are some private options which define transports for delivery to | |
15849 | files and pipes, and for generating autoreplies. See the \file@_transport\, | |
15850 | \pipe@_transport\ and \reply@_transport\ descriptions below. | |
15851 | ||
15852 | ||
15853 | .section Redirection data | |
15854 | The router operates by interpreting a text string which it obtains either by | |
15855 | expanding the contents of the \data\ option, or by reading the entire contents | |
15856 | of a file whose name is given in the \file\ option. These two options are | |
15857 | mutually exclusive. The first is commonly used for handling system aliases, in | |
15858 | a configuration like this: | |
15859 | .display asis | |
15860 | system_aliases: | |
15861 | driver = redirect | |
15862 | data = ${lookup{$local_part}lsearch{/etc/aliases}} | |
15863 | .endd | |
4964e932 | 15864 | If the lookup fails, the expanded string in this example is empty. When the |
495ae4b0 PH |
15865 | expansion of \data\ results in an empty string, the router declines. A forced |
15866 | expansion failure also causes the router to decline; other expansion failures | |
15867 | cause delivery to be deferred. | |
495ae4b0 PH |
15868 | |
15869 | A configuration using \file\ is commonly used for handling users' \(.forward)\ | |
15870 | files, like this: | |
15871 | .display asis | |
15872 | userforward: | |
15873 | driver = redirect | |
15874 | check_local_user | |
15875 | file = $home/.forward | |
15876 | no_verify | |
15877 | .endd | |
15878 | If the file does not exist, or causes no action to be taken (for example, it is | |
15879 | empty or consists only of comments), the router declines. \**Warning**\: This | |
15880 | is not the case when the file contains syntactically valid items that happen to | |
15881 | yield empty addresses, for example, items containing only RFC 2822 address | |
15882 | comments. | |
15883 | ||
15884 | ||
15885 | .section Forward files and address verification | |
15886 | .index address redirection||while verifying | |
15887 | It is usual to set \no@_verify\ on \%redirect%\ routers which handle users' | |
15888 | \(.forward)\ files, as in the example above. There are two reasons for this: | |
15889 | .numberpars $. | |
15890 | When Exim is receiving an incoming SMTP message from a remote host, it is | |
4964e932 PH |
15891 | running under the Exim uid, not as root. |
15892 | No additional groups are set up, even if the Exim uid is a member of other | |
495ae4b0 PH |
15893 | groups (that is, the \*initgroups()*\ function is not run). |
15894 | Exim is unable to change uid to read the file as the user, and it may not be | |
15895 | able to read it as the Exim user. So in practice the router may not be able to | |
15896 | operate. | |
15897 | .nextp | |
15898 | However, even when the router can operate, the existence of a \(.forward)\ file | |
15899 | is unimportant when verifying an address. What should be checked is whether the | |
15900 | local part is a valid user name or not. Cutting out the redirection processing | |
15901 | saves some resources. | |
15902 | .endp | |
15903 | ||
15904 | ||
15905 | ||
15906 | ||
15907 | .section Interpreting redirection data | |
15908 | .index Sieve filter||specifying in redirection data | |
15909 | .index filter||specifying in redirection data | |
15910 | The contents of the data string, whether obtained from \data\ or \file\, can be | |
15911 | interpreted in two different ways: | |
15912 | .numberpars $. | |
15913 | If the \allow@_filter\ option is set true, and the data begins with the text | |
15914 | `@#Exim filter' or `@#Sieve filter', it is interpreted as a list of | |
15915 | \*filtering*\ instructions in the form of an Exim or Sieve filter file, | |
15916 | respectively. Details of the syntax and semantics of filter files are described | |
15917 | in a separate document entitled \*Exim's interfaces to mail filtering*\; this | |
15918 | document is intended for use by end users. | |
15919 | .nextp | |
15920 | Otherwise, the data must be a comma-separated list of redirection items, as | |
15921 | described in the next section. | |
15922 | .endp | |
4964e932 PH |
15923 | When a message is redirected to a file (a `mail folder'), the file name given |
15924 | in a non-filter redirection list must always be an absolute path. A filter may | |
15925 | generate a relative path -- how this is handled depends on the transport's | |
15926 | configuration. See section ~~SECTfildiropt for a discussion of this issue for | |
495ae4b0 PH |
15927 | the \%appendfile%\ transport. |
15928 | ||
15929 | ||
15930 | .section Items in a non-filter redirection list | |
15931 | .rset SECTitenonfilred "~~chapter.~~section" | |
15932 | .index address redirection||non-filter list items | |
15933 | When the redirection data is not an Exim or Sieve filter, for example, if it | |
15934 | comes from a conventional alias or forward file, it consists of a list of | |
15935 | addresses, file names, pipe commands, or certain special items (see section | |
15936 | ~~SECTspecitredli below). The special items can be individually enabled or | |
15937 | disabled by means of options whose names begin with \allow@_\ or \forbid@_\, | |
15938 | depending on their default values. The items in the list are separated by | |
15939 | commas or newlines. | |
15940 | If a comma is required in an item, the entire item must be enclosed in double | |
15941 | quotes. | |
15942 | ||
15943 | Lines starting with a @# character are comments, and are ignored, and @# may | |
15944 | also appear following a comma, in which case everything between the @# and the | |
15945 | next newline character is ignored. | |
15946 | ||
15947 | If an item is entirely enclosed in double quotes, these are removed. Otherwise | |
15948 | double quotes are retained because some forms of mail address require their use | |
15949 | (but never to enclose the entire address). In the following description, `item' | |
15950 | refers to what remains after any surrounding double quotes have been removed. | |
15951 | ||
4964e932 PH |
15952 | \**Warning**\: If you use an Exim expansion to construct a redirection address, |
15953 | and the expansion contains a reference to \$local@_part$\, you should make use | |
15954 | of the \quote\ expansion operator, in case the local part contains special | |
15955 | characters. For example, to redirect all mail for the domain | |
15956 | \*obsolete.example*\, retaining the existing local part, you could use this | |
495ae4b0 PH |
15957 | setting: |
15958 | .display asis | |
15959 | data = ${quote:$local_part}@newdomain.example | |
15960 | .endd | |
15961 | ||
15962 | ||
15963 | .section Redirecting to a local mailbox | |
15964 | .rset SECTredlocmai "~~chapter.~~section" | |
15965 | .index routing||loops in | |
15966 | .index loop||while routing, avoidance of | |
15967 | .index address redirection||to local mailbox | |
15968 | A redirection item may safely be the same as the address currently under | |
15969 | consideration. This does not cause a routing loop, because a router is | |
15970 | automatically skipped if any ancestor of the address that is being processed | |
4964e932 | 15971 | is the same as the current address and was processed by the current router. |
495ae4b0 PH |
15972 | Such an address is therefore passed to the following routers, so it is handled |
15973 | as if there were no redirection. When making this loop-avoidance test, the | |
15974 | complete local part, including any prefix or suffix, is used. | |
15975 | ||
15976 | .index address redirection||local part without domain | |
15977 | Specifying the same local part without a domain is a common usage in personal | |
15978 | filter files when the user wants to have messages delivered to the local | |
15979 | mailbox and also forwarded elsewhere. For example, the user whose login is | |
15980 | \*cleo*\ might have a \(.forward)\ file containing this: | |
15981 | .display asis | |
15982 | cleo, cleopatra@egypt.example | |
15983 | .endd | |
15984 | .index backslash in alias file | |
15985 | .index alias file||backslash in | |
15986 | For compatibility with other MTAs, such unqualified local parts may be | |
15987 | preceeded by `@\', but this is not a requirement for loop prevention. However, | |
15988 | it does make a difference if more than one domain is being handled | |
15989 | synonymously. | |
15990 | ||
15991 | If an item begins with `@\' and the rest of the item parses as a valid RFC 2822 | |
15992 | address that does not include a domain, the item is qualified using the domain | |
15993 | of the incoming address. In the absence of a leading `@\', unqualified | |
15994 | addresses are qualified using the value in \qualify@_recipient\, but you can | |
15995 | force the incoming domain to be used by setting \qualify__preserve@_domain\. | |
15996 | ||
4964e932 | 15997 | Care must be taken if there are alias names for local users. |
495ae4b0 PH |
15998 | Consider an MTA handling a single local domain where the system alias file |
15999 | contains: | |
16000 | .display asis | |
16001 | Sam.Reman: spqr | |
16002 | .endd | |
16003 | Now suppose that Sam (whose login id is \*spqr*\) wants to save copies of | |
4964e932 | 16004 | messages in the local mailbox, and also forward copies elsewhere. He creates |
495ae4b0 PH |
16005 | this forward file: |
16006 | .display asis | |
16007 | Sam.Reman, spqr@reme.elsewhere.example | |
16008 | .endd | |
16009 | With these settings, an incoming message addressed to \*Sam.Reman*\ fails. The | |
16010 | \%redirect%\ router for system aliases does not process \*Sam.Reman*\ the | |
4964e932 | 16011 | second time round, because it has previously routed it, |
495ae4b0 PH |
16012 | and the following routers presumably cannot handle the alias. The forward file |
16013 | should really contain | |
16014 | .display asis | |
16015 | spqr, spqr@reme.elsewhere.example | |
16016 | .endd | |
16017 | but because this is such a common error, the \check@_ancestor\ option (see | |
16018 | below) exists to provide a way to get round it. This is normally set on a | |
16019 | \%redirect%\ router that is handling users' \(.forward)\ files. | |
16020 | ||
16021 | ||
16022 | .section Special items in redirection lists | |
16023 | .rset SECTspecitredli "~~chapter.~~section" | |
16024 | In addition to addresses, the following types of item may appear in redirection | |
16025 | lists (that is, in non-filter redirection data): | |
16026 | ||
16027 | .numberpars $. | |
16028 | .index pipe||in redirection list | |
16029 | .index address redirection||to pipe | |
16030 | An item is treated as a pipe command if it begins with `|' and does not parse | |
16031 | as a valid RFC 2822 address that includes a domain. A transport for running the | |
4964e932 | 16032 | command must be specified by the \pipe@_transport\ option. |
495ae4b0 PH |
16033 | Normally, either the router or the transport specifies a user and a group under |
16034 | which to run the delivery. The default is to use the Exim user and group. | |
495ae4b0 PH |
16035 | |
16036 | Single or double quotes can be used for enclosing the individual arguments of | |
16037 | the pipe command; no interpretation of escapes is done for single quotes. If | |
16038 | the command contains a comma character, it is necessary to put the whole item | |
16039 | in double quotes, for example: | |
16040 | .display asis | |
16041 | "|/some/command ready,steady,go" | |
16042 | .endd | |
16043 | since items in redirection lists are terminated by commas. Do not, however, | |
16044 | quote just the command. An item such as | |
16045 | .display asis | |
16046 | |"/some/command ready,steady,go" | |
16047 | .endd | |
16048 | is interpreted as a pipe with a rather strange command name, and no arguments. | |
16049 | .nextp | |
16050 | .index file||in redirection list | |
16051 | .index address redirection||to file | |
16052 | An item is interpreted as a path name if it begins with `/' and does not parse | |
16053 | as a valid RFC 2822 address that includes a domain. For example, | |
16054 | .display asis | |
16055 | /home/world/minbari | |
16056 | .endd | |
16057 | is treated as a file name, but | |
16058 | .display asis | |
16059 | /s=molari/o=babylon/@x400gate.way | |
16060 | .endd | |
16061 | is treated as an address. For a file name, a transport must be specified using | |
16062 | the \file@_transport\ option. However, if the generated path name ends with a | |
16063 | forward slash character, it is interpreted as a directory name rather than a | |
16064 | file name, and \directory@_transport\ is used instead. | |
16065 | ||
495ae4b0 PH |
16066 | Normally, either the router or the transport specifies a user and a group under |
16067 | which to run the delivery. The default is to use the Exim user and group. | |
16068 | .index \(/dev/null)\ | |
16069 | However, if a redirection item is the path \(/dev/null)\, delivery to it is | |
16070 | bypassed at a high level, and the log entry shows `$*$$*$bypassed$*$$*$' | |
16071 | instead of a transport name. In this case the user and group are not used. | |
495ae4b0 PH |
16072 | .nextp |
16073 | .index included address list | |
16074 | .index address redirection||included external list | |
16075 | If an item is of the form | |
16076 | .display | |
16077 | :include:<<path name>> | |
16078 | .endd | |
16079 | a list of further items is taken from the given file and included at that | |
4964e932 PH |
16080 | point. |
16081 | \**Note**\: such a file can not be a filter file; it is just an out-of-line | |
495ae4b0 PH |
16082 | addition to the list. |
16083 | The items in the included list are separated by commas or newlines and are not | |
16084 | subject to expansion. If this is the first item in an alias list in an | |
16085 | \%lsearch%\ file, a colon must be used to terminate the alias name. This | |
16086 | example is incorrect: | |
16087 | .display asis | |
16088 | list1 :include:/opt/lists/list1 | |
16089 | .endd | |
16090 | It must be given as | |
16091 | .display asis | |
16092 | list1: :include:/opt/lists/list1 | |
16093 | .endd | |
16094 | .nextp | |
16095 | .index address redirection||to black hole | |
16096 | Sometimes you want to throw away mail to a particular local part. Making the | |
16097 | \data\ option expand to an empty string does not work, because that causes the | |
16098 | router to decline. Instead, the alias item | |
16099 | .index black hole | |
16100 | .index abandoning mail | |
16101 | .display | |
16102 | :blackhole: | |
16103 | .endd | |
16104 | can be used. It does what its name implies. No delivery is done, and no error | |
16105 | message is generated. This has the same effect as specifing \(/dev/null)\, but | |
16106 | can be independently disabled. | |
16107 | ||
4964e932 PH |
16108 | \**Warning**\: If \":blackhole:"\ appears anywhere in a redirection list, no |
16109 | delivery is done for the original local part, even if other redirection items | |
16110 | are present. If you are generating a multi-item list (for example, by reading a | |
16111 | database) and need the ability to provide a no-op item, you must use | |
495ae4b0 PH |
16112 | \(/dev/null)\. |
16113 | ||
16114 | .nextp | |
16115 | .index delivery||forcing failure | |
16116 | .index delivery||forcing deferral | |
16117 | .index failing delivery||forcing | |
16118 | .index deferred delivery, forcing | |
16119 | .index customizing||failure message | |
16120 | An attempt to deliver a particular address can be deferred or forced to fail by | |
16121 | redirection items of the form | |
16122 | .display | |
16123 | :defer: | |
16124 | $rm{or} | |
16125 | :fail: | |
16126 | .endd | |
16127 | respectively. When a redirection list contains such an item, it applies to the | |
16128 | entire redirection; any other items in the list are ignored (:::blackhole:: is | |
16129 | different). Any text following :::fail:: or :::defer:: is placed in the error | |
16130 | text associated with the failure. For example, an alias file might contain: | |
16131 | .display asis | |
16132 | X.Employee: :fail: Gone away, no forwarding address | |
16133 | .endd | |
16134 | In the case of an address that is being verified from an ACL or as the subject | |
8408f763 PH |
16135 | of a |
16136 | .index \\VRFY\\||error text, display of | |
16137 | \\VRFY\\ command, the text is included in the SMTP error response by | |
16138 | default. | |
16139 | .em | |
16140 | .index \\EXPN\\||error text, display of | |
16141 | The text is not included in the response to an \\EXPN\\ command. | |
16142 | .nem | |
16143 | ||
16144 | In an ACL, an explicitly provided message overrides the default, but the | |
16145 | default message is available in the variable \$acl@_verify@_message$\ and can | |
16146 | therefore be included in a custom message if this is desired. Exim sends a 451 | |
16147 | SMTP code for a :::defer::, and 550 for :::fail::. In non-SMTP cases the text | |
16148 | is included in the error message that Exim generates. | |
495ae4b0 PH |
16149 | |
16150 | ||
16151 | ||
16152 | Normally the error text is the rest of the redirection list -- a comma does not | |
16153 | terminate it -- but a newline does act as a terminator. Newlines are not | |
16154 | normally present in alias expansions. In \%lsearch%\ lookups they are removed as | |
16155 | part of the continuation process, but they may exist in other kinds of lookup | |
16156 | and in :::include:: files. | |
16157 | ||
16158 | During routing for message delivery (as opposed to verification), a redirection | |
16159 | containing :::fail:: causes an immediate failure of the incoming address, | |
16160 | whereas :::defer:: causes the message to remain on the queue so that a | |
16161 | subsequent delivery attempt can happen at a later time. If an address is | |
16162 | deferred for too long, it will ultimately fail, because the normal retry | |
16163 | rules still apply. | |
16164 | .nextp | |
16165 | .index alias file||exception to default | |
16166 | Sometimes it is useful to use a single-key search type with a default (see | |
16167 | chapter ~~CHAPfdlookup) to look up aliases. However, there may be a need for | |
16168 | exceptions to the default. These can be handled by aliasing them to | |
16169 | .display asis | |
16170 | :unknown: | |
16171 | .endd | |
16172 | This differs from :::fail:: in that it causes the \%redirect%\ router to decline, | |
16173 | whereas :::fail:: forces routing to fail. A lookup which results in an empty | |
16174 | redirection list has the same effect. | |
16175 | .endp | |
16176 | ||
16177 | .section Duplicate addresses | |
16178 | .index duplicate addresses | |
16179 | .index address||duplicate, discarding | |
16180 | .index pipe||duplicated | |
16181 | Exim removes duplicate addresses from the list to which it is delivering, so as | |
16182 | to deliver just one copy to each address. This does not apply to deliveries | |
16183 | routed to pipes by different immediate parent addresses, but an indirect | |
16184 | aliasing scheme of the type | |
16185 | .display asis | |
16186 | pipe: |/some/command $local_part | |
16187 | localpart1: pipe | |
16188 | localpart2: pipe | |
16189 | .endd | |
16190 | does not work with a message that is addressed to both local parts, because | |
16191 | when the second is aliased to the intermediate local part `pipe' it gets | |
16192 | discarded as being the same as a previously handled address. However, a scheme | |
16193 | such as | |
16194 | .display asis | |
16195 | localpart1: |/some/command $local_part | |
16196 | localpart2: |/some/command $local_part | |
16197 | .endd | |
16198 | does result in two different pipe deliveries, because the immediate parents of | |
16199 | the pipes are distinct. | |
16200 | ||
16201 | ||
16202 | .section Repeated redirection expansion | |
16203 | .index repeated redirection expansion | |
16204 | .index address redirection||repeated for each delivery attempt | |
16205 | When a message cannot be delivered to all of its recipients immediately, | |
16206 | leading to two or more delivery attempts, redirection expansion is carried out | |
16207 | afresh each time for those addresses whose children were not all previously | |
16208 | delivered. If redirection is being used as a mailing list, this can lead to new | |
16209 | members of the list receiving copies of old messages. The \one@_time\ option | |
16210 | can be used to avoid this. | |
16211 | ||
16212 | .section Errors in redirection lists | |
16213 | .index address redirection||errors | |
16214 | If \skip@_syntax@_errors\ is set, a malformed address that causes a parsing | |
16215 | error is skipped, and an entry is written to the main log. This may be useful | |
16216 | for mailing lists that are automatically managed. Otherwise, if an error is | |
16217 | detected while generating the list of new addresses, the original address is | |
16218 | deferred. See also \syntax@_errors@_to\. | |
16219 | ||
16220 | ||
16221 | .section Private options for the redirect router | |
16222 | ||
16223 | The private options for the \%redirect%\ router are as follows: | |
16224 | ||
d43194df | 16225 | .startconf redirect |
495ae4b0 PH |
16226 | .index options||\%redirect%\ router |
16227 | ||
16228 | .conf allow@_defer boolean false | |
16229 | Setting this option allows the use of :::defer:: in non-filter redirection | |
16230 | data, | |
16231 | or the \defer\ command in an Exim filter file. | |
16232 | ||
16233 | .conf allow@_fail boolean false | |
16234 | .index failing delivery||from filter | |
16235 | If this option is true, the :::fail:: item can be used in a redirection list, | |
16236 | and the \fail\ command may be used in a filter file. | |
16237 | ||
16238 | .conf allow@_filter boolean false | |
16239 | .index filter||enabling use of | |
16240 | .index Sieve filter||enabling use of | |
16241 | Setting this option allows Exim to interpret redirection data that starts with | |
16242 | `@#Exim filter' or `@#Sieve filter' as a set of filtering instructions. There | |
16243 | are some features of Exim filter files that some administrators may wish to | |
d43194df PH |
16244 | lock out; see the \forbid@_filter@_xxx\ options below. |
16245 | .em | |
16246 | It is also possible to lock out Exim filters or Sieve filters while allowing | |
16247 | the other type; see \forbid@_exim@_filter\ and \forbid@_sieve@_filter\. | |
16248 | .nem | |
16249 | ||
16250 | The filter is run using the uid and gid set by the generic \user\ and \group\ | |
16251 | options. These take their defaults from the password data if | |
16252 | \check@_local@_user\ is set, so in the normal case of users' personal filter | |
16253 | files, the filter is run as the relevant user. When \allow@_filter\ is set | |
16254 | true, Exim insists that either \check@_local@_user\ or \user\ is set. | |
495ae4b0 PH |
16255 | |
16256 | ||
16257 | .conf allow@_freeze boolean false | |
16258 | .index freezing messages||allowing in filter | |
16259 | Setting this option allows the use of the \freeze\ command in an Exim filter. | |
16260 | This command is more normally encountered in system filters, and is disabled by | |
16261 | default for redirection filters because it isn't something you usually want to | |
16262 | let ordinary users do. | |
16263 | ||
16264 | ||
16265 | .conf check@_ancestor boolean false | |
16266 | This option is concerned with handling generated addresses that are the same | |
16267 | as some address in the list of redirection ancestors of the current address. | |
16268 | Although it is turned off by default in the code, it is set in the default | |
16269 | configuration file for handling users' \(.forward)\ files. It is recommended | |
16270 | for this use of the \%redirect%\ router. | |
16271 | ||
495ae4b0 PH |
16272 | When \check@_ancestor\ is set, if a generated address (including the domain) is |
16273 | the same as any ancestor of the current address, it is replaced by a copy of | |
16274 | the current address. This helps in the case where local part A is aliased to B, | |
4964e932 | 16275 | and B has a \(.forward)\ file pointing back to A. For example, within a single |
495ae4b0 PH |
16276 | domain, the local part `Joe.Bloggs' is aliased to `jb' and \(@~jb/.forward)\ |
16277 | contains: | |
495ae4b0 PH |
16278 | .display |
16279 | @\Joe.Bloggs, <<other item(s)>> | |
16280 | .endd | |
16281 | Without the \check@_ancestor\ setting, either local part (`jb' or `joe.bloggs') | |
16282 | gets processed once by each router and so ends up as it was originally. If `jb' | |
16283 | is the real mailbox name, mail to `jb' gets delivered (having been turned into | |
16284 | `joe.bloggs' by the \(.forward)\ file and back to `jb' by the alias), but mail | |
16285 | to `joe.bloggs' fails. Setting \check@_ancestor\ on the \%redirect%\ router that | |
16286 | handles the \(.forward)\ file prevents it from turning `jb' back into | |
16287 | `joe.bloggs' when that was the original address. See also the \repeat@_use\ | |
16288 | option below. | |
16289 | ||
16290 | .conf check@_group boolean "see below" | |
16291 | When the \file\ option is used, the group owner of the file is checked only | |
16292 | when this option is set. The permitted groups are those listed in the | |
16293 | \owngroups\ option, together with the user's default group if | |
16294 | \check@_local@_user\ is set. If the file has the wrong group, routing is | |
16295 | deferred. The default setting for this option is true if \check@_local@_user\ | |
16296 | is set and the \modemask\ option permits the group write bit, or if the | |
16297 | \owngroups\ option is set. Otherwise it is false, and no group check occurs. | |
16298 | ||
16299 | ||
16300 | .conf check@_owner boolean "see below" | |
16301 | When the \file\ option is used, the owner of the file is checked only when this | |
16302 | option is set. If \check@_local@_user\ is set, the local user is permitted; | |
16303 | otherwise the owner must be one of those listed in the \owners\ option. The | |
16304 | default value for this option is true if \check@_local@_user\ or \owners\ is | |
16305 | set. Otherwise the default is false, and no owner check occurs. | |
16306 | ||
16307 | .conf data string$**$ unset | |
16308 | This option is mutually exclusive with \file\. One or other of them must be | |
16309 | set, but not both. The contents of \data\ are expanded, and then used as the | |
16310 | list of forwarding items, or as a set of filtering instructions. If the | |
16311 | expansion is forced to fail, or the result is an empty string or a string that | |
16312 | has no effect (consists entirely of comments), the router declines. | |
16313 | ||
16314 | When filtering instructions are used, the string must begin with `@#Exim | |
16315 | filter', and all comments in the string, including this initial one, must be | |
16316 | terminated with newline characters. For example: | |
16317 | .display asis | |
16318 | data = #Exim filter\n\ | |
16319 | if $h_to: contains Exim then save $home/mail/exim endif | |
16320 | .endd | |
16321 | If you are reading the data from a database where newlines cannot be included, | |
16322 | you can use the \$@{sg@}$\ expansion item to turn the escape string of your | |
16323 | choice into a newline. | |
16324 | ||
16325 | .conf directory@_transport string$**$ unset | |
16326 | A \%redirect%\ router sets up a direct delivery to a directory when a path name | |
16327 | ending with a slash is specified as a new `address'. The transport used is | |
16328 | specified by this option, which, after expansion, must be the name of a | |
16329 | configured transport. This should normally be an \%appendfile%\ transport. | |
16330 | ||
16331 | .conf file string$**$ unset | |
16332 | This option specifies the name of a file that contains the redirection data. It | |
16333 | is mutually exclusive with the \data\ option. The string is expanded before | |
16334 | use; if the expansion is forced to fail, the router declines. Other expansion | |
16335 | failures cause delivery to be deferred. The result of a successful expansion | |
16336 | must be an absolute path. The entire file is read and used as the redirection | |
16337 | data. If the data is an empty string or a string that has no effect (consists | |
16338 | entirely of comments), the router declines. | |
16339 | ||
16340 | .index NFS||checking for file existence | |
16341 | If the attempt to open the file fails with a `does not exist' error, Exim | |
16342 | runs a check on the containing directory, | |
16343 | unless \ignore@_enotdir\ is true (see below). | |
16344 | If the directory does not appear to exist, delivery is deferred. This can | |
16345 | happen when users' \(.forward)\ files are in NFS-mounted directories, and there | |
16346 | is a mount problem. If the containing directory does exist, but the file does | |
16347 | not, the router declines. | |
16348 | ||
16349 | .conf file@_transport string$**$ unset | |
16350 | A \%redirect%\ router sets up a direct delivery to a file when a path name not | |
16351 | ending in a slash is specified as a new `address'. The transport used is | |
16352 | specified by this option, which, after expansion, must be the name of a | |
4964e932 | 16353 | configured transport. |
495ae4b0 PH |
16354 | This should normally be an \%appendfile%\ transport. |
16355 | When it is running, the file name is in \$address@_file$\. | |
16356 | ||
16357 | .conf forbid@_blackhole boolean false | |
16358 | If this option is true, the :::blackhole:: item may not appear in a redirection | |
16359 | list. | |
16360 | ||
d43194df PH |
16361 | .em |
16362 | .conf forbid@_exim@_filter boolean false | |
16363 | If this option is set true, only Sieve filters are permitted when | |
16364 | \allow@_filter\ is true. | |
16365 | .nem | |
16366 | ||
16367 | ||
495ae4b0 PH |
16368 | .conf forbid@_file boolean false |
16369 | .index delivery||to file, forbidding | |
16370 | .index Sieve filter||forbidding delivery to a file | |
16371 | .index Sieve filter||`keep' facility, disabling | |
16372 | If this option is true, this router may not generate a new address that | |
16373 | specifies delivery to a local file or directory, either from a filter or from a | |
16374 | conventional forward file. This option is forced to be true if \one@_time\ is | |
16375 | set. It applies to Sieve filters as well as to Exim filters, but if true, it | |
16376 | locks out the Sieve's `keep' facility. | |
16377 | ||
16378 | .conf forbid@_filter@_existstest boolean false | |
16379 | .index filter||locking out certain features | |
16380 | If this option is true, string expansions in Exim filters are not allowed to | |
16381 | make use of the \exists\ condition. | |
16382 | ||
16383 | .conf forbid@_filter@_logwrite boolean false | |
16384 | If this option is true, use of the logging facility in Exim filters is not | |
16385 | permitted. Logging is in any case available only if the filter is being run | |
16386 | under some unprivileged uid (which is normally the case for ordinary users' | |
16387 | \(.forward)\ files). | |
16388 | ||
16389 | .conf forbid@_filter@_lookup boolean false | |
16390 | If this option is true, string expansions in Exim filter files are not allowed | |
16391 | to make use of \lookup\ items. | |
16392 | ||
16393 | .conf forbid@_filter@_perl boolean false | |
16394 | This option is available only if Exim is built with embedded Perl support. If | |
16395 | it is true, string expansions in Exim filter files are not allowed to make use | |
16396 | of the embedded Perl support. | |
16397 | ||
16398 | .conf forbid@_filter@_readfile boolean false | |
16399 | If this option is true, string expansions in Exim filter files are not allowed | |
16400 | to make use of \readfile\ items. | |
16401 | ||
16402 | .conf forbid@_filter@_readsocket boolean false | |
16403 | If this option is true, string expansions in Exim filter files are not allowed | |
16404 | to make use of \readsocket\ items. | |
16405 | ||
16406 | .conf forbid@_filter@_reply boolean false | |
16407 | If this option is true, this router may not generate an automatic reply | |
d43194df PH |
16408 | message. Automatic replies can be generated only from Exim |
16409 | .em | |
16410 | or Sieve filter files, not from traditional forward files. | |
16411 | .nem | |
16412 | This option is forced to be true if \one@_time\ is set. | |
495ae4b0 PH |
16413 | |
16414 | .conf forbid@_filter@_run boolean false | |
16415 | If this option is true, string expansions in Exim filter files are not allowed | |
16416 | to make use of \run\ items. | |
16417 | ||
16418 | .conf forbid@_include boolean false | |
16419 | If this option is true, items of the form | |
16420 | .display | |
16421 | :include:<<path name>> | |
16422 | .endd | |
16423 | are not permitted in non-filter redirection lists. | |
16424 | ||
16425 | .conf forbid@_pipe boolean false | |
16426 | .index delivery||to pipe, forbidding | |
16427 | If this option is true, this router may not generate a new address which | |
16428 | specifies delivery to a pipe, either from an Exim filter or from a conventional | |
16429 | forward file. This option is forced to be true if \one@_time\ is set. | |
16430 | ||
d43194df PH |
16431 | .em |
16432 | .conf forbid@_sieve@_filter boolean false | |
16433 | If this option is set true, only Exim filters are permitted when | |
16434 | \allow@_filter\ is true. | |
16435 | .nem | |
16436 | ||
16437 | ||
495ae4b0 PH |
16438 | .conf hide@_child@_in@_errmsg boolean false |
16439 | .index bounce message||redirection details, suppressing | |
16440 | If this option is true, it prevents Exim from quoting a child address if it | |
16441 | generates a bounce or delay message for it. Instead it says `an address | |
16442 | generated from <<the top level address>>'. Of course, this applies only to | |
16443 | bounces generated locally. If a message is forwarded to another host, $it{its} | |
16444 | bounce may well quote the generated address. | |
16445 | ||
16446 | .conf ignore@_eacces boolean false | |
16447 | .index \\EACCES\\ | |
16448 | If this option is set and an attempt to open a redirection file yields the | |
16449 | \\EACCES\\ error (permission denied), the \%redirect%\ router behaves as if the | |
16450 | file did not exist. | |
16451 | ||
16452 | .conf ignore@_enotdir boolean false | |
16453 | .index \\ENOTDIR\\ | |
16454 | If this option is set and an attempt to open a redirection file yields the | |
16455 | \\ENOTDIR\\ error (something on the path is not a directory), the \%redirect%\ | |
16456 | router behaves as if the file did not exist. | |
16457 | ||
16458 | Setting \ignore@_enotdir\ has another effect as well: When a \%redirect%\ | |
16459 | router that has the \file\ option set discovers that the file does not exist | |
16460 | (the \\ENOENT\\ error), it tries to \*stat()*\ the parent directory, as a check | |
16461 | against unmounted NFS directories. If the parent can not be statted, delivery | |
16462 | is deferred. However, it seems wrong to do this check when \ignore@_enotdir\ is | |
16463 | set, because that option tells Exim to ignore `something on the path is not a | |
16464 | directory' (the \\ENOTDIR\\ error). This is a confusing area, because it seems | |
16465 | that some operating systems give \\ENOENT\\ where others give \\ENOTDIR\\. | |
16466 | ||
16467 | ||
16468 | .conf include@_directory string unset | |
16469 | If this option is set, the path names of any :::include:: items in a redirection | |
16470 | list must start with this directory. | |
16471 | ||
16472 | .conf modemask "octal integer" 022 | |
16473 | This specifies mode bits which must not be set for a file specified by the | |
16474 | \file\ option. If any of the forbidden bits are set, delivery is deferred. | |
16475 | ||
16476 | .conf one@_time boolean false | |
16477 | .index one-time aliasing/forwarding expansion | |
16478 | .index alias file||one-time expansion | |
16479 | .index forward file||one-time expansion | |
16480 | .index mailing lists||one-time expansion | |
16481 | .index address redirection||one-time expansion | |
16482 | Sometimes the fact that Exim re-evaluates aliases and reprocesses redirection | |
16483 | files each time it tries to deliver a message causes a problem | |
4964e932 PH |
16484 | when one or more of the generated addresses fails be delivered at the first |
16485 | attempt. The problem is not one of duplicate delivery -- Exim is clever enough | |
495ae4b0 PH |
16486 | to handle that -- but of what happens when the redirection list changes during |
16487 | the time that the message is on Exim's queue. This is particularly true in the | |
16488 | case of mailing lists, where new subscribers might receive copies of messages | |
16489 | that were posted before they subscribed. | |
16490 | ||
16491 | If \one@_time\ is set and any addresses generated by the router fail to | |
16492 | deliver at the first attempt, the failing addresses are added to the message as | |
16493 | `top level' addresses, and the parent address that generated them is marked | |
16494 | `delivered'. Thus, redirection does not happen again at the next | |
16495 | delivery attempt. | |
16496 | ||
16497 | \**Warning 1**\: This means that any header line addition or removal that is | |
16498 | specified by this router would be lost if delivery did not succeed at the | |
16499 | first attempt. For this reason, the \headers@_add\ and \headers@_remove\ | |
16500 | generic options are not permitted when \one@_time\ is set. | |
16501 | ||
16502 | \**Warning 2**\: To ensure that the router generates only addresses (as opposed | |
16503 | to pipe or file deliveries or auto-replies) \forbid@_file\, \forbid@_pipe\, | |
16504 | and \forbid@_filter@_reply\ are forced to be true when \one@_time\ is set. | |
16505 | ||
16506 | The original top-level address is remembered with each of the generated | |
16507 | addresses, and is output in any log messages. However, any intermediate parent | |
16508 | addresses are not recorded. This makes a difference to the log only if | |
16509 | \all__parents\ log selector is set. It is expected that \one@_time\ will | |
16510 | typically be used for mailing lists, where there is normally just one level of | |
16511 | expansion. | |
16512 | ||
16513 | .conf owners "string list" unset | |
16514 | .index ownership||alias file | |
16515 | .index ownership||forward file | |
16516 | .index alias file||ownership | |
16517 | .index forward file||ownership | |
16518 | This specifies a list of permitted owners for the file specified by \file\. | |
16519 | This list is in addition to the local user when \check@_local@_user\ is set. | |
16520 | See \check@_owner\ above. | |
16521 | ||
16522 | .conf owngroups "string list" unset | |
16523 | This specifies a list of permitted groups for the file specified by \file\. The | |
16524 | list is in addition to the local user's primary group when \check@_local@_user\ | |
16525 | is set. See \check@_group\ above. | |
16526 | ||
495ae4b0 PH |
16527 | .conf pipe@_transport string$**$ unset |
16528 | A \%redirect%\ router sets up a direct delivery to a pipe when a string starting | |
16529 | with a vertical bar character is specified as a new `address'. The transport | |
16530 | used is specified by this option, which, after expansion, must be the name of a | |
4964e932 | 16531 | configured transport. |
495ae4b0 PH |
16532 | This should normally be a \%pipe%\ transport. |
16533 | When the transport is run, the pipe command is in \$address@_pipe$\. | |
16534 | ||
d43194df PH |
16535 | .conf qualify@_domain string$**$ unset |
16536 | If this option is set and an unqualified address (one without a domain) is | |
16537 | generated, it is qualified with the domain specified by expanding this string, | |
16538 | instead of the global setting in \qualify@_recipient\. If the expansion fails, | |
16539 | the router declines. If you want to revert to the default, you can have the | |
16540 | expansion generate \$qualify@_recipient$\. | |
16541 | ||
495ae4b0 PH |
16542 | .conf qualify@_preserve@_domain boolean false |
16543 | .index domain||in redirection, preserving | |
16544 | .index preserving domain in redirection | |
16545 | .index address redirection||domain, preserving | |
16546 | If this is set and an unqualified address (one without a domain) is generated, | |
4964e932 | 16547 | it is qualified with the domain of the |
495ae4b0 PH |
16548 | parent address (the immediately preceding ancestor) instead of the local |
16549 | \qualify@_domain\ or global \qualify@_recipient\ value. | |
495ae4b0 PH |
16550 | |
16551 | .conf repeat@_use boolean true | |
16552 | If this option is set false, the router is skipped for a child address that has | |
16553 | any ancestor that was routed by this router. This test happens before any of | |
16554 | the other preconditions are tested. Exim's default anti-looping rules skip | |
16555 | only when the ancestor is the same as the current address. See also | |
16556 | \check@_ancestor\ above and the generic \redirect@_router\ option. | |
16557 | ||
16558 | .conf reply@_transport string$**$ unset | |
16559 | A \%redirect%\ router sets up an automatic reply when a \mail\ or \vacation\ | |
16560 | command is used in a filter file. The transport used is specified by this | |
16561 | option, which, after expansion, must be the name of a configured transport. | |
4964e932 | 16562 | This should normally be an \%autoreply%\ transport. Other transports are |
495ae4b0 PH |
16563 | unlikely to do anything sensible or useful. |
16564 | ||
16565 | .conf rewrite boolean true | |
16566 | .index address redirection||disabling rewriting | |
16567 | If this option is set false, addresses generated by the router are not | |
16568 | subject to address rewriting. Otherwise, they are treated like new addresses | |
16569 | and are rewritten according to the global rewriting rules. | |
16570 | ||
d43194df PH |
16571 | |
16572 | .em | |
16573 | .conf sieve@_vacation@_directory string$**$ unset | |
16574 | .index Sieve filter||vacation directory | |
16575 | To enable the `vacation' extension for Sieve filters, you must set | |
16576 | \sieve@_vacation@_directory\ to the directory where vacation databases are held | |
16577 | (do not put anything else in that directory), and ensure that the | |
16578 | \reply@_transport\ option refers to an \%autoreply%\ transport. | |
16579 | .nem | |
16580 | ||
16581 | ||
495ae4b0 PH |
16582 | .conf skip@_syntax@_errors boolean false |
16583 | .index forward file||broken | |
16584 | .index address redirection||broken files | |
16585 | .index alias file||broken | |
16586 | .index broken alias or forward files | |
16587 | .index ignoring faulty addresses | |
16588 | .index skipping faulty addresses | |
16589 | .index error||skipping bad syntax | |
16590 | If \skip@_syntax@_errors\ is set, syntactically malformed addresses in | |
16591 | non-filter redirection data are skipped, and each failing address is logged. If | |
16592 | \syntax@_errors@_to\ is set, a message is sent to the address it defines, | |
16593 | giving details of the failures. If \syntax@_errors@_text\ is set, its contents | |
16594 | are expanded and placed at the head of the error message generated by | |
16595 | \syntax@_errors@_to\. Usually it is appropriate to set \syntax@_errors@_to\ to | |
16596 | be the same address as the generic \errors@_to\ option. The | |
16597 | \skip@_syntax@_errors\ option is often used when handling mailing lists. | |
16598 | ||
16599 | If all the addresses in a redirection list are skipped because of syntax | |
16600 | errors, the router declines to handle the original address, and it is passed to | |
16601 | the following routers. | |
16602 | ||
16603 | If \skip@_syntax@_errors\ is set when an Exim filter is interpreted, any syntax | |
16604 | error in the filter causes filtering to be abandoned without any action being | |
16605 | taken. The incident is logged, and the router declines to handle the address, | |
16606 | so it is passed to the following routers. | |
16607 | ||
16608 | .index Sieve filter||syntax errors in | |
d43194df PH |
16609 | .em |
16610 | Syntax errors in a Sieve filter file cause the `keep' action to | |
16611 | occur. This action is specified by RFC 3028. | |
16612 | .nem | |
16613 | The values of \skip@_syntax@_errors\, \syntax@_errors@_to\, and | |
495ae4b0 PH |
16614 | \syntax@_errors@_text\ are not used. |
16615 | ||
16616 | \skip@_syntax@_errors\ can be used to specify that errors in users' forward | |
16617 | lists or filter files should not prevent delivery. The \syntax@_errors@_to\ | |
16618 | option, used with an address that does not get redirected, can be used to | |
16619 | notify users of these errors, by means of a router like this: | |
16620 | .display flow asis | |
16621 | userforward: | |
16622 | driver = redirect | |
16623 | allow_filter | |
16624 | check_local_user | |
16625 | file = $home/.forward | |
16626 | file_transport = address_file | |
16627 | pipe_transport = address_pipe | |
16628 | reply_transport = address_reply | |
16629 | no_verify | |
16630 | skip_syntax_errors | |
16631 | syntax_errors_to = real-$local_part@$domain | |
16632 | syntax_errors_text = \ | |
16633 | This is an automatically generated message. An error has\n\ | |
16634 | been found in your .forward file. Details of the error are\n\ | |
16635 | reported below. While this error persists, you will receive\n\ | |
16636 | a copy of this message for every message that is addressed\n\ | |
16637 | to you. If your .forward file is a filter file, or if it is\n\ | |
16638 | a non-filter file containing no valid forwarding addresses,\n\ | |
16639 | a copy of each incoming message will be put in your normal\n\ | |
16640 | mailbox. If a non-filter file contains at least one valid\n\ | |
16641 | forwarding address, forwarding to the valid addresses will\n\ | |
16642 | happen, and those will be the only deliveries that occur. | |
16643 | .endd | |
16644 | You also need a router to ensure that local addresses that are prefixed by | |
16645 | \"real-"\ are recognized, but not forwarded or filtered. For example, you could | |
16646 | put this immediately before the \%userforward%\ router: | |
16647 | .display asis | |
16648 | real_localuser: | |
16649 | driver = accept | |
16650 | check_local_user | |
16651 | local_part_prefix = real- | |
16652 | transport = local_delivery | |
16653 | .endd | |
16654 | ||
16655 | .conf syntax@_errors@_text string$**$ unset | |
16656 | See \skip@_syntax@_errors\ above. | |
16657 | ||
16658 | .conf syntax@_errors@_to string unset | |
16659 | See \skip@_syntax@_errors\ above. | |
16660 | ||
16661 | .endconf | |
16662 | ||
16663 | ||
16664 | ||
16665 | ||
16666 | ||
16667 | . | |
16668 | . | |
16669 | . | |
16670 | . ============================================================================ | |
16671 | .chapter Environment for running local transports | |
16672 | .rset CHAPenvironment "~~chapter" | |
16673 | .set runningfoot "local transport environment" | |
16674 | .index local transports||environment for | |
16675 | .index environment for local transports | |
16676 | .index transport||local, environment for | |
16677 | Local transports handle deliveries to files and pipes. (The \%autoreply%\ | |
16678 | transport can be thought of as similar to a pipe.) Exim always runs transports | |
16679 | in subprocesses, under specified uids and gids. Typical deliveries to local | |
16680 | mailboxes run under the uid and gid of the local user. | |
16681 | ||
16682 | Exim also sets a specific current directory while running the transport; for | |
16683 | some transports a home directory setting is also relevant. The \%pipe%\ | |
d43194df | 16684 | transport is the only one that sets up environment variables; see section |
495ae4b0 PH |
16685 | ~~SECTpipeenv for details. |
16686 | ||
16687 | The values used for the uid, gid, and the directories may come from several | |
16688 | different places. In many cases, the router that handles the address associates | |
16689 | settings with that address as a result of its \check@_local@_user\, \group\, or | |
16690 | \user\ options. However, values may also be given in the transport's own | |
16691 | configuration, and these override anything that comes from the router. | |
16692 | ||
d43194df PH |
16693 | |
16694 | .em | |
16695 | .section Concurrent deliveries | |
16696 | .index concurrent deliveries | |
16697 | .index simultaneous deliveries | |
16698 | If two different messages for the same local recpient arrive more or less | |
16699 | simultaneously, the two delivery processes are likely to run concurrently. When | |
16700 | the \%appendfile%\ transport is used to write to a file, Exim applies locking | |
16701 | rules to stop concurrent processes from writing to the same file at the same | |
16702 | time. | |
16703 | ||
16704 | However, when you use a \%pipe%\ transport, it is up to you to arrange any | |
16705 | locking that is needed. Here is a silly example: | |
16706 | .display asis | |
16707 | my_transport: | |
16708 | driver = pipe | |
16709 | command = /bin/sh -c 'cat >>/some/file' | |
16710 | .endd | |
16711 | This is supposed to write the message at the end of the file. However, if two | |
16712 | messages arrive at the same time, the file will be scrambled. You can use the | |
16713 | \exim@_lock\ utility program (see section ~~SECTmailboxmaint) to lock a file | |
16714 | using the same algorithm that Exim itself uses. | |
16715 | .nem | |
16716 | ||
16717 | ||
495ae4b0 PH |
16718 | .section Uids and gids |
16719 | .rset SECTenvuidgid "~~chapter.~~section" | |
16720 | .index local transports||uid and gid | |
16721 | .index transport||local, uid and gid | |
16722 | All transports have the options \group\ and \user\. If \group\ is set, it | |
16723 | overrides any group that the router set in the address, even if \user\ is not | |
16724 | set for the transport. This makes it possible, for example, to run local mail | |
16725 | delivery under the uid of the recipient (set by the router), but in a special | |
16726 | group (set by the transport). For example: | |
16727 | .display asis | |
16728 | # Routers ... | |
16729 | # User/group are set by check_local_user in this router | |
16730 | local_users: | |
16731 | driver = accept | |
16732 | check_local_user | |
4964e932 | 16733 | transport = group_delivery |
495ae4b0 PH |
16734 | |
16735 | # Transports ... | |
16736 | # This transport overrides the group | |
16737 | group_delivery: | |
16738 | driver = appendfile | |
16739 | file = /var/spool/mail/$local_part | |
16740 | group = mail | |
16741 | .endd | |
16742 | If \user\ is set for a transport, its value overrides what is set in the | |
16743 | address. If \user\ is non-numeric and \group\ is not set, the gid associated | |
16744 | with the user is used. If \user\ is numeric, \group\ must be set. | |
16745 | ||
16746 | .index \initgroups\ option | |
16747 | When the uid is taken from the transport's configuration, the \*initgroups()*\ | |
16748 | function is called for the groups associated with that uid if the \initgroups\ | |
16749 | option is set for the transport. When the uid is not specified by the | |
16750 | transport, but is associated with the address by a router, the option for | |
16751 | calling \*initgroups()*\ is taken from the router configuration. | |
16752 | ||
16753 | .index \%pipe%\ transport||uid for | |
16754 | The \%pipe%\ transport contains the special option \pipe@_as@_creator\. If this | |
16755 | is set and \user\ is not set, the uid of the process that called Exim to | |
16756 | receive the message is used, and if \group\ is not set, the corresponding | |
16757 | original gid is also used. | |
16758 | ||
16759 | ||
16760 | .section Current and home directories | |
16761 | .index current directory for local transport | |
16762 | .index home directory||for local transport | |
16763 | .index transport||local, home directory for | |
16764 | .index transport||local, current directory for | |
16765 | Routers may set current and home directories for local transports by means of | |
16766 | the \transport__current@_directory\ and \transport@_home@_directory\ options. | |
16767 | However, if the transport's \current__directory\ or \home@_directory\ options | |
16768 | are set, they override the router's values. In detail, the home directory | |
16769 | for a local transport is taken from the first of these values that is set: | |
16770 | .numberpars $. | |
16771 | The \home@_directory\ option on the transport; | |
16772 | .nextp | |
16773 | The \transport@_home@_directory\ option on the router; | |
16774 | .nextp | |
16775 | The password data if \check@_local@_user\ is set on the router; | |
16776 | .nextp | |
16777 | The \router@_home@_directory\ option on the router. | |
16778 | .endp | |
16779 | The current directory is taken from the first of these values that is set: | |
16780 | .numberpars $. | |
16781 | The \current@_directory\ option on the transport; | |
16782 | .nextp | |
16783 | The \transport@_current@_directory\ option on the router. | |
16784 | .endp | |
16785 | ||
16786 | If neither the router nor the transport sets a current directory, Exim uses the | |
16787 | value of the home directory, if it is set. Otherwise it sets the current | |
16788 | directory to \(/)\ before running a local transport. | |
16789 | ||
16790 | ||
16791 | .section Expansion variables derived from the address | |
16792 | Normally a local delivery is handling a single address, and in that case the | |
16793 | variables such as \$domain$\ and \$local@_part$\ are set during local | |
16794 | deliveries. However, in some circumstances more than one address may be handled | |
16795 | at once (for example, while writing batch SMTP for onward transmission by some | |
16796 | other means). In this case, the variables associated with the local part are | |
16797 | never set, \$domain$\ is set only if all the addresses have the same | |
16798 | domain, and \$original@_domain$\ is never set. | |
16799 | ||
16800 | ||
16801 | ||
16802 | ||
16803 | ||
16804 | ||
16805 | ||
16806 | . | |
16807 | . | |
16808 | . | |
16809 | . ============================================================================ | |
16810 | .chapter Generic options for transports | |
16811 | .rset CHAPtransportgeneric "~~chapter" | |
16812 | .set runningfoot "generic transport options" | |
16813 | ||
16814 | .index generic options||transport | |
16815 | .index options||generic, for transports | |
16816 | .index transport||generic options for | |
16817 | The following generic options apply to all transports: | |
16818 | ||
d43194df | 16819 | .startconf transports |
495ae4b0 PH |
16820 | .conf body@_only boolean false |
16821 | .index transport||body only | |
16822 | .index message||transporting body only | |
16823 | .index body of message||transporting | |
16824 | If this option is set, the message's headers are not transported. It is | |
16825 | mutually exclusive with \headers@_only\. If it is used with the \%appendfile%\ or | |
16826 | \%pipe%\ transports, the settings of \message@_prefix\ and \message@_suffix\ | |
16827 | should be checked, because this option does not automatically suppress them. | |
16828 | ||
16829 | .conf current@_directory string$**$ unset | |
16830 | .index transport||current directory for | |
16831 | This specifies the current directory that is to be set while running the | |
16832 | transport, overriding any value that may have been set by the router. | |
16833 | If the expansion fails for any reason, including forced failure, an error is | |
16834 | logged, and delivery is deferred. | |
16835 | ||
16836 | .conf disable@_logging boolean false | |
4964e932 PH |
16837 | If this option is set true, nothing is logged for any |
16838 | deliveries by the transport or for any | |
495ae4b0 PH |
16839 | transport errors. You should not set this option unless you really, really know |
16840 | what you are doing. | |
16841 | ||
16842 | .conf debug@_print string$**$ unset | |
16843 | .index testing||variables in drivers | |
16844 | If this option is set and debugging is enabled (see the \-d-\ command line | |
16845 | option), the string is expanded and included in the debugging output when the | |
4964e932 PH |
16846 | transport is run. |
16847 | If expansion of the string fails, the error message is written to the debugging | |
495ae4b0 PH |
16848 | output, and Exim carries on processing. |
16849 | This facility is provided to help with checking out the values of variables and | |
16850 | so on when debugging driver configurations. For example, if a \headers@_add\ | |
16851 | option is not working properly, \debug@_print\ could be used to output the | |
16852 | variables it references. A newline is added to the text if it does not end with | |
16853 | one. | |
16854 | ||
16855 | .conf delivery@_date@_add boolean false | |
16856 | .index ::Delivery-date:: header line | |
16857 | If this option is true, a ::Delivery-date:: header is added to the message. This | |
16858 | gives the actual time the delivery was made. As this is not a standard header, | |
16859 | Exim has a configuration option (\delivery@_date@_remove\) which requests its | |
16860 | removal from incoming messages, so that delivered messages can safely be resent | |
16861 | to other recipients. | |
16862 | ||
16863 | .conf driver string unset | |
16864 | This specifies which of the available transport drivers is to be used. | |
16865 | There is no default, and this option must be set for every transport. | |
16866 | ||
16867 | .conf envelope@_to@_add boolean false | |
16868 | .index ::Envelope-to:: header line | |
16869 | If this option is true, an ::Envelope-to:: header is added to the message. This | |
16870 | gives the original address(es) in the incoming envelope that caused this | |
16871 | delivery to happen. More than one address may be present if the transport is | |
16872 | configured to handle several addresses at once, or if more than one original | |
16873 | address was redirected to the same final address. As this is not a standard | |
16874 | header, Exim has a configuration option (\envelope@_to@_remove\) which requests | |
16875 | its removal from incoming messages, so that delivered messages can safely be | |
16876 | resent to other recipients. | |
16877 | ||
16878 | .conf group string$**$ "Exim group" | |
16879 | .index transport||group, specifying | |
16880 | This option specifies a gid for running the transport process, overriding any | |
16881 | value that the router supplies, and also overriding any value associated with | |
16882 | \user\ (see below). | |
16883 | ||
16884 | .conf headers@_add string$**$ unset | |
16885 | .index header lines||adding in transport | |
16886 | .index transport||header lines, adding | |
d43194df PH |
16887 | .em |
16888 | This option specifies a string of text that is expanded and added to the header | |
16889 | portion of a message as it is transported, as described in section | |
16890 | ~~SECTheadersaddrem. Additional header lines can also be specified by routers. | |
16891 | If the result of the expansion is an empty string, or if the expansion is | |
16892 | forced to fail, no action is taken. Other expansion failures are treated as | |
16893 | errors and cause the delivery to be deferred. | |
16894 | .nem | |
495ae4b0 PH |
16895 | |
16896 | .conf headers@_only boolean false | |
16897 | .index transport||header lines only | |
16898 | .index message||transporting headers only | |
16899 | .index header lines||transporting | |
16900 | If this option is set, the message's body is not transported. It is mutually | |
16901 | exclusive with \body@_only\. If it is used with the \%appendfile%\ or \%pipe%\ | |
16902 | transports, the settings of \message@_prefix\ and \message__suffix\ should be | |
16903 | checked, since this option does not automatically suppress them. | |
16904 | ||
16905 | .conf headers@_remove string$**$ unset | |
16906 | .index header lines||removing | |
16907 | .index transport||header lines, removing | |
d43194df PH |
16908 | .em |
16909 | This option specifies a string that is expanded into a list of header names; | |
16910 | these headers are omitted from the message as it is transported, as described | |
16911 | in section ~~SECTheadersaddrem. Header removal can also be specified by | |
16912 | routers. If the result of the expansion is an empty string, or if the expansion | |
16913 | is forced to fail, no action is taken. Other expansion failures are treated as | |
495ae4b0 | 16914 | errors and cause the delivery to be deferred. |
d43194df | 16915 | .nem |
495ae4b0 PH |
16916 | |
16917 | .conf headers@_rewrite string unset | |
16918 | .index transport||header lines, rewriting | |
16919 | .index rewriting||at transport time | |
16920 | This option allows addresses in header lines to be rewritten at transport time, | |
16921 | that is, as the message is being copied to its destination. The contents of the | |
16922 | option are a colon-separated list of rewriting rules. Each rule is in exactly | |
16923 | the same form as one of the general rewriting rules that are applied when a | |
16924 | message is received. These are described in chapter ~~CHAPrewrite. For example, | |
16925 | .display asis | |
16926 | headers_rewrite = a@b c@d f : \ | |
16927 | x@y w@z | |
16928 | .endd | |
16929 | changes \a@@b\ into \c@@d\ in ::From:: header lines, and \x@@y\ into \w@@z\ in | |
16930 | all address-bearing header lines. The rules are applied to the header lines | |
16931 | just before they are written out at transport time, so they affect only those | |
16932 | copies of the message that pass through the transport. However, only the | |
16933 | message's original header lines, and any that were added by a system filter, | |
16934 | are rewritten. If a router or transport adds header lines, they are | |
16935 | not affected by this option. These rewriting rules are $it{not} applied to the | |
16936 | envelope. You can change the return path using \return@_path\, but you cannot | |
16937 | change envelope recipients at this time. | |
16938 | ||
16939 | .conf home@_directory string$**$ unset | |
16940 | .index transport||home directory for | |
16941 | This option specifies a home directory setting for the transport, overriding | |
16942 | any value that may be set by the router. The home directory is placed in | |
16943 | \$home$\ while expanding the transport's private options. It is also used as | |
16944 | the current directory if no current directory is set by the | |
16945 | \current__directory\ option on the transport or the | |
16946 | \transport__current__directory\ option on the router. | |
16947 | If the expansion fails for any reason, including forced failure, an error is | |
16948 | logged, and delivery is deferred. | |
16949 | ||
16950 | ||
16951 | .index additional groups | |
16952 | .index groups, additional | |
16953 | .index transport||group, additional | |
16954 | .conf initgroups boolean false | |
16955 | If this option is true and the uid for the delivery process is provided by the | |
16956 | transport, the \*initgroups()*\ function is called when running the transport | |
16957 | to ensure that any additional groups associated with the uid are set up. | |
16958 | ||
16959 | .conf message@_size@_limit string$**$ 0 | |
16960 | .index limit||message size per transport | |
16961 | .index size||of message, limit | |
16962 | .index transport||message size, limiting | |
16963 | This option controls the size of messages passed through the transport. It is | |
16964 | expanded before use; the result of the expansion must be a sequence of digits, | |
16965 | optionally followed by K or M. | |
4964e932 | 16966 | If the expansion fails for any reason, including forced failure, or if the |
495ae4b0 PH |
16967 | result is not of the required form, delivery is deferred. |
16968 | If the value is greater than zero and the size of a message exceeds this | |
16969 | limit, the address is failed. If there is any chance that the resulting bounce | |
16970 | message could be routed to the same transport, you should ensure that | |
16971 | \return@_size@_limit\ is less than the transport's \message@_size@_limit\, as | |
16972 | otherwise the bounce message will fail to get delivered. | |
16973 | ||
16974 | ||
16975 | .conf rcpt@_include@_affixes boolean false | |
16976 | .index prefix||for local part, including in envelope | |
16977 | .index suffix||for local part, including in envelope | |
16978 | .index local part||prefix | |
16979 | .index local part||suffix | |
16980 | When this option is false (the default), and an address that has had any | |
16981 | affixes (prefixes or suffixes) removed from the local part is delivered by any | |
16982 | form of SMTP or LMTP, the affixes are not included. For example, if a router | |
16983 | that contains | |
16984 | .display asis | |
16985 | local_part_prefix = *- | |
16986 | .endd | |
16987 | routes the address \*abc-xyz@@some.domain*\ to an SMTP transport, the envelope | |
16988 | is delivered with | |
16989 | .display asis | |
16990 | RCPT TO:<xyz@some.domain> | |
16991 | .endd | |
16992 | If \rcpt@_include@_affixes\ is set true, the whole local part is included in | |
16993 | the \\RCPT\\ command. This option applies to BSMTP deliveries by the | |
16994 | \%appendfile%\ and \%pipe%\ transports as well as to the \%lmtp%\ and \%smtp%\ | |
16995 | transports. | |
16996 | ||
16997 | .conf retry@_use@_local@_part boolean "see below" | |
16998 | .index hints database||retry keys | |
16999 | When a delivery suffers a temporary failure, a retry record is created | |
17000 | in Exim's hints database. For remote deliveries, the key for the retry record | |
17001 | is based on the name and/or IP address of the failing remote host. For local | |
17002 | deliveries, the key is normally the entire address, including both the local | |
17003 | part and the domain. This is suitable for most common cases of local delivery | |
17004 | temporary failure -- for example, exceeding a mailbox quota should delay only | |
17005 | deliveries to that mailbox, not to the whole domain. | |
17006 | ||
17007 | However, in some special cases you may want to treat a temporary local delivery | |
17008 | as a failure associated with the domain, and not with a particular local part. | |
17009 | (For example, if you are storing all mail for some domain in files.) You can do | |
17010 | this by setting \retry@_use@_local@_part\ false. | |
17011 | ||
17012 | For all the local transports, its default value is true. For remote transports, | |
17013 | the default value is false for tidiness, but changing the value has no effect | |
17014 | on a remote transport in the current implementation. | |
17015 | ||
17016 | .conf return@_path string$**$ unset | |
17017 | .index envelope sender | |
17018 | .index transport||return path, changing | |
17019 | .index return path||changing in transport | |
17020 | If this option is set, the string is expanded at transport time and replaces | |
17021 | the existing return path (envelope sender) value in the copy of the message | |
17022 | that is being delivered. An empty return path is permitted. This feature is | |
17023 | designed for remote deliveries, where the value of this option is used in the | |
17024 | SMTP \\MAIL\\ command. If you set \return@_path\ for a local transport, the | |
17025 | only effect is to change the address that is placed in the ::Return-path:: | |
17026 | header line, if one is added to the message (see the next option). | |
17027 | ||
17028 | The expansion can refer to the existing value via \$return@_path$\. This is | |
17029 | either the message's envelope sender, or an address set by the | |
17030 | \errors@_to\ option on a router. If the expansion is forced to fail, no | |
17031 | replacement occurs; if it fails for another reason, delivery is deferred. This | |
17032 | option can be used to support VERP (Variable Envelope Return Paths) -- see | |
17033 | chapter ~~CHAPSMTP. | |
17034 | ||
4964e932 | 17035 | \**Note**\: If a delivery error is detected locally, |
495ae4b0 PH |
17036 | including the case when a remote server rejects a message at SMTP time, |
17037 | the bounce message is not sent to the value of this option, but to the | |
17038 | previously set errors address (which defaults to the incoming sender address). | |
495ae4b0 PH |
17039 | |
17040 | ||
17041 | .conf return@_path@_add boolean false | |
17042 | .index ::Return-path:: header line | |
17043 | If this option is true, a ::Return-path:: header is added to the message. | |
17044 | Although the return path is normally available in the prefix line of BSD | |
17045 | mailboxes, this is commonly not displayed by MUAs, and so the user does not | |
17046 | have easy access to it. | |
17047 | ||
17048 | RFC 2821 states that the ::Return-path:: header is added to a message `when the | |
17049 | delivery SMTP server makes the final delivery'. This implies that this header | |
17050 | should not be present in incoming messages. Exim has a configuration option, | |
17051 | \return@_path@_remove\, which requests removal of this header from incoming | |
17052 | messages, so that delivered messages can safely be resent to other recipients. | |
17053 | ||
17054 | .conf shadow@_condition string$**$ unset | |
17055 | See \shadow@_transport\ below. | |
17056 | ||
17057 | .conf shadow@_transport string unset | |
17058 | .index shadow transport | |
17059 | .index transport||shadow | |
17060 | A local transport may set the \shadow@_transport\ option to the name of another | |
17061 | local transport. Shadow remote transports are not supported. | |
17062 | ||
17063 | Whenever a delivery to the main transport succeeds, and either | |
17064 | \shadow@_condition\ is unset, or its expansion does not result in the empty | |
17065 | string or one of the strings `0' or `no' or `false', the message is also passed | |
17066 | to the shadow transport, with the same delivery address or addresses. | |
4964e932 | 17067 | If expansion fails, no action is taken except that non-forced expansion |
495ae4b0 PH |
17068 | failures cause a log line to be written. |
17069 | ||
17070 | The result of the shadow transport is discarded and does not affect the | |
17071 | subsequent processing of the message. Only a single level of shadowing is | |
17072 | provided; the \shadow@_transport\ option is ignored on any transport when it is | |
17073 | running as a shadow. Options concerned with output from pipes are also ignored. | |
17074 | ||
17075 | The log line for the successful delivery has an item added on the end, of the | |
17076 | form | |
17077 | .display | |
17078 | ST=<<shadow transport name>> | |
17079 | .endd | |
17080 | If the shadow transport did not succeed, the error message is put in | |
17081 | parentheses afterwards. | |
17082 | ||
17083 | Shadow transports can be used for a number of different purposes, including | |
17084 | keeping more detailed log information than Exim normally provides, and | |
17085 | implementing automatic acknowledgement policies based on message headers that | |
17086 | some sites insist on. | |
17087 | ||
17088 | .conf transport@_filter string$**$ unset | |
17089 | .index transport||filter | |
17090 | .index filter||transport filter | |
17091 | This option sets up a filtering (in the Unix shell sense) process for messages | |
17092 | at transport time. It should not be confused with mail filtering as set up by | |
17093 | individual users or via a system filter. | |
17094 | ||
17095 | When the message is about to be written out, the command specified by | |
17096 | \transport@_filter\ is started up in a separate process, and the entire | |
17097 | message, including the header lines, is passed to it on its standard input | |
17098 | (this in fact is done from a third process, to avoid deadlock). | |
17099 | The command must be specified as an absolute path. | |
17100 | ||
d43194df PH |
17101 | .em |
17102 | The lines of the message that are written to the transport filter are | |
17103 | terminated by newline (`@\n'). | |
17104 | .nem | |
495ae4b0 PH |
17105 | The message is passed to the filter before any SMTP-specific processing, such |
17106 | as turning `@\n' into `@\r@\n' and escaping lines beginning with a dot, and | |
17107 | also before any processing implied by the settings of \check@_string\ and | |
17108 | \escape@_string\ in the \%appendfile%\ or \%pipe%\ transports. | |
17109 | ||
d43194df PH |
17110 | .em |
17111 | The standard error for the filter process is set to the same destination as its | |
17112 | standard output; this is read and written to the message's ultimate | |
17113 | destination. | |
17114 | .nem | |
495ae4b0 PH |
17115 | The filter can perform any transformations it likes, but of course should take |
17116 | care not to break RFC 2822 syntax. A demonstration Perl script is provided in | |
17117 | \(util/transport-filter.pl)\; this makes a few arbitrary modifications just to | |
17118 | show the possibilities. Exim does not check the result, except to test for a | |
17119 | final newline when SMTP is in use. All messages transmitted over SMTP must end | |
17120 | with a newline, so Exim supplies one if it is missing. | |
17121 | ||
17122 | .index SMTP||\\SIZE\\ | |
17123 | A problem might arise if the filter increases the size of a message that is | |
17124 | being sent down an SMTP connection. If the receiving SMTP server has indicated | |
17125 | support for the \\SIZE\\ parameter, Exim will have sent the size of the message | |
17126 | at the start of the SMTP session. If what is actually sent is substantially | |
17127 | more, the server might reject the message. This can be worked round by setting | |
17128 | the \size@_addition\ option on the \%smtp%\ transport, either to allow for | |
17129 | additions to the message, or to disable the use of \\SIZE\\ altogether. | |
17130 | ||
d43194df PH |
17131 | The value of the \transport@_filter\ option is the command string for starting |
17132 | the filter, which is run directly from Exim, not under a shell. The string is | |
17133 | parsed by Exim in the same way as a command string for the \%pipe%\ transport: | |
17134 | Exim breaks it up into arguments and then expands each argument separately. The | |
17135 | special argument \$pipe@_addresses$\ is replaced by a number of arguments, one | |
17136 | for each address that applies to this delivery. (This isn't an ideal name for | |
17137 | this feature here, but as it was already implemented for the \%pipe%\ | |
17138 | transport, it seemed sensible not to change it.) | |
495ae4b0 PH |
17139 | |
17140 | .index \$host$\ | |
17141 | .index \$host@_address$\ | |
17142 | The expansion variables \$host$\ and \$host@_address$\ are available when the | |
17143 | transport is a remote one. They contain the name and IP address of the host to | |
17144 | which the message is being sent. For example: | |
17145 | .display asis | |
17146 | transport_filter = /some/directory/transport-filter.pl \ | |
17147 | $host $host_address $sender_address $pipe_addresses | |
17148 | .endd | |
17149 | The filter process is run under the same uid and gid as the normal delivery. | |
17150 | For remote deliveries this is the Exim uid/gid by default. | |
d43194df PH |
17151 | .em |
17152 | The command should normally yield a zero return code. A non-zero code is taken | |
17153 | to mean that the transport filter failed in some way. Delivery of the message | |
17154 | is deferred. It is not possible to cause a message to be bounced from a | |
17155 | transport filter. | |
17156 | .nem | |
495ae4b0 PH |
17157 | |
17158 | If a transport filter is set on an autoreply transport, the original message is | |
17159 | passed through the filter as it is being copied into the newly generated | |
17160 | message, which happens if the \return@_message\ option is set. | |
17161 | ||
17162 | .conf transport@_filter@_timeout time 5m | |
17163 | .index transport||filter, timeout | |
4964e932 PH |
17164 | When Exim is reading the output of a transport filter, it a applies a timeout |
17165 | that can be set by this option. Exceeding the timeout is treated as a | |
495ae4b0 PH |
17166 | temporary delivery failure. |
17167 | ||
17168 | ||
17169 | .conf user string$**$ "Exim user" | |
17170 | .index uid (user id)||local delivery | |
17171 | .index transport||user, specifying | |
17172 | This option specifies the user under whose uid the delivery process is to be | |
17173 | run, overriding any uid that may have been set by the router. If the user is | |
17174 | given as a name, the uid is looked up from the password data, and the | |
17175 | associated group is taken as the value of the gid to be used if the \group\ | |
17176 | option is not set. | |
17177 | ||
495ae4b0 PH |
17178 | For deliveries that use local transports, a user and group are normally |
17179 | specified explicitly or implicitly (for example, as a result of | |
17180 | \check@_local@_user\) by the router or transport. | |
495ae4b0 PH |
17181 | |
17182 | .index hints database||access by remote transport | |
17183 | For remote transports, you should leave this option unset unless you really are | |
17184 | sure you know what you are doing. When a remote transport is running, it needs | |
17185 | to be able to access Exim's hints databases, because each host may have its own | |
17186 | retry data. | |
17187 | ||
17188 | .endconf | |
17189 | ||
17190 | ||
17191 | ||
17192 | ||
17193 | ||
17194 | . | |
17195 | . | |
17196 | . | |
17197 | . ============================================================================ | |
17198 | .chapter Address batching in local transports | |
17199 | .set runningfoot "address batching" | |
17200 | .rset CHAPbatching ~~chapter | |
17201 | .index transport||local, address batching in | |
17202 | The only remote transport (\%smtp%\) is normally configured to handle more than | |
17203 | one address at a time, so that when several addresses are routed to the same | |
17204 | remote host, just one copy of the message is sent. Local transports, however, | |
17205 | normally handle one address at a time. That is, a separate instance of the | |
17206 | transport is run for each address that is routed to the transport. A separate | |
17207 | copy of the message is delivered each time. | |
17208 | ||
17209 | .index batched local delivery | |
17210 | .index \batch@_max\ | |
17211 | .index \batch@_id\ | |
17212 | In special cases, it may be desirable to handle several addresses at once in a | |
17213 | local transport, for example: | |
17214 | .numberpars $. | |
17215 | In an \%appendfile%\ transport, when storing messages in files for later | |
17216 | delivery by some other means, a single copy of the message with multiple | |
17217 | recipients saves space. | |
17218 | .nextp | |
17219 | In an \%lmtp%\ transport, when delivering over `local SMTP' to some process, | |
17220 | a single copy saves time, and is the normal way LMTP is expected to work. | |
17221 | .nextp | |
4964e932 PH |
17222 | In a \%pipe%\ transport, when passing the message |
17223 | to a scanner program or | |
495ae4b0 PH |
17224 | to some other delivery mechanism such as UUCP, multiple recipients may be |
17225 | acceptable. | |
17226 | .endp | |
17227 | The three local transports (\%appendfile%\, \%lmtp%\, and \%pipe%\) all have | |
17228 | the same options for controlling multiple (`batched') deliveries, namely | |
17229 | \batch@_max\ and \batch@_id\. To save repeating the information for each | |
17230 | transport, these options are described here. | |
17231 | ||
17232 | The \batch@_max\ option specifies the maximum number of addresses that can be | |
17233 | delivered together in a single run of the transport. Its default value is one. | |
17234 | When more than one address is routed to a transport that has a \batch@_max\ | |
17235 | value greater than one, the addresses are delivered in a batch (that is, in a | |
17236 | single run of the transport), subject to certain conditions: | |
17237 | .numberpars $. | |
17238 | If any of the transport's options contain a reference to \$local@_part$\, no | |
17239 | batching is possible. | |
17240 | .nextp | |
17241 | If any of the transport's options contain a reference to \$domain$\, only | |
17242 | addresses with the same domain are batched. | |
17243 | .nextp | |
17244 | .index customizing||batching condition | |
17245 | If \batch@_id\ is set, it is expanded for each address, and only those | |
17246 | addresses with the same expanded value are batched. This allows you to specify | |
17247 | customized batching conditions. | |
4964e932 PH |
17248 | Failure of the expansion for any reason, including forced failure, disables |
17249 | batching, but it does not stop the delivery from taking place. | |
495ae4b0 PH |
17250 | .nextp |
17251 | Batched addresses must also have the same errors address (where to send | |
17252 | delivery errors), the same header additions and removals, the same user and | |
17253 | group for the transport, and if a host list is present, the first host must | |
17254 | be the same. | |
17255 | .endp | |
17256 | .index ::Envelope-to:: header line | |
17257 | If the generic \envelope@_to@_add\ option is set for the transport, the | |
17258 | ::Envelope-to:: header that is added to the message contains all the addresses | |
17259 | that are batched together. | |
17260 | ||
17261 | The \%appendfile%\ and \%pipe%\ transports have an option called \use@_bsmtp\, | |
17262 | which causes them to deliver the message in `batched SMTP' format, with the | |
17263 | envelope represented as SMTP commands. The \check@_string\ and \escape@_string\ | |
17264 | options are forced to the values | |
17265 | .display asis | |
17266 | check_string = "." | |
17267 | escape_string = ".." | |
17268 | .endd | |
17269 | when batched SMTP is in use. A full description of the batch SMTP mechanism is | |
17270 | given in section ~~SECTbatchSMTP. The \%lmtp%\ transport does not have a | |
17271 | \use@_bsmtp\ option, because it always delivers using the SMTP protocol. | |
17272 | ||
17273 | .index \%pipe%\ transport||with multiple addresses | |
4964e932 PH |
17274 | If you are not using BSMTP, but are using a \%pipe%\ transport, you can include |
17275 | \$pipe@_addresses$\ as part of the command. This is not a true variable; it is | |
17276 | a bit of magic that causes each of the recipient addresses to be inserted into | |
17277 | the command as a separate argument. This provides a way of accessing all the | |
495ae4b0 PH |
17278 | addresses that are being delivered in the batch. |
17279 | ||
17280 | If you are using a batching \%appendfile%\ transport without \use@_bsmtp\, the | |
17281 | only way to preserve the recipient addresses is to set the \envelope@_to@_add\ | |
4964e932 | 17282 | option. This causes an ::Envelope-to:: header line to be added to the message, |
495ae4b0 PH |
17283 | containing all the recipients. |
17284 | ||
17285 | ||
17286 | ||
17287 | . | |
17288 | . | |
17289 | . | |
17290 | . ============================================================================ | |
17291 | .chapter The appendfile transport | |
17292 | .set runningfoot "appendfile transport" | |
17293 | .rset CHAPappendfile ~~chapter | |
17294 | .index \%appendfile%\ transport | |
17295 | .index transports||\%appendfile%\ | |
17296 | .index directory creation | |
17297 | .index creating directories | |
17298 | The \%appendfile%\ transport delivers a message by appending it to an existing | |
17299 | file, or by creating an entirely new file in a specified directory. Single | |
17300 | files to which messages are appended can be in the traditional Unix mailbox | |
17301 | format, or optionally in the MBX format supported by the Pine MUA and | |
17302 | University of Washington IMAP daemon, $it{inter alia}. When each message is | |
17303 | being delivered as a separate file, `maildir' format can optionally be used to | |
17304 | give added protection against failures that happen part-way through the | |
17305 | delivery. A third form of separate-file delivery known as `mailstore' is also | |
17306 | supported. For all file formats, Exim attempts to create as many levels of | |
17307 | directory as necessary, provided that \create@_directory\ is set. | |
17308 | ||
17309 | The code for the optional formats is not included in the Exim binary by | |
17310 | default. It is necessary to set \\SUPPORT@_MBX\\, \\SUPPORT@_MAILDIR\\ and/or | |
17311 | \\SUPPORT@_MAILSTORE\\ in \(Local/Makefile)\ to have the appropriate code | |
17312 | included. | |
17313 | ||
17314 | .index quota||system | |
17315 | Exim recognises system quota errors, and generates an appropriate message. Exim | |
17316 | also supports its own quota control within the transport, for use when the | |
17317 | system facility is unavailable or cannot be used for some reason. | |
17318 | ||
17319 | If there is an error while appending to a file (for example, quota exceeded or | |
17320 | partition filled), Exim attempts to reset the file's length and last | |
17321 | modification time back to what they were before. If there is an error while | |
17322 | creating an entirely new file, the new file is removed. | |
17323 | ||
17324 | Before appending to a file, a number of security checks are made, and the | |
17325 | file is locked. A detailed description is given below, after the list of | |
17326 | private options. | |
17327 | ||
17328 | \%appendfile%\ is most commonly used for local deliveries to users' mailboxes. | |
17329 | However, it can also be used as a pseudo-remote transport for putting messages | |
17330 | into files for remote delivery by some means other than Exim. `Batch SMTP' | |
4964e932 | 17331 | format is often used in this case (see the \use@_bsmtp\ option). |
495ae4b0 PH |
17332 | |
17333 | ||
17334 | .section The file and directory options | |
17335 | .rset SECTfildiropt "~~chapter.~~section" | |
4964e932 PH |
17336 | The \file\ option specifies a single file, to which the message is appended; |
17337 | the \directory\ option specifies a directory, in which a new file containing | |
495ae4b0 PH |
17338 | the message is created. Only one of these two options can be set, and for |
17339 | normal deliveries to mailboxes, one of them \*must*\ be set. | |
17340 | ||
17341 | However, \%appendfile%\ is also used for delivering messages to files or | |
17342 | directories whose names (or parts of names) are obtained from alias, | |
17343 | forwarding, or filtering operations (for example, a \save\ command in a user's | |
17344 | Exim filter). When such a transport is running, \$local@_part$\ contains the | |
17345 | local part that was aliased or forwarded, and \$address@_file$\ contains the | |
17346 | name (or partial name) of the file or directory generated by the redirection | |
17347 | operation. There are two cases: | |
17348 | .numberpars $. | |
17349 | If neither \file\ nor \directory\ is set, the redirection operation | |
4964e932 PH |
17350 | must specify an absolute path (one that begins with \"/"\). This is the most |
17351 | common case when users with local accounts use filtering to sort mail into | |
495ae4b0 PH |
17352 | different folders. See for example, the \%address@_file%\ transport in the |
17353 | default configuration. If the path ends with a slash, it is assumed to be the | |
4964e932 | 17354 | name of a directory. A delivery to a directory can also be forced by setting |
495ae4b0 PH |
17355 | \maildir@_format\ or \mailstore@_format\. |
17356 | .nextp | |
17357 | If \file\ or \directory\ is set for a delivery from a redirection, it is used | |
17358 | to determine the file or directory name for the delivery. Normally, the | |
4964e932 | 17359 | contents of \$address@_file$\ are used in some way in the string expansion. |
495ae4b0 PH |
17360 | .endp |
17361 | ||
17362 | .index Sieve filter||configuring \%appendfile%\ | |
17363 | .index Sieve filter||relative mailbox path handling | |
17364 | As an example of the second case, consider an environment where users do not | |
17365 | have home directories. They may be permitted to use Exim filter commands of the | |
17366 | form: | |
17367 | .display asis | |
17368 | save folder23 | |
17369 | .endd | |
17370 | or Sieve filter commands of the form: | |
17371 | .display asis | |
4964e932 | 17372 | require "fileinto"; |
495ae4b0 PH |
17373 | fileinto "folder23"; |
17374 | .endd | |
17375 | In this situation, the expansion of \file\ or \directory\ in the transport must | |
4964e932 PH |
17376 | transform the relative path into an appropriate absolute file name. In the case |
17377 | of Sieve filters, the name \*inbox*\ must be handled. It is the name that is | |
17378 | used as a result of a `keep' action in the filter. This example shows one way | |
495ae4b0 PH |
17379 | of handling this requirement: |
17380 | .display asis | |
17381 | file = ${if eq{$address_file}{inbox} \ | |
17382 | {/var/mail/$local_part} \ | |
17383 | {${if eq{${substr_0_1:$address_file}}{/} \ | |
17384 | {$address_file} \ | |
17385 | {$home/mail/$address_file} \ | |
17386 | }} \ | |
17387 | } | |
17388 | .endd | |
4964e932 | 17389 | With this setting of \file\, \*inbox*\ refers to the standard mailbox location, |
495ae4b0 PH |
17390 | absolute paths are used without change, and other folders are in the \(mail)\ |
17391 | directory within the home directory. | |
17392 | ||
17393 | \**Note 1**\: While processing an Exim filter, a relative path such as | |
17394 | \(folder23)\ is turned into an absolute path if a home directory is known to | |
17395 | the router. In particular, this is the case if \check@_local@_user\ is set. If | |
17396 | you want to prevent this happening at routing time, you can set | |
17397 | \router@_home@_directory\ empty. This forces the router to pass the relative | |
17398 | path to the transport. | |
17399 | ||
17400 | \**Note 2**\: An absolute path in \$address@_file$\ is not treated specially; | |
17401 | the \file\ or \directory\ option is still used if it is set. | |
17402 | ||
17403 | ||
17404 | ||
17405 | .section Private options for appendfile | |
17406 | .index options||\%appendfile%\ transport | |
17407 | ||
d43194df | 17408 | .startconf appendfile |
495ae4b0 PH |
17409 | |
17410 | .conf allow@_fifo boolean false | |
17411 | .index fifo (named pipe) | |
17412 | .index named pipe (fifo) | |
17413 | .index pipe||named (fifo) | |
17414 | Setting this option permits delivery to named pipes (FIFOs) as well as to | |
17415 | regular files. If no process is reading the named pipe at delivery time, the | |
17416 | delivery is deferred. | |
17417 | ||
17418 | .conf allow@_symlink boolean false | |
17419 | .index symbolic link||to mailbox | |
17420 | .index mailbox||symbolic link | |
17421 | By default, \%appendfile%\ will not deliver if the path name for the file is | |
17422 | that of a symbolic link. Setting this option relaxes that constraint, but there | |
17423 | are security issues involved in the use of symbolic links. Be sure you know | |
17424 | what you are doing if you set this. Details of exactly what this option affects | |
17425 | are included in the discussion which follows this list of options. | |
17426 | ||
17427 | .conf batch@_id string$**$ unset | |
17428 | See the description of local delivery batching in chapter ~~CHAPbatching. | |
4964e932 PH |
17429 | However, batching is automatically disabled for \%appendfile%\ deliveries that |
17430 | happen as a result of forwarding or aliasing or other redirection directly to a | |
495ae4b0 PH |
17431 | file. |
17432 | ||
17433 | .conf batch@_max integer 1 | |
17434 | See the description of local delivery batching in chapter ~~CHAPbatching. | |
17435 | ||
17436 | .conf check@_group boolean false | |
17437 | When this option is set, the group owner of the file defined by the \file\ | |
17438 | option is checked to see that it is the same as the group under which the | |
17439 | delivery process is running. The default setting is false because the default | |
17440 | file mode is 0600, which means that the group is irrelevant. | |
17441 | ||
17442 | .conf check@_owner boolean true | |
17443 | When this option is set, the owner of the file defined by the \file\ option is | |
17444 | checked to ensure that it is the same as the user under which the delivery | |
17445 | process is running. | |
17446 | ||
17447 | .conf check@_string string "see below" | |
17448 | .index `From' line | |
17449 | As \%appendfile%\ writes the message, the start of each line is tested for | |
17450 | matching \check@_string\, and if it does, the initial matching characters are | |
17451 | replaced by the contents of \escape@_string\. The value of \check@_string\ is a | |
17452 | literal string, not a regular expression, and the case of any letters it | |
17453 | contains is significant. | |
17454 | ||
17455 | If \use@_bsmtp\ is set the values of \check@_string\ and \escape@_string\ are | |
17456 | forced to `.' and `..' respectively, and any settings in the configuration are | |
17457 | ignored. Otherwise, they default to `From ' and `>From ' when the \file\ option | |
4964e932 | 17458 | is set, and unset when |
495ae4b0 PH |
17459 | any of the \directory\, \maildir\, or \mailstore\ options are set. |
17460 | ||
17461 | The default settings, along with \message@_prefix\ and \message@_suffix\, are | |
17462 | suitable for traditional `BSD' mailboxes, where a line beginning with `From ' | |
17463 | indicates the start of a new message. All four options need changing if another | |
17464 | format is used. For example, to deliver to mailboxes in MMDF format: | |
17465 | .index MMDF format mailbox | |
17466 | .index mailbox||MMDF format | |
17467 | .display asis | |
17468 | check_string = "\1\1\1\1\n" | |
17469 | escape_string = "\1\1\1\1 \n" | |
17470 | message_prefix = "\1\1\1\1\n" | |
17471 | message_suffix = "\1\1\1\1\n" | |
17472 | .endd | |
17473 | ||
17474 | .index directory creation | |
17475 | .conf create@_directory boolean true | |
17476 | When this option is true, Exim attempts to create any missing superior | |
17477 | directories for the file that it is about to write. A created directory's mode | |
17478 | is given by the \directory@_mode\ option. | |
d43194df PH |
17479 | .em |
17480 | The group ownership of a newly created directory is highly dependent on the | |
17481 | operating system (and possibly the file system) that is being used. For | |
17482 | example, in Solaris, if the parent directory has the setgid bit set, its group | |
17483 | is propagated to the child; if not, the currently set group is used. However, | |
17484 | in FreeBSD, the parent's group is always used. | |
17485 | .nem | |
495ae4b0 PH |
17486 | |
17487 | .conf create@_file string "anywhere" | |
17488 | This option constrains the location of files and directories that are created | |
17489 | by this transport. It applies to files defined by the \file\ option and | |
17490 | directories defined by the \directory\ option. In the case of maildir delivery, | |
17491 | it applies to the top level directory, not the maildir directories beneath. | |
17492 | ||
17493 | The option must be set to one of the words `anywhere', `inhome', or | |
17494 | `belowhome'. In the second and third cases, a home directory must have been set | |
17495 | for the transport. This option is not useful when an explicit file name is | |
17496 | given for normal mailbox deliveries. It is intended for the case when file | |
17497 | names are generated from users' \(.forward)\ files. These are usually handled | |
17498 | by an \%appendfile%\ transport called \address@_file\. See also | |
17499 | \file@_must@_exist\. | |
17500 | ||
17501 | .conf directory string$**$ unset | |
17502 | This option is mutually exclusive with the \file\ option, but one of \file\ or | |
17503 | \directory\ must be set, unless the delivery is the direct result of a | |
17504 | redirection (see section ~~SECTfildiropt). | |
17505 | ||
17506 | When \directory\ is set, the string is expanded, and the message is delivered | |
17507 | into a new file or files in or below the given directory, instead of being | |
17508 | appended to a single mailbox file. A number of different formats are provided | |
17509 | (see \maildir@_format\ and \mailstore@_format\), and see section ~~SECTopdir | |
17510 | for further details of this form of delivery. | |
17511 | ||
17512 | .conf directory@_file string$**$ "$tt{q@$@{base62:@$tod@_epoch@}-@$inode}" | |
17513 | .index base62 | |
17514 | When \directory\ is set, but neither \maildir@_format\ nor \mailstore@_format\ | |
17515 | is set, \%appendfile%\ delivers each message into a file whose name is obtained | |
17516 | by expanding this string. The default value generates a unique name from the | |
17517 | current time, in base 62 form, and the inode of the file. The variable | |
17518 | \$inode$\ is available only when expanding this option. | |
17519 | ||
17520 | .conf directory@_mode "octal integer" 0700 | |
17521 | If \%appendfile%\ creates any directories as a result of the \create@_directory\ | |
17522 | option, their mode is specified by this option. | |
17523 | ||
17524 | .conf escape@_string string "see description" | |
17525 | See \check@_string\ above. | |
17526 | ||
17527 | .conf file string$**$ unset | |
17528 | This option is mutually exclusive with the \directory\ option, but one of | |
17529 | \file\ or \directory\ must be set, unless the delivery is the direct result of | |
17530 | a redirection (see section ~~SECTfildiropt). The \file\ option specifies a | |
17531 | single file, to which the message is appended. One or more of | |
17532 | \use@_fcntl@_lock\, \use@_flock@_lock\, or \use@_lockfile\ must be set with | |
17533 | \file\. | |
17534 | .index NFS||lock file | |
17535 | .index locking files | |
17536 | .index lock files | |
17537 | If you are using more than one host to deliver over NFS into the same | |
17538 | mailboxes, you should always use lock files. | |
17539 | ||
17540 | The string value is expanded for each delivery, and must yield an absolute | |
17541 | path. The most common settings of this option are variations on one of these | |
17542 | examples: | |
17543 | .display asis | |
17544 | file = /var/spool/mail/$local_part | |
17545 | file = /home/$local_part/inbox | |
17546 | file = $home/inbox | |
17547 | .endd | |
17548 | .index `sticky' bit | |
17549 | In the first example, all deliveries are done into the same directory. If Exim | |
17550 | is configured to use lock files (see \use@_lockfile\ below) it must be able to | |
17551 | create a file in the directory, so the `sticky' bit must be turned on for | |
17552 | deliveries to be possible, or alternatively the \group\ option can be used to | |
17553 | run the delivery under a group id which has write access to the directory. | |
17554 | ||
17555 | ||
17556 | .conf file@_format string unset | |
17557 | .index file||mailbox, checking existing format | |
17558 | This option requests the transport to check the format of an existing file | |
17559 | before adding to it. The check consists of matching a specific string at the | |
17560 | start of the file. The value of the option consists of an even number of | |
17561 | colon-separated strings. The first of each pair is the test string, and the | |
17562 | second is the name of a transport. If the transport associated with a matched | |
17563 | string is not the current transport, control is passed over to the other | |
17564 | transport. For example, suppose the standard \%local@_delivery%\ transport has | |
17565 | this added to it: | |
17566 | .display asis | |
17567 | file_format = "From : local_delivery :\ | |
17568 | \1\1\1\1\n : local_mmdf_delivery" | |
17569 | .endd | |
17570 | Mailboxes that begin with `From' are still handled by this transport, but if a | |
17571 | mailbox begins with four binary ones followed by a newline, control is passed | |
17572 | to a transport called \local__mmdf__delivery\, which presumably is configured | |
17573 | to do the delivery in MMDF format. If a mailbox does not exist or is empty, it | |
17574 | is assumed to match the current transport. If the start of a mailbox doesn't | |
17575 | match any string, or if the transport named for a given string is not defined, | |
17576 | delivery is deferred. | |
17577 | ||
17578 | .conf file@_must@_exist boolean false | |
17579 | If this option is true, the file specified by the \file\ option must exist, and | |
17580 | an error occurs if it does not. Otherwise, it is created if it does not exist. | |
17581 | ||
17582 | .conf lock@_fcntl@_timeout time 0s | |
17583 | .index timeout||mailbox locking | |
17584 | .index mailbox locking||blocking and non-blocking | |
17585 | .index locking files | |
17586 | By default, the \%appendfile%\ transport uses non-blocking calls to \*fcntl()*\ | |
17587 | when locking an open mailbox file. If the call fails, the delivery process | |
17588 | sleeps for \lock@_interval\ and tries again, up to \lock@_retries\ times. | |
17589 | Non-blocking calls are used so that the file is not kept open during the wait | |
17590 | for the lock; the reason for this is to make it as safe as possible for | |
17591 | deliveries over NFS in the case when processes might be accessing an NFS | |
17592 | mailbox without using a lock file. This should not be done, but | |
17593 | misunderstandings and hence misconfigurations are not unknown. | |
17594 | ||
17595 | On a busy system, however, the performance of a non-blocking lock approach is | |
17596 | not as good as using a blocking lock with a timeout. In this case, the waiting | |
17597 | is done inside the system call, and Exim's delivery process acquires the lock | |
17598 | and can proceed as soon as the previous lock holder releases it. | |
17599 | ||
17600 | If \lock@_fcntl@_timeout\ is set to a non-zero time, blocking locks, with that | |
17601 | timeout, are used. There may still be some retrying: the maximum number of | |
17602 | retries is | |
17603 | .display asis | |
17604 | (lock_retries * lock_interval) / lock_fcntl_timeout | |
17605 | .endd | |
17606 | rounded up to the next whole number. In other words, the total time during | |
17607 | which \%appendfile%\ is trying to get a lock is roughly the same, unless | |
17608 | \lock@_fcntl@_timeout\ is set very large. | |
17609 | ||
17610 | You should consider setting this option if you are getting a lot of delayed | |
17611 | local deliveries because of errors of the form | |
17612 | .display asis | |
17613 | failed to lock mailbox /some/file (fcntl) | |
17614 | .endd | |
17615 | ||
17616 | .conf lock@_flock@_timeout time 0s | |
17617 | This timeout applies to file locking when using \*flock()*\ (see \use@_flock\); | |
17618 | the timeout operates in a similar manner to \lock@_fcntl@_timeout\. | |
17619 | ||
17620 | .conf lock@_interval time 3s | |
17621 | This specifies the time to wait between attempts to lock the file. See below | |
17622 | for details of locking. | |
17623 | ||
17624 | .conf lock@_retries integer 10 | |
17625 | This specifies the maximum number of attempts to lock the file. A value of zero | |
17626 | is treated as 1. See below for details of locking. | |
17627 | ||
17628 | .conf lockfile@_mode "octal integer" 0600 | |
17629 | This specifies the mode of the created lock file, when a lock file is being | |
17630 | used (see \use@_lockfile\). | |
17631 | ||
17632 | .conf lockfile@_timeout time 30m | |
17633 | .index timeout||mailbox locking | |
17634 | When a lock file is being used (see \use@_lockfile\), if a lock file already | |
17635 | exists and is older than this value, it is assumed to have been left behind by | |
17636 | accident, and Exim attempts to remove it. | |
17637 | ||
d43194df PH |
17638 | .em |
17639 | .conf mailbox@_filecount string$**$ unset | |
17640 | .index mailbox||specifying size of | |
17641 | .index size||of mailbox | |
17642 | If this option is set, it is expanded, and the result is taken as the current | |
17643 | number of files in the mailbox. It must be a decimal number, optionally | |
17644 | followed by K or M. This provides a way of obtaining this information from an | |
17645 | external source that maintains the data. | |
17646 | ||
17647 | .conf mailbox@_size string$**$ unset | |
17648 | .index mailbox||specifying size of | |
17649 | .index size||of mailbox | |
17650 | If this option is set, it is expanded, and the result is taken as the current | |
17651 | size the mailbox. It must be a decimal number, optionally followed by K or M. | |
17652 | This provides a way of obtaining this information from an external source that | |
17653 | maintains the data. This is likely to be helpful for maildir deliveries where | |
17654 | it is computationally expensive to compute the size of a mailbox. | |
17655 | .nem | |
17656 | ||
495ae4b0 PH |
17657 | .conf maildir@_format boolean false |
17658 | .index maildir format||specifying | |
17659 | If this option is set with the \directory\ option, the delivery is into a new | |
17660 | file, in the `maildir' format that is used by other mail software. When the | |
17661 | transport is activated directly from a \%redirect%\ router (for example, the | |
17662 | \%address@_file%\ transport in the default configuration), setting | |
17663 | \maildir@_format\ causes the path received from the router to be treated as a | |
17664 | directory, whether or not it ends with \"/"\. This option is available only if | |
17665 | \\SUPPORT@_MAILDIR\\ is present in \(Local/Makefile)\. See section | |
17666 | ~~SECTmaildirdelivery below for further details. | |
17667 | ||
495ae4b0 PH |
17668 | .conf maildir@_quota@_directory@_regex string "See below" |
17669 | .index maildir format||quota, directories included in | |
17670 | .index quota||maildir, directories included in | |
17671 | This option is relevant only when \maildir@_use@_size@_file\ is set. It defines | |
17672 | a regular expression for specifying directories that should be included in the | |
17673 | quota calculation. The default value is | |
17674 | .display asis | |
17675 | maildir_quota_directory_regex = ^(?:cur|new|\..*)$ | |
17676 | .endd | |
17677 | which includes the \(cur)\ and \(new)\ directories, and any maildir++ folders | |
4964e932 | 17678 | (directories whose names begin with a dot). If you want to exclude the |
495ae4b0 PH |
17679 | \(Trash)\ |
17680 | folder from the count (as some sites do), you need to change this setting to | |
17681 | .display asis | |
17682 | maildir_quota_directory_regex = ^(?:cur|new|\.(?!Trash).*)$ | |
17683 | .endd | |
17684 | This uses a negative lookahead in the regular expression to exclude the | |
17685 | directory whose name is \(.Trash)\. | |
495ae4b0 PH |
17686 | |
17687 | .conf maildir@_retries integer 10 | |
17688 | This option specifies the number of times to retry when writing a file in | |
17689 | `maildir' format. See section ~~SECTmaildirdelivery below. | |
17690 | ||
17691 | .conf maildir@_tag string$**$ unset | |
17692 | This option applies only to deliveries in maildir format, and is described in | |
17693 | section ~~SECTmaildirdelivery below. | |
17694 | ||
17695 | .conf maildir@_use@_size@_file boolean false | |
17696 | .index maildir format||\(maildirsize)\ file | |
17697 | Setting this option true enables support for \(maildirsize)\ files. Exim | |
17698 | creates a \(maildirsize)\ file in a maildir if one does not exist, taking the | |
17699 | quota from the \quota\ option of the transport. If \quota\ is unset, the value | |
17700 | is zero. See section ~~SECTmaildirdelivery below for further details. | |
17701 | ||
17702 | .conf mailstore@_format boolean false | |
17703 | .index mailstore format||specifying | |
17704 | If this option is set with the \directory\ option, the delivery is into two new | |
17705 | files in `mailstore' format. The option is available only if | |
17706 | \\SUPPORT@_MAILSTORE\\ is present in \(Local/Makefile)\. See section | |
17707 | ~~SECTopdir below for further details. | |
17708 | ||
17709 | .conf mailstore@_prefix string$**$ unset | |
17710 | This option applies only to deliveries in mailstore format, and is described in | |
17711 | section ~~SECTopdir below. | |
17712 | ||
17713 | .conf mailstore@_suffix string$**$ unset | |
17714 | This option applies only to deliveries in mailstore format, and is described in | |
17715 | section ~~SECTopdir below. | |
17716 | ||
17717 | .conf mbx@_format boolean false | |
17718 | .index locking files | |
17719 | .index file||locking | |
17720 | .index file||MBX format | |
17721 | .index MBX format, specifying | |
17722 | This option is available only if Exim has been compiled with \\SUPPORT@_MBX\\ | |
17723 | set in \(Local/Makefile)\. If \mbx@_format\ is set with the \file\ option, | |
17724 | the message is appended to the mailbox file in MBX format instead of | |
17725 | traditional Unix format. This format is supported by Pine4 and its associated | |
17726 | IMAP and POP daemons, by means of the \*c-client*\ library that they all use. | |
17727 | ||
17728 | \**Note**\: The \message@_prefix\ and \message@_suffix\ options are not | |
17729 | automatically changed by the use of \mbx@_format\. They should normally be set | |
4964e932 | 17730 | empty when using MBX format, so this option almost always appears in this |
495ae4b0 PH |
17731 | combination: |
17732 | .display asis | |
17733 | mbx_format = true | |
17734 | message_prefix = | |
17735 | message_suffix = | |
17736 | .endd | |
17737 | ||
17738 | If none of the locking options are mentioned in the configuration, | |
17739 | \use@_mbx@_lock\ is assumed and the other locking options default to false. It | |
17740 | is possible to specify the other kinds of locking with \mbx@_format\, but | |
17741 | \use@_fcntl@_lock\ and \use@_mbx@_lock\ are mutually exclusive. MBX locking | |
17742 | interworks with \*c-client*\, providing for shared access to the mailbox. It | |
17743 | should not be used if any program that does not use this form of locking is | |
17744 | going to access the mailbox, nor should it be used if the mailbox file is NFS | |
17745 | mounted, because it works only when the mailbox is accessed from a single host. | |
17746 | ||
17747 | If you set \use@_fcntl@_lock\ with an MBX-format mailbox, you cannot use | |
17748 | the standard version of \*c-client*\, because as long as it has a mailbox open | |
17749 | (this means for the whole of a Pine or IMAP session), Exim will not be able to | |
17750 | append messages to it. | |
17751 | ||
17752 | .conf message@_prefix string$**$ "see below" | |
17753 | .index `From' line | |
17754 | The string specified here is expanded and output at the start of every message. | |
17755 | The default is unset unless \file\ is specified and \use@_bsmtp\ is not set, in | |
17756 | which case it is: | |
17757 | .display asis | |
17758 | message_prefix = "From ${if def:return_path{$return_path}\ | |
17759 | {MAILER-DAEMON}} $tod_bsdinbox\n" | |
17760 | .endd | |
17761 | ||
17762 | .conf message@_suffix string$**$ "see below" | |
17763 | The string specified here is expanded and output at the end of every message. | |
17764 | The default is unset unless \file\ is specified and \use@_bsmtp\ is not set, in | |
17765 | which case it is a single newline character. The suffix can be suppressed by | |
17766 | setting | |
17767 | .display asis | |
17768 | message_suffix = | |
17769 | .endd | |
17770 | ||
17771 | .conf mode "octal integer" 0600 | |
17772 | If the output file is created, it is given this mode. If it already exists and | |
17773 | has wider permissions, they are reduced to this mode. If it has narrower | |
17774 | permissions, an error occurs unless \mode__fail__narrower\ is false. However, | |
17775 | if the delivery is the result of a \save\ command in a filter file specifing a | |
17776 | particular mode, the mode of the output file is always forced to take that | |
17777 | value, and this option is ignored. | |
17778 | ||
17779 | .conf mode@_fail@_narrower boolean true | |
17780 | This option applies in the case when an existing mailbox file has a narrower | |
17781 | mode than that specified by the \mode\ option. If \mode@_fail@_narrower\ is | |
17782 | true, the delivery is deferred (`mailbox has the wrong mode'); otherwise Exim | |
17783 | continues with the delivery attempt, using the existing mode of the file. | |
17784 | ||
17785 | .conf notify@_comsat boolean false | |
17786 | If this option is true, the \*comsat*\ daemon is notified after every successful | |
17787 | delivery to a user mailbox. This is the daemon that notifies logged on users | |
17788 | about incoming mail. | |
17789 | ||
17790 | .conf quota string$**$ unset | |
17791 | .index quota||imposed by Exim | |
17792 | This option imposes a limit on the size of the file to which Exim is appending, | |
17793 | or to the total space used in the directory tree when the \directory\ option is | |
17794 | set. In the latter case, computation of the space used is expensive, because | |
17795 | all the files in the directory (and any sub-directories) have to be | |
4964e932 | 17796 | individually inspected and their sizes summed. |
495ae4b0 PH |
17797 | (See \quota@_size@_regex\ and \maildir@_use@_size@_file\ for ways to avoid this |
17798 | in environments where users have no shell access to their mailboxes). | |
17799 | ||
17800 | As there is no interlock against two simultaneous deliveries into a | |
17801 | multi-file mailbox, it is possible for the quota to be overrun in this case. | |
17802 | For single-file mailboxes, of course, an interlock is a necessity. | |
495ae4b0 PH |
17803 | |
17804 | A file's size is taken as its \*used*\ value. Because of blocking effects, this | |
17805 | may be a lot less than the actual amount of disk space allocated to the file. | |
17806 | If the sizes of a number of files are being added up, the rounding effect can | |
17807 | become quite noticeable, especially on systems that have large block sizes. | |
17808 | Nevertheless, it seems best to stick to the \*used*\ figure, because this is | |
17809 | the obvious value which users understand most easily. | |
17810 | ||
17811 | The value of the option is expanded, and must then be a numerical value | |
17812 | (decimal point allowed), optionally followed by one of the letters K or M. The | |
17813 | expansion happens while Exim is running as root, before it changes uid for the | |
17814 | delivery. This means that files which are inaccessible to the end user can be | |
17815 | used to hold quota values that are looked up in the expansion. When delivery | |
17816 | fails because this quota is exceeded, the handling of the error is as for | |
17817 | system quota failures. | |
17818 | ||
4964e932 | 17819 | \**Note**\: A value of zero is interpreted as `no quota'. |
495ae4b0 PH |
17820 | |
17821 | By default, Exim's quota checking mimics system quotas, and restricts the | |
17822 | mailbox to the specified maximum size, though the value is not accurate to the | |
17823 | last byte, owing to separator lines and additional headers that may get added | |
17824 | during message delivery. When a mailbox is nearly full, large messages may get | |
17825 | refused even though small ones are accepted, because the size of the current | |
17826 | message is added to the quota when the check is made. This behaviour can be | |
17827 | changed by setting \quota@_is@_inclusive\ false. When this is done, the check | |
17828 | for exceeding the quota does not include the current message. Thus, deliveries | |
17829 | continue until the quota has been exceeded; thereafter, no further messages are | |
17830 | delivered. See also \quota@_warn@_threshold\. | |
17831 | ||
17832 | .conf quota@_directory string$**$ unset | |
17833 | This option defines the directory to check for quota purposes when delivering | |
17834 | into individual files. The default is the delivery directory, or, if a file | |
17835 | called \(maildirfolder)\ exists in a maildir directory, the parent of the | |
17836 | delivery directory. | |
17837 | ||
17838 | .conf quota@_filecount string$**$ 0 | |
17839 | This option applies when the \directory\ option is set. It limits the total | |
17840 | number of files in the directory (compare the inode limit in system quotas). It | |
17841 | can only be used if \quota\ is also set. The value is expanded; an expansion | |
17842 | failure causes delivery to be deferred. | |
17843 | ||
17844 | .conf quota@_is@_inclusive boolean true | |
17845 | See \quota\ above. | |
17846 | ||
17847 | .conf quota@_size@_regex string unset | |
17848 | This option applies when one of the delivery modes that writes a separate file | |
17849 | for each message is being used. When Exim wants to find the size of one of | |
17850 | these files in order to test the quota, it first checks \quota@_size@_regex\. | |
17851 | If this is set to a regular expression that matches the file name, and it | |
17852 | captures one string, that string is interpreted as a representation of the | |
17853 | file's size. The value of \quota@_size@_regex\ is not expanded. | |
17854 | ||
17855 | This feature is useful only when users have no shell access to their mailboxes | |
17856 | -- otherwise they could defeat the quota simply by renaming the files. This | |
17857 | facility can be used with maildir deliveries, by setting \maildir@_tag\ to add | |
17858 | the file length to the file name. For example: | |
17859 | .display asis | |
17860 | maildir_tag = ,S=$message_size | |
17861 | quota_size_regex = ,S=(\d+) | |
17862 | .endd | |
4964e932 PH |
17863 | The regular expression should not assume that the length is at the end of the |
17864 | file name (even though \maildir@_tag\ puts it there) because maildir MUAs | |
495ae4b0 PH |
17865 | sometimes add other information onto the ends of message file names. |
17866 | ||
17867 | .conf quota@_warn@_message string$**$ "see below" | |
17868 | See below for the use of this option. If it is not set when | |
17869 | \quota@_warn@_threshold\ is set, it defaults to | |
17870 | .display asis | |
17871 | quota_warn_message = "\ | |
17872 | To: $local_part@$domain\n\ | |
17873 | Subject: Your mailbox\n\n\ | |
17874 | This message is automatically created \ | |
17875 | by mail delivery software.\n\n\ | |
17876 | The size of your mailbox has exceeded \ | |
17877 | a warning threshold that is\n\ | |
17878 | set by the system administrator.\n" | |
17879 | .endd | |
17880 | ||
17881 | .conf quota@_warn@_threshold string$**$ 0 | |
17882 | .index quota||warning threshold | |
17883 | .index mailbox||size warning | |
17884 | .index size||of mailbox | |
17885 | This option is expanded in the same way as \quota\ (see above). If the | |
17886 | resulting value is greater than zero, and delivery of the message causes the | |
17887 | size of the file or total space in the directory tree to cross the given | |
17888 | threshold, a warning message is sent. If \quota\ is also set, the threshold may | |
17889 | be specified as a percentage of it by following the value with a percent sign. | |
17890 | For example: | |
17891 | .display asis | |
17892 | quota = 10M | |
17893 | quota_warn_threshold = 75% | |
17894 | .endd | |
17895 | If \quota\ is not set, a setting of \quota@_warn@_threshold\ that ends with a | |
17896 | percent sign is ignored. | |
17897 | ||
17898 | The warning message itself is specified by the \quota@_warn@_message\ option, | |
17899 | and it must start with a ::To:: header line containing the recipient(s). A | |
17900 | ::Subject:: line should also normally be supplied. The \quota\ option does not | |
17901 | have to be set in order to use this option; they are independent of one | |
17902 | another except when the threshold is specified as a percentage. | |
17903 | ||
17904 | .conf use@_bsmtp boolean false | |
17905 | .index envelope sender | |
17906 | If this option is set true, \%appendfile%\ writes messages in `batch SMTP' | |
17907 | format, with the envelope sender and recipient(s) included as SMTP commands. If | |
17908 | you want to include a leading \\HELO\\ command with such messages, you can do | |
17909 | so by setting the \message@_prefix\ option. See section ~~SECTbatchSMTP for | |
17910 | details of batch SMTP. | |
17911 | ||
17912 | .conf use@_crlf boolean false | |
17913 | .index carriage return | |
17914 | .index linefeed | |
17915 | This option causes lines to be terminated with the two-character CRLF sequence | |
17916 | (carriage return, linefeed) instead of just a linefeed character. In the case | |
17917 | of batched SMTP, the byte sequence written to the file is then an exact image | |
17918 | of what would be sent down a real SMTP connection. | |
17919 | ||
17920 | The contents of the \message@_prefix\ and \message@_suffix\ options are written | |
17921 | verbatim, so must contain their own carriage return characters if these are | |
17922 | needed. In cases where these options have non-empty defaults, the values end | |
4964e932 | 17923 | with a single linefeed, so they |
495ae4b0 PH |
17924 | must |
17925 | be changed to end with \"@\r@\n"\ if \use@_crlf\ is set. | |
17926 | ||
17927 | .conf use@_fcntl@_lock boolean "see below" | |
17928 | This option controls the use of the \*fcntl()*\ function to lock a file for | |
17929 | exclusive use when a message is being appended. It is set by default unless | |
17930 | \use@_flock@_lock\ is set. Otherwise, it should be turned off only if you know | |
17931 | that all your MUAs use lock file locking. When both \use@_fcntl@_lock\ and | |
17932 | \use@_flock@_lock\ are unset, \use@_lockfile\ must be set. | |
17933 | ||
17934 | .conf use@_flock@_lock boolean false | |
17935 | This option is provided to support the use of \*flock()*\ for file locking, for | |
17936 | the few situations where it is needed. Most modern operating systems support | |
17937 | \*fcntl()*\ and \*lockf()*\ locking, and these two functions interwork with | |
17938 | each other. Exim uses \*fcntl()*\ locking by default. | |
17939 | ||
17940 | This option is required only if you are using an operating system where | |
17941 | \*flock()*\ is used by programs that access mailboxes (typically MUAs), and | |
17942 | where \*flock()*\ does not correctly interwork with \*fcntl()*\. You can use | |
17943 | both \*fcntl()*\ and \*flock()*\ locking simultaneously if you want. | |
17944 | ||
17945 | .index Solaris||\*flock()*\ support | |
17946 | Not all operating systems provide \*flock()*\. Some versions of Solaris do not | |
17947 | have it (and some, I think, provide a not quite right version built on top of | |
17948 | \*lockf()*\). If the OS does not have \*flock()*\, Exim will be built without | |
17949 | the ability to use it, and any attempt to do so will cause a configuration | |
17950 | error. | |
17951 | ||
17952 | \**Warning**\: \*flock()*\ locks do not work on NFS files (unless \*flock()*\ | |
17953 | is just being mapped onto \*fcntl()*\ by the OS). | |
17954 | ||
17955 | .conf use@_lockfile boolean "see below" | |
17956 | If this option is turned off, Exim does not attempt to create a lock file when | |
17957 | appending to a mailbox file. In this situation, the only locking is by | |
17958 | \*fcntl()*\. You should only turn \use@_lockfile\ off if you are absolutely | |
17959 | sure that every MUA that is ever going to look at your users' mailboxes uses | |
17960 | \*fcntl()*\ rather than a lock file, and even then only when you are not | |
17961 | delivering over NFS from more than one host. | |
17962 | ||
17963 | .index NFS||lock file | |
17964 | In order to append to an NFS file safely from more than one host, it is | |
17965 | necessary to take out a lock $it{before} opening the file, and the lock file | |
17966 | achieves this. Otherwise, even with \*fcntl()*\ locking, there is a risk of | |
17967 | file corruption. | |
17968 | ||
17969 | The \use@_lockfile\ option is set by default unless \use@_mbx@_lock\ is set. It | |
17970 | is not possible to turn both \use@_lockfile\ and \use@_fcntl@_lock\ off, except | |
17971 | when \mbx@_format\ is set. | |
17972 | ||
17973 | .conf use@_mbx@_lock boolean "see below" | |
17974 | This option is available only if Exim has been compiled with \\SUPPORT@_MBX\\ | |
17975 | set in \(Local/Makefile)\. Setting the option specifies that special MBX | |
17976 | locking rules be used. It is set by default if \mbx@_format\ is set and none of | |
17977 | the locking options are mentioned in the configuration. The locking rules are | |
17978 | the same as are used by the \*c-client*\ library that underlies Pine and the | |
17979 | IMAP4 and POP daemons that come with it (see the discussion below). The rules | |
17980 | allow for shared access to the mailbox. However, this kind of locking does not | |
17981 | work when the mailbox is NFS mounted. | |
17982 | ||
17983 | You can set \use@_mbx@_lock\ with either (or both) of \use@_fcntl@_lock\ and | |
17984 | \use@_flock@_lock\ to control what kind of locking is used in implementing the | |
17985 | MBX locking rules. The default is to use \*fcntl()*\ if \use@_mbx@_lock\ is set | |
17986 | without \use@_fcntl@_lock\ or \use@_flock@_lock\. | |
17987 | .endconf | |
17988 | ||
17989 | ||
17990 | .section Operational details for appending | |
17991 | .rset SECTopappend "~~chapter.~~section" | |
17992 | .index appending to a file | |
17993 | .index file||appending | |
17994 | Before appending to a file, the following preparations are made: | |
17995 | .numberpars $. | |
17996 | If the name of the file is \(/dev/null)\, no action is taken, and a success | |
17997 | return is given. | |
17998 | .nextp | |
17999 | .index directory creation | |
18000 | If any directories on the file's path are missing, Exim creates them if the | |
18001 | \create@_directory\ option is set. A created directory's mode is given by the | |
18002 | \directory@_mode\ option. | |
18003 | .nextp | |
18004 | If \file@_format\ is set, the format of an existing file is checked. If this | |
18005 | indicates that a different transport should be used, control is passed to that | |
18006 | transport. | |
18007 | .nextp | |
18008 | .index file||locking | |
18009 | .index locking files | |
18010 | .index NFS||lock file | |
18011 | If \use@_lockfile\ is set, a lock file is built in a way that will work | |
18012 | reliably over NFS, as follows: | |
18013 | .numberpars $. | |
18014 | Create a `hitching post' file whose name is that of the lock file with the | |
18015 | current time, primary host name, and process id added, by opening for writing | |
18016 | as a new file. If this fails with an access error, delivery is deferred. | |
18017 | .nextp | |
18018 | Close the hitching post file, and hard link it to the lock file name. | |
18019 | .nextp | |
18020 | If the call to \*link()*\ succeeds, creation of the lock file has succeeded. | |
18021 | Unlink the hitching post name. | |
18022 | .nextp | |
18023 | Otherwise, use \*stat()*\ to get information about the hitching post file, and | |
18024 | then unlink hitching post name. If the number of links is exactly two, creation | |
18025 | of the lock file succeeded but something (for example, an NFS server crash and | |
18026 | restart) caused this fact not to be communicated to the \*link()*\ call. | |
18027 | .nextp | |
18028 | If creation of the lock file failed, wait for \lock@_interval\ and try again, | |
18029 | up to \lock@_retries\ times. However, since any program that writes to a | |
18030 | mailbox should complete its task very quickly, it is reasonable to time out old | |
18031 | lock files that are normally the result of user agent and system crashes. If an | |
18032 | existing lock file is older than \lockfile@_timeout\ Exim attempts to unlink it | |
18033 | before trying again. | |
18034 | .endp | |
18035 | .nextp | |
18036 | A call is made to \*lstat()*\ to discover whether the main file exists, and if | |
18037 | so, what its characteristics are. If \*lstat()*\ fails for any reason other | |
18038 | than non-existence, delivery is deferred. | |
18039 | .nextp | |
18040 | .index symbolic link||to mailbox | |
18041 | .index mailbox||symbolic link | |
18042 | If the file does exist and is a symbolic link, delivery is deferred, unless the | |
18043 | \allow@_symlink\ option is set, in which case the ownership of the link is | |
18044 | checked, and then \*stat()*\ is called to find out about the real file, which | |
18045 | is then subjected to the checks below. The check on the top-level link | |
18046 | ownership prevents one user creating a link for another's mailbox in a sticky | |
18047 | directory, though allowing symbolic links in this case is definitely not a good | |
18048 | idea. If there is a chain of symbolic links, the intermediate ones are not | |
18049 | checked. | |
18050 | .nextp | |
18051 | If the file already exists but is not a regular file, or if the file's owner | |
18052 | and group (if the group is being checked -- see \check@_group\ above) are | |
18053 | different from the user and group under which the delivery is running, | |
18054 | delivery is deferred. | |
18055 | .nextp | |
18056 | If the file's permissions are more generous than specified, they are reduced. | |
18057 | If they are insufficient, delivery is deferred, unless \mode@_fail@_narrower\ | |
18058 | is set false, in which case the delivery is tried using the existing | |
18059 | permissions. | |
18060 | .nextp | |
18061 | The file's inode number is saved, and the file is then opened for appending. If | |
18062 | this fails because the file has vanished, \%appendfile%\ behaves as if it hadn't | |
18063 | existed (see below). For any other failures, delivery is deferred. | |
18064 | .nextp | |
18065 | If the file is opened successfully, check that the inode number hasn't | |
18066 | changed, that it is still a regular file, and that the owner and permissions | |
18067 | have not changed. If anything is wrong, defer delivery and freeze the message. | |
18068 | .nextp | |
18069 | If the file did not exist originally, defer delivery if the \file@_must@_exist\ | |
18070 | option is set. Otherwise, check that the file is being created in a permitted | |
18071 | directory if the \create@_file\ option is set (deferring on failure), and then | |
18072 | open for writing as a new file, with the \\O@_EXCL\\ and \\O@_CREAT\\ options, | |
18073 | except when dealing with a symbolic link (the \allow@_symlink\ option must be | |
18074 | set). In this case, which can happen if the link points to a non-existent file, | |
18075 | the file is opened for writing using \\O@_CREAT\\ but not \\O@_EXCL\\, because | |
18076 | that prevents link following. | |
18077 | .nextp | |
18078 | .index loop||while file testing | |
18079 | If opening fails because the file exists, obey the tests given above for | |
18080 | existing files. However, to avoid looping in a situation where the file is | |
18081 | being continuously created and destroyed, the exists/not-exists loop is broken | |
18082 | after 10 repetitions, and the message is then frozen. | |
18083 | .nextp | |
18084 | If opening fails with any other error, defer delivery. | |
18085 | .nextp | |
18086 | .index file||locking | |
18087 | .index locking files | |
18088 | Once the file is open, unless both \use@_fcntl@_lock\ and \use@_flock@_lock\ | |
18089 | are false, it is locked using \*fcntl()*\ or \*flock()*\ or both. If | |
4964e932 | 18090 | \use@_mbx@_lock\ is false, an exclusive lock is requested in each case. |
495ae4b0 PH |
18091 | However, if \use@_mbx@_lock\ is true, |
18092 | Exim takes out a shared lock on the open file, | |
18093 | and an exclusive lock on the file whose name is | |
18094 | .display | |
18095 | /tmp/.<<device-number>>.<<inode-number>> | |
18096 | .endd | |
18097 | using the device and inode numbers of the open mailbox file, in accordance with | |
18098 | the MBX locking rules. | |
18099 | ||
18100 | If Exim fails to lock the file, there are two possible courses of action, | |
18101 | depending on the value of the locking timeout. This is obtained from | |
18102 | \lock@_fcntl@_timeout\ or \lock@_flock@_timeout\, as appropriate. | |
18103 | ||
18104 | If the timeout value is zero, the file is closed, Exim waits for | |
18105 | \lock@_interval\, and then goes back and re-opens the file as above and tries | |
18106 | to lock it again. This happens up to \lock@_retries\ times, after which the | |
18107 | delivery is deferred. | |
18108 | ||
18109 | If the timeout has a value greater than zero, blocking calls to \*fcntl()*\ or | |
18110 | \*flock()*\ are used (with the given timeout), so there has already been some | |
18111 | waiting involved by the time locking fails. Nevertheless, Exim does not give up | |
18112 | immediately. It retries up to | |
18113 | .display | |
18114 | (lock@_retries * lock@_interval) / <<timeout>> | |
18115 | .endd | |
18116 | times (rounded up). | |
18117 | .endp | |
18118 | ||
18119 | At the end of delivery, Exim closes the file (which releases the \*fcntl()*\ | |
18120 | and/or \*flock()*\ locks) and then deletes the lock file if one was created. | |
18121 | ||
18122 | .section Operational details for delivery to a new file | |
18123 | .rset SECTopdir "~~chapter.~~section" | |
18124 | .index delivery||to single file | |
18125 | .index `From' line | |
18126 | When the \directory\ option is set instead of \file\, each message is delivered | |
4964e932 PH |
18127 | into a newly-created file or set of files. When \%appendfile%\ is activated |
18128 | directly from a \%redirect%\ router, neither \file\ nor \directory\ is normally | |
18129 | set, because the path for delivery is supplied by the router. (See for example, | |
18130 | the \%address@_file%\ transport in the default configuration.) In this case, | |
18131 | delivery is to a new file if either the path name ends in \"/"\, or the | |
495ae4b0 PH |
18132 | \maildir@_format\ or \mailstore@_format\ option is set. |
18133 | ||
18134 | No locking is required while writing the message to a new file, so the various | |
18135 | locking options of the transport are ignored. The `From' line that by default | |
18136 | separates messages in a single file is not normally needed, nor is the escaping | |
18137 | of message lines that start with `From', and there is no need to ensure a | |
18138 | newline at the end of each message. Consequently, the default values for | |
18139 | \check@_string\, \message@_prefix\, and \message@_suffix\ are all unset when | |
18140 | any of \directory\, \maildir@_format\, or \mailstore@_format\ is set. | |
18141 | ||
4964e932 PH |
18142 | If Exim is required to check a \quota\ setting, it adds up the sizes of all the |
18143 | files in the delivery directory by default. However, you can specify a | |
18144 | different directory by setting \quota@_directory\. Also, for maildir deliveries | |
495ae4b0 PH |
18145 | (see below) the \(maildirfolder)\ convention is honoured. |
18146 | ||
18147 | ||
18148 | .index maildir format | |
18149 | .index mailstore format | |
18150 | There are three different ways in which delivery to individual files can be | |
18151 | done, controlled by the settings of the \maildir@_format\ and | |
18152 | \mailstore@_format\ options. Note that code to support maildir or mailstore | |
18153 | formats is not included in the binary unless \\SUPPORT@_MAILDIR\\ or | |
18154 | \\SUPPORT@_MAILSTORE\\, respectively, is set in \(Local/Makefile)\. | |
18155 | ||
18156 | .index directory creation | |
18157 | In all three cases an attempt is made to create the directory and any necessary | |
18158 | sub-directories if they do not exist, provided that the \create@_directory\ | |
18159 | option is set (the default). The location of a created directory can be | |
18160 | constrained by setting \create@_file\. A created directory's mode is given by | |
18161 | the \directory@_mode\ option. If creation fails, or if the \create@_directory\ | |
18162 | option is not set when creation is required, delivery is deferred. | |
18163 | ||
18164 | ||
18165 | .section Maildir delivery | |
18166 | .rset SECTmaildirdelivery "~~chapter.~~section" | |
18167 | .index maildir format||description of | |
18168 | If the \maildir@_format\ option is true, Exim delivers each message by writing | |
18169 | it to a file whose name is \(tmp/<<stime>>.H<<mtime>>P<<pid>>.<<host>>)\ in the | |
4964e932 | 18170 | given directory. If the delivery is successful, the file is renamed into the |
495ae4b0 PH |
18171 | \(new)\ subdirectory. |
18172 | ||
18173 | In the file name, <<stime>> is the current time of day in seconds, and | |
18174 | <<mtime>> is the microsecond fraction of the time. After a maildir delivery, | |
18175 | Exim checks that the time-of-day clock has moved on by at least one microsecond | |
18176 | before terminating the delivery process. This guarantees uniqueness for the | |
18177 | file name. However, as a precaution, Exim calls \*stat()*\ for the file before | |
18178 | opening it. If any response other than \\ENOENT\\ (does not exist) is given, | |
18179 | Exim waits 2 seconds and tries again, up to \maildir@_retries\ times. | |
18180 | ||
18181 | .index quota||in maildir delivery | |
18182 | .index maildir++ | |
18183 | If Exim is required to check a \quota\ setting before a maildir delivery, and | |
18184 | \quota@_directory\ is not set, it looks for a file called \(maildirfolder)\ in | |
18185 | the maildir directory (alongside \(new)\, \(cur)\, \(tmp)\). If this exists, | |
18186 | Exim assumes the directory is a maildir++ folder directory, which is one level | |
18187 | down from the user's top level mailbox directory. This causes it to start at | |
18188 | the parent directory instead of the current directory when calculating the | |
18189 | amount of space used. | |
18190 | ||
d43194df PH |
18191 | .em |
18192 | One problem with delivering into a multi-file mailbox is that it is | |
18193 | computationally expensive to compute the size of the mailbox for quota | |
18194 | checking. Various approaches have been taken to reduce the amount of work | |
18195 | needed. The next two sections describe two of them. A third alternative is to | |
18196 | use some external process for maintaining the size data, and use the expansion | |
18197 | of the \mailbox@_size\ option as a way of importing it into Exim. | |
18198 | .nem | |
18199 | ||
495ae4b0 PH |
18200 | |
18201 | .section Using tags to record message sizes | |
4964e932 | 18202 | If \maildir@_tag\ is set, the string is expanded for each delivery. |
495ae4b0 PH |
18203 | When the maildir file is renamed into the \(new)\ sub-directory, the |
18204 | tag is added to its name. However, if adding the tag takes the length of the | |
18205 | name to the point where the test \*stat()*\ call fails with \\ENAMETOOLONG\\, | |
4964e932 | 18206 | the tag is dropped and the maildir file is created with no tag. |
495ae4b0 PH |
18207 | |
18208 | Tags can be used to encode the size of files in their names; see | |
4964e932 | 18209 | \quota@_size@_regex\ above for an example. The expansion of \maildir@_tag\ |
495ae4b0 PH |
18210 | happens after the message has been written. The value of the \$message@_size$\ |
18211 | variable is set to the number of bytes actually written. If the expansion is | |
18212 | forced to fail, the tag is ignored, but a non-forced failure causes delivery to | |
18213 | be deferred. The expanded tag may contain any printing characters except `/'. | |
18214 | Non-printing characters in the string are ignored; if the resulting string is | |
18215 | empty, it is ignored. If it starts with an alphanumeric character, a leading | |
18216 | colon is inserted. | |
18217 | ||
18218 | ||
495ae4b0 PH |
18219 | .section Using a maildirsize file |
18220 | .index quota||in maildir delivery | |
18221 | .index maildir format||\(maildirsize)\ file | |
18222 | If \maildir@_use@_size@_file\ is true, Exim implements the maildir++ rules for | |
18223 | storing quota and message size information in a file called \(maildirsize)\ | |
18224 | within the maildir directory. If this file does not exist, Exim creates it, | |
18225 | setting the quota from the \quota\ option of the transport. If the maildir | |
18226 | directory itself does not exist, it is created before any attempt to write a | |
18227 | \(maildirsize)\ file. | |
18228 | ||
18229 | The \(maildirsize)\ file is used to hold information about the sizes of | |
18230 | messages in the maildir, thus speeding up quota calculations. The quota value | |
18231 | in the file is just a cache; if the quota is changed in the transport, the new | |
18232 | value overrides the cached value when the next message is delivered. The cache | |
18233 | is maintained for the benefit of other programs that access the maildir and | |
18234 | need to know the quota. | |
18235 | ||
18236 | If the \quota\ option in the transport is unset or zero, the \(maildirsize)\ | |
18237 | file is maintained (with a zero quota setting), but no quota is imposed. | |
18238 | ||
18239 | A regular expression is available for controlling which directories in the | |
4964e932 | 18240 | maildir participate in quota calculations. See the description of the |
495ae4b0 | 18241 | \maildir@_quota@_directory@_regex\ option above for details. |
495ae4b0 PH |
18242 | |
18243 | ||
18244 | .section Mailstore delivery | |
18245 | .index mailstore format||description of | |
18246 | If the \mailstore@_format\ option is true, each message is written as two files | |
18247 | in the given directory. A unique base name is constructed from the message id | |
18248 | and the current delivery process, and the files that are written use this base | |
18249 | name plus the suffixes \(.env)\ and \(.msg)\. The \(.env)\ file contains the | |
18250 | message's envelope, and the \(.msg)\ file contains the message itself. | |
18251 | ||
18252 | During delivery, the envelope is first written to a file with the suffix | |
18253 | \(.tmp)\. The \(.msg)\ file is then written, and when it is complete, the | |
18254 | \(.tmp)\ file is renamed as the \(.env)\ file. Programs that access messages in | |
18255 | mailstore format should wait for the presence of both a \(.msg)\ and a \(.env)\ | |
18256 | file before accessing either of them. An alternative approach is to wait for | |
18257 | the absence of a \(.tmp)\ file. | |
18258 | ||
18259 | The envelope file starts with any text defined by the \mailstore@_prefix\ | |
18260 | option, expanded and terminated by a newline if there isn't one. Then follows | |
18261 | the sender address on one line, then all the recipient addresses, one per line. | |
18262 | There can be more than one recipient only if the \batch@_max\ option is set | |
18263 | greater than one. Finally, \mailstore@_suffix\ is expanded and the result | |
18264 | appended to the file, followed by a newline if it does not end with one. | |
18265 | ||
18266 | If expansion of \mailstore@_prefix\ or \mailstore@_suffix\ ends with a forced | |
18267 | failure, it is ignored. Other expansion errors are treated as serious | |
18268 | configuration errors, and delivery is deferred. | |
18269 | ||
18270 | ||
18271 | .section Non-special new file delivery | |
18272 | If neither \maildir@_format\ nor \mailstore@_format\ is set, a single new file | |
18273 | is created directly in the named directory. For example, when delivering | |
18274 | messages into files in batched SMTP format for later delivery to some host (see | |
18275 | section ~~SECTbatchSMTP), a setting such as | |
18276 | .display asis | |
18277 | directory = /var/bsmtp/$host | |
18278 | .endd | |
18279 | might be used. A message is written to a file with a temporary name, which is | |
18280 | then renamed when the delivery is complete. The final name is obtained by | |
18281 | expanding the contents of the \directory@_file\ option. | |
18282 | ||
18283 | ||
18284 | ||
18285 | ||
18286 | ||
18287 | . | |
18288 | . | |
18289 | . | |
18290 | . | |
18291 | . ============================================================================ | |
18292 | .chapter The autoreply transport | |
18293 | .set runningfoot "autoreply transport" | |
18294 | .index transports||\%autoreply%\ | |
18295 | .index \%autoreply%\ transport | |
18296 | The \%autoreply%\ transport is not a true transport in that it does not cause | |
d43194df PH |
18297 | the message to be transmitted. Instead, it generates a new mail message. |
18298 | .em | |
18299 | If the router that passes the message to this transport does not have the | |
18300 | \unseen\ option set, the original message (for the current recipient) is not | |
18301 | delivered anywhere. However, when the \unseen\ option is set on the router that | |
18302 | passes the message to this transport, routing of the address continues, so | |
18303 | another router can set up a normal message delivery. | |
18304 | .nem | |
18305 | ||
18306 | The \%autoreply%\ transport is usually run as the result of mail filtering, a | |
18307 | `vacation' message being the standard example. However, it can also be run | |
18308 | directly from a router like any other transport. To reduce the possibility of | |
18309 | message cascades, messages created by the \%autoreply%\ transport always have | |
18310 | empty envelope sender addresses, like bounce messages. | |
495ae4b0 PH |
18311 | |
18312 | The parameters of the message to be sent can be specified in the configuration | |
18313 | by options described below. However, these are used only when the address | |
18314 | passed to the transport does not contain its own reply information. When the | |
4964e932 | 18315 | transport is run as a consequence of a |
495ae4b0 PH |
18316 | \mail\ |
18317 | or \vacation\ command in a filter file, the parameters of the message are | |
18318 | supplied by the filter, and passed with the address. The transport's options | |
18319 | that define the message are then ignored (so they are not usually set in this | |
18320 | case). The message is specified entirely by the filter or by the transport; it | |
18321 | is never built from a mixture of options. However, the \file@_optional\, | |
18322 | \mode\, and \return@_message\ options apply in all cases. | |
18323 | ||
18324 | \%Autoreply%\ is implemented as a local transport. When used as a result of a | |
18325 | command in a user's filter file, \%autoreply%\ normally runs under the uid and | |
18326 | gid of the user, and with appropriate current and home directories (see chapter | |
18327 | ~~CHAPenvironment). | |
18328 | ||
18329 | There is a subtle difference between routing a message to a \%pipe%\ transport | |
18330 | that generates some text to be returned to the sender, and routing it to an | |
18331 | \%autoreply%\ transport. This difference is noticeable only if more than one | |
18332 | address from the same message is so handled. In the case of a pipe, the | |
18333 | separate outputs from the different addresses are gathered up and returned to | |
18334 | the sender in a single message, whereas if \%autoreply%\ is used, a separate | |
18335 | message is generated for each address that is passed to it. | |
18336 | ||
18337 | Non-printing characters are not permitted in the header lines generated for the | |
18338 | message that \%autoreply%\ creates, with the exception of newlines that are | |
4964e932 | 18339 | immediately followed by whitespace. If any non-printing characters are found, |
495ae4b0 PH |
18340 | the transport defers. |
18341 | Whether characters with the top bit set count as printing characters or not is | |
18342 | controlled by the \print@_topbitchars\ global option. | |
18343 | ||
18344 | If any of the generic options for manipulating headers (for example, | |
18345 | \headers@_add\) are set on an \%autoreply%\ transport, they apply to the copy of | |
18346 | the original message that is included in the generated message when | |
18347 | \return@_message\ is set. They do not apply to the generated message itself. | |
18348 | ||
18349 | If the \%autoreply%\ transport receives return code 2 from Exim when it submits | |
18350 | the message, indicating that there were no recipients, it does not treat this | |
18351 | as an error. This means that autoreplies sent to \$sender@_address$\ when this | |
18352 | is empty (because the incoming message is a bounce message) do not cause | |
18353 | problems. They are just discarded. | |
18354 | ||
18355 | ||
18356 | .section Private options for autoreply | |
18357 | ||
d43194df | 18358 | .startconf autoreply |
495ae4b0 PH |
18359 | .index options||\%autoreply%\ transport |
18360 | .conf bcc string$**$ unset | |
18361 | This specifies the addresses that are to receive `blind carbon copies' of the | |
18362 | message when the message is specified by the transport. | |
18363 | ||
18364 | .conf cc string$**$ unset | |
18365 | This specifies recipients of the message and the contents of the ::Cc:: header | |
18366 | when the message is specified by the transport. | |
18367 | ||
18368 | .conf file string$**$ unset | |
18369 | The contents of the file are sent as the body of the message when the message | |
18370 | is specified by the transport. If both \file\ and \text\ are set, the text | |
18371 | string comes first. | |
18372 | ||
18373 | .conf file@_expand boolean false | |
18374 | If this is set, the contents of the file named by the \file\ option are | |
18375 | subjected to string expansion as they are added to the message. | |
18376 | ||
18377 | .conf file@_optional boolean false | |
18378 | If this option is true, no error is generated if the file named by the \file\ | |
18379 | option or passed with the address does not exist or cannot be read. | |
18380 | ||
18381 | .conf from string$**$ unset | |
18382 | This specifies the contents of the ::From:: header when the message is specified | |
18383 | by the transport. | |
18384 | ||
18385 | .conf headers string$**$ unset | |
18386 | This specifies additional RFC 2822 headers that are to be added to the message when | |
18387 | the message is specified by the transport. Several can be given by using `@\n' | |
18388 | to separate them. There is no check on the format. | |
18389 | ||
18390 | .conf log string$**$ unset | |
18391 | This option names a file in which a record of every message sent is logged when | |
18392 | the message is specified by the transport. | |
18393 | ||
18394 | .conf mode "octal integer" 0600 | |
18395 | If either the log file or the `once' file has to be created, this mode is used. | |
18396 | ||
d43194df PH |
18397 | .em |
18398 | .conf never@_mail "address list$**$" unset | |
18399 | If any run of the transport creates a message with a recipient that matches any | |
18400 | item in the list, that recipient is quietly discarded. If all recipients are | |
18401 | discarded, no message is created. | |
18402 | .nem | |
18403 | ||
495ae4b0 | 18404 | .conf once string$**$ unset |
4964e932 | 18405 | This option names a file or DBM database in which a record of each |
495ae4b0 PH |
18406 | ::To:: recipient is kept when the message is specified by the transport. |
18407 | \**Note**\: This does not apply to ::Cc:: or ::Bcc:: recipients. | |
18408 | If \once@_file@_size\ is not set, a DBM database is used, and it is allowed to | |
18409 | grow as large as necessary. If a potential recipient is already in the | |
18410 | database, no message is sent by default. However, if \once@_repeat\ specifies a | |
18411 | time greater than zero, the message is sent if that much time has elapsed since | |
18412 | a message was last sent to this recipient. If \once\ is unset, the message is | |
18413 | always sent. | |
18414 | ||
18415 | If \once@_file@_size\ is set greater than zero, it changes the way Exim | |
18416 | implements the \once\ option. Instead of using a DBM file to record every | |
18417 | recipient it sends to, it uses a regular file, whose size will never get larger | |
18418 | than the given value. In the file, it keeps a linear list of recipient | |
18419 | addresses and times at which they were sent messages. If the file is full when | |
18420 | a new address needs to be added, the oldest address is dropped. If | |
18421 | \once@_repeat\ is not set, this means that a given recipient may receive | |
18422 | multiple messages, but at unpredictable intervals that depend on the rate of | |
18423 | turnover of addresses in the file. If \once@_repeat\ is set, it specifies a | |
18424 | maximum time between repeats. | |
18425 | ||
18426 | .conf once@_file@_size integer 0 | |
18427 | See \once\ above. | |
18428 | ||
18429 | .conf once@_repeat time$**$ 0s | |
18430 | See \once\ above. | |
18431 | After expansion, the value of this option must be a valid time value. | |
18432 | ||
18433 | .conf reply@_to string$**$ unset | |
18434 | This specifies the contents of the ::Reply-To:: header when the message is | |
18435 | specified by the transport. | |
18436 | ||
18437 | .conf return@_message boolean false | |
18438 | If this is set, a copy of the original message is returned with the new | |
18439 | message, subject to the maximum size set in the \return@_size@_limit\ global | |
18440 | configuration option. | |
18441 | ||
18442 | .conf subject string$**$ unset | |
18443 | This specifies the contents of the ::Subject:: header when the message is | |
18444 | specified by the transport. | |
d43194df PH |
18445 | .em |
18446 | It is tempting to quote the original subject in automatic responses. For | |
18447 | example: | |
18448 | .display asis | |
18449 | subject = Re: $h_subject: | |
18450 | .endd | |
18451 | There is a danger in doing this, however. It may allow a third party to | |
18452 | subscribe your users to an opt-in mailing list, provided that the list accepts | |
18453 | bounce messages as subscription confirmations. Well-managed lists require a | |
18454 | non-bounce message to confirm a subscription, so the danger is relatively | |
18455 | small. | |
18456 | .nem | |
495ae4b0 PH |
18457 | |
18458 | .conf text string$**$ unset | |
18459 | This specifies a single string to be used as the body of the message when the | |
18460 | message is specified by the transport. If both \text\ and \file\ are set, the | |
18461 | text comes first. | |
18462 | ||
18463 | .conf to string$**$ unset | |
18464 | This specifies recipients of the message and the contents of the ::To:: header | |
18465 | when the message is specified by the transport. | |
18466 | ||
18467 | .endconf | |
18468 | ||
18469 | ||
18470 | ||
18471 | . | |
18472 | . | |
18473 | . | |
18474 | . | |
18475 | . ============================================================================ | |
18476 | .chapter The lmtp transport | |
18477 | .set runningfoot "lmtp transport" | |
18478 | .index transports||\%lmtp%\ | |
18479 | .index \%lmtp%\ transport | |
18480 | .index LMTP||over a pipe | |
18481 | .index LMTP||over a socket | |
18482 | .rset CHAPLMTP "~~chapter" | |
18483 | The \%lmtp%\ transport runs the LMTP protocol (RFC 2033) over a pipe to a | |
18484 | specified command | |
18485 | or by interacting with a Unix domain socket. | |
18486 | This transport is something of a cross between the \%pipe%\ and \%smtp%\ | |
18487 | transports. Exim also has support for using LMTP over TCP/IP; this is | |
18488 | implemented as an option for the \%smtp%\ transport. Because LMTP is expected | |
18489 | to be of minority interest, the default build-time configure in \(src/EDITME)\ | |
18490 | has it commented out. You need to ensure that | |
18491 | .display asis | |
18492 | TRANSPORT_LMTP=yes | |
18493 | .endd | |
18494 | is present in your \(Local/Makefile)\ in order to have the \%lmtp%\ transport | |
18495 | included in the Exim binary. | |
18496 | ||
18497 | The private options of the \%lmtp%\ transport are as follows: | |
18498 | ||
d43194df | 18499 | .startconf lmtp |
495ae4b0 PH |
18500 | .index options||\%lmtp%\ transport |
18501 | ||
18502 | .conf batch@_id string$**$ unset | |
18503 | See the description of local delivery batching in chapter ~~CHAPbatching. | |
18504 | ||
18505 | .conf batch@_max integer 1 | |
18506 | This limits the number of addresses that can be handled in a single delivery. | |
18507 | Most LMTP servers can handle several addresses at once, so it is normally a | |
18508 | good idea to increase this value. See the description of local delivery | |
18509 | batching in chapter ~~CHAPbatching. | |
18510 | ||
18511 | .conf command string$**$ unset | |
18512 | This option must be set if \socket\ is not set. | |
18513 | The string is a command which is run in a separate process. It is split up into | |
18514 | a command name and list of arguments, each of which is separately expanded (so | |
18515 | expansion cannot change the number of arguments). The command is run directly, | |
18516 | not via a shell. The message is passed to the new process using the standard | |
18517 | input and output to operate the LMTP protocol. | |
18518 | ||
18519 | .conf socket string$**$ unset | |
4964e932 PH |
18520 | This option must be set if \command\ is not set. The result of expansion must |
18521 | be the name of a Unix domain socket. The transport connects to the socket and | |
495ae4b0 PH |
18522 | delivers the message to it using the LMTP protocol. |
18523 | ||
18524 | .conf timeout time 5m | |
4964e932 | 18525 | The transport is aborted if the created process |
495ae4b0 PH |
18526 | or Unix domain socket |
18527 | does not respond to LMTP commands or message input within this timeout. | |
18528 | ||
18529 | .endconf | |
18530 | ||
18531 | Here is an example of a typical LMTP transport: | |
18532 | .display asis | |
18533 | lmtp: | |
18534 | driver = lmtp | |
18535 | command = /some/local/lmtp/delivery/program | |
18536 | batch_max = 20 | |
18537 | user = exim | |
18538 | .endd | |
18539 | This delivers up to 20 addresses at a time, in a mixture of domains if | |
18540 | necessary, running as the user \*exim*\. | |
18541 | ||
18542 | ||
18543 | ||
18544 | . | |
18545 | . | |
18546 | . | |
18547 | . | |
18548 | . ============================================================================ | |
18549 | .chapter The pipe transport | |
18550 | .rset CHAPpipetransport "~~chapter" | |
18551 | .set runningfoot "pipe transport" | |
18552 | .index transports||\%pipe%\ | |
18553 | .index \%pipe%\ transport | |
18554 | The \%pipe%\ transport is used to deliver messages via a pipe to a command | |
d43194df PH |
18555 | running in another process. |
18556 | .em | |
18557 | One example is the | |
18558 | use of \%pipe%\ as a pseudo-remote transport for passing messages to some other | |
18559 | delivery mechanism (such as UUCP). Another is the use by individual users to | |
18560 | automatically process their incoming messages. The \%pipe%\ transport can be | |
18561 | used in one of the following ways: | |
18562 | .nem | |
495ae4b0 | 18563 | .numberpars $. |
d43194df | 18564 | A router routes one address to a transport in the normal way, and the transport |
495ae4b0 | 18565 | is configured as a \%pipe%\ transport. In this case, \$local@_part$\ contains |
d43194df PH |
18566 | the local part of the address (as usual), and the command that is run is |
18567 | specified by the \command\ option on the transport. | |
18568 | .nextp | |
18569 | .em | |
18570 | If the \batch@_max\ option is set greater than 1 (the default), the transport | |
18571 | can be called upon to handle more than one address in a single run. In this | |
18572 | case, \$local@_part$\ is not set (because it is not unique). However, the | |
18573 | pseudo-variable \$pipe@_addresses$\ (described in section ~~SECThowcommandrun | |
18574 | below) contains all the addresses that are being handled. | |
18575 | .nem | |
495ae4b0 PH |
18576 | .nextp |
18577 | A router redirects an address directly to a pipe command (for example, from an | |
18578 | alias or forward file). In this case, \$local@_part$\ contains the local part | |
18579 | that was redirected, and \$address@_pipe$\ contains the text of the pipe | |
18580 | command itself. The \command\ option on the transport is ignored. | |
18581 | .endp | |
18582 | ||
4964e932 PH |
18583 | The \%pipe%\ transport is a non-interactive delivery method. Exim can also |
18584 | deliver messages over pipes using the LMTP interactive protocol. This is | |
495ae4b0 PH |
18585 | implemented by the \%lmtp%\ transport. |
18586 | ||
18587 | In the case when \%pipe%\ is run as a consequence of an entry in a local user's | |
18588 | \(.forward)\ file, the command runs under the uid and gid of that user. In | |
18589 | other cases, the uid and gid have to be specified explicitly, either on the | |
18590 | transport or on the router that handles the address. Current and `home' | |
18591 | directories are also controllable. See chapter ~~CHAPenvironment for details of | |
18592 | the local delivery environment. | |
18593 | ||
d43194df PH |
18594 | |
18595 | .em | |
18596 | .section Concurrent delivery | |
18597 | If two messages arrive at almost the same time, and both are routed to a pipe | |
18598 | delivery, the two pipe transports may be run concurrently. You must ensure that | |
18599 | any pipe commands you set up are robust against this happening. If the commands | |
18600 | write to a file, the \exim@_lock\ utility might be of use. | |
18601 | .nem | |
18602 | ||
18603 | ||
495ae4b0 PH |
18604 | .section Returned status and data |
18605 | .index \%pipe%\ transport||returned data | |
18606 | If the command exits with a non-zero return code, the delivery is deemed to | |
18607 | have failed, unless either the \ignore@_status\ option is set (in which case | |
18608 | the return code is treated as zero), or the return code is one of those listed | |
18609 | in the \temp@_errors\ option, which are interpreted as meaning `try again | |
18610 | later'. In this case, delivery is deferred. Details of a permanent failure are | |
18611 | logged, but are not included in the bounce message, which merely contains | |
18612 | `local delivery failed'. | |
18613 | ||
18614 | If the return code is greater than 128 and the command being run is a shell | |
18615 | script, it normally means that the script was terminated by a signal whose | |
18616 | value is the return code minus 128. | |
18617 | ||
4964e932 PH |
18618 | If Exim is unable to run the command (that is, if \*execve()*\ fails), the |
18619 | return code is set to 127. This is the value that a shell returns if it is | |
18620 | asked to run a non-existent command. The wording for the log line suggests that | |
495ae4b0 PH |
18621 | a non-existent command may be the problem. |
18622 | ||
18623 | The \return@_output\ option can affect the result of a pipe delivery. If it is | |
18624 | set and the command produces any output on its standard output or standard | |
18625 | error streams, the command is considered to have failed, even if it gave a zero | |
18626 | return code or if \ignore@_status\ is set. The output from the command is | |
18627 | included as part of the bounce message. The \return@_fail@_output\ option is | |
18628 | similar, except that output is returned only when the command exits with a | |
18629 | failure return code, that is, a value other than zero or a code that matches | |
18630 | \temp@_errors\. | |
18631 | ||
18632 | ||
18633 | .section How the command is run | |
18634 | .rset SECThowcommandrun "~~chapter.~~section" | |
18635 | .index \%pipe%\ transport||path for command | |
18636 | The command line is (by default) broken down into a command name and arguments | |
18637 | by the \%pipe%\ transport itself. The \allow@_commands\ and \restrict@_to@_path\ | |
18638 | options can be used to restrict the commands that may be run. | |
18639 | .index quoting||in pipe command | |
18640 | Unquoted arguments are delimited by white space. If an argument appears in | |
18641 | double quotes, backslash is interpreted as an escape character in the usual | |
18642 | way. If an argument appears in single quotes, no escaping is done. | |
18643 | ||
18644 | String expansion is applied to the command line except when it comes from a | |
18645 | traditional \(.forward)\ file (commands from a filter file are expanded). The | |
18646 | expansion is applied to each argument in turn rather than to the whole line. | |
18647 | For this reason, any string expansion item that contains white space must be | |
18648 | quoted so as to be contained within a single argument. A setting such as | |
18649 | .display asis | |
18650 | command = /some/path ${if eq{$local_part}{postmaster}{xxx}{yyy}} | |
18651 | .endd | |
18652 | will not work, because the expansion item gets split between several | |
18653 | arguments. You have to write | |
18654 | .display asis | |
18655 | command = /some/path "${if eq{$local_part}{postmaster}{xxx}{yyy}}" | |
18656 | .endd | |
18657 | to ensure that it is all in one argument. The expansion is done in this way, | |
18658 | argument by argument, so that the number of arguments cannot be changed as a | |
18659 | result of expansion, and quotes or backslashes in inserted variables do not | |
18660 | interact with external quoting. | |
18661 | ||
18662 | .index transport||filter | |
18663 | .index filter||transport filter | |
18664 | Special handling takes place when an argument consists of precisely the text | |
18665 | `$tt{@$pipe@_addresses}'. This is not a general expansion variable; the only | |
18666 | place this string is recognized is when it appears as an argument for a pipe or | |
18667 | transport filter command. It causes each address that is being handled to be | |
18668 | inserted in the argument list at that point $it{as a separate argument}. This | |
18669 | avoids any problems with spaces or shell metacharacters, and is of use when a | |
18670 | \%pipe%\ transport is handling groups of addresses in a batch. | |
18671 | ||
18672 | After splitting up into arguments and expansion, the resulting command is run | |
18673 | in a subprocess directly from the transport, $it{not} under a shell. The | |
18674 | message that is being delivered is supplied on the standard input, and the | |
18675 | standard output and standard error are both connected to a single pipe that is | |
18676 | read by Exim. The \max@_output\ option controls how much output the command may | |
18677 | produce, and the \return@_output\ and \return@_fail@_output\ options control | |
18678 | what is done with it. | |
18679 | ||
18680 | Not running the command under a shell (by default) lessens the security risks | |
18681 | in cases when a command from a user's filter file is built out of data that was | |
18682 | taken from an incoming message. If a shell is required, it can of course be | |
18683 | explicitly specified as the command to be run. However, there are circumstances | |
18684 | where existing commands (for example, in \(.forward)\ files) expect to be run | |
18685 | under a shell and cannot easily be modified. To allow for these cases, there is | |
18686 | an option called \use@_shell\, which changes the way the \%pipe%\ transport | |
18687 | works. Instead of breaking up the command line as just described, it expands it | |
18688 | as a single string and passes the result to \(/bin/sh)\. The | |
18689 | \restrict@_to@_path\ option and the \$pipe@_addresses$\ facility cannot be used | |
18690 | with \use@_shell\, and the whole mechanism is inherently less secure. | |
18691 | ||
18692 | ||
18693 | .section Environment variables | |
18694 | .rset SECTpipeenv "~~chapter.~~section" | |
18695 | .index \%pipe%\ transport||environment for command | |
18696 | .index environment for pipe transport | |
18697 | The environment variables listed below are set up when the command is invoked. | |
18698 | This list is a compromise for maximum compatibility with other MTAs. Note that | |
18699 | the \environment\ option can be used to add additional variables to this | |
18700 | environment. | |
18701 | .display flow | |
18702 | .tabs 20 | |
18703 | DOMAIN $t $rm{the domain of the address} | |
18704 | HOME $t $rm{the home directory, if set} | |
18705 | HOST $t $rm{the host name when called from a router (see below)} | |
18706 | LOCAL@_PART $t $rm{see below} | |
18707 | LOCAL@_PART@_PREFIX $t $rm{see below} | |
18708 | LOCAL@_PART@_SUFFIX $t $rm{see below} | |
18709 | LOGNAME $t $rm{see below} | |
18710 | MESSAGE@_ID $t $rm{the message's id} | |
18711 | PATH $t $rm{as specified by the \path\ option below} | |
18712 | QUALIFY@_DOMAIN $t $rm{the sender qualification domain} | |
18713 | RECIPIENT $t $rm{the complete recipient address} | |
18714 | SENDER $t $rm{the sender of the message (empty if a bounce)} | |
18715 | SHELL $t `$tt{/bin/sh}' | |
18716 | TZ $t $rm{the value of the \timezone\ option, if set} | |
18717 | USER $t $rm{see below} | |
18718 | .endd | |
18719 | ||
18720 | When a \%pipe%\ transport is called directly from (for example) an \%accept%\ | |
18721 | router, \\LOCAL@_PART\\ is set to the local part of the address. When it is | |
18722 | called as a result of a forward or alias expansion, \\LOCAL@_PART\\ is set to | |
18723 | the local part of the address that was expanded. In both cases, any affixes are | |
18724 | removed from the local part, and made available in \\LOCAL@_PART@_PREFIX\\ and | |
18725 | \\LOCAL@_PART@_SUFFIX\\, respectively. \\LOGNAME\\ and \\USER\\ are set to the | |
18726 | same value as \\LOCAL@_PART\\ for compatibility with other MTAs. | |
18727 | ||
18728 | .index \\HOST\\ | |
18729 | \\HOST\\ is set only when a \%pipe%\ transport is called from a router that | |
18730 | associates hosts with an address, typically when using \%pipe%\ as a | |
18731 | pseudo-remote transport. \\HOST\\ is set to the first host name specified by | |
18732 | the router. | |
18733 | ||
18734 | .index \\HOME\\ | |
18735 | If the transport's generic \home@_directory\ option is set, its value is used | |
18736 | for the \\HOME\\ environment variable. Otherwise, a home directory may be set | |
18737 | by the router's \transport@_home@_directory\ option, which defaults to the | |
18738 | user's home directory if \check@_local@_user\ is set. | |
18739 | ||
18740 | .section Private options for pipe | |
18741 | .index options||\%pipe%\ transport | |
d43194df PH |
18742 | |
18743 | .startconf pipe | |
495ae4b0 PH |
18744 | |
18745 | .conf allow@_commands "string list$**$" unset | |
18746 | .index \%pipe%\ transport||permitted commands | |
18747 | The string is expanded, and is then interpreted as a colon-separated list of | |
18748 | permitted commands. If \restrict@_to@_path\ is not set, the only commands | |
18749 | permitted are those in the \allow@_commands\ list. They need not be absolute | |
18750 | paths; the \path\ option is still used for relative paths. If | |
18751 | \restrict@_to@_path\ is set with \allow@_commands\, the command must either be | |
18752 | in the \allow@_commands\ list, or a name without any slashes that is found on | |
18753 | the path. In other words, if neither \allow@_commands\ nor \restrict@_to@_path\ | |
18754 | is set, there is no restriction on the command, but otherwise only commands | |
18755 | that are permitted by one or the other are allowed. For example, if | |
18756 | .display asis | |
18757 | allow_commands = /usr/bin/vacation | |
18758 | .endd | |
18759 | and \restrict@_to@_path\ is not set, the only permitted command is | |
18760 | \(/usr/bin/vacation)\. The \allow@_commands\ option may not be set if | |
18761 | \use@_shell\ is set. | |
18762 | ||
18763 | .conf batch@_id string$**$ unset | |
18764 | See the description of local delivery batching in chapter ~~CHAPbatching. | |
18765 | ||
18766 | .conf batch@_max integer 1 | |
18767 | This limits the number of addresses that can be handled in a single delivery. | |
18768 | See the description of local delivery batching in chapter ~~CHAPbatching. | |
18769 | ||
18770 | .conf check@_string string unset | |
18771 | As \%pipe%\ writes the message, the start of each line is tested for matching | |
18772 | \check@_string\, and if it does, the initial matching characters are replaced | |
18773 | by the contents of \escape@_string\, provided both are set. The value of | |
18774 | \check@_string\ is a literal string, not a regular expression, and the case of | |
18775 | any letters it contains is significant. When \use@_bsmtp\ is set, the contents | |
18776 | of \check@_string\ and \escape@_string\ are forced to values that implement the | |
18777 | SMTP escaping protocol. Any settings made in the configuration file are | |
18778 | ignored. | |
18779 | ||
18780 | .conf command string$**$ unset | |
18781 | This option need not be set when \%pipe%\ is being used to deliver to pipes | |
18782 | obtained directly from address redirections. In other cases, the option must be | |
18783 | set, to provide a command to be run. It need not yield an absolute path (see | |
18784 | the \path\ option below). The command is split up into separate arguments by | |
18785 | Exim, and each argument is separately expanded, as described in section | |
18786 | ~~SECThowcommandrun above. | |
18787 | ||
18788 | .conf environment string$**$ unset | |
18789 | .index \%pipe%\ transport||environment for command | |
18790 | .index environment for \%pipe%\ transport | |
18791 | This option is used to add additional variables to the environment in which the | |
18792 | command runs (see section ~~SECTpipeenv for the default list). Its value is a | |
18793 | string which is expanded, and then interpreted as a colon-separated list of | |
18794 | environment settings of the form `<<name>>=<<value>>'. | |
18795 | ||
18796 | .conf escape@_string string unset | |
18797 | See \check@_string\ above. | |
18798 | ||
18799 | .conf freeze@_exec@_fail boolean false | |
18800 | .index exec failure | |
18801 | .index failure of exec | |
18802 | .index \%pipe%\ transport||failure of exec | |
18803 | Failure to exec the command in a pipe transport is by default treated like | |
18804 | any other failure while running the command. However, if \freeze@_exec@_fail\ | |
18805 | is set, failure to exec is treated specially, and causes the message to be | |
18806 | frozen, whatever the setting of \ignore@_status\. | |
18807 | ||
18808 | .conf ignore@_status boolean false | |
18809 | If this option is true, the status returned by the subprocess that is set up to | |
18810 | run the command is ignored, and Exim behaves as if zero had been returned. | |
4964e932 | 18811 | Otherwise, a non-zero status |
495ae4b0 PH |
18812 | or termination by signal |
18813 | causes an error return from the transport unless the status value is one of | |
18814 | those listed in \temp@_errors\; these cause the delivery to be deferred and | |
18815 | tried again later. | |
18816 | ||
18817 | .conf log@_defer@_output boolean false | |
18818 | .index \%pipe%\ transport||logging output | |
18819 | If this option is set, and the status returned by the command is | |
18820 | one of the codes listed in \temp@_errors\ (that is, delivery was deferred), | |
18821 | and any output was produced, the first line of it is written to the main log. | |
18822 | ||
18823 | .conf log@_fail@_output boolean false | |
18824 | If this option is set, and the command returns any output, and also ends with a | |
18825 | return code that is neither zero nor one of the return codes listed in | |
18826 | \temp@_errors\ (that is, the delivery failed), the first line of output is | |
18827 | written to the main log. | |
8408f763 PH |
18828 | .em |
18829 | This option and \log@_output\ are mutually exclusive. Only one of them may be | |
18830 | set. | |
18831 | .nem | |
495ae4b0 PH |
18832 | |
18833 | .conf log@_output boolean false | |
18834 | If this option is set and the command returns any output, the first line of | |
18835 | output is written to the main log, whatever the return code. | |
8408f763 PH |
18836 | .em |
18837 | This option and \log@_fail@_output\ are mutually exclusive. Only one of them | |
18838 | may be set. | |
18839 | .nem | |
495ae4b0 PH |
18840 | |
18841 | .conf max@_output integer 20K | |
18842 | This specifies the maximum amount of output that the command may produce on its | |
18843 | standard output and standard error file combined. If the limit is exceeded, the | |
18844 | process running the command is killed. This is intended as a safety measure to | |
18845 | catch runaway processes. The limit is applied independently of the settings of | |
18846 | the options that control what is done with such output (for example, | |
18847 | \return@_output\). Because of buffering effects, the amount of output may | |
18848 | exceed the limit by a small amount before Exim notices. | |
18849 | ||
18850 | .conf message@_prefix string$**$ "see below" | |
18851 | The string specified here is expanded and output at the start of every message. | |
18852 | The default is unset if \use@_bsmtp\ is set. Otherwise it is | |
18853 | .display asis | |
18854 | message_prefix = \ | |
18855 | From ${if def:return_path{$return_path}{MAILER-DAEMON}}\ | |
18856 | ${tod_bsdinbox}\n | |
18857 | .endd | |
18858 | .index Cyrus | |
18859 | .index \tmail\ | |
18860 | .index `From' line | |
18861 | This is required by the commonly used \(/usr/bin/vacation)\ program. | |
18862 | However, it must $it{not} be present if delivery is to the Cyrus IMAP server, | |
18863 | or to the \tmail\ local delivery agent. The prefix can be suppressed by setting | |
18864 | .display asis | |
18865 | message_prefix = | |
18866 | .endd | |
18867 | ||
18868 | .conf message@_suffix string$**$ "see below" | |
18869 | The string specified here is expanded and output at the end of every message. | |
18870 | The default is unset if \use@_bsmtp\ is set. Otherwise it is a single newline. | |
18871 | The suffix can be suppressed by setting | |
18872 | .display asis | |
18873 | message_suffix = | |
18874 | .endd | |
18875 | ||
18876 | .conf path string $tt{/usr/bin} | |
18877 | This option specifies the string that is set up in the \\PATH\\ environment | |
18878 | variable of the subprocess. If the \command\ option does not yield an absolute | |
18879 | path name, the command is sought in the \\PATH\\ directories, in the usual way. | |
4964e932 | 18880 | \**Warning**\: This does not apply to a command specified as a transport |
495ae4b0 PH |
18881 | filter. |
18882 | ||
18883 | .conf pipe@_as@_creator boolean false | |
18884 | .index uid (user id)||local delivery | |
18885 | If the generic \user\ option is not set and this option is true, the delivery | |
18886 | process is run under the uid that was in force when Exim was originally called | |
18887 | to accept the message. If the group id is not otherwise set (via the generic | |
18888 | \group\ option), the gid that was in force when Exim was originally called to | |
18889 | accept the message is used. | |
18890 | ||
18891 | .conf restrict@_to@_path boolean false | |
18892 | When this option is set, any command name not listed in \allow@_commands\ must | |
18893 | contain no slashes. The command is searched for only in the directories listed | |
18894 | in the \path\ option. This option is intended for use in the case when a pipe | |
18895 | command has been generated from a user's \(.forward)\ file. This is usually | |
18896 | handled by a \%pipe%\ transport called \address@_pipe\. | |
18897 | ||
18898 | .conf return@_fail@_output boolean false | |
18899 | If this option is true, and the command produced any output and ended with a | |
18900 | return code other than zero or one of the codes listed in \temp@_errors\ (that | |
18901 | is, the delivery failed), the output is returned in the bounce message. | |
18902 | However, if the message has a null sender (that is, it is itself a bounce | |
18903 | message), output from the command is discarded. | |
8408f763 PH |
18904 | .em |
18905 | This option and \return@_output\ are mutually exclusive. Only one of them may | |
18906 | be set. | |
18907 | .nem | |
495ae4b0 PH |
18908 | |
18909 | .conf return@_output boolean false | |
18910 | If this option is true, and the command produced any output, the delivery is | |
18911 | deemed to have failed whatever the return code from the command, and the output | |
18912 | is returned in the bounce message. Otherwise, the output is just discarded. | |
18913 | However, if the message has a null sender (that is, it is a bounce message), | |
18914 | output from the command is always discarded, whatever the setting of this | |
18915 | option. | |
8408f763 PH |
18916 | .em |
18917 | This option and \return@_fail@_output\ are mutually exclusive. Only one of them | |
18918 | may be set. | |
18919 | .nem | |
495ae4b0 PH |
18920 | |
18921 | .conf temp@_errors "string list" "see below" | |
18922 | .index \%pipe%\ transport||temporary failure | |
18923 | This option contains either a colon-separated list of numbers, or a single | |
4964e932 | 18924 | asterisk. If \ignore@_status\ is false |
495ae4b0 | 18925 | and \return@_output\ is not set, |
495ae4b0 PH |
18926 | and the command exits with a non-zero return code, the failure is treated as |
18927 | temporary and the delivery is deferred if the return code matches one of the | |
18928 | numbers, or if the setting is a single asterisk. Otherwise, non-zero return | |
18929 | codes are treated as permanent errors. The default setting contains the codes | |
18930 | defined by \\EX@_TEMPFAIL\\ and \\EX@_CANTCREAT\\ in \(sysexits.h)\. If Exim is | |
18931 | compiled on a system that does not define these macros, it assumes values of 75 | |
18932 | and 73, respectively. | |
18933 | ||
18934 | .conf timeout time 1h | |
18935 | If the command fails to complete within this time, it is killed. This normally | |
18936 | causes the delivery to fail. A zero time interval specifies no timeout. In | |
18937 | order to ensure that any subprocesses created by the command are also killed, | |
18938 | Exim makes the initial process a process group leader, and kills the whole | |
18939 | process group on a timeout. However, this can be defeated if one of the | |
18940 | processes starts a new process group. | |
18941 | ||
18942 | .conf umask "octal integer" 022 | |
18943 | This specifies the umask setting for the subprocess that runs the command. | |
18944 | ||
18945 | .conf use@_bsmtp boolean false | |
18946 | .index envelope sender | |
18947 | If this option is set true, the \%pipe%\ transport writes messages in `batch | |
18948 | SMTP' format, with the envelope sender and recipient(s) included as SMTP | |
18949 | commands. If you want to include a leading \\HELO\\ command with such messages, | |
18950 | you can do so by setting the \message@_prefix\ option. See section | |
18951 | ~~SECTbatchSMTP for details of batch SMTP. | |
18952 | ||
18953 | .conf use@_crlf boolean false | |
18954 | .index carriage return | |
18955 | .index linefeed | |
18956 | This option causes lines to be terminated with the two-character CRLF sequence | |
18957 | (carriage return, linefeed) instead of just a linefeed character. In the case | |
18958 | of batched SMTP, the byte sequence written to the pipe is then an exact image | |
18959 | of what would be sent down a real SMTP connection. | |
18960 | ||
18961 | The contents of the \message@_prefix\ and \message@_suffix\ options are written | |
18962 | verbatim, so must contain their own carriage return characters if these are | |
18963 | needed. Since the default values for both \message@_prefix\ and | |
18964 | \message@_suffix\ end with a single linefeed, their values | |
18965 | must | |
18966 | be changed to end with \"@\r@\n"\ if \use@_crlf\ is set. | |
18967 | ||
18968 | .conf use@_shell boolean false | |
18969 | If this option is set, it causes the command to be passed to \(/bin/sh)\ | |
18970 | instead of being run directly from the transport, as described in section | |
18971 | ~~SECThowcommandrun. This is less secure, but is needed in some situations | |
18972 | where the command is expected to be run under a shell and cannot easily be | |
18973 | modified. The \allow@_commands\ and \restrict@_to@_path\ options, and the | |
18974 | `$tt{@$pipe@_addresses}' facility are incompatible with \use@_shell\. The | |
18975 | command is expanded as a single string, and handed to \(/bin/sh)\ as data for | |
18976 | its \-c-\ option. | |
18977 | ||
18978 | .endconf | |
18979 | ||
18980 | .section Using an external local delivery agent | |
18981 | .index local delivery||using an external agent | |
18982 | .index \*procmail*\ | |
18983 | .index external local delivery | |
18984 | .index delivery||\*procmail*\ | |
18985 | .index delivery||by external agent | |
18986 | The \%pipe%\ transport can be used to pass all messages that require local | |
18987 | delivery to a separate local delivery agent such as \procmail\. When doing | |
18988 | this, care must be taken to ensure that the pipe is run under an appropriate | |
18989 | uid and gid. In some configurations one wants this to be a uid that is trusted | |
18990 | by the delivery agent to supply the correct sender of the message. It may be | |
18991 | necessary to recompile or reconfigure the delivery agent so that it trusts an | |
18992 | appropriate user. The following is an example transport and router | |
18993 | configuration for \procmail\: | |
18994 | .display asis | |
18995 | # transport | |
18996 | procmail_pipe: | |
18997 | driver = pipe | |
18998 | command = /usr/local/bin/procmail -d $local_part | |
18999 | return_path_add | |
19000 | delivery_date_add | |
19001 | envelope_to_add | |
19002 | check_string = "From " | |
19003 | escape_string = ">From " | |
19004 | user = $local_part | |
19005 | group = mail | |
19006 | .endd | |
19007 | .display asis | |
19008 | # router | |
19009 | procmail: | |
19010 | driver = accept | |
19011 | check_local_user | |
19012 | transport = procmail_pipe | |
19013 | .endd | |
19014 | ||
19015 | In this example, the pipe is run as the local user, but with the group set to | |
19016 | \*mail*\. An alternative is to run the pipe as a specific user such as \*mail*\ | |
19017 | or \*exim*\, but in this case you must arrange for \procmail\ to trust that | |
19018 | user to supply a correct sender address. If you do not specify either a \group\ | |
19019 | or a \user\ option, the pipe command is run as the local user. The home | |
19020 | directory is the user's home directory by default. | |
19021 | ||
19022 | Note that the command that the pipe transport runs does $it{not} begin with | |
19023 | .display asis | |
19024 | IFS=" " | |
19025 | .endd | |
19026 | as shown in the \procmail\ documentation, because Exim does not by default use | |
19027 | a shell to run pipe commands. | |
19028 | ||
19029 | .index Cyrus | |
19030 | The next example shows a transport and a router for a system where local | |
19031 | deliveries are handled by the Cyrus IMAP server. | |
19032 | .display asis | |
19033 | # transport | |
19034 | local_delivery_cyrus: | |
19035 | driver = pipe | |
19036 | command = /usr/cyrus/bin/deliver \ | |
19037 | -m ${substr_1:$local_part_suffix} -- $local_part | |
19038 | user = cyrus | |
19039 | group = mail | |
19040 | return_output | |
19041 | log_output | |
19042 | message_prefix = | |
19043 | message_suffix = | |
19044 | .endd | |
19045 | .display asis | |
19046 | # router | |
19047 | local_user_cyrus: | |
19048 | driver = accept | |
19049 | check_local_user | |
19050 | local_part_suffix = .* | |
19051 | transport = local_delivery_cyrus | |
19052 | .endd | |
19053 | Note the unsetting of \message@_prefix\ and \message@_suffix\, and the use of | |
19054 | \return@_output\ to cause any text written by Cyrus to be returned to the | |
19055 | sender. | |
19056 | ||
19057 | ||
19058 | . | |
19059 | . | |
19060 | . | |
19061 | . | |
19062 | . ============================================================================ | |
19063 | .chapter The smtp transport | |
19064 | .rset CHAPsmtptrans "~~chapter" | |
19065 | .set runningfoot "smtp transport" | |
19066 | .index transports||\%smtp%\ | |
19067 | .index \%smtp%\ transport | |
19068 | The \%smtp%\ transport delivers messages over TCP/IP connections using the SMTP | |
19069 | or LMTP protocol. The list of hosts to try can either be taken from the address | |
19070 | that is being processed (having been set up by the router), or specified | |
19071 | explicitly for the transport. Timeout and retry processing (see chapter | |
19072 | ~~CHAPretry) is applied to each IP address independently. | |
19073 | ||
19074 | .section Multiple messages on a single connection | |
19075 | The sending of multiple messages over a single TCP/IP connection can arise in | |
19076 | two ways: | |
19077 | .numberpars $. | |
19078 | If a message contains more than \max@_rcpt\ (see below) addresses that are | |
19079 | routed to the same host, more than one copy of the message has to be sent to | |
19080 | that host. In this situation, multiple copies may be sent in a single run of | |
19081 | the \%smtp%\ transport over a single TCP/IP connection. (What Exim actually does | |
19082 | when it has too many addresses to send in one message also depends on the value | |
19083 | of the global \remote@_max@_parallel\ option. Details are given in section | |
19084 | ~~SECToutSMTPTCP.) | |
19085 | .nextp | |
19086 | .index hints database||remembering routing | |
19087 | When a message has been successfully delivered over a TCP/IP connection, Exim | |
19088 | looks in its hints database to see if there are any other messages awaiting a | |
19089 | connection to the same host. If there are, a new delivery process is started | |
19090 | for one of them, and the current TCP/IP connection is passed on to it. The new | |
19091 | process may in turn send multiple copies and possibly create yet another | |
19092 | process. | |
19093 | .endp | |
19094 | ||
19095 | For each copy sent over the same TCP/IP connection, a sequence counter is | |
19096 | incremented, and if it ever gets to the value of \connection@_max@_messages\, | |
19097 | no further messages are sent over that connection. | |
19098 | ||
19099 | ||
19100 | .section Use of the @$host variable | |
19101 | .index \$host$\ | |
19102 | .index \$host@_address$\ | |
19103 | At the start of a run of the \%smtp%\ transport, the values of \$host$\ and | |
19104 | \$host@_address$\ are the name and IP address of the first host on the host list | |
19105 | passed by the router. However, when the transport is about to connect to a | |
19106 | specific host, and while it is connected to that host, \$host$\ and | |
19107 | \$host@_address$\ are set to the values for that host. These are the values | |
19108 | that are in force when the \helo@_data\, \hosts@_try@_auth\, \interface\, | |
19109 | \serialize@_hosts\, and the various TLS options are expanded. | |
19110 | ||
19111 | ||
19112 | .section Private options for smtp | |
19113 | The private options of the \%smtp%\ transport are as follows: | |
19114 | ||
19115 | .index options||\%smtp%\ transport | |
d43194df | 19116 | .startconf smtp |
495ae4b0 PH |
19117 | .conf allow@_localhost boolean false |
19118 | .index local host||sending to | |
19119 | .index fallback||hosts specified on transport | |
19120 | When a host specified in \hosts\ or \fallback@_hosts\ (see below) turns out to | |
19121 | be the local host, or is listed in \hosts@_treat@_as@_local\, delivery is | |
19122 | deferred by default. However, if \allow@_localhost\ is set, Exim goes on to do | |
19123 | the delivery anyway. This should be used only in special cases when the | |
19124 | configuration ensures that no looping will result (for example, a differently | |
19125 | configured Exim is listening on the port to which the message is sent). | |
19126 | ||
19127 | .conf authenticated@_sender string$**$ unset | |
19128 | .index Cyrus | |
19129 | When Exim has authenticated as a client, this option sets a value for the | |
19130 | \\AUTH=\\ item on outgoing \\MAIL\\ commands, overriding any existing | |
19131 | authenticated sender value. If the string expansion is forced to fail, the | |
19132 | option is ignored. Other expansion failures cause delivery to be deferred. If | |
19133 | the result of expansion is an empty string, that is also ignored. | |
19134 | ||
19135 | If the SMTP session is not authenticated, the expansion of | |
19136 | \authenticated@_sender\ still happens (and can cause the delivery to be | |
19137 | deferred if it fails), but no \\AUTH=\\ item is added to \\MAIL\\ commands. | |
19138 | ||
19139 | This option allows you to use the \%smtp%\ transport in LMTP mode to | |
19140 | deliver mail to Cyrus IMAP and provide the proper local part as the | |
19141 | `authenticated sender', via a setting such as: | |
19142 | .display asis | |
19143 | authenticated_sender = $local_part | |
19144 | .endd | |
19145 | This removes the need for IMAP subfolders to be assigned special ACLs to | |
19146 | allow direct delivery to those subfolders. | |
19147 | ||
19148 | Because of expected uses such as that just described for Cyrus (when no | |
19149 | domain is involved), there is no checking on the syntax of the provided | |
19150 | value. | |
19151 | ||
19152 | .conf command@_timeout time 5m | |
19153 | This sets a timeout for receiving a response to an SMTP command that has been | |
19154 | sent out. It is also used when waiting for the initial banner line from the | |
19155 | remote host. Its value must not be zero. | |
19156 | ||
19157 | .conf connect@_timeout time 5m | |
19158 | This sets a timeout for the \*connect()*\ function, which sets up a TCP/IP call | |
19159 | to a remote host. A setting of zero allows the system timeout (typically | |
19160 | several minutes) to act. To have any effect, the value of this option must be | |
19161 | less than the system timeout. However, it has been observed that on some | |
19162 | systems there is no system timeout, which is why the default value for this | |
19163 | option is 5 minutes, a value recommended by RFC 1123. | |
19164 | ||
19165 | .index SMTP||passed connection | |
19166 | .index SMTP||multiple deliveries | |
19167 | .index multiple SMTP deliveries | |
19168 | .conf connection@_max@_messages integer 500 | |
19169 | This controls the maximum number of separate message deliveries that are sent | |
19170 | over a single TCP/IP connection. If the value is zero, there is no limit. | |
19171 | For testing purposes, this value can be overridden by the \-oB-\ command line | |
19172 | option. | |
19173 | ||
19174 | .conf data@_timeout time 5m | |
19175 | This sets a timeout for the transmission of each block in the data portion of | |
19176 | the message. As a result, the overall timeout for a message depends on the size | |
19177 | of the message. Its value must not be zero. See also \final@_timeout\. | |
19178 | ||
19179 | .conf delay@_after@_cutoff boolean true | |
19180 | This option controls what happens when all remote IP addresses for a given | |
19181 | domain have been inaccessible for so long that they have passed their retry | |
19182 | cutoff times. | |
19183 | ||
19184 | In the default state, if the next retry time has not been reached for any of | |
19185 | them, the address is bounced without trying any deliveries. In other words, | |
19186 | Exim delays retrying an IP address after the final cutoff time until a new | |
19187 | retry time is reached, and can therefore bounce an address without ever trying | |
19188 | a delivery, when machines have been down for a long time. Some people are | |
19189 | unhappy at this prospect, so... | |
19190 | ||
19191 | If \delay@_after@_cutoff\ is set false, Exim behaves differently. If all IP | |
19192 | addresses are past their final cutoff time, Exim tries to deliver to those | |
19193 | IP addresses that have not been tried since the message arrived. If there are | |
19194 | none, of if they all fail, the address is bounced. In other words, it does not | |
19195 | delay when a new message arrives, but immediately tries those expired IP | |
19196 | addresses that haven't been tried since the message arrived. If there is a | |
19197 | continuous stream of messages for the dead hosts, unsetting | |
19198 | \delay@_after@_cutoff\ means that there will be many more attempts to deliver | |
19199 | to them. | |
19200 | ||
19201 | .conf dns@_qualify@_single boolean true | |
19202 | If the \hosts\ or \fallback@_hosts\ option is being used, | |
19203 | and the \gethostbyname\ option is false, | |
19204 | the \\RES@_DEFNAMES\\ resolver option is set. See the \qualify@_single\ option | |
19205 | in chapter ~~CHAPdnslookup for more details. | |
19206 | ||
19207 | .conf dns@_search@_parents boolean false | |
19208 | .index \search@_parents\ | |
19209 | If the \hosts\ or \fallback@_hosts\ option is being used, and the | |
19210 | \gethostbyname\ option is false, the \\RES@_DNSRCH\\ resolver option is set. | |
19211 | See the \search@_parents\ option in chapter ~~CHAPdnslookup for more details. | |
19212 | ||
19213 | ||
19214 | .conf fallback@_hosts "string list" unset | |
19215 | .index fallback||hosts specified on transport | |
19216 | String expansion is not applied to this option. The argument must be a | |
19217 | colon-separated list of host names or IP addresses. Fallback hosts can also be | |
19218 | specified on routers, which associate them with the addresses they process. As | |
19219 | for the \hosts\ option without \hosts@_override\, \fallback@_hosts\ specified | |
19220 | on the transport is used only if the address does not have its own associated | |
19221 | fallback host list. Unlike \hosts\, a setting of \fallback@_hosts\ on an | |
19222 | address is not overridden by \hosts@_override\. However, \hosts@_randomize\ | |
19223 | does apply to fallback host lists. | |
19224 | ||
19225 | If Exim is unable to deliver to any of the hosts for a particular address, and | |
19226 | the errors are not permanent rejections, the address is put on a separate | |
19227 | transport queue with its host list replaced by the fallback hosts, unless the | |
19228 | address was routed via MX records and the current host was in the original MX | |
19229 | list. In that situation, the fallback host list is not used. | |
19230 | ||
19231 | Once normal deliveries are complete, the fallback queue is delivered by | |
19232 | re-running the same transports with the new host lists. If several failing | |
19233 | addresses have the same fallback hosts (and \max@_rcpt\ permits it), a single | |
19234 | copy of the message is sent. | |
19235 | ||
19236 | The resolution of the host names on the fallback list is controlled by the | |
19237 | \gethostbyname\ option, as for the \hosts\ option. Fallback hosts apply | |
19238 | both to cases when the host list comes with the address and when it is taken | |
19239 | from \hosts\. This option provides a `use a smart host only if delivery fails' | |
19240 | facility. | |
19241 | ||
19242 | .conf final@_timeout time 10m | |
19243 | This is the timeout that applies while waiting for the response to the final | |
19244 | line containing just `.' that terminates a message. Its value must not be zero. | |
19245 | ||
19246 | .conf gethostbyname boolean false | |
19247 | If this option is true when the \hosts\ and/or \fallback@_hosts\ options are | |
4964e932 | 19248 | being used, names are looked up using \*gethostbyname()*\ |
495ae4b0 PH |
19249 | (or \*getipnodebyname()*\ when available) |
19250 | instead of using the DNS. Of course, that function may in fact use the DNS, but | |
19251 | it may also consult other sources of information such as \(/etc/hosts)\. | |
19252 | ||
19253 | .index \\HELO\\||argument, setting | |
19254 | .index \\EHLO\\||argument, setting | |
19255 | .conf helo@_data string$**$ $tt{@$primary@_hostname} | |
19256 | The value of this option is expanded, and used as the argument for the \\EHLO\\ | |
19257 | or \\HELO\\ command that starts the outgoing SMTP session. | |
19258 | ||
19259 | .conf hosts "string list$**$" unset | |
19260 | Hosts are associated with an address by a router such as \%dnslookup%\, which | |
19261 | finds the hosts by looking up the address domain in the DNS. However, addresses | |
19262 | can be passed to the \%smtp%\ transport by any router, and not all of them can | |
19263 | provide an associated host list. The \hosts\ option specifies a list of hosts | |
19264 | which are used if the address being processed does not have any hosts | |
19265 | associated with it. The hosts specified by \hosts\ are also used, whether or | |
19266 | not the address has its own hosts, if \hosts@_override\ is set. | |
19267 | ||
19268 | The string is first expanded, before being interpreted as a colon-separated | |
19269 | list of host names or IP addresses. If the expansion fails, delivery is | |
19270 | deferred. Unless the failure was caused by the inability to complete a lookup, | |
19271 | the error is logged to the panic log as well as the main log. Host names are | |
19272 | looked up either by searching directly for address records in the DNS or by | |
19273 | calling \*gethostbyname()*\ | |
19274 | (or \*getipnodebyname()*\ when available), | |
19275 | depending on the setting of the \gethostbyname\ option. When Exim is compiled | |
19276 | with IPv6 support, if a host that is looked up in the DNS has both IPv4 and | |
19277 | IPv6 addresses, both types of address are used. | |
19278 | ||
19279 | During delivery, the hosts are tried in order, subject to their retry status, | |
19280 | unless \hosts@_randomize\ is set. | |
19281 | ||
19282 | .conf hosts@_avoid@_esmtp "host list$**$" unset | |
19283 | .index ESMTP, avoiding use of | |
19284 | .index \\HELO\\||forcing use of | |
19285 | .index \\EHLO\\||avoiding use of | |
19286 | .index \\PIPELINING\\||avoiding the use of | |
19287 | This option is for use with broken hosts that announce ESMTP facilities (for | |
19288 | example, \\PIPELINING\\) and then fail to implement them properly. When a host | |
19289 | matches \hosts@_avoid@_esmtp\, Exim sends \\HELO\\ rather than \\EHLO\\ at the | |
19290 | start of the SMTP session. This means that it cannot use any of the ESMTP | |
19291 | facilities such as \\AUTH\\, \\PIPELINING\\, \\SIZE\\, and \\STARTTLS\\. | |
19292 | ||
19293 | .conf hosts@_avoid@_tls "host list$**$" unset | |
19294 | .index TLS||avoiding for certain hosts | |
19295 | Exim will not try to start a TLS session when delivering to any host that | |
19296 | matches this list. See chapter ~~CHAPTLS for details of TLS. | |
19297 | ||
19298 | .conf hosts@_max@_try integer 5 | |
19299 | .index host||maximum number to try | |
19300 | .index limit||number of hosts tried | |
19301 | .index limit||number of MX tried | |
19302 | .index MX record||maximum tried | |
19303 | This option limits the number of IP addresses that are tried for any one | |
d43194df PH |
19304 | delivery in cases where there are temporary delivery errors. Section |
19305 | ~~SECTvalhosmax describes in detail how the value of this option is used. | |
19306 | ||
19307 | .em | |
19308 | .conf hosts@_max@_try@_hardlimit integer 50 | |
19309 | This is an additional check on the maximum number of IP addresses that Exim | |
19310 | tries for any one delivery. Section ~~SECTvalhosmax describes its use and why | |
19311 | it exists. | |
19312 | .nem | |
495ae4b0 PH |
19313 | |
19314 | .conf hosts@_nopass@_tls "host list$**$" unset | |
19315 | .index TLS||passing connection | |
19316 | .index multiple SMTP deliveries | |
19317 | .index TLS||multiple message deliveries | |
19318 | For any host that matches this list, a connection on which a TLS session has | |
19319 | been started will not be passed to a new delivery process for sending another | |
19320 | message on the same connection. See section ~~SECTmulmessam for an explanation | |
19321 | of when this might be needed. | |
19322 | ||
19323 | .conf hosts@_override boolean false | |
19324 | If this option is set and the \hosts\ option is also set, any hosts that are | |
19325 | attached to the address are ignored, and instead the hosts specified by the | |
19326 | \hosts\ option are always used. This option does not apply to | |
19327 | \fallback@_hosts\. | |
19328 | ||
19329 | .conf hosts@_randomize boolean false | |
19330 | .index randomized host list | |
19331 | .index host||list of, randomized | |
19332 | .index fallback||randomized hosts | |
19333 | If this option is set, and either the list of hosts is taken from the | |
19334 | \hosts\ or the \fallback@_hosts\ option, or the hosts supplied by the router | |
19335 | were not obtained from MX records (this includes fallback hosts from the | |
19336 | router), and were not randomizied by the router, the order of trying the hosts | |
19337 | is randomized each time the transport runs. Randomizing the order of a host | |
19338 | list can be used to do crude load sharing. | |
19339 | ||
19340 | When \hosts@_randomize\ is true, a host list may be split into groups whose | |
19341 | order is separately randomized. This makes it possible to set up MX-like | |
19342 | behaviour. The boundaries between groups are indicated by an item that is just | |
19343 | \"+"\ in the host list. For example: | |
19344 | .display asis | |
19345 | hosts = host1:host2:host3:+:host4:host5 | |
19346 | .endd | |
19347 | The order of the first three hosts and the order of the last two hosts is | |
19348 | randomized for each use, but the first three always end up before the last two. | |
19349 | If \hosts@_randomize\ is not set, a \"+"\ item in the list is ignored. | |
19350 | ||
19351 | .index authentication||required by client | |
19352 | .conf hosts@_require@_auth "host list$**$" unset | |
19353 | This option provides a list of servers for which authentication must succeed | |
19354 | before Exim will try to transfer a message. If authentication fails for | |
19355 | servers which are not in this list, Exim tries to send unauthenticated. If | |
19356 | authentication fails for one of these servers, delivery is deferred. This | |
19357 | temporary error is detectable in the retry rules, so it can be turned into a | |
19358 | hard failure if required. See also \hosts@_try@_auth\, and chapter | |
19359 | ~~CHAPSMTPAUTH for details of authentication. | |
19360 | ||
19361 | .conf hosts@_require@_tls "host list$**$" unset | |
19362 | .index TLS||requiring for certain servers | |
19363 | Exim will insist on using a TLS session when delivering to any host that | |
19364 | matches this list. See chapter ~~CHAPTLS for details of TLS. | |
4964e932 | 19365 | \**Note**\: This option affects outgoing mail only. To insist on TLS for |
495ae4b0 PH |
19366 | incoming messages, use an appropriate ACL. |
19367 | ||
19368 | .index authentication||optional in client | |
19369 | .conf hosts@_try@_auth "host list$**$" unset | |
19370 | This option provides a list of servers to which, provided they announce | |
19371 | authentication support, Exim will attempt to authenticate as a client when it | |
19372 | connects. If authentication fails, Exim will try to transfer the message | |
19373 | unauthenticated. See also \hosts@_require@_auth\, and chapter ~~CHAPSMTPAUTH | |
19374 | for details of authentication. | |
19375 | ||
19376 | .index bind IP address | |
19377 | .index IP address||binding | |
19378 | .conf interface "string list$**$" unset | |
19379 | This option specifies which interface to bind to when making an outgoing SMTP | |
19380 | call. The variables \$host$\ and \$host@_address$\ refer to the host to which a | |
19381 | connection is about to be made during the expansion of the string. Forced | |
19382 | expansion failure, or an empty string result causes the option to be ignored. | |
4964e932 | 19383 | Otherwise, after expansion, |
495ae4b0 PH |
19384 | the string must be a list of IP addresses, colon-separated by default, but the |
19385 | separator can be changed in the usual way. | |
495ae4b0 PH |
19386 | For example: |
19387 | .display asis | |
19388 | interface = <; 192.168.123.123 ; 3ffe:ffff:836f::fe86:a061 | |
19389 | .endd | |
19390 | The first interface of the correct type (IPv4 or IPv6) is used for the outgoing | |
19391 | connection. If none of them are the correct type, the option is ignored. If | |
19392 | \interface\ is not set, or is ignored, the system's IP functions choose which | |
19393 | interface to use if the host has more than one. | |
19394 | ||
19395 | .conf keepalive boolean true | |
19396 | .index keepalive||on outgoing connection | |
19397 | This option controls the setting of \\SO@_KEEPALIVE\\ on outgoing TCP/IP socket | |
19398 | connections. When set, it causes the kernel to probe idle connections | |
19399 | periodically, by sending packets with `old' sequence numbers. The other end of | |
19400 | the connection should send a acknowledgement if the connection is still okay or | |
19401 | a reset if the connection has been aborted. The reason for doing this is that | |
19402 | it has the beneficial effect of freeing up certain types of connection that can | |
19403 | get stuck when the remote host is disconnected without tidying up the TCP/IP | |
19404 | call properly. The keepalive mechanism takes several hours to detect | |
19405 | unreachable hosts. | |
19406 | ||
19407 | .conf max@_rcpt integer 100 | |
19408 | .index \\RCPT\\||maximum number of outgoing | |
19409 | This option limits the number of \\RCPT\\ commands that are sent in a single | |
19410 | SMTP message transaction. Each set of addresses is treated independently, and | |
19411 | so can cause parallel connections to the same host if \remote@_max@_parallel\ | |
19412 | permits this. | |
19413 | ||
19414 | .conf multi@_domain boolean true | |
19415 | When this option is set, the \%smtp%\ transport can handle a number of addresses | |
19416 | containing a mixture of different domains provided they all resolve to the same | |
19417 | list of hosts. Turning the option off restricts the transport to handling only | |
19418 | one domain at a time. This is useful if you want to use \$domain$\ in an | |
19419 | expansion for the transport, because it is set only when there is a single | |
19420 | domain involved in a remote delivery. | |
19421 | ||
19422 | .conf port string$**$ "see below" | |
19423 | .index port||sending TCP/IP | |
19424 | .index TCP/IP||setting outgoing port | |
19425 | This option specifies the TCP/IP port on the server to which Exim connects. If | |
19426 | it begins with a digit it is taken as a port number; otherwise it is looked up | |
19427 | using \*getservbyname()*\. The default value is normally `smtp', but if | |
19428 | \protocol\ is set to `lmtp', the default is `lmtp'. | |
4964e932 | 19429 | If the expansion fails, or if a port number cannot be found, delivery is |
495ae4b0 PH |
19430 | deferred. |
19431 | ||
19432 | ||
19433 | .conf protocol string "smtp" | |
19434 | .index LMTP||over TCP/IP | |
19435 | If this option is set to `lmtp' instead of `smtp', the default value for the | |
19436 | \port\ option changes to `lmtp', and the transport operates the LMTP protocol | |
19437 | (RFC 2033) instead of SMTP. This protocol is sometimes used for local | |
19438 | deliveries into closed message stores. Exim also has support for running LMTP | |
19439 | over a pipe to a local process -- see chapter ~~CHAPLMTP. | |
19440 | ||
19441 | .conf retry@_include@_ip@_address boolean true | |
19442 | Exim normally includes both the host name and the IP address in the key it | |
19443 | constructs for indexing retry data after a temporary delivery failure. This | |
19444 | means that when one of several IP addresses for a host is failing, it gets | |
19445 | tried periodically (controlled by the retry rules), but use of the other IP | |
19446 | addresses is not affected. | |
19447 | ||
19448 | However, in some dialup environments hosts are assigned a different IP address | |
19449 | each time they connect. In this situation the use of the IP address as part of | |
19450 | the retry key leads to undesirable behaviour. Setting this option false causes | |
19451 | Exim to use only the host name. This should normally be done on a separate | |
19452 | instance of the \%smtp%\ transport, set up specially to handle the dialup hosts. | |
19453 | ||
19454 | .conf serialize@_hosts "host list$**$" unset | |
19455 | .index serializing connections | |
19456 | .index host||serializing connections | |
19457 | Because Exim operates in a distributed manner, if several messages for the same | |
19458 | host arrive at around the same time, more than one simultaneous connection to | |
19459 | the remote host can occur. This is not usually a problem except when there is a | |
19460 | slow link between the hosts. In that situation it may be helpful to restrict | |
19461 | Exim to one connection at a time. This can be done by setting | |
19462 | \serialize@_hosts\ to match the relevant hosts. | |
19463 | ||
19464 | .index hints database||serializing deliveries to a host | |
19465 | Exim implements serialization by means of a hints database in which a record is | |
19466 | written whenever a process connects to one of the restricted hosts. The record | |
19467 | is deleted when the connection is completed. Obviously there is scope for | |
19468 | records to get left lying around if there is a system or program crash. To | |
19469 | guard against this, Exim ignores any records that are more than six hours old. | |
19470 | ||
19471 | If you set up this kind of serialization, you should also arrange to delete the | |
19472 | relevant hints database whenever your system reboots. The names of the files | |
19473 | start with \(misc)\ and they are kept in the \(spool/db)\ directory. There | |
19474 | may be one or two files, depending on the type of DBM in use. The same files | |
19475 | are used for ETRN serialization. | |
19476 | ||
19477 | .conf size@_addition integer 1024 | |
19478 | .index SMTP||\\SIZE\\ | |
19479 | .index message||size issue for transport filter | |
19480 | .index size||of message | |
19481 | .index transport||filter | |
19482 | .index filter||transport filter | |
19483 | If a remote SMTP server indicates that it supports the \\SIZE\\ option of the | |
19484 | \\MAIL\\ command, Exim uses this to pass over the message size at the start of | |
19485 | an SMTP transaction. It adds the value of \size@_addition\ to the value it | |
19486 | sends, to allow for headers and other text that may be added during delivery by | |
19487 | configuration options or in a transport filter. It may be necessary to increase | |
19488 | this if a lot of text is added to messages. | |
19489 | ||
19490 | Alternatively, if the value of \size@_addition\ is set negative, it disables | |
19491 | the use of the \\SIZE\\ option altogether. | |
19492 | ||
19493 | .conf tls@_certificate string$**$ unset | |
19494 | .index TLS||client certificate, location of | |
19495 | .index certificate||for client, location of | |
19496 | The value of this option must be the absolute path to a file which contains the | |
19497 | client's certificate, for use when sending a message over an encrypted | |
19498 | connection. The values of \$host$\ and \$host@_address$\ are set to the name | |
19499 | and address of the server during the expansion. See chapter ~~CHAPTLS for | |
19500 | details of TLS. | |
19501 | ||
4964e932 PH |
19502 | \**Note**\: This option must be set if you want Exim to use TLS when sending |
19503 | messages as a client. The global option of the same name specifies the | |
19504 | certificate for Exim as a server; it is not automatically assumed that the same | |
495ae4b0 PH |
19505 | certificate should be used when Exim is operating as a client. |
19506 | ||
495ae4b0 PH |
19507 | .conf tls@_crl string$**$ unset |
19508 | .index TLS||client certificate revocation list | |
19509 | .index certificate||revocation list for client | |
19510 | This option specifies a certificate revocation list. The expanded value must | |
19511 | be the name of a file that contains a CRL in PEM format. | |
495ae4b0 PH |
19512 | |
19513 | .conf tls@_privatekey string$**$ unset | |
19514 | .index TLS||client private key, location of | |
19515 | The value of this option must be the absolute path to a file which contains the | |
19516 | client's private key, for use when sending a message over an encrypted | |
19517 | connection. The values of \$host$\ and \$host@_address$\ are set to the name | |
4964e932 PH |
19518 | and address of the server during the expansion. |
19519 | If this option is unset, the private key is assumed to be in the same file as | |
495ae4b0 PH |
19520 | the certificate. |
19521 | See chapter ~~CHAPTLS for details of TLS. | |
19522 | ||
19523 | .conf tls@_require@_ciphers string$**$ unset | |
19524 | .index TLS||requiring specific ciphers | |
19525 | .index cipher||requiring specific | |
19526 | The value of this option must be a list of permitted cipher suites, for use | |
d43194df PH |
19527 | when setting up an outgoing encrypted connection. (There is a global option of |
19528 | the same name for controlling incoming connections.) The values of \$host$\ and | |
19529 | \$host@_address$\ are set to the name and address of the server during the | |
19530 | expansion. See chapter ~~CHAPTLS for details of TLS; note that this option is | |
19531 | used in different ways by OpenSSL and GnuTLS (see sections ~~SECTreqciphssl and | |
19532 | ~~SECTreqciphgnu). | |
19533 | .em | |
19534 | For GnuTLS, the order of the ciphers is a preference order. | |
19535 | .nem | |
495ae4b0 PH |
19536 | |
19537 | .conf tls@_tempfail@_tryclear boolean true | |
4964e932 | 19538 | When the server host is not in \hosts@_require@_tls\, and there is a problem in |
495ae4b0 PH |
19539 | setting up a TLS session, this option determines whether or not Exim should try |
19540 | to deliver the message unencrypted. If it is set false, delivery to the | |
19541 | current host is deferred; if there are other hosts, they are tried. If this | |
19542 | option is set true, Exim attempts to deliver unencrypted after a 4\*xx*\ | |
19543 | response to \\STARTTLS\\. Also, if \\STARTTLS\\ is accepted, but the subsequent | |
19544 | TLS negotiation fails, Exim closes the current connection (because it is in an | |
19545 | unknown state), opens a new one to the same host, and then tries the delivery | |
19546 | in clear. | |
19547 | ||
19548 | .conf tls@_verify@_certificates string$**$ unset | |
19549 | .index TLS||server certificate verification | |
19550 | .index certificate||verification of server | |
19551 | The value of this option must be the absolute path to a file containing | |
19552 | permitted server certificates, for use when setting up an encrypted connection. | |
19553 | Alternatively, if you are using OpenSSL, you can set | |
19554 | \tls@_verify@_certificates\ to the name of a directory containing certificate | |
19555 | files. This does not work with GnuTLS; the option must be set to the name of a | |
19556 | single file if you are using GnuTLS. The values of \$host$\ and | |
19557 | \$host@_address$\ are set to the name and address of the server during the | |
19558 | expansion of this option. See chapter ~~CHAPTLS for details of TLS. | |
19559 | ||
19560 | .endconf | |
19561 | ||
19562 | ||
d43194df | 19563 | .section How the limits for the number of hosts to try are used |
495ae4b0 PH |
19564 | .rset SECTvalhosmax "~~chapter.~~section" |
19565 | .index host||maximum number to try | |
19566 | .index limit||hosts, maximum number tried | |
d43194df PH |
19567 | .em |
19568 | There are two options that are concerned with the number of hosts that are | |
19569 | tried when an SMTP delivery takes place. They are \hosts@_max@_try\ and | |
19570 | \hosts@_max@_try@_hardlimit\. | |
19571 | .nem | |
19572 | ||
495ae4b0 PH |
19573 | The \hosts@_max@_try\ option limits the number of hosts that are tried |
19574 | for a single delivery. However, despite the term `host' in its name, the option | |
4964e932 | 19575 | actually applies to each IP address independently. In other words, a multihomed |
495ae4b0 PH |
19576 | host is treated as several independent hosts, just as it is for retrying. |
19577 | ||
19578 | Many of the larger ISPs have multiple MX records which often point to | |
19579 | multihomed hosts. As a result, a list of a dozen or more IP addresses may be | |
19580 | created as a result of routing one of these domains. | |
19581 | ||
19582 | Trying every single IP address on such a long list does not seem sensible; if | |
19583 | several at the top of the list fail, it is reasonable to assume there is some | |
19584 | problem that is likely to affect all of them. Roughly speaking, the value of | |
4964e932 | 19585 | \hosts@_max@_try\ is the maximum number that are tried before deferring the |
495ae4b0 PH |
19586 | delivery. However, the logic cannot be quite that simple. |
19587 | ||
19588 | Firstly, IP addresses that are skipped because their retry times have not | |
19589 | arrived do not count, and in addition, addresses that are past their retry | |
19590 | limits are also not counted, even when they are tried. This means that when | |
19591 | some IP addresses are past their retry limits, more than the value of | |
19592 | \hosts@_max@_retry\ may be tried. The reason for this behaviour is to ensure | |
d43194df PH |
19593 | that all IP addresses are considered before timing out an email address (but |
19594 | see below for an exception). | |
495ae4b0 PH |
19595 | |
19596 | Secondly, when the \hosts@_max@_try\ limit is reached, Exim looks down the host | |
19597 | list to see if there is a subsequent host with a different (higher valued) MX. | |
d43194df PH |
19598 | If there is, that host is considered next, and the current IP address is used |
19599 | but not counted. This behaviour helps in the case of a domain with a retry rule | |
19600 | that hardly ever delays any hosts, as is now explained: | |
495ae4b0 | 19601 | |
4964e932 | 19602 | Consider the case of a long list of hosts with one MX value, and a few with a |
495ae4b0 PH |
19603 | higher MX value. If \hosts@_max@_try\ is small (the default is 5) only a few |
19604 | hosts at the top of the list are tried at first. With the default retry rule, | |
19605 | which specifies increasing retry times, the higher MX hosts are eventually | |
19606 | tried when those at the top of the list are skipped because they have not | |
19607 | reached their retry times. | |
19608 | ||
19609 | However, it is common practice to put a fixed short retry time on domains for | |
19610 | large ISPs, on the grounds that their servers are rarely down for very long. | |
19611 | Unfortunately, these are exactly the domains that tend to resolve to long lists | |
19612 | of hosts. The short retry time means that the lowest MX hosts are tried every | |
19613 | time. The attempts may be in a different order because of random sorting, but | |
d43194df PH |
19614 | without the special MX check, the higher MX hosts would never be tried |
19615 | .em | |
19616 | until all the lower MX hosts had timed out (which might be several days), | |
19617 | because there are always some lower MX hosts that have reached their retry | |
19618 | times. With the special check, Exim considers at least one IP address from each | |
19619 | MX value at every delivery attempt, even if the \hosts@_max@_try\ limit has | |
19620 | already been reached. | |
19621 | ||
19622 | The above logic means that \hosts@_max@_try\ is not a hard limit, and in | |
19623 | particular, Exim normally eventually tries all the IP addresses before timing | |
19624 | out an email address. When \hosts@_max@_try\ was implemented, this seemed a | |
19625 | reasonable thing to do. Recently, however, some lunatic DNS configurations have | |
19626 | been set up with hundreds of IP addresses for some domains. It can | |
19627 | take a very long time indeed for an address to time out in these cases. | |
19628 | ||
19629 | The \hosts@_max@_try@_hardlimit\ option was added to help with this problem. | |
19630 | Exim never tries more than this number of IP addresses; if it hits this limit | |
19631 | and they are all timed out, the email address is bounced, even though not all | |
19632 | possible IP addresses have been tried. | |
19633 | .nem | |
495ae4b0 PH |
19634 | |
19635 | ||
19636 | ||
19637 | ||
19638 | . | |
19639 | . | |
19640 | . | |
19641 | . | |
19642 | . ============================================================================ | |
19643 | .chapter Address rewriting | |
19644 | .set runningfoot "address rewriting" | |
19645 | .rset CHAPrewrite ~~chapter | |
19646 | .index rewriting||addresses | |
19647 | There are some circumstances in which Exim automatically rewrites domains in | |
19648 | addresses. The two most common are when an address is given without a domain | |
19649 | (referred to as an `unqualified address') or when an address contains an | |
19650 | abbreviated domain that is expanded by DNS lookup. | |
19651 | ||
19652 | Unqualified envelope addresses are accepted only for locally submitted | |
19653 | messages, or messages from hosts that match \sender@_unqualified@_hosts\ or | |
19654 | \recipient@_unqualified@_hosts\, respectively. Unqualified addresses in header | |
19655 | lines are qualified if they are in locally submitted messages, or messages from | |
19656 | hosts that are permitted to send unqualified envelope addresses. Otherwise, | |
19657 | unqualified addresses in header lines are neither qualified nor rewritten. | |
19658 | ||
19659 | One situation in which Exim does $it{not} automatically rewrite a domain is | |
19660 | when it is the name of a CNAME record in the DNS. The older RFCs suggest that | |
19661 | such a domain should be rewritten using the `canonical' name, and some MTAs do | |
19662 | this. The new RFCs do not contain this suggestion. | |
d43194df | 19663 | |
495ae4b0 PH |
19664 | .section Explicitly configured address rewriting |
19665 | This chapter describes the rewriting rules that can be used in the | |
19666 | main rewrite section of the configuration file, and also in the generic | |
19667 | \headers@_rewrite\ option that can be set on any transport. | |
19668 | ||
19669 | Some people believe that configured address rewriting is a Mortal Sin. | |
19670 | Others believe that life is not possible without it. Exim provides the | |
19671 | facility; you do not have to use it. | |
19672 | ||
495ae4b0 PH |
19673 | The main rewriting rules that appear in the `rewrite' section of the |
19674 | configuration file are applied to addresses in incoming messages, both envelope | |
19675 | addresses and addresses in header lines. Each rule specifies the types of | |
19676 | address to which it applies. | |
495ae4b0 PH |
19677 | |
19678 | Rewriting of addresses in header lines applies only to those headers that | |
19679 | were received with the message, and, in the case of transport rewriting, those | |
19680 | that were added by a system filter. That is, it applies only to those headers | |
19681 | that are common to all copies of the message. Header lines that are added by | |
19682 | individual routers or transports (and which are therefore specific to | |
19683 | individual recipient addresses) are not rewritten. | |
19684 | ||
19685 | In general, rewriting addresses from your own system or domain has some | |
19686 | legitimacy. Rewriting other addresses should be done only with great care and | |
19687 | in special circumstances. The author of Exim believes that rewriting should be | |
19688 | used sparingly, and mainly for `regularizing' addresses in your own domains. | |
19689 | Although it can sometimes be used as a routing tool, this is very strongly | |
19690 | discouraged. | |
19691 | ||
19692 | There are two commonly encountered circumstances where rewriting is used, as | |
19693 | illustrated by these examples: | |
19694 | .numberpars $. | |
19695 | The company whose domain is \*hitch.fict.example*\ has a number of hosts that | |
19696 | exchange mail with each other behind a firewall, but there is only a single | |
19697 | gateway to the outer world. The gateway rewrites \*@*.hitch.fict.example*\ as | |
19698 | \*hitch.fict.example*\ when sending mail off-site. | |
19699 | .nextp | |
19700 | A host rewrites the local parts of its own users so that, for example, | |
19701 | \*fp42@@hitch.fict.example*\ becomes \*Ford.Prefect@@hitch.fict.example*\. | |
19702 | .endp | |
19703 | ||
495ae4b0 PH |
19704 | .section When does rewriting happen? |
19705 | .index rewriting||timing of | |
19706 | .index ~~ACL||rewriting addresses in | |
19707 | Configured address rewriting can take place at several different stages of a | |
4964e932 | 19708 | message's processing. |
495ae4b0 | 19709 | |
4964e932 | 19710 | At the start of an ACL for \\MAIL\\, the sender address may have been rewritten |
495ae4b0 PH |
19711 | by a special SMTP-time rewrite rule (see section ~~SECTrewriteS), but no |
19712 | ordinary rewrite rules have yet been applied. If, however, the sender address | |
19713 | is verified in the ACL, it is rewritten before verification, and remains | |
19714 | rewritten thereafter. The subsequent value of \$sender@_address$\ is the | |
19715 | rewritten address. This also applies if sender verification happens in a | |
19716 | \\RCPT\\ ACL. Otherwise, when the sender address is not verified, it is | |
19717 | rewritten as soon as a message's header lines have been received. | |
19718 | ||
19719 | Similarly, at the start of an ACL for \\RCPT\\, the current recipient's address | |
19720 | may have been rewritten by a special SMTP-time rewrite rule, but no ordinary | |
19721 | rewrite rules have yet been applied to it. However, the behaviour is different | |
19722 | from the sender address when a recipient is verified. The address is rewritten | |
19723 | for the verification, but the rewriting is not remembered at this stage. The | |
19724 | value of \$local@_part$\ and \$domain$\ after verification are always the same | |
4964e932 | 19725 | as they were before (that is, they contain the unrewritten -- except for |
495ae4b0 PH |
19726 | SMTP-time rewriting -- address). |
19727 | ||
4964e932 | 19728 | Once a message's header lines have been received, all the envelope recipient |
495ae4b0 PH |
19729 | addresses are permanently rewritten, and rewriting is also applied to the |
19730 | addresses in the header lines (if configured). | |
19731 | .index \*local@_scan()*\ function||address rewriting, timing of | |
19732 | Thus, all the rewriting is completed before the \\DATA\\ ACL and | |
19733 | \*local@_scan()*\ functions are run. | |
19734 | ||
19735 | When an address is being routed, either for delivery or for verification, | |
19736 | rewriting is applied immediately to child addresses that are generated by | |
19737 | redirection, unless \no@_rewrite\ is set on the router. | |
495ae4b0 PH |
19738 | |
19739 | .index envelope sender, rewriting | |
19740 | .index rewriting||at transport time | |
19741 | At transport time, additional rewriting of addresses in header lines can be | |
19742 | specified by setting the generic \headers@_rewrite\ option on a transport. This | |
19743 | option contains rules that are identical in form to those in the rewrite | |
19744 | section of the configuration file. In addition, the outgoing envelope sender | |
19745 | can be rewritten by means of the \return@_path\ transport option. However, it | |
19746 | is not possible to rewrite envelope recipients at transport time. | |
19747 | ||
19748 | ||
19749 | ||
19750 | .section Testing the rewriting rules that apply on input | |
19751 | .index rewriting||testing | |
19752 | .index testing||rewriting | |
19753 | Exim's input rewriting configuration appears in a part of the run time | |
19754 | configuration file headed by `begin rewrite'. It can be tested by the \-brw-\ | |
19755 | command line option. This takes an address (which can be a full RFC 2822 | |
19756 | address) as its argument. The output is a list of how the address would be | |
19757 | transformed by the rewriting rules for each of the different places it might | |
19758 | appear in an incoming message, that is, for each different header and for the | |
19759 | envelope sender and recipient fields. For example, | |
19760 | .display asis | |
19761 | exim -brw ph10@exim.workshop.example | |
19762 | .endd | |
19763 | might produce the output | |
19764 | .display asis | |
19765 | sender: Philip.Hazel@exim.workshop.example | |
19766 | from: Philip.Hazel@exim.workshop.example | |
19767 | to: ph10@exim.workshop.example | |
19768 | cc: ph10@exim.workshop.example | |
19769 | bcc: ph10@exim.workshop.example | |
19770 | reply-to: Philip.Hazel@exim.workshop.example | |
19771 | env-from: Philip.Hazel@exim.workshop.example | |
19772 | env-to: ph10@exim.workshop.example | |
19773 | .endd | |
19774 | which shows that rewriting has been set up for that address when used in any of | |
19775 | the source fields, but not when it appears as a recipient address. At the | |
19776 | present time, there is no equivalent way of testing rewriting rules that are | |
19777 | set for a particular transport. | |
19778 | ||
19779 | .section Rewriting rules | |
19780 | .index rewriting||rules | |
19781 | The rewrite section of the configuration file consists of lines of rewriting | |
19782 | rules in the form | |
19783 | .display | |
19784 | <<source pattern>> <<replacement>> <<flags>> | |
19785 | .endd | |
19786 | Rewriting rules that are specified for the \headers@_rewrite\ generic transport | |
19787 | option are given as a colon-separated list. Each item in the list takes the | |
19788 | same form as a line in the main rewriting configuration | |
19789 | (except that any colons must be doubled, of course). | |
19790 | ||
19791 | The formats of source patterns and replacement strings are described below. | |
19792 | Each is terminated by white space, unless enclosed in double quotes, in which | |
19793 | case normal quoting conventions apply inside the quotes. The flags are single | |
19794 | characters which may appear in any order. Spaces and tabs between them are | |
19795 | ignored. | |
19796 | ||
19797 | For each address that could potentially be rewritten, the rules are scanned in | |
19798 | order, and replacements for the address from earlier rules can themselves be | |
19799 | replaced by later rules (but see the `q' and `R' flags). | |
19800 | ||
19801 | The order in which addresses are rewritten is undefined, may change between | |
19802 | releases, and must not be relied on, with one exception: when a message is | |
19803 | received, the envelope sender is always rewritten first, before any header | |
19804 | lines are rewritten. For example, the replacement string for a rewrite of an | |
19805 | address in ::To:: must not assume that the message's address in ::From:: has (or | |
19806 | has not) already been rewritten. However, a rewrite of ::From:: may assume that | |
19807 | the envelope sender has already been rewritten. | |
19808 | ||
19809 | The variables \$local@_part$\ and \$domain$\ can be used in the replacement | |
19810 | string to refer to the address that is being rewritten. Note that lookup-driven | |
19811 | rewriting can be done by a rule of the form | |
19812 | .display asis | |
19813 | *@* ${lookup ... | |
19814 | .endd | |
19815 | where the lookup key uses \$1$\ and \$2$\ or \$local@_part$\ and \$domain$\ to | |
19816 | refer to the address that is being rewritten. | |
19817 | ||
19818 | .section Rewriting patterns | |
19819 | .index rewriting||patterns | |
19820 | .index address list||in a rewriting pattern | |
19821 | The source pattern in a rewriting rule is any item which may appear in an | |
19822 | address list (see section ~~SECTaddresslist). It is in fact processed as a | |
19823 | single-item address list, which means that it is expanded before being tested | |
19824 | against the address. | |
19825 | ||
4964e932 PH |
19826 | Domains in patterns should be given in lower case. Local parts in patterns are |
19827 | case-sensitive. If you want to do case-insensitive matching of local parts, you | |
495ae4b0 PH |
19828 | can use a regular expression that starts with \"^(?i)"\. |
19829 | ||
19830 | .index numerical variables (\$1$\, \$2$\, etc)||in rewriting rules | |
19831 | After matching, the numerical variables \$1$\, \$2$\, etc. may be set, | |
19832 | depending on the type of match which occurred. These can be used in the | |
19833 | replacement string to insert portions of the incoming address. \$0$\ always | |
19834 | refers to the complete incoming address. When a regular expression is used, the | |
19835 | numerical variables are set from its capturing subexpressions. For other types | |
19836 | of pattern they are set as follows: | |
19837 | ||
19838 | .numberpars $. | |
19839 | If a local part or domain starts with an asterisk, the numerical variables | |
19840 | refer to the character strings matched by asterisks, with \$1$\ associated with | |
19841 | the first asterisk, and \$2$\ with the second, if present. For example, if the | |
19842 | pattern | |
19843 | .display | |
19844 | *queen@@*.fict.example | |
19845 | .endd | |
19846 | is matched against the address \*hearts-queen@@wonderland.fict.example*\ then | |
19847 | .display asis | |
19848 | $0 = hearts-queen@wonderland.fict.example | |
19849 | $1 = hearts- | |
19850 | $2 = wonderland | |
19851 | .endd | |
19852 | Note that if the local part does not start with an asterisk, but the domain | |
19853 | does, it is \$1$\ that contains the wild part of the domain. | |
19854 | .nextp | |
19855 | If the domain part of the pattern is a partial lookup, the wild and fixed parts | |
19856 | of the domain are placed in the next available numerical variables. Suppose, | |
19857 | for example, that the address \*foo@@bar.baz.example*\ is processed by a | |
19858 | rewriting rule of the form | |
19859 | .display | |
19860 | *@@partial-dbm;/some/dbm/file <<replacement string>> | |
19861 | .endd | |
19862 | and the key in the file that matches the domain is \"*.baz.example"\. Then | |
19863 | .display asis | |
19864 | $1 = foo | |
19865 | $2 = bar | |
19866 | $3 = baz.example | |
19867 | .endd | |
19868 | If the address \*foo@@baz.example*\ is looked up, this matches the same | |
19869 | wildcard file entry, and in this case \$2$\ is set to the empty string, but | |
19870 | \$3$\ is still set to \*baz.example*\. If a non-wild key is matched in a | |
19871 | partial lookup, \$2$\ is again set to the empty string and \$3$\ is set to the | |
19872 | whole domain. For non-partial domain lookups, no numerical variables are set. | |
19873 | .endp | |
19874 | ||
19875 | .section Rewriting replacements | |
19876 | .index rewriting||replacements | |
19877 | If the replacement string for a rule is a single asterisk, addresses that | |
19878 | match the pattern and the flags are $it{not} rewritten, and no subsequent | |
19879 | rewriting rules are scanned. For example, | |
19880 | .display asis | |
19881 | hatta@lookingglass.fict.example * f | |
19882 | .endd | |
19883 | specifies that \*hatta@@lookingglass.fict.example*\ is never to be rewritten in | |
19884 | ::From:: headers. | |
19885 | ||
19886 | If the replacement string is not a single asterisk, it is expanded, and must | |
19887 | yield a fully qualified address. Within the expansion, the variables | |
19888 | \$local@_part$\ and \$domain$\ refer to the address that is being rewritten. | |
19889 | Any letters they contain retain their original case -- they are not lower | |
19890 | cased. The numerical variables are set up according to the type of pattern that | |
19891 | matched the address, as described above. If the expansion is forced to fail by | |
19892 | the presence of `fail' in a conditional or lookup item, rewriting by the | |
19893 | current rule is abandoned, but subsequent rules may take effect. Any other | |
19894 | expansion failure causes the entire rewriting operation to be abandoned, and an | |
19895 | entry written to the panic log. | |
19896 | ||
19897 | ||
19898 | .section Rewriting flags | |
19899 | There are three different kinds of flag that may appear on rewriting rules: | |
19900 | .numberpars $. | |
19901 | Flags that specify which headers and envelope addresses to rewrite: E, F, T, b, | |
19902 | c, f, h, r, s, t. | |
19903 | .nextp | |
19904 | A flag that specifies rewriting at SMTP time: S. | |
19905 | .nextp | |
19906 | Flags that control the rewriting process: Q, q, R, w. | |
19907 | .endp | |
19908 | For rules that are part of the \headers@_rewrite\ generic transport option, | |
19909 | E, F, T, and S are not permitted. | |
19910 | ||
19911 | ||
19912 | .section Flags specifying which headers and envelope addresses to rewrite | |
19913 | .index rewriting||flags | |
19914 | If none of the following flag letters, nor the `S' flag (see section | |
19915 | ~~SECTrewriteS) are present, a main rewriting rule applies to all headers and | |
19916 | to both the sender and recipient fields of the envelope, whereas a | |
19917 | transport-time rewriting rule just applies to all headers. Otherwise, the | |
19918 | rewriting rule is skipped unless the relevant addresses are being processed. | |
19919 | .display | |
19920 | E $rm{rewrite all envelope fields} | |
19921 | F $rm{rewrite the envelope From field} | |
19922 | T $rm{rewrite the envelope To field} | |
19923 | b $rm{rewrite the ::Bcc:: header} | |
19924 | c $rm{rewrite the ::Cc:: header} | |
19925 | f $rm{rewrite the ::From:: header} | |
19926 | h $rm{rewrite all headers} | |
19927 | r $rm{rewrite the ::Reply-To:: header} | |
19928 | s $rm{rewrite the ::Sender:: header} | |
19929 | t $rm{rewrite the ::To:: header} | |
19930 | .endd | |
19931 | You should be particularly careful about rewriting ::Sender:: headers, and | |
19932 | restrict this to special known cases in your own domains. | |
19933 | ||
19934 | .section The SMTP-time rewriting flag | |
19935 | .rset SECTrewriteS "~~chapter.~~section" | |
19936 | .index SMTP||rewriting malformed addresses | |
19937 | .index \\RCPT\\||rewriting argument of | |
19938 | .index \\MAIL\\||rewriting argument of | |
19939 | The rewrite flag `S' specifies a rewrite of incoming envelope addresses at SMTP | |
19940 | time, as soon as an address is received in a \\MAIL\\ or \\RCPT\\ command, and | |
19941 | before any other processing; even before syntax checking. The pattern is | |
19942 | required to be a regular expression, and it is matched against the whole of the | |
19943 | data for the command, including any surrounding angle brackets. | |
19944 | ||
19945 | This form of rewrite rule allows for the handling of addresses that are not | |
19946 | compliant with RFCs 2821 and 2822 (for example, `bang paths' in batched SMTP | |
19947 | input). Because the input is not required to be a syntactically valid address, | |
19948 | the variables \$local@_part$\ and \$domain$\ are not available during the | |
19949 | expansion of the replacement string. The result of rewriting replaces the | |
19950 | original address in the \\MAIL\\ or \\RCPT\\ command. | |
19951 | ||
19952 | .section Flags controlling the rewriting process | |
19953 | There are four flags which control the way the rewriting process works. These | |
19954 | take effect only when a rule is invoked, that is, when the address is of the | |
19955 | correct type (matches the flags) and matches the pattern: | |
19956 | .numberpars $. | |
19957 | If the `Q' flag is set on a rule, the rewritten address is permitted to be an | |
19958 | unqualified local part. It is qualified with \qualify@_recipient\. In the | |
19959 | absence of `Q' the rewritten address must always include a domain. | |
19960 | .nextp | |
19961 | If the `q' flag is set on a rule, no further rewriting rules are considered, | |
19962 | even if no rewriting actually takes place because of a `fail' in the expansion. | |
19963 | The `q' flag is not effective if the address is of the wrong type (does not | |
19964 | match the flags) or does not match the pattern. | |
19965 | .nextp | |
19966 | The `R' flag causes a successful rewriting rule to be re-applied to the new | |
19967 | address, up to ten times. It can be combined with the `q' flag, to stop | |
19968 | rewriting once it fails to match (after at least one successful rewrite). | |
19969 | .nextp | |
19970 | .index rewriting||whole addresses | |
19971 | When an address in a header is rewritten, the rewriting normally applies only | |
19972 | to the working part of the address, with any comments and RFC 2822 `phrase' | |
19973 | left unchanged. For example, rewriting might change | |
19974 | .display asis | |
19975 | From: Ford Prefect <fp42@restaurant.hitch.fict.example> | |
19976 | .endd | |
19977 | into | |
19978 | .display asis | |
19979 | From: Ford Prefect <prefectf@hitch.fict.example> | |
19980 | .endd | |
19981 | Sometimes there is a need to replace the whole address item, and this can be | |
19982 | done by adding the flag letter `w' to a rule. If this is set on a rule that | |
19983 | causes an address in a header line to be rewritten, the entire address is | |
19984 | replaced, not just the working part. The replacement must be a complete RFC | |
19985 | 2822 address, including the angle brackets if necessary. If text outside angle | |
19986 | brackets contains a character whose value is greater than 126 or less than 32 | |
19987 | (except for tab), the text is encoded according to RFC 2047. | |
19988 | The character set is taken from \headers@_charset\, which defaults to | |
19989 | ISO-8859-1. | |
19990 | ||
19991 | When the `w' flag is set on a rule that causes an envelope address to be | |
19992 | rewritten, all but the working part of the replacement address is discarded. | |
19993 | .endp | |
19994 | ||
19995 | .section Rewriting examples | |
19996 | Here is an example of the two common rewriting paradigms: | |
19997 | .display asis | |
19998 | *@*.hitch.fict.example $1@hitch.fict.example | |
19999 | *@hitch.fict.example ${lookup{$1}dbm{/etc/realnames}\ | |
20000 | {$value}fail}@hitch.fict.example bctfrF | |
20001 | .endd | |
20002 | Note the use of `fail' in the lookup expansion in the second rule, forcing | |
20003 | the string expansion to fail if the lookup does not succeed. In this context it | |
20004 | has the effect of leaving the original address unchanged, but Exim goes on to | |
20005 | consider subsequent rewriting rules, if any, because the `q' flag is not | |
20006 | present in that rule. An alternative to `fail' would be to supply \$1$\ | |
20007 | explicitly, which would cause the rewritten address to be the same as before, | |
20008 | at the cost of a small bit of processing. Not supplying either of these is an | |
20009 | error, since the rewritten address would then contain no local part. | |
20010 | ||
20011 | The first example above replaces the domain with a superior, more general | |
20012 | domain. This may not be desirable for certain local parts. If the rule | |
20013 | .display asis | |
20014 | root@*.hitch.fict.example * | |
20015 | .endd | |
20016 | were inserted before the first rule, rewriting would be suppressed for the | |
20017 | local part \*root*\ at any domain ending in \*hitch.fict.example*\. | |
20018 | ||
20019 | Rewriting can be made conditional on a number of tests, by making use of | |
20020 | \${if$\ in the expansion item. For example, to apply a rewriting rule only to | |
20021 | messages that originate outside the local host: | |
20022 | .display asis | |
20023 | *@*.hitch.fict.example "${if !eq {$sender_host_address}{}\ | |
20024 | {$1@hitch.fict.example}fail}" | |
20025 | .endd | |
20026 | The replacement string is quoted in this example because it contains white | |
20027 | space. | |
20028 | ||
20029 | .index rewriting||bang paths | |
20030 | .index bang paths||rewriting | |
20031 | Exim does not handle addresses in the form of `bang paths'. If it sees such an | |
20032 | address it treats it as an unqualified local part which it qualifies with the | |
20033 | local qualification domain (if the source of the message is local or if the | |
20034 | remote host is permitted to send unqualified addresses). Rewriting can | |
20035 | sometimes be used to handle simple bang paths with a fixed number of | |
20036 | components. For example, the rule | |
20037 | .display asis | |
20038 | \N^([^!]+)!(.*)@your.domain.example$\N $2@$1 | |
20039 | .endd | |
20040 | rewrites a two-component bang path \*host.name!user*\ as the domain address | |
20041 | \*user@@host.name*\. However, there is a security implication in using this as | |
20042 | a global rewriting rule for envelope addresses. It can provide a backdoor | |
20043 | method for using your system as a relay, because the incoming addresses appear | |
20044 | to be local. If the bang path addresses are received via SMTP, it is safer to | |
20045 | use the `S' flag to rewrite them as they are received, so that relay checking | |
20046 | can be done on the rewritten addresses. | |
20047 | ||
20048 | ||
20049 | ||
20050 | ||
20051 | ||
20052 | . | |
20053 | . | |
20054 | . | |
20055 | . | |
20056 | . ============================================================================ | |
20057 | .chapter Retry configuration | |
20058 | .set runningfoot "retry configuration" | |
20059 | .rset CHAPretry ~~chapter | |
20060 | .index retry||configuration, description of | |
20061 | .index configuration file||retry section | |
20062 | The `retry' section of the run time configuration file contains a list of retry | |
20063 | rules which control how often Exim tries to deliver messages that cannot be | |
20064 | delivered at the first attempt. If there are no retry rules, temporary errors | |
20065 | are treated as permanent. The \-brt-\ command line option can be used to test | |
20066 | which retry rule will be used for a given address or domain. | |
20067 | ||
20068 | The most common cause of retries is temporary failure to deliver to a remote | |
20069 | host because the host is down, or inaccessible because of a network problem. | |
20070 | Exim's retry processing in this case is applied on a per-host (strictly, per IP | |
20071 | address) basis, not on a per-message basis. Thus, if one message has recently | |
20072 | been delayed, delivery of a new message to the same host is not immediately | |
20073 | tried, but waits for the host's retry time to arrive. If the \retry@_defer\ log | |
20074 | selector is set, the message | |
20075 | .index retry||time not reached | |
20076 | `retry time not reached' is written to the main log whenever a delivery is | |
20077 | skipped for this reason. Section ~~SECToutSMTPerr contains more details of the | |
20078 | handling of errors during remote deliveries. | |
20079 | ||
20080 | Retry processing applies to routing as well as to delivering, except as covered | |
20081 | in the next paragraph. The retry rules do not distinguish between these | |
20082 | actions. It is not possible, for example, to specify different behaviour for | |
20083 | failures to route the domain \*snark.fict.example*\ and failures to deliver to | |
20084 | the host \*snark.fict.example*\. I didn't think anyone would ever need this | |
20085 | added complication, so did not implement it. However, although they share the | |
20086 | same retry rule, the actual retry times for routing and transporting a given | |
20087 | domain are maintained independently. | |
20088 | ||
20089 | When a delivery is not part of a queue run (typically an immediate delivery on | |
20090 | receipt of a message), the routers are always run, and local deliveries are | |
20091 | always attempted, even if retry times are set for them. This makes for better | |
20092 | behaviour if one particular message is causing problems (for example, causing | |
20093 | quota overflow, or provoking an error in a filter file). If such a delivery | |
20094 | suffers a temporary failure, the retry data is updated as normal, and | |
20095 | subsequent delivery attempts from queue runs occur only when the retry time for | |
20096 | the local address is reached. | |
20097 | ||
20098 | ||
20099 | .section Retry rules | |
20100 | .index retry||rules | |
d43194df PH |
20101 | .em |
20102 | Each retry rule occupies one line and consists of three or four parts, | |
20103 | separated by white space: a pattern, an error name, an optional list of sender | |
20104 | addresses, and a list of retry parameters. The pattern and sender lists must be | |
20105 | enclosed in double quotes if they contain white space. The rules are searched in | |
20106 | order until one is found where the pattern, error name, and sender list (if | |
20107 | present) match the failing host or address, the error that occurred, and the | |
20108 | message's sender, respectively. | |
20109 | .nem | |
495ae4b0 PH |
20110 | |
20111 | The pattern is any single item that may appear in an address list (see section | |
20112 | ~~SECTaddresslist). It is in fact processed as a one-item address list, which | |
20113 | means that it is expanded before being tested against the address that has | |
20114 | been delayed. Address list processing treats a plain domain name as if it were | |
20115 | preceded by `*@@', which makes it possible for many retry rules to start with | |
20116 | just a domain. For example, | |
20117 | .display asis | |
20118 | lookingglass.fict.example * F,24h,30m; | |
20119 | .endd | |
20120 | provides a rule for any address in the \*lookingglass.fict.example*\ domain, | |
20121 | whereas | |
20122 | .display asis | |
20123 | alice@lookingglass.fict.example * F,24h,30m; | |
20124 | .endd | |
20125 | applies only to temporary failures involving the local part \alice\. | |
4964e932 | 20126 | In practice, almost all rules start with a domain name pattern without a local |
495ae4b0 PH |
20127 | part. |
20128 | ||
20129 | .index regular expressions||in retry rules | |
d43194df PH |
20130 | \**Warning**\: If you use a regular expression in a routing rule pattern, it |
20131 | must match a complete address, not just a domain, because that is how regular | |
20132 | expressions work in address lists. | |
495ae4b0 PH |
20133 | .display |
20134 | ^@\Nxyz@\d+@\.abc@\.example@$@\N * G,1h,10m,2 \Wrong\ | |
20135 | ^@\N[^@@]+@@xyz@\d+@\.abc@\.example@$@\N * G,1h,10m,2 \Right\ | |
20136 | .endd | |
20137 | ||
20138 | ||
20139 | .section Choosing which retry rule to use | |
20140 | When Exim is looking for a retry rule after a routing attempt has failed (for | |
20141 | example, after a DNS timeout), each line in the retry configuration is tested | |
20142 | against the complete address only if \retry__use@_local@_part\ is set for the | |
20143 | router. Otherwise, only the domain is used, except when matching against a | |
20144 | regular expression, when the local part of the address is replaced with `*'. A | |
20145 | domain on its own can match a domain pattern, or a pattern that starts with | |
20146 | `*@@'. By default, \retry@_use@_local@_part\ is true for routers where | |
20147 | \check@_local@_user\ is true, and false for other routers. | |
20148 | ||
20149 | Similarly, when Exim is looking for a retry rule after a local delivery has | |
20150 | failed (for example, after a mailbox full error), each line in the retry | |
20151 | configuration is tested against the complete address only if | |
20152 | \retry@_use@_local@_part\ is set for the transport (it defaults true for all | |
20153 | local transports). | |
20154 | ||
495ae4b0 PH |
20155 | When Exim is looking for a retry rule after a remote delivery attempt has |
20156 | failed, what happens depends on the type of failure. After a 4\*xx*\ SMTP | |
20157 | response for a recipient address, the whole address is used when searching the | |
4964e932 | 20158 | retry rules. The rule that is found is used to create a retry time for the |
495ae4b0 PH |
20159 | failing address. |
20160 | ||
20161 | For a temporary error that is not related to an individual address, | |
495ae4b0 PH |
20162 | (for example, a connection timeout), each line in the retry configuration is |
20163 | checked twice. First, the name of the remote host is used as a domain name | |
20164 | (preceded by `*@@' when matching a regular expression). If this does not match | |
20165 | the line, the domain from the email address is tried in a similar fashion. For | |
20166 | example, suppose the MX records for \*a.b.c.example*\ are | |
20167 | .display asis | |
20168 | a.b.c.example MX 5 x.y.z.example | |
20169 | MX 6 p.q.r.example | |
20170 | MX 7 m.n.o.example | |
20171 | .endd | |
20172 | and the retry rules are | |
20173 | .display asis | |
20174 | p.q.r.example * F,24h,30m; | |
20175 | a.b.c.example * F,4d,45m; | |
20176 | .endd | |
20177 | and a delivery to the host \*x.y.z.example*\ fails. The first rule matches | |
20178 | neither the host nor the domain, so Exim looks at the second rule. This does | |
20179 | not match the host, but it does match the domain, so it is used to calculate | |
20180 | the retry time for the host \*x.y.z.example*\. Meanwhile, Exim tries to deliver | |
20181 | to \*p.q.r.example*\. If this fails, the first retry rule is used, because it | |
20182 | matches the host. | |
20183 | ||
20184 | In other words, failures to deliver to host \*p.q.r.example*\ use the first | |
20185 | rule to determine retry times, but for all the other hosts for the domain | |
20186 | \*a.b.c.example*\, the second rule is used. The second rule is also used if | |
20187 | routing to \*a.b.c.example*\ suffers a temporary failure. | |
20188 | ||
20189 | .section Retry rules for specific errors | |
20190 | .index retry||specific errors, specifying | |
20191 | The second field in a retry rule is the name of a particular error, or an | |
20192 | asterisk, which matches any error. The errors that can be tested for are: | |
d43194df PH |
20193 | .em |
20194 | ||
20195 | .push | |
20196 | .indent 2em | |
20197 | .tempindent 0 | |
20198 | \auth@_failed\: Authentication failed when trying to send to a host in the | |
20199 | \hosts@_require@_auth\ list in an \%smtp%\ transport. | |
20200 | ||
20201 | .tempindent 0 | |
20202 | \rcpt@_4xx\: A 4\*xx*\ error was received for an outgoing \\RCPT\\ command. | |
20203 | Either the first or both of the x's can be given as specific digits, for | |
20204 | example: \"rcpt@_45x"\ or \"rcpt@_436"\. For example, to recognize 452 errors | |
20205 | given to \\RCPT\\ commands by a particular host, and have retries every ten | |
20206 | minutes and a one-hour timeout, you could set up a retry rule of this form: | |
20207 | .display asis | |
20208 | the.host.name rcpt_452 F,1h,10m | |
20209 | .endd | |
20210 | These errors apply to both outgoing SMTP (the \%smtp%\ transport) and outgoing | |
20211 | LMTP (either the \%lmtp%\ transport, or the \%smtp%\ transport in LMTP mode). | |
20212 | Note, however, that they apply only to responses to \\RCPT\\ commands. | |
20213 | ||
20214 | .tempindent 0 | |
20215 | \refused@_MX\: A connection to a host obtained from an MX record was refused. | |
20216 | ||
20217 | .tempindent 0 | |
20218 | \refused@_A\: A connection to a host not obtained from an MX record was | |
20219 | refused. | |
20220 | ||
20221 | .tempindent 0 | |
20222 | \refused\: A connection was refused. | |
20223 | ||
20224 | .tempindent 0 | |
20225 | \timeout@_connect@_MX\: A connection attempt to a host obtained from an MX | |
20226 | record timed out. | |
20227 | ||
20228 | .tempindent 0 | |
20229 | \timeout@_connect@_A\: A connection attempt to a host not obtained from an MX | |
20230 | record timed out. | |
20231 | ||
20232 | .tempindent 0 | |
20233 | \timeout@_connect\: A connection attempt timed out. | |
20234 | ||
20235 | .tempindent 0 | |
20236 | \timeout@_MX\: There was a timeout while connecting or during an SMTP session | |
20237 | with a host obtained from an MX record. | |
20238 | ||
20239 | .tempindent 0 | |
20240 | \timeout@_A\: There was a timeout while connecting or during an SMTP session | |
20241 | with a host not obtained from an MX record. | |
20242 | ||
20243 | .tempindent 0 | |
20244 | \timeout\: There was a timeout while connecting or during an SMTP session. | |
20245 | ||
20246 | .tempindent 0 | |
20247 | \quota\: A mailbox quota was exceeded in a local delivery by the | |
20248 | \%appendfile%\ transport. | |
20249 | ||
20250 | .index quota||error testing in retry rule | |
495ae4b0 | 20251 | .index retry||quota error testing |
d43194df PH |
20252 | .tempindent 0 |
20253 | \quota@_\<<time>>: A mailbox quota was exceeded in a local delivery by | |
20254 | the \%appendfile%\ transport, and the mailbox has not been accessed for | |
20255 | <<time>>. For example, \*quota@_4d*\ applies to a quota error when the mailbox | |
20256 | has not been accessed for four days. | |
20257 | ||
20258 | .pop | |
20259 | ||
495ae4b0 | 20260 | |
495ae4b0 | 20261 | .index mailbox||time of last read |
d43194df PH |
20262 | The idea of \quota@_\<<time>> is to make it possible to have shorter timeouts |
20263 | when the mailbox is full and is not being read by its owner. Ideally, it should | |
20264 | be based on the last time that the user accessed the mailbox. However, it is | |
20265 | not always possible to determine this. Exim uses the following heuristic rules: | |
495ae4b0 | 20266 | .numberpars $. |
d43194df PH |
20267 | If the mailbox is a single file, the time of last access (the `atime') is used. |
20268 | As no new messages are being delivered (because the mailbox is over quota), | |
20269 | Exim does not access the file, so this is the time of last user access. | |
495ae4b0 PH |
20270 | .nextp |
20271 | .index maildir format||time of last read | |
4964e932 | 20272 | For a maildir delivery, the time of last modification of the \(new)\ |
d43194df PH |
20273 | subdirectory is used. As the mailbox is over quota, no new files are created in |
20274 | the \(new)\ subdirectory, because no new messages are being delivered. Any | |
20275 | change to the \(new)\ subdirectory is therefore assumed to be the result of an | |
20276 | MUA moving a new message to the \(cur)\ directory when it is first read. The | |
20277 | time that is used is therefore the last time that the user read a new message. | |
20278 | .nextp | |
20279 | For other kinds of multi-file mailbox, the time of last access cannot be | |
20280 | obtained, so a retry rule that uses this type of error field is never matched. | |
495ae4b0 | 20281 | .endp |
d43194df | 20282 | .nem |
495ae4b0 PH |
20283 | The quota errors apply both to system-enforced quotas and to Exim's own quota |
20284 | mechanism in the \%appendfile%\ transport. The \*quota*\ error also applies | |
20285 | when a local delivery is deferred because a partition is full (the \\ENOSPC\\ | |
20286 | error). | |
20287 | ||
20288 | ||
d43194df PH |
20289 | .em |
20290 | .section Retry rules for specified senders | |
20291 | .index retry||rules, sender-specific | |
20292 | You can specify retry rules that apply only when the failing message has a | |
20293 | specific sender. In particular, this can be used to define retry rules that | |
20294 | apply only to bounce messages. The third item in a retry rule can be of this | |
20295 | form: | |
20296 | .display | |
20297 | senders=<<address list>> | |
20298 | .endd | |
20299 | The retry timings themselves are then the fourth item. For example: | |
20300 | .display asis | |
20301 | * * senders=: F,1h,30m | |
20302 | .endd | |
20303 | matches all temporary errors for bounce messages sent to any host. If the | |
20304 | address list contains white space, it must be enclosed in quotes. For example: | |
20305 | .display | |
20306 | a.domain timeout senders="x@b.dom : y@c.dom" G,8h,10m,1.5 | |
20307 | .endd | |
20308 | When testing retry rules using \-brt-\, you can supply a sender using the \-f-\ | |
20309 | command line option, like this: | |
20310 | .display asis | |
20311 | exim -f "" -brt user@dom.ain | |
20312 | .endd | |
20313 | If you do not set \-f-\ with \-brt-\, a retry rule that contains a senders list | |
20314 | is never matched. | |
20315 | .nem | |
20316 | ||
20317 | ||
20318 | ||
20319 | .section Retry parameters | |
495ae4b0 | 20320 | .index retry||parameters in rules |
d43194df PH |
20321 | The third |
20322 | .em | |
20323 | (or fourth, if a senders list is present) | |
20324 | .nem | |
20325 | field in a retry rule is a sequence of retry parameter sets, separated by | |
20326 | semicolons. Each set consists of | |
495ae4b0 PH |
20327 | .display |
20328 | <<letter>>,<<cutoff time>>,<<arguments>> | |
20329 | .endd | |
20330 | The letter identifies the algorithm for computing a new retry time; the cutoff | |
20331 | time is the time beyond which this algorithm no longer applies, and the | |
20332 | arguments vary the algorithm's action. The cutoff time is measured from the | |
20333 | time that the first failure for the domain (combined with the local part if | |
20334 | relevant) was detected, not from the time the message was received. | |
20335 | .index retry||algorithms | |
20336 | The available algorithms are: | |
20337 | .numberpars $. | |
d43194df PH |
20338 | \*F*\: retry at fixed intervals. There is a single time parameter specifying |
20339 | the interval. | |
495ae4b0 | 20340 | .nextp |
d43194df PH |
20341 | \*G*\: retry at geometrically increasing intervals. The first argument |
20342 | specifies a starting value for the interval, and the second a multiplier, which | |
20343 | is used to increase the size of the interval at each retry. | |
495ae4b0 PH |
20344 | .endp |
20345 | When computing the next retry time, the algorithm definitions are scanned in | |
20346 | order until one whose cutoff time has not yet passed is reached. This is then | |
20347 | used to compute a new retry time that is later than the current time. In the | |
20348 | case of fixed interval retries, this simply means adding the interval to the | |
20349 | current time. For geometrically increasing intervals, retry intervals are | |
20350 | computed from the rule's parameters until one that is greater than the previous | |
20351 | interval is found. The main configuration variable | |
20352 | .index limit||retry interval | |
20353 | .index retry||interval, maximum | |
20354 | .index \retry@_interval@_max\ | |
20355 | \retry@_interval@_max\ limits the maximum interval between retries. | |
20356 | ||
20357 | A single remote domain may have a number of hosts associated with it, and each | |
20358 | host may have more than one IP address. Retry algorithms are selected on the | |
20359 | basis of the domain name, but are applied to each IP address independently. If, | |
20360 | for example, a host has two IP addresses and one is unusable, Exim will | |
20361 | generate retry times for it and will not try to use it until its next retry | |
20362 | time comes. Thus the good IP address is likely to be tried first most of the | |
20363 | time. | |
20364 | ||
20365 | .index hints database||use for retrying | |
20366 | Retry times are hints rather than promises. Exim does not make any attempt to | |
20367 | run deliveries exactly at the computed times. Instead, a queue runner process | |
20368 | starts delivery processes for delayed messages periodically, and these attempt | |
20369 | new deliveries only for those addresses that have passed their next retry time. | |
20370 | If a new message arrives for a deferred address, an immediate delivery attempt | |
20371 | occurs only if the address has passed its retry time. In the absence of new | |
20372 | messages, the minimum time between retries is the interval between queue runner | |
20373 | processes. There is not much point in setting retry times of five minutes if | |
20374 | your queue runners happen only once an hour, unless there are a significant | |
20375 | number of incoming messages (which might be the case on a system that is | |
20376 | sending everything to a smart host, for example). | |
20377 | ||
20378 | The data in the retry hints database can be inspected by using the | |
20379 | \*exim@_dumpdb*\ or \*exim@_fixdb*\ utility programs (see chapter ~~CHAPutils). The | |
20380 | latter utility can also be used to change the data. The \*exinext*\ utility | |
20381 | script can be used to find out what the next retry times are for the hosts | |
20382 | associated with a particular mail domain, and also for local deliveries that | |
20383 | have been deferred. | |
20384 | ||
20385 | .section Retry rule examples | |
20386 | Here are some example retry rules: | |
20387 | .display asis | |
20388 | alice@wonderland.fict.example quota_5d F,7d,3h | |
20389 | wonderland.fict.example quota_5d | |
20390 | wonderland.fict.example * F,1h,15m; G,2d,1h,2; | |
20391 | lookingglass.fict.example * F,24h,30m; | |
20392 | * refused_A F,2h,20m; | |
20393 | * * F,2h,15m; G,16h,1h,1.5; F,5d,8h | |
20394 | .endd | |
20395 | The first rule sets up special handling for mail to | |
20396 | \*alice@@wonderland.fict.example*\ when there is an over-quota error and the | |
20397 | mailbox has not been read for at least 5 days. Retries continue every three | |
20398 | hours for 7 days. The second rule handles over-quota errors for all other local | |
20399 | parts at \*wonderland.fict.example*\; the absence of a local part has the same | |
20400 | effect as supplying `$*$@@'. As no retry algorithms are supplied, messages that | |
20401 | fail are bounced immediately if the mailbox has not been read for at least 5 | |
20402 | days. | |
20403 | ||
20404 | The third rule handles all other errors at \*wonderland.fict.example*\; retries | |
20405 | happen every 15 minutes for an hour, then with geometrically increasing | |
20406 | intervals until two days have passed since a delivery first failed. After the | |
20407 | first hour there is a delay of one hour, then two hours, then four hours, and | |
20408 | so on (this is a rather extreme example). | |
20409 | ||
20410 | The fourth rule controls retries for the domain \*lookingglass.fict.example*\. | |
20411 | They happen every 30 minutes for 24 hours only. The remaining two rules handle | |
20412 | all other domains, with special action for connection refusal from hosts that | |
20413 | were not obtained from an MX record. | |
20414 | ||
20415 | The final rule in a retry configuration should always have asterisks in the | |
20416 | first two fields so as to provide a general catch-all for any addresses that do | |
20417 | not have their own special handling. This example tries every 15 minutes for 2 | |
20418 | hours, then with intervals starting at one hour and increasing by a factor of | |
20419 | 1.5 up to 16 hours, then every 8 hours up to 5 days. | |
20420 | ||
20421 | ||
20422 | .section Timeout of retry data | |
20423 | .index timeout||of retry data | |
20424 | .index \retry@_data@_expire\ | |
20425 | .index hints database||data expiry | |
20426 | .index retry||timeout of data | |
20427 | Exim timestamps the data that it writes to its retry hints database. When it | |
20428 | consults the data during a delivery it ignores any that is older than the value | |
20429 | set in \retry@_data@_expire\ (default 7 days). If, for example, a host hasn't | |
20430 | been tried for 7 days, Exim will try to deliver to it immediately a message | |
20431 | arrives, and if that fails, it will calculate a retry time as if it were | |
20432 | failing for the first time. | |
20433 | ||
20434 | This improves the behaviour for messages routed to rarely-used hosts such as MX | |
20435 | backups. If such a host was down at one time, and happens to be down again when | |
20436 | Exim tries a month later, using the old retry data would imply that it had been | |
20437 | down all the time, which is not a justified assumption. | |
20438 | ||
20439 | If a host really is permanently dead, this behaviour causes a burst of retries | |
20440 | every now and again, but only if messages routed to it are rare. It there is a | |
20441 | message at least once every 7 days the retry data never expires. | |
20442 | ||
20443 | ||
20444 | ||
20445 | .section Long-term failures | |
20446 | .index delivery||failure, long-term | |
20447 | .index retry||after long-term failure | |
20448 | Special processing happens when an email address has been failing for so long | |
20449 | that the cutoff time for the last algorithm is reached. For example, using the | |
20450 | default retry rule: | |
20451 | .display asis | |
20452 | * * F,2h,15m; G,16h,1h,1.5; F,4d,6h | |
20453 | .endd | |
20454 | the cutoff time is four days. Reaching the retry cutoff is independent of how | |
20455 | long any specific message has been failing; it is the length of continuous | |
4964e932 | 20456 | failure for the recipient address that counts. |
495ae4b0 PH |
20457 | |
20458 | When the cutoff time is reached for a local delivery, or for all the IP | |
20459 | addresses associated with a remote delivery, a subsequent delivery failure | |
20460 | causes Exim to give up on the address, and a bounce message is generated. | |
20461 | In order to cater for new messages that use the failing address, a next retry | |
20462 | time is still computed from the final algorithm, and is used as follows: | |
20463 | ||
20464 | For local deliveries, one delivery attempt is always made for any subsequent | |
20465 | messages. If this delivery fails, the address fails immediately. The | |
20466 | post-cutoff retry time is not used. | |
20467 | ||
20468 | If the delivery is remote, there are two possibilities, controlled by the | |
20469 | .index \delay@_after@_cutoff\ | |
20470 | \delay@_after@_cutoff\ option of the \%smtp%\ transport. The option is true by | |
20471 | default and in that case: | |
20472 | .numberpars " " | |
20473 | Until the post-cutoff retry time for one of the IP addresses is reached, | |
20474 | the failing email address is bounced immediately, without a delivery attempt | |
20475 | taking place. After that time, one new delivery attempt is made to those IP | |
20476 | addresses that are past their retry times, and if that still fails, the address | |
20477 | is bounced and new retry times are computed. | |
20478 | .endp | |
20479 | ||
20480 | In other words, when all the hosts for a given email address have been failing | |
20481 | for a long time, Exim bounces rather then defers until one of the hosts' retry | |
20482 | times is reached. Then it tries once, and bounces if that attempt fails. This | |
20483 | behaviour ensures that few resources are wasted in repeatedly trying to deliver | |
20484 | to a broken destination, but if the host does recover, Exim will eventually | |
20485 | notice. | |
20486 | ||
20487 | If \delay@_after@_cutoff\ is set false, Exim behaves differently. If all IP | |
20488 | addresses are past their final cutoff time, Exim tries to deliver to those IP | |
20489 | addresses that have not been tried since the message arrived. If there are | |
20490 | no suitable IP addresses, or if they all fail, the address is bounced. In other | |
20491 | words, it does not delay when a new message arrives, but tries the expired | |
20492 | addresses immediately, unless they have been tried since the message arrived. | |
20493 | If there is a continuous stream of messages for the failing domains, setting | |
20494 | \delay@_after@_cutoff\ false means that there will be many more attempts to | |
20495 | deliver to permanently failing IP addresses than when \delay@_after@_cutoff\ is | |
20496 | true. | |
20497 | ||
20498 | .section Ultimate address timeout | |
20499 | .index retry||ultimate address timeout | |
20500 | An additional rule is needed to cope with cases where a host is intermittently | |
20501 | available, or when a message has some attribute that prevents its delivery when | |
20502 | others to the same address get through. In this situation, because some | |
20503 | messages are successfully delivered, the `retry clock' for the address keeps | |
20504 | getting restarted, and so a message could remain on the queue for ever. To | |
20505 | prevent this, if a message has been on the queue for longer than the cutoff | |
20506 | time of any applicable retry rule for a given address, a delivery is attempted | |
20507 | for that address, even if it is not yet time, and if this delivery fails, the | |
20508 | address is timed out. A new retry time is not computed in this case, so that | |
20509 | other messages for the same address are considered immediately. | |
20510 | ||
20511 | ||
20512 | ||
20513 | ||
20514 | ||
20515 | . | |
20516 | . | |
20517 | . | |
20518 | . | |
20519 | . ============================================================================ | |
20520 | .chapter SMTP authentication | |
20521 | .set runningfoot "SMTP authentication" | |
20522 | .rset CHAPSMTPAUTH "~~chapter" | |
20523 | .index SMTP||authentication configuration | |
20524 | .index authentication | |
20525 | The `authenticators' section of Exim's run time configuration is concerned with | |
20526 | SMTP authentication. This facility is an extension to the SMTP protocol, | |
20527 | described in RFC 2554, which allows a client SMTP host to authenticate itself | |
20528 | to a server. This is a common way for a server to recognize clients that | |
20529 | are permitted to use it as a relay. SMTP authentication is not of relevance to | |
20530 | the transfer of mail between servers that have no managerial connection with | |
20531 | each other. | |
20532 | ||
20533 | .index \\AUTH\\||description of | |
20534 | Very briefly, the way SMTP authentication works is as follows: | |
20535 | .numberpars $. | |
4964e932 | 20536 | The server advertises a number of authentication \*mechanisms*\ in response to |
495ae4b0 PH |
20537 | the client's \\EHLO\\ command. |
20538 | .nextp | |
20539 | The client issues an \\AUTH\\ command, naming a specific mechanism. The command | |
20540 | may, optionally, contain some authentication data. | |
20541 | .nextp | |
20542 | The server may issue one or more \*challenges*\, to which the client must send | |
20543 | appropriate responses. In simple authentication mechanisms, the challenges are | |
20544 | just prompts for user names and passwords. The server does not have to issue | |
20545 | any challenges -- in some mechanisms the relevant data may all be transmitted | |
20546 | with the \\AUTH\\ command. | |
20547 | .nextp | |
20548 | The server either accepts or denies authentication. | |
20549 | .nextp | |
20550 | If authentication succeeds, the client may optionally make use of the \\AUTH\\ | |
20551 | option on the \\MAIL\\ command to pass an authenticated sender in subsequent | |
20552 | mail transactions. Authentication lasts for the remainder of the SMTP | |
20553 | connection. | |
20554 | .nextp | |
20555 | If authentication fails, the client may give up, or it may try a different | |
20556 | authentication mechanism, or it may try transferring mail over the | |
20557 | unauthenticated connection. | |
20558 | .endp | |
20559 | If you are setting up a client, and want to know which authentication | |
20560 | mechanisms the server supports, you can use Telnet to connect to port 25 (the | |
20561 | SMTP port) on the server, and issue an \\EHLO\\ command. The response to this | |
20562 | includes the list of supported mechanisms. For example: | |
20563 | .display | |
20564 | @$ $cb{telnet server.example 25} | |
20565 | Trying 192.168.34.25... | |
20566 | Connected to server.example. | |
20567 | Escape character is '@^]'. | |
20568 | 220 server.example ESMTP Exim 4.20 ... | |
20569 | $cb{ehlo client.example} | |
20570 | 250-server.example Hello client.example [10.8.4.5] | |
20571 | 250-SIZE 52428800 | |
20572 | 250-PIPELINING | |
20573 | 250-AUTH PLAIN | |
20574 | 250 HELP | |
20575 | .endd | |
20576 | The second-last line of this example output shows that the server supports | |
20577 | authentication using the PLAIN mechanism. In Exim, the different authentication | |
20578 | mechanisms are configured by specifying \*authenticator*\ drivers. Like the | |
20579 | routers and transports, which authenticators are included in the binary is | |
20580 | controlled by build-time definitions. The following are currently available, | |
20581 | included by setting | |
20582 | .display asis | |
20583 | AUTH_CRAM_MD5=yes | |
20584 | AUTH_PLAINTEXT=yes | |
20585 | AUTH_SPA=yes | |
20586 | .endd | |
20587 | in \(Local/Makefile)\, respectively. The first of these supports the CRAM-MD5 | |
20588 | authentication mechanism (RFC 2195), and the second can be configured to | |
20589 | support the PLAIN authentication mechanism (RFC 2595) or the LOGIN mechanism, | |
20590 | which is not formally documented, but used by several MUAs. The third | |
20591 | authenticator supports Microsoft's \*Secure Password Authentication*\ | |
20592 | mechanism. | |
20593 | ||
20594 | The authenticators are configured using the same syntax as other drivers (see | |
20595 | section ~~SECTfordricon). If no authenticators are required, no authentication | |
20596 | section need be present in the configuration file. Each authenticator can in | |
20597 | principle have both server and client functions. When Exim is receiving SMTP | |
20598 | mail, it is acting as a server; when it is sending out messages over SMTP, it | |
20599 | is acting as a client. Authenticator configuration options are provided for use | |
20600 | in both these circumstances. | |
20601 | ||
20602 | To make it clear which options apply to which situation, the prefixes | |
20603 | \server@_\ and \client@_\ are used on option names that are specific to either | |
20604 | the server or the client function, respectively. Server and client functions | |
20605 | are disabled if none of their options are set. If an authenticator is to be | |
20606 | used for both server and client functions, a single definition, using both sets | |
20607 | of options, is required. For example: | |
20608 | .display asis | |
20609 | cram: | |
20610 | driver = cram_md5 | |
20611 | public_name = CRAM-MD5 | |
20612 | server_secret = ${if eq{$1}{ph10}{secret1}fail} | |
20613 | client_name = ph10 | |
20614 | client_secret = secret2 | |
20615 | .endd | |
20616 | The \server@_\ option is used when Exim is acting as a server, and the | |
20617 | \client@_\ options when it is acting as a client. | |
20618 | ||
20619 | Descriptions of the individual authenticators are given in subsequent chapters. | |
20620 | The remainder of this chapter covers the generic options for the | |
20621 | authenticators, followed by general discussion of the way authentication works | |
20622 | in Exim. | |
20623 | ||
20624 | ||
20625 | .section Generic options for authenticators | |
20626 | .index authentication||generic options | |
20627 | ||
d43194df | 20628 | .startconf authenticators |
495ae4b0 PH |
20629 | .index options||generic, for authenticators |
20630 | ||
20631 | .conf driver string unset | |
20632 | This option must always be set. It specifies which of the available | |
20633 | authenticators is to be used. | |
20634 | ||
20635 | .conf public@_name string unset | |
20636 | This option specifies the name of the authentication mechanism that the driver | |
20637 | implements, and by which it is known to the outside world. These names should | |
20638 | contain only upper case letters, digits, underscores, and hyphens (RFC 2222), | |
20639 | but Exim in fact matches them caselessly. If \public@_name\ is not set, it | |
20640 | defaults to the driver's instance name. | |
20641 | ||
20642 | .conf server@_advertise@_condition string$**$ unset | |
20643 | When a server is about to advertise an authentication mechanism, the condition | |
20644 | is expanded. If it yields the empty string, `0', `no', or `false', the | |
4964e932 PH |
20645 | mechanism is not advertised. |
20646 | If the expansion fails, the mechanism is not advertised. If the failure was not | |
495ae4b0 PH |
20647 | forced, and was not caused by a lookup defer, the incident is logged. |
20648 | See section ~~SECTauthexiser below for further discussion. | |
20649 | ||
20650 | .conf server@_debug@_print string$**$ unset | |
20651 | If this option is set and authentication debugging is enabled (see the \-d-\ | |
20652 | command line option), the string is expanded and included in the debugging | |
20653 | output when the authenticator is run as a server. This can help with checking | |
20654 | out the values of variables. | |
4964e932 | 20655 | If expansion of the string fails, the error message is written to the debugging |
495ae4b0 PH |
20656 | output, and Exim carries on processing. |
20657 | ||
20658 | .conf server@_set@_id string$**$ unset | |
20659 | When an Exim server successfully authenticates a client, this string is | |
20660 | expanded using data from the authentication, and preserved for any incoming | |
20661 | messages in the variable \$authenticated@_id$\. It is also included in the log | |
20662 | lines for incoming messages. For example, a user/password authenticator | |
20663 | configuration might preserve the user name that was used to authenticate, and | |
20664 | refer to it subsequently during delivery of the message. | |
20665 | If expansion fails, the option is ignored. | |
20666 | ||
20667 | .conf server@_mail@_auth@_condition string$**$ unset | |
20668 | This option allows a server to discard authenticated sender addresses supplied | |
4964e932 | 20669 | as part of \\MAIL\\ commands in SMTP connections that are authenticated by the |
495ae4b0 PH |
20670 | driver on which \server__mail__auth@_condition\ is set. The option is not used |
20671 | as part of the authentication process; instead its (unexpanded) value is | |
20672 | remembered for later use. | |
20673 | How it is used is described in the following section. | |
20674 | .endconf | |
20675 | ||
20676 | ||
20677 | ||
20678 | .section The AUTH parameter on MAIL commands | |
20679 | .rset SECTauthparamail "~~chapter.~~section" | |
20680 | .index authentication||sender, authenticated | |
20681 | .index \\AUTH\\||on \\MAIL\\ command | |
4964e932 | 20682 | When a client supplied an \\AUTH=\\ item on a \\MAIL\\ command, Exim applies |
495ae4b0 PH |
20683 | the following checks before accepting it as the authenticated sender of the |
20684 | message: | |
20685 | .numberpars $. | |
4964e932 | 20686 | If the connection is not using extended SMTP (that is, \\HELO\\ was used rather |
495ae4b0 PH |
20687 | than \\EHLO\\), the use of \\AUTH=\\ is a syntax error. |
20688 | .nextp | |
20689 | If the value of the \\AUTH=\\ parameter is `@<@>', it is ignored. | |
20690 | .nextp | |
20691 | If \acl@_smtp@_mailauth\ is defined, the ACL it specifies is run. While it is | |
20692 | running, the value of \$authenticated@_sender$\ is set to the value obtained | |
20693 | from the \\AUTH=\\ parameter. If the ACL does not yield `accept', the value of | |
20694 | \$authenticated@_sender$\ is deleted. The \acl@_smtp@_mailauth\ ACL may not | |
20695 | return `drop' or `discard'. If it defers, a temporary error code (451) is given | |
20696 | for the \\MAIL\\ command. | |
20697 | .nextp | |
20698 | If \acl@_smtp@_mailauth\ is not defined, the value of the \\AUTH=\\ parameter | |
20699 | is accepted and placed in \$authenticated@_sender$\ only if the client has | |
20700 | authenticated. | |
20701 | .nextp | |
20702 | If the \\AUTH=\\ value was accepted by either of the two previous rules, and | |
20703 | the client has authenticated, and the authenticator has a setting for the | |
20704 | \server@_mail@_auth@_condition\, the condition is checked at this point. The | |
20705 | valued that was saved from the authenticator is expanded. If the expansion | |
20706 | fails, or yields an empty string, `0', `no', or `false', the value of | |
20707 | \$authenticated__sender$\ is deleted. If the expansion yields any other value, | |
20708 | the value of \$authenticated@_sender$\ is retained and passed on with the | |
20709 | message. | |
20710 | .endp | |
20711 | ||
20712 | When \$authenticated@_sender$\ is set for a message, it is passed on to other | |
20713 | hosts to which Exim authenticates as a client. Do not confuse this value with | |
20714 | \$authenticated@_id$\, which is a string obtained from the authentication | |
20715 | process, and which is not usually a complete email address. | |
20716 | ||
20717 | Whenever an \\AUTH=\\ value is ignored, the incident is logged. The ACL for | |
20718 | \\MAIL\\, if defined, is run after \\AUTH=\\ is accepted or ignored. It can | |
20719 | therefore make use of \$authenticated@_sender$\. The converse is not true: the | |
20720 | value of \$sender@_address$\ is not yet set up when the \acl@_smtp@_mailauth\ | |
20721 | ACL is run. | |
20722 | ||
20723 | ||
20724 | .section Authentication on an Exim server | |
20725 | .rset SECTauthexiser "~~chapter.~~section" | |
20726 | .index authentication||on an Exim server | |
4964e932 PH |
20727 | When Exim receives an \\EHLO\\ command, it advertises the public names of those |
20728 | authenticators that are configured as servers, subject to the following | |
495ae4b0 PH |
20729 | conditions: |
20730 | .numberpars $. | |
20731 | The client host must match \auth@_advertise@_hosts\ (default $*$). | |
20732 | .nextp | |
4964e932 | 20733 | It the \server@_advertise@_condition\ option is set, its expansion must not |
495ae4b0 PH |
20734 | yield the empty string, `0', `no', or `false'. |
20735 | .endp | |
4964e932 | 20736 | The order in which the authenticators are defined controls the order in which |
495ae4b0 PH |
20737 | the mechanisms are advertised. |
20738 | ||
20739 | Some mail clients (for example, some versions of Netscape) require the user to | |
20740 | provide a name and password for authentication whenever \\AUTH\\ is advertised, | |
20741 | even though authentication may not in fact be needed (for example, Exim may be | |
20742 | set up to allow unconditional relaying from the client by an IP address check). | |
20743 | You can make such clients more friendly by not advertising \\AUTH\\ to them. | |
20744 | For example, if clients on the 10.9.8.0/24 network are permitted (by the ACL | |
20745 | that runs for \\RCPT\\) to relay without authentication, you should set | |
20746 | .display asis | |
20747 | auth_advertise_hosts = ! 10.9.8.0/24 | |
20748 | .endd | |
20749 | so that no authentication mechanisms are advertised to them. | |
20750 | ||
20751 | The \server@_advertise@_condition\ controls the advertisement of individual | |
20752 | authentication mechanisms. For example, it can be used to restrict the | |
20753 | advertisement of a patricular mechanism to encrypted connections, by a setting | |
20754 | such as: | |
20755 | .display asis | |
20756 | server_advertise_condition = ${if eq{$tls_cipher}{}{no}{yes}} | |
20757 | .endd | |
4964e932 | 20758 | If the session is encrypted, \$tls@_cipher$\ is not empty, and so the expansion |
495ae4b0 PH |
20759 | yields `yes', which allows the advertisement to happen. |
20760 | ||
20761 | When an Exim server receives an \\AUTH\\ command from a client, it rejects it | |
20762 | immediately if \\AUTH\\ was not advertised in response to an earlier \\EHLO\\ | |
20763 | command. This is the case if | |
20764 | .numberpars $. | |
20765 | The client host does not match \auth@_advertise@_hosts\; or | |
20766 | .nextp | |
20767 | No authenticators are configured with server options; or | |
20768 | .nextp | |
4964e932 | 20769 | Expansion of \server@_advertise@_condition\ blocked the advertising of all the |
495ae4b0 PH |
20770 | server authenticators. |
20771 | .endp | |
20772 | ||
20773 | Otherwise, Exim runs the ACL specified by \acl@_smtp@_auth\ in order | |
20774 | to decide whether to accept the command. If \acl@_smtp@_auth\ is not set, | |
4964e932 | 20775 | \\AUTH\\ is accepted from any client host. |
495ae4b0 PH |
20776 | |
20777 | If \\AUTH\\ is not rejected by the ACL, Exim searches its configuration for a | |
4964e932 | 20778 | server authentication mechanism that was advertised in response to \\EHLO\\ and |
495ae4b0 PH |
20779 | that matches the one named in the \\AUTH\\ command. If it finds one, it runs |
20780 | the appropriate authentication protocol, and authentication either succeeds or | |
20781 | fails. If there is no matching advertised mechanism, the \\AUTH\\ command is | |
20782 | rejected with a 504 error. | |
20783 | ||
20784 | When a message is received from an authenticated host, the value of | |
d43194df PH |
20785 | \$received@_protocol$\ is set to |
20786 | .em | |
20787 | `esmtpa' | |
20788 | .nem | |
20789 | instead of `esmtp', and \$sender@_host@_authenticated$\ contains the name (not | |
20790 | the public name) of the authenticator driver that successfully authenticated | |
20791 | the client from which the message was received. This variable is empty if there | |
20792 | was no successful authentication. | |
495ae4b0 PH |
20793 | |
20794 | ||
20795 | ||
20796 | .section Testing server authentication | |
20797 | .index authentication||testing a server | |
20798 | .index \\AUTH\\||testing a server | |
20799 | .index base64 encoding||creating authentication test data | |
20800 | Exim's \-bh-\ option can be useful for testing server authentication | |
20801 | configurations. The data for the \\AUTH\\ command has to be sent using base64 | |
20802 | encoding. A quick way to produce such data for testing is the following Perl | |
20803 | script: | |
20804 | .display asis | |
20805 | use MIME::Base64; | |
20806 | printf ("%s", encode_base64(eval "\"$ARGV[0]\"")); | |
20807 | .endd | |
20808 | .index binary zero||in authentication data | |
20809 | This interprets its argument as a Perl string, and then encodes it. The | |
20810 | interpretation as a Perl string allows binary zeros, which are required for | |
20811 | some kinds of authentication, to be included in the data. For example, a | |
20812 | command line to run this script on such data might be | |
20813 | .display asis | |
20814 | encode '\0user\0password' | |
20815 | .endd | |
20816 | Note the use of single quotes to prevent the shell interpreting the | |
20817 | backslashes, so that they can be interpreted by Perl to specify characters | |
4964e932 | 20818 | whose code value is zero. |
495ae4b0 PH |
20819 | |
20820 | \**Warning 1**\: If either of the user or password strings starts with an octal | |
20821 | digit, you must use three zeros instead of one after the leading backslash. If | |
20822 | you do not, the octal digit that starts your string will be incorrectly | |
20823 | interpreted as part of the code for the first character. | |
20824 | ||
4964e932 PH |
20825 | \**Warning 2**\: If there are characters in the strings that Perl interprets |
20826 | specially, you must use a Perl escape to prevent them being misinterpreted. For | |
495ae4b0 PH |
20827 | example, a command such as |
20828 | .display asis | |
20829 | encode '\0user@domain.com\0pas$$word' | |
20830 | .endd | |
20831 | gives an incorrect answer because of the unescaped `@@' and `@$' characters. | |
20832 | ||
20833 | If you have the \mimencode\ command installed, another way to do produce | |
20834 | base64-encoded strings is to run the command | |
20835 | .display asis | |
20836 | echo -e -n `\0user\0password' | mimencode | |
20837 | .endd | |
20838 | The \-e-\ option of \echo\ enables the interpretation of backslash escapes in | |
20839 | the argument, and the \-n-\ option specifies no newline at the end of its | |
20840 | output. However, not all versions of \echo\ recognize these options, so you | |
20841 | should check your version before relying on this suggestion. | |
20842 | ||
20843 | ||
20844 | .section Authentication by an Exim client | |
20845 | .index authentication||on an Exim client | |
20846 | The \%smtp%\ transport has two options called \hosts@_require@_auth\ and | |
20847 | \hosts@_try@_auth\. When the \%smtp%\ transport connects to a server that | |
20848 | announces support for authentication, and the host matches an entry in either | |
20849 | of these options, Exim (as a client) tries to authenticate as follows: | |
20850 | .numberpars $. | |
20851 | For each authenticator that is configured as a client, it searches the | |
20852 | authentication mechanisms announced by the server for one whose name | |
20853 | matches the public name of the authenticator. | |
20854 | .nextp | |
20855 | When it finds one that matches, it runs the authenticator's client code. | |
20856 | The variables \$host$\ and \$host@_address$\ are available for any string | |
20857 | expansions that the client might do. They are set to the server's name and | |
20858 | IP address. If any expansion is forced to fail, the authentication attempt | |
20859 | is abandoned, | |
20860 | and Exim moves on to the next authenticator. | |
20861 | Otherwise an expansion failure causes delivery to be | |
20862 | deferred. | |
20863 | .nextp | |
20864 | If the result of the authentication attempt is a temporary error or a timeout, | |
20865 | Exim abandons trying to send the message to the host for the moment. It will | |
20866 | try again later. If there are any backup hosts available, they are tried in the | |
20867 | usual way. | |
20868 | .nextp | |
20869 | If the response to authentication is a permanent error (5xx code), Exim carries | |
20870 | on searching the list of authenticators and tries another one if possible. If | |
20871 | all authentication attempts give permanent errors, or if there are no attempts | |
20872 | because no mechanisms match | |
20873 | (or option expansions force failure), | |
20874 | what happens depends on whether the host matches \hosts@_require@_auth\ or | |
20875 | \hosts@_try@_auth\. In the first case, a temporary error is generated, and | |
20876 | delivery is deferred. The error can be detected in the retry rules, and thereby | |
20877 | turned into a permanent error if you wish. In the second case, Exim tries to | |
20878 | deliver the message unauthenticated. | |
20879 | .endp | |
20880 | .index \\AUTH\\||on \\MAIL\\ command | |
20881 | When Exim has authenticated itself to a remote server, it adds the \\AUTH\\ | |
20882 | parameter to the \\MAIL\\ commands it sends, if it has an authenticated sender | |
4964e932 PH |
20883 | for the message. |
20884 | If the message came from a remote host, the authenticated sender is the one | |
20885 | that was receiving on an incoming \\MAIL\\ command, provided that the incoming | |
495ae4b0 PH |
20886 | connection was authenticated and the \server@_mail@_auth\ condition allowed the |
20887 | authenticated sender to be retained. If a local process calls Exim to send a | |
20888 | message, the sender address that is built from the login name and | |
20889 | \qualify@_domain\ is treated as authenticated. However, if the | |
20890 | \authenticated@_sender\ option is set on the \%smtp%\ transport, it overrides | |
20891 | the authenticated sender that was received with the message. | |
20892 | ||
20893 | ||
20894 | ||
20895 | ||
20896 | ||
20897 | ||
20898 | . | |
20899 | . | |
20900 | . | |
20901 | . | |
20902 | . ============================================================================ | |
20903 | .chapter The plaintext authenticator | |
20904 | .rset CHAPplaintext "~~chapter" | |
20905 | .set runningfoot "plaintext authenticator" | |
20906 | .index \%plaintext%\ authenticator | |
20907 | .index authenticators||\%plaintext%\ | |
20908 | The \%plaintext%\ authenticator can be configured to support the PLAIN and | |
20909 | LOGIN authentication mechanisms, both of which transfer authentication data as | |
20910 | plain (unencrypted) text (though base64 encoded). The use of plain text is a | |
20911 | security risk. If you use one of these mechanisms without also making use of | |
20912 | SMTP encryption (see chapter ~~CHAPTLS) you should not use the same passwords | |
20913 | for SMTP connections as you do for login accounts. | |
20914 | ||
20915 | .section Using plaintext in a server | |
20916 | When running as a server, \%plaintext%\ performs the authentication test by | |
20917 | expanding a string. It has the following options: | |
20918 | ||
d43194df | 20919 | .startconf plaintext |
495ae4b0 PH |
20920 | .index options||\%plaintext%\ authenticator (server) |
20921 | ||
20922 | .conf server@_prompts string$**$ unset | |
20923 | The contents of this option, after expansion, must be a colon-separated list of | |
20924 | prompt strings. If expansion fails, a temporary authentication rejection is | |
20925 | given. | |
20926 | ||
20927 | .conf server@_condition string$**$ unset | |
20928 | This option must be set in order to configure the driver as a server. Its use | |
20929 | is described below. | |
20930 | ||
20931 | .endconf | |
20932 | ||
20933 | .index \\AUTH\\||in \%plaintext%\ authenticator | |
20934 | .index binary zero||in \%plaintext%\ authenticator | |
20935 | .index numerical variables (\$1$\, \$2$\, etc)||in \%plaintext%\ authenticator | |
20936 | .index base64 encoding||in \%plaintext%\ authenticator | |
20937 | The data sent by the client with the \\AUTH\\ command, or in response to | |
20938 | subsequent prompts, is base64 encoded, and so may contain any byte values | |
20939 | when decoded. If any data is supplied with the command, it is treated as a | |
20940 | list of strings, separated by NULs (binary zeros), which are placed in the | |
20941 | expansion variables \$1$\, \$2$\, etc. If there are more strings in | |
20942 | \server@_prompts\ than the number of strings supplied with the \\AUTH\\ | |
20943 | command, the remaining prompts are used to obtain more data. Each response from | |
20944 | the client may be a list of NUL-separated strings. | |
20945 | ||
20946 | Once a sufficient number of data strings have been received, | |
20947 | \server@_condition\ is expanded. | |
20948 | If the expansion is forced to fail, authentication fails. Any other expansion | |
20949 | failure causes a temporary error code to be returned. | |
20950 | If the result of a successful expansion is an empty string, `0', `no', or | |
20951 | `false', authentication fails. If the result of the expansion is `1', `yes', or | |
20952 | `true', authentication succeeds and the generic \server@_set@_id\ option is | |
20953 | expanded and saved in \$authenticated@_id$\. For any other result, a temporary | |
20954 | error code is returned, with the expanded string as the error text. | |
20955 | ||
4964e932 PH |
20956 | \**Warning**\: If you use a lookup in the expansion to find the user's |
20957 | password, be sure to make the authentication fail if the user is unknown. | |
495ae4b0 PH |
20958 | There are good and bad examples at the end of the next section. |
20959 | ||
20960 | ||
20961 | .section The PLAIN authentication mechanism | |
20962 | .index PLAIN authentication mechanism | |
20963 | .index authentication||PLAIN mechanism | |
20964 | .index binary zero||in \%plaintext%\ authenticator | |
20965 | The PLAIN authentication mechanism (RFC 2595) specifies that three strings be | |
4964e932 | 20966 | sent as one item of data (that is, one combined string containing two NUL |
495ae4b0 PH |
20967 | separators). The data is sent either as part of the \\AUTH\\ command, or |
20968 | subsequently in response to an empty prompt from the server. | |
20969 | ||
20970 | The second and third strings are a user name and a corresponding password. | |
20971 | Using a single fixed user name and password as an example, this could be | |
20972 | configured as follows: | |
20973 | .display asis | |
20974 | fixed_plain: | |
20975 | driver = plaintext | |
20976 | public_name = PLAIN | |
4964e932 | 20977 | server_prompts = : |
495ae4b0 PH |
20978 | server_condition = \ |
20979 | ${if and {{eq{$2}{username}}{eq{$3}{mysecret}}}{yes}{no}} | |
20980 | server_set_id = $2 | |
20981 | .endd | |
20982 | The \server@_prompts\ setting specifies a single, empty prompt (empty items at | |
20983 | the end of a string list are ignored). If all the data comes as part of the | |
20984 | \\AUTH\\ command, as is commonly the case, the prompt is not used. This | |
20985 | authenticator is advertised in the response to \\EHLO\\ as | |
20986 | .display asis | |
20987 | 250-AUTH PLAIN | |
20988 | .endd | |
20989 | and a client host can authenticate itself by sending the command | |
20990 | .display asis | |
20991 | AUTH PLAIN AHVzZXJuYW1lAG15c2VjcmV0 | |
20992 | .endd | |
20993 | As this contains three strings (more than the number of prompts), no further | |
20994 | data is required from the client. Alternatively, the client may just send | |
20995 | .display asis | |
20996 | AUTH PLAIN | |
20997 | .endd | |
4964e932 | 20998 | to initiate authentication, in which case the server replies with an empty |
495ae4b0 PH |
20999 | prompt. The client must respond with the combined data string. |
21000 | ||
495ae4b0 PH |
21001 | The data string is base64 encoded, as required by the RFC. This example, |
21002 | when decoded, is \"<<NUL>>username<<NUL>>mysecret"\, where <<NUL>> represents a | |
21003 | zero byte. This is split up into three strings, the first of which is empty. | |
21004 | The \server@_condition\ option in the authenticator checks that the second two | |
21005 | are \"username"\ and \"mysecret"\ respectively. | |
21006 | ||
4964e932 PH |
21007 | Having just one fixed user name and password, as in this example, is not very |
21008 | realistic, though for a small organization with only a handful of | |
495ae4b0 | 21009 | authenticating clients it could make sense. |
495ae4b0 PH |
21010 | |
21011 | A more sophisticated instance of this authenticator could use the user name in | |
21012 | \$2$\ to look up a password in a file or database, and maybe do an encrypted | |
21013 | comparison (see \crypteq\ in chapter ~~CHAPexpand). Here is a example of this | |
21014 | approach, where the passwords are looked up in a DBM file. \**Warning**\: This | |
21015 | is an incorrect example: | |
21016 | .display asis | |
21017 | server_condition = \ | |
21018 | ${if eq{$3}{${lookup{$2}dbm{/etc/authpwd}}}{yes}{no}} | |
21019 | .endd | |
21020 | The expansion uses the user name (\$2$\) as the key to look up a password, | |
21021 | which it then compares to the supplied password (\$3$\). Why is this example | |
21022 | incorrect? It works fine for existing users, but consider what happens if a | |
21023 | non-existent user name is given. The lookup fails, but as no success/failure | |
4964e932 PH |
21024 | strings are given for the lookup, it yields an empty string. Thus, to defeat |
21025 | the authentication, all a client has to do is to supply a non-existent user | |
495ae4b0 PH |
21026 | name and an empty password. The correct way of writing this test is: |
21027 | .display asis | |
21028 | server_condition = ${lookup{$2}dbm{/etc/authpwd}\ | |
4964e932 | 21029 | {${if eq{$value}{$3}{yes}{no}}}{no}} |
495ae4b0 PH |
21030 | .endd |
21031 | In this case, if the lookup succeeds, the result is checked; if the lookup | |
21032 | fails, authentication fails. If \crypteq\ is being used instead of \eq\, the | |
21033 | first example is in fact safe, because \crypteq\ always fails if its second | |
21034 | argument is empty. However, the second way of writing the test makes the logic | |
21035 | clearer. | |
21036 | ||
21037 | ||
21038 | .section The LOGIN authentication mechanism | |
21039 | .index LOGIN authentication mechanism | |
21040 | .index authentication||LOGIN mechanism | |
21041 | The LOGIN authentication mechanism is not documented in any RFC, but is in use | |
21042 | in a number of programs. No data is sent with the \\AUTH\\ command. Instead, a | |
21043 | user name and password are supplied separately, in response to prompts. The | |
21044 | plaintext authenticator can be configured to support this as in this example: | |
21045 | .display asis | |
21046 | fixed_login: | |
21047 | driver = plaintext | |
21048 | public_name = LOGIN | |
21049 | server_prompts = User Name : Password | |
21050 | server_condition = \ | |
21051 | ${if and {{eq{$1}{username}}{eq{$2}{mysecret}}}{yes}{no}} | |
21052 | server_set_id = $1 | |
21053 | .endd | |
21054 | Because of the way plaintext operates, this authenticator accepts data supplied | |
21055 | with the \\AUTH\\ command (in contravention of the specification of LOGIN), but | |
21056 | if the client does not supply it (as is the case for LOGIN clients), the prompt | |
21057 | strings are used to obtain two data items. | |
21058 | ||
21059 | Some clients are very particular about the precise text of the prompts. For | |
21060 | example, Outlook Express is reported to recognize only `Username:' and | |
21061 | `Password:'. Here is an example of a LOGIN authenticator which uses those | |
21062 | strings, and which uses the \ldapauth\ expansion condition to check the user | |
21063 | name and password by binding to an LDAP server: | |
21064 | .display asis | |
21065 | login: | |
21066 | driver = plaintext | |
21067 | public_name = LOGIN | |
21068 | server_prompts = Username:: : Password:: | |
21069 | server_condition = ${if ldapauth \ | |
4964e932 | 21070 | .newline |
495ae4b0 PH |
21071 | {user="cn=${quote_ldap_dn:$1},ou=people,o=example.org" \ |
21072 | pass=${quote:$2} \ | |
4964e932 | 21073 | .newline |
495ae4b0 PH |
21074 | ldap://ldap.example.org/}{yes}{no}} |
21075 | server_set_id = uid=$1,ou=people,o=example.org | |
21076 | .endd | |
21077 | Note the use of the \quote@_ldap@_dn\ operator to correctly quote the DN for | |
21078 | authentication. However, the basic \quote\ operator, rather than any of the | |
4964e932 PH |
21079 | LDAP quoting operators, is the correct one to use for the password, because |
21080 | quoting is needed only to make the password conform to the Exim syntax. At the | |
495ae4b0 PH |
21081 | LDAP level, the password is an uninterpreted string. |
21082 | ||
21083 | ||
4964e932 | 21084 | .section Support for different kinds of authentication |
495ae4b0 PH |
21085 | A number of string expansion features are provided for the purpose of |
21086 | interfacing to different ways of user authentication. These include checking | |
21087 | traditionally encrypted passwords from \(/etc/passwd)\ (or equivalent), PAM, | |
21088 | Radius, \ldapauth\, and \*pwcheck*\. For details see section ~~SECTexpcond. | |
21089 | ||
21090 | ||
21091 | ||
21092 | .section Using plaintext in a client | |
21093 | The \%plaintext%\ authenticator has just one client option: | |
21094 | ||
d43194df | 21095 | .startconf plaintext |
495ae4b0 PH |
21096 | .index options||\%plaintext%\ authenticator (client) |
21097 | ||
21098 | .conf client@_send string$**$ unset | |
21099 | The string is a colon-separated list of authentication data strings. Each | |
21100 | string is independently expanded before being sent to the server. The first | |
21101 | string is sent with the \\AUTH\\ command; any more strings are sent in response | |
21102 | to prompts from the server. | |
21103 | ||
21104 | \**Note**\: you cannot use expansion to create multiple strings, because | |
21105 | splitting takes priority and happens first. | |
21106 | ||
21107 | Because the PLAIN authentication mechanism requires NUL (binary zero) bytes in | |
21108 | the data, further processing is applied to each string before it is sent. If | |
21109 | there are any single circumflex characters in the string, they are converted to | |
21110 | NULs. Should an actual circumflex be required as data, it must be doubled in | |
21111 | the string. | |
21112 | ||
21113 | .endconf | |
21114 | ||
21115 | This is an example of a client configuration that implements the PLAIN | |
21116 | authentication mechanism with a fixed user name and password: | |
21117 | .display asis | |
21118 | fixed_plain: | |
21119 | driver = plaintext | |
21120 | public_name = PLAIN | |
21121 | client_send = ^username^mysecret | |
21122 | .endd | |
21123 | The lack of colons means that the entire text is sent with the \\AUTH\\ | |
21124 | command, with the circumflex characters converted to NULs. A similar example | |
21125 | that uses the LOGIN mechanism is: | |
21126 | .display asis | |
21127 | fixed_login: | |
21128 | driver = plaintext | |
21129 | public_name = LOGIN | |
21130 | client_send = : username : mysecret | |
21131 | .endd | |
21132 | The initial colon means that the first string is empty, so no data is sent with | |
21133 | the \\AUTH\\ command itself. The remaining strings are sent in response to | |
21134 | prompts. | |
21135 | ||
21136 | ||
21137 | ||
21138 | ||
21139 | . | |
21140 | . | |
21141 | . | |
21142 | . | |
21143 | . ============================================================================ | |
21144 | .chapter The cram@_md5 authenticator | |
21145 | .set runningfoot "cram@_md5 authenticator" | |
21146 | .index \%cram@_md5%\ authenticator | |
21147 | .index authenticators||\%cram@_md5%\ | |
21148 | .index CRAM-MD5 authentication mechanism | |
21149 | .index authentication||CRAM-MD5 mechanism | |
21150 | The CRAM-MD5 authentication mechanism is described in RFC 2195. The server | |
21151 | sends a challenge string to the client, and the response consists of a user | |
21152 | name and the CRAM-MD5 digest of the challenge string combined with a secret | |
21153 | string (password) which is known to both server and client. Thus, the secret | |
21154 | is not sent over the network as plain text, which makes this authenticator more | |
21155 | secure than \%plaintext%\. However, the downside is that the secret has to be | |
21156 | available in plain text at either end. | |
21157 | ||
21158 | .section Using cram@_md5 as a server | |
21159 | This authenticator has one server option, which must be set to configure the | |
21160 | authenticator as a server: | |
21161 | ||
d43194df | 21162 | .startconf cram@_md5 |
495ae4b0 PH |
21163 | .index options||\%cram@_md5%\ authenticator (server) |
21164 | ||
21165 | .conf server@_secret string$**$ unset | |
21166 | .index numerical variables (\$1$\, \$2$\, etc)||in \%cram@_md5%\ authenticator | |
21167 | When the server receives the client's response, the user name is placed in | |
21168 | the expansion variable \$1$\, and \server@_secret\ is expanded to obtain the | |
21169 | password for that user. The server then computes the CRAM-MD5 digest that the | |
21170 | client should have sent, and checks that it received the correct string. If the | |
21171 | expansion of \server@_secret\ is forced to fail, authentication fails. If the | |
21172 | expansion fails for some other reason, a temporary error code is returned to | |
21173 | the client. | |
21174 | ||
21175 | .endconf | |
21176 | ||
21177 | For example, the following authenticator checks that the user name given by the | |
21178 | client is `ph10', and if so, uses `secret' as the password. For any other user | |
4964e932 | 21179 | name, authentication fails. |
495ae4b0 PH |
21180 | .display asis |
21181 | fixed_cram: | |
21182 | driver = cram_md5 | |
21183 | public_name = CRAM-MD5 | |
21184 | server_secret = ${if eq{$1}{ph10}{secret}fail} | |
21185 | server_set_id = $1 | |
21186 | .endd | |
21187 | If authentication succeeds, the setting of \server@_set@_id\ preserves the user | |
21188 | name in \$authenticated@_id$\. | |
21189 | A more tyical configuration might look up the secret string in a file, using | |
21190 | the user name as the key. For example: | |
21191 | .display asis | |
21192 | lookup_cram: | |
21193 | driver = cram_md5 | |
21194 | public_name = CRAM-MD5 | |
21195 | server_secret = ${lookup{$1}lsearch{/etc/authpwd}{$value}fail} | |
21196 | server_set_id = $1 | |
21197 | .endd | |
21198 | Note that this expansion explicitly forces failure if the lookup fails | |
21199 | because \$1$\ contains an unknown user name. | |
21200 | ||
21201 | .section Using cram@_md5 as a client | |
21202 | When used as a client, the \%cram@_md5%\ authenticator has two options: | |
21203 | ||
d43194df | 21204 | .startconf cram@_md5 |
495ae4b0 PH |
21205 | .index options||\%cram@_md5%\ authenticator (client) |
21206 | ||
21207 | .conf client@_name string$**$ "the primary host name" | |
21208 | This string is expanded, and the result used as the user name data when | |
21209 | computing the response to the server's challenge. | |
21210 | ||
21211 | .conf client@_secret string$**$ unset | |
21212 | This option must be set for the authenticator to work as a client. Its value is | |
21213 | expanded and the result used as the secret string when computing the response. | |
21214 | ||
21215 | .endconf | |
21216 | ||
21217 | Different user names and secrets can be used for different servers by referring | |
21218 | to \$host$\ or \$host@_address$\ in the options. | |
21219 | ||
21220 | Forced failure of either expansion string is treated as an indication that this | |
21221 | authenticator is not prepared to handle this case. Exim moves on to the next | |
21222 | configured client authenticator. Any other expansion failure causes Exim to | |
21223 | give up trying to send the message to the current server. | |
21224 | ||
21225 | A simple example configuration of a \%cram@_md5%\ authenticator, using fixed | |
21226 | strings, is: | |
21227 | .display asis | |
21228 | fixed_cram: | |
21229 | driver = cram_md5 | |
21230 | public_name = CRAM-MD5 | |
21231 | client_name = ph10 | |
21232 | client_secret = secret | |
21233 | .endd | |
21234 | ||
21235 | ||
21236 | ||
21237 | ||
d43194df PH |
21238 | . |
21239 | . | |
21240 | . | |
21241 | . | |
21242 | . ============================================================================ | |
21243 | .chapter The cyrus@_sasl authenticator | |
21244 | .set runningfoot "cyrus@_sasl authenticator" | |
21245 | .index \%cyrus@_sasl%\ authenticator | |
21246 | .index authenticators||\%cyrus@_sasl%\ | |
21247 | .index Cyrus, SASL library | |
21248 | .em | |
21249 | The code for this authenticator was provided by Matthew Byng-Maddick of A L | |
21250 | Digital Ltd (\?http://www.aldigital.co.uk?\). | |
21251 | ||
21252 | The \%cyrus@_sasl%\ authenticator provides server support for the Cyrus SASL | |
21253 | library implementation of the RFC 2222 (`Simple Authentication and Security | |
21254 | Layer'). This library supports a number of authentication mechanisms, including | |
21255 | PLAIN and LOGIN, but also several others that Exim does not support directly. | |
8408f763 PH |
21256 | In particular, there is support for Kerberos authentication. |
21257 | ||
d43194df PH |
21258 | The \%cyrus@_sasl%\ authenticator provides a gatewaying mechanism directly to |
21259 | the Cyrus interface, so if your Cyrus library can do, for example, CRAM-MD5, | |
21260 | then so can the \%cyrus@_sasl%\ authenticator. By default it uses the public | |
21261 | name of the driver to determine which mechanism to support. | |
21262 | ||
21263 | Where access to some kind of secret file is required, for example in GSSAPI | |
21264 | or CRAM-MD5, it is worth noting that the authenticator runs as the \*exim*\ | |
21265 | user, and that the Cyrus SASL library has no way of escalating privileges | |
21266 | by default. You may also find you need to set environment variables, | |
21267 | depending on the driver you are using. | |
21268 | ||
21269 | .section Using cyrus@_sasl as a server | |
21270 | The \%cyrus@_sasl%\ authenticator has four private options. It puts the | |
21271 | username (on a successful authentication) into \$1$\. | |
21272 | ||
21273 | .startconf cyrus@_sasl | |
21274 | .conf server@_hostname string$**$ $tt{$primary@_hostname} | |
21275 | This option selects the hostname that is used when communicating with | |
21276 | the library. It is up to the underlying SASL plug-in what it does with | |
21277 | this data. | |
21278 | ||
21279 | .conf server@_mech string $tt{public@_name} | |
21280 | This option selects the authentication mechanism this driver should | |
21281 | use. It allows you to use a different underlying mechanism from the | |
21282 | advertised name. For example: | |
21283 | .display asis | |
21284 | sasl: | |
21285 | driver = cyrus_sasl | |
21286 | public_name = X-ANYTHING | |
21287 | server_mech = CRAM-MD5 | |
21288 | server_set_id = $1 | |
21289 | .endd | |
21290 | ||
21291 | .conf server@_realm string unset | |
21292 | This specifies the SASL realm that the server claims to be in. | |
21293 | ||
21294 | .conf server@_service string $tt{smtp} | |
21295 | This is the SASL service that the server claims to implement. | |
21296 | ||
21297 | .endconf | |
21298 | ||
21299 | For straightforward cases, you do not need to set any of the authenticator's | |
21300 | private options. All you need to do is to specify an appropriate mechanism as | |
21301 | the public name. Thus, if you have a SASL library that supports CRAM-MD5 and | |
21302 | PLAIN, you could have two authenticators as follows: | |
21303 | .display asis | |
21304 | sasl_cram_md5: | |
21305 | driver = cyrus_sasl | |
21306 | public_name = CRAM-MD5 | |
21307 | server_set_id = $1 | |
21308 | ||
21309 | sasl_plain: | |
21310 | driver = cyrus_sasl | |
21311 | public_name = PLAIN | |
21312 | server_set_id = $1 | |
21313 | .endd | |
21314 | ||
21315 | Cyrus SASL does implement the LOGIN authentication method, even though it is | |
21316 | not a standard method. It is disabled by default in the source distribution, | |
21317 | but it is present in many binary distributions. | |
21318 | ||
21319 | .nem | |
21320 | ||
21321 | ||
495ae4b0 PH |
21322 | |
21323 | . | |
21324 | . | |
21325 | . | |
21326 | . | |
21327 | . ============================================================================ | |
21328 | .chapter The spa authenticator | |
21329 | .set runningfoot "spa authenticator" | |
21330 | .index \%spa%\ authenticator | |
21331 | .index authenticators||\%spa%\ | |
21332 | .index authentication||Microsoft Secure Password | |
21333 | .index authentication||NTLM | |
21334 | .index Microsoft Secure Password Authentication | |
21335 | .index NTLM authentication | |
21336 | The \%spa%\ authenticator provides client support for Microsoft's \*Secure | |
21337 | Password Authentication*\ mechanism, | |
21338 | which is also sometimes known as NTLM (NT LanMan). The code for client side of | |
21339 | this authenticator was contributed by Marc Prud'hommeaux, and much of it is | |
21340 | taken from the Samba project (\?http://www.samba.org?\). The code for the | |
21341 | server side was subsequently contributed by Tom Kistner. | |
21342 | ||
21343 | The mechanism works as follows: | |
21344 | .numberpars $. | |
21345 | After the \\AUTH\\ command has been accepted, the client sends an SPA | |
21346 | authentication request based on the user name and optional domain. | |
21347 | .nextp | |
21348 | The server sends back a challenge. | |
21349 | .nextp | |
21350 | The client builds a challenge response which makes use of the user's password | |
21351 | and sends it to the server, which then accepts or rejects it. | |
21352 | .endp | |
21353 | Encryption is used to protect the password in transit. | |
21354 | ||
21355 | ||
21356 | .section Using spa as a server | |
21357 | The \%spa%\ authenticator has just one server option: | |
21358 | ||
d43194df | 21359 | .startconf spa |
495ae4b0 PH |
21360 | .index options||\%spa%\ authenticator (server) |
21361 | ||
21362 | .conf server@_password string$**$ unset | |
21363 | .index numerical variables (\$1$\, \$2$\, etc)||in \%spa%\ authenticator | |
4964e932 | 21364 | This option is expanded, and the result must be the cleartext password for the |
495ae4b0 PH |
21365 | authenticating user, whose name is at this point in \$1$\. For example: |
21366 | .display asis | |
21367 | spa: | |
21368 | driver = spa | |
21369 | public_name = NTLM | |
21370 | server_password = ${lookup{$1}lsearch{/etc/exim/spa_clearpass}} | |
21371 | .endd | |
4964e932 | 21372 | If the expansion is forced to fail, authentication fails. Any other expansion |
495ae4b0 PH |
21373 | failure causes a temporary error code to be returned. |
21374 | ||
21375 | .endconf | |
21376 | ||
21377 | ||
21378 | ||
21379 | .section Using spa as a client | |
21380 | The \%spa%\ authenticator has the following client options: | |
21381 | ||
d43194df | 21382 | .startconf spa |
495ae4b0 PH |
21383 | .index options||\%spa%\ authenticator (client) |
21384 | ||
21385 | .conf client@_domain string$**$ unset | |
21386 | This option specifies an optional domain for the authentication. | |
21387 | ||
21388 | .conf client@_password string$**$ unset | |
21389 | This option specifies the user's password, and must be set. | |
21390 | ||
21391 | .conf client@_username string$**$ unset | |
21392 | This option specifies the user name, and must be set. | |
21393 | ||
21394 | .endconf | |
21395 | ||
21396 | Here is an example of a configuration of this authenticator for use with the | |
21397 | mail servers at \*msn.com*\: | |
21398 | .display asis | |
21399 | msn: | |
21400 | driver = spa | |
21401 | public_name = MSN | |
21402 | client_username = msn/msn_username | |
21403 | client_password = msn_plaintext_password | |
21404 | client_domain = DOMAIN_OR_UNSET | |
21405 | .endd | |
21406 | ||
21407 | ||
21408 | ||
21409 | ||
21410 | ||
21411 | ||
21412 | . | |
21413 | . | |
21414 | . | |
21415 | . | |
21416 | . ============================================================================ | |
21417 | .chapter Encrypted SMTP connections using TLS/SSL | |
21418 | .set runningfoot "TLS encryption" | |
21419 | .rset CHAPTLS "~~chapter" | |
21420 | .index encryption||on SMTP connection | |
21421 | .index SMTP||encryption | |
21422 | .index TLS||on SMTP connection | |
21423 | .index OpenSSL | |
21424 | .index GnuTLS | |
495ae4b0 PH |
21425 | Support for TLS (Transport Layer Security), formerly known as SSL (Secure |
21426 | Sockets Layer), is implemented by making use of the OpenSSL library or the | |
d43194df PH |
21427 | GnuTLS library (Exim requires GnuTLS release 1.0 or later). There is no |
21428 | cryptographic code in the Exim distribution itself for implementing TLS. In | |
21429 | order to use this feature you must install OpenSSL or GnuTLS, and then build a | |
21430 | version of Exim that includes TLS support (see section ~~SECTinctlsssl). You | |
21431 | also need to understand the basic concepts of encryption at a managerial level, | |
21432 | and in particular, the way that public keys, private keys, and certificates are | |
21433 | used. | |
495ae4b0 PH |
21434 | |
21435 | RFC 2487 defines how SMTP connections can make use of encryption. Once a | |
21436 | connection is established, the client issues a \\STARTTLS\\ command. If the | |
21437 | server accepts this, the client and the server negotiate an encryption | |
21438 | mechanism. If the negotiation succeeds, the data that subsequently passes | |
21439 | between them is encrypted. | |
21440 | ||
495ae4b0 PH |
21441 | Exim's ACLs can detect whether the current SMTP session is encrypted or not, |
21442 | and if so, what cipher suite is in use, whether the client supplied a | |
21443 | certificate, and whether or not that certificate was verified. This makes it | |
21444 | possible for an Exim server to deny or accept certain commands based on the | |
21445 | encryption state. | |
21446 | ||
21447 | \**Warning**\: certain types of firewall and certain anti-virus products can | |
21448 | disrupt TLS connections. You need to turn off SMTP scanning for these products | |
21449 | in order to get TLS to work. | |
21450 | ||
21451 | ||
d43194df | 21452 | .em |
8408f763 | 21453 | .section Support for the legacy `ssmtp' (aka `smtps') protocol |
d43194df | 21454 | .index ssmtp protocol |
8408f763 | 21455 | .index smtps protocol |
d43194df | 21456 | .index SMTP||ssmtp protocol |
8408f763 | 21457 | .index SMTP||smtps protocol |
d43194df PH |
21458 | Early implementations of encrypted SMTP used a different TCP port from normal |
21459 | SMTP, and expected an encryption negotiation to start immediately, instead of | |
21460 | waiting for a \\STARTTLS\\ command from the client using the standard SMTP | |
8408f763 PH |
21461 | port. The protocol was called `ssmtp' or `smtps', and port 465 was allocated |
21462 | for this purpose. | |
d43194df PH |
21463 | |
21464 | This approach was abandoned when encrypted SMTP was standardised, but there are | |
21465 | still some legacy clients that use it. Exim supports these clients by means of | |
21466 | the \tls@_on@_connect@_ports\ global option. Its value must be a list of port | |
21467 | numbers; the most common use is expected to be: | |
21468 | .display asis | |
21469 | tls_on_connect_ports = 465 | |
21470 | .endd | |
21471 | The port numbers specified by this option apply to all SMTP connections, both | |
21472 | via the daemon and via \*inetd*\. You still need to specify all the ports that | |
21473 | the daemon uses (by setting \daemon@_smtp@_ports\ or \local@_interfaces\ or the | |
21474 | \-oX-\ command line option) because \tls@_on@_connect@_ports\ does not add an | |
21475 | extra port -- rather, it specifies different behaviour on a port that is | |
21476 | defined elsewhere. | |
21477 | ||
21478 | There is also a \-tls-on-connect-\ command line option. This overrides | |
21479 | \tls@_on@_connect@_ports\; it forces the legacy behaviour for all ports. | |
21480 | .nem | |
21481 | ||
21482 | ||
21483 | ||
21484 | ||
495ae4b0 PH |
21485 | .section OpenSSL vs GnuTLS |
21486 | .index TLS||OpenSSL \*vs*\ GnuTLS | |
21487 | .rset SECTopenvsgnu "~~chapter.~~section" | |
21488 | The first TLS support in Exim was implemented using OpenSSL. Support for GnuTLS | |
21489 | followed later, when the first versions of GnuTLS were released. To build Exim | |
21490 | to use GnuTLS, you need to set | |
21491 | .display asis | |
21492 | USE_GNUTLS=yes | |
21493 | .endd | |
21494 | in Local/Makefile, in addition to | |
21495 | .display asis | |
21496 | SUPPORT_TLS=yes | |
21497 | .endd | |
21498 | You must also set \\TLS@_LIBS\\ and \\TLS@_INCLUDE\\ appropriately, so that the | |
21499 | include files and libraries for GnuTLS can be found. | |
21500 | ||
21501 | There are some differences in usage when using GnuTLS instead of OpenSSL: | |
21502 | .numberpars $. | |
4964e932 | 21503 | The \tls@_verify@_certificates\ option must contain the name of a file, not the |
495ae4b0 | 21504 | name of a directory (for OpenSSL it can be either). |
495ae4b0 PH |
21505 | .nextp |
21506 | The \tls@_dhparam\ option is ignored, because early versions of GnuTLS had no | |
4964e932 | 21507 | facility for varying its Diffie-Hellman parameters. I understand that this has |
495ae4b0 PH |
21508 | changed, but Exim has not been updated to provide this facility. |
21509 | .nextp | |
21510 | GnuTLS uses RSA and D-H parameters that take a substantial amount of | |
21511 | time to compute. It is unreasonable to re-compute them for every TLS | |
21512 | session. Therefore, Exim keeps this data in a file in its spool | |
21513 | directory, called \(gnutls-params)\. The file is owned by the Exim user and is | |
21514 | readable only by its owner. Every Exim process that start up GnuTLS reads the | |
21515 | RSA and D-H parameters from this file. If the file does not exist, the first | |
21516 | Exim process that needs it computes the data and writes it to a temporary file | |
21517 | which is renamed once it is complete. It does not matter if several Exim | |
21518 | processes do this simultaneously (apart from wasting a few resources). Once a | |
21519 | file is in place, new Exim processes immediately start using it. | |
21520 | ||
21521 | For maximum security, the parameters that are stored in this file should be | |
21522 | recalculated periodically, the frequency depending on your paranoia level. | |
21523 | Arranging this is easy; just delete the file when you want new values to be | |
21524 | computed. | |
21525 | .nextp | |
4964e932 PH |
21526 | Distinguished Name (DN) strings reported by the OpenSSL library use a slash for |
21527 | separating fields; GnuTLS uses commas, in accordance with RFC 2253. This | |
495ae4b0 | 21528 | affects the value of the \$tls@_peerdn$\ variable. |
495ae4b0 PH |
21529 | .nextp |
21530 | OpenSSL identifies cipher suites using hyphens as separators, for example: | |
21531 | DES-CBC3-SHA. GnuTLS uses underscores, for example: RSA@_ARCFOUR@_SHA. What is | |
21532 | more, OpenSSL complains if underscores are present in a cipher list. To make | |
21533 | life simpler, Exim changes underscores to hyhens for OpenSSL and hyphens to | |
21534 | underscores for GnuTLS when processing lists of cipher suites in the | |
4964e932 | 21535 | \tls@_require@_ciphers\ options (the global option and the \%smtp%\ transport |
495ae4b0 | 21536 | option). |
495ae4b0 | 21537 | .nextp |
495ae4b0 | 21538 | The \tls@_require@_ciphers\ options operate differently, as described in the |
d43194df | 21539 | following sections. |
495ae4b0 PH |
21540 | .endp |
21541 | ||
d43194df PH |
21542 | .section Requiring specific ciphers in OpenSSL |
21543 | .rset SECTreqciphssl "~~chapter.~~section" | |
21544 | .index TLS||requiring specific ciphers (OpenSSL) | |
21545 | .index \tls@_require@_ciphers\||OpenSSL | |
21546 | There is a function in the OpenSSL library that can be passed a list of cipher | |
21547 | suites before the cipher negotiation takes place. This specifies which ciphers | |
21548 | are acceptable. The list is colon separated and may contain names like | |
495ae4b0 | 21549 | DES-CBC3-SHA. Exim passes the expanded value of \tls@_require@_ciphers\ |
d43194df PH |
21550 | directly to this function call. The following quotation from the OpenSSL |
21551 | documentation specifies what forms of item are allowed in the cipher string: | |
495ae4b0 PH |
21552 | .numberpars $. |
21553 | It can consist of a single cipher suite such as RC4-SHA. | |
21554 | .nextp | |
21555 | It can represent a list of cipher suites containing a certain algorithm, | |
21556 | or cipher suites of a certain type. For example SHA1 represents all | |
21557 | ciphers suites using the digest algorithm SHA1 and SSLv3 represents all | |
21558 | SSL v3 algorithms. | |
21559 | .nextp | |
21560 | Lists of cipher suites can be combined in a single cipher string using | |
21561 | the + character. This is used as a logical and operation. For example | |
21562 | SHA1+DES represents all cipher suites containing the SHA1 and the DES | |
21563 | algorithms. | |
21564 | .nextp | |
21565 | Each cipher string can be optionally preceded by the characters \"!"\, \"-"\ or | |
21566 | \"+"\. | |
21567 | .numberpars " " | |
21568 | If \"!"\ is used then the ciphers are permanently deleted from the list. The | |
21569 | ciphers deleted can never reappear in the list even if they are explicitly | |
21570 | stated. | |
21571 | .nextp | |
21572 | If \"-"\ is used then the ciphers are deleted from the list, but some or all | |
21573 | of the ciphers can be added again by later options. | |
21574 | .nextp | |
21575 | If \"+"\ is used then the ciphers are moved to the end of the list. This | |
21576 | option doesn't add any new ciphers it just moves matching existing ones. | |
21577 | .nextp | |
21578 | If none of these characters is present then the string is just interpreted as a | |
21579 | list of ciphers to be appended to the current preference list. If the list | |
21580 | includes any ciphers already present they will be ignored: that is, they will | |
21581 | not moved to the end of the list. | |
21582 | .endp | |
21583 | .endp | |
21584 | ||
d43194df PH |
21585 | |
21586 | .section Requiring specific ciphers in GnuTLS | |
21587 | .rset SECTreqciphgnu "~~chapter.~~section" | |
21588 | .index TLS||requiring specific ciphers (GnuTLS) | |
21589 | .index \tls@_require@_ciphers\||GnuTLS | |
495ae4b0 PH |
21590 | The GnuTLS library does not have a combined function like OpenSSL. Instead, |
21591 | it allows the caller to specify separate lists of key-exchange methods, | |
21592 | main cipher algorithms, and MAC algorithms. Unfortunately, these lists are | |
21593 | numerical, and the library does not have a function for turning names into | |
21594 | numbers. Consequently, the list of recognized names has to be built into | |
21595 | the application. | |
21596 | ||
21597 | At present, Exim permits only the list of main cipher algorithms to be | |
21598 | changed. The \tls@_require@_ciphers\ option is in the same format as for | |
21599 | OpenSSL. Exim searches each item for the name of available algorithm. For | |
d43194df | 21600 | example, if the list contains RSA@_AES@_SHA then AES is recognized. |
495ae4b0 PH |
21601 | |
21602 | The cipher algorithms list starts out with a default set of algorithms. If | |
21603 | the first item in \tls@_require@_ciphers\ does \*not*\ start with an | |
21604 | exclamation mark, all the default items are deleted. Thus, only those specified | |
21605 | can be used. If the first item in \tls@_require@_ciphers\ \*does*\ start with | |
21606 | an exclamation mark, the defaults are left on the list. | |
21607 | ||
21608 | Then, any item that starts with an exclamation mark causes the relevent | |
21609 | algorithms to be removed from the list, and any item that does not start | |
21610 | with an exclamation mark causes the relevant algorithms to be added to the | |
21611 | list. Thus, | |
21612 | .display asis | |
21613 | tls_require_ciphers = !RSA_ARCFOUR_SHA | |
21614 | .endd | |
21615 | allows all the defaults except those that use ARCFOUR, whereas | |
21616 | .display asis | |
21617 | tls_require_ciphers = AES : 3DES | |
21618 | .endd | |
21619 | allows only cipher suites that use AES and 3DES. The currently recognized | |
d43194df PH |
21620 | algorithms are: |
21621 | .em | |
21622 | AES@_256, AES@_128, AES (both of the preceding), 3DES, and ARCFOUR@_128. | |
21623 | Unrecognized algorithms are ignored. In a server, the order of the list is | |
21624 | unimportant; the server will advertise the availability of all the relevant | |
21625 | cipher suites. However, in a client, the order of the list specifies a | |
21626 | preference order for the algorithms. The first one in the client's list that is | |
21627 | also advertised by the server is tried first. The default order is as listed | |
21628 | above. | |
21629 | .nem | |
495ae4b0 PH |
21630 | |
21631 | ||
21632 | .section Configuring an Exim server to use TLS | |
21633 | .index TLS||configuring an Exim server | |
21634 | When Exim has been built with TLS support, it advertises the availability of | |
21635 | the \\STARTTLS\\ command to client hosts that match \tls@_advertise@_hosts\, | |
21636 | but not to any others. The default value of this option is unset, which means | |
21637 | that \\STARTTLS\\ is not advertised at all. This default is chosen because you | |
21638 | need to set some other options in order to make TLS avaliable, and also it is | |
21639 | sensible for systems that want to use TLS only as a client. | |
21640 | ||
21641 | If a client issues a \\STARTTLS\\ command and there is some configuration | |
21642 | problem in the server, the command is rejected with a 454 error. If the client | |
21643 | persists in trying to issue SMTP commands, all except \\QUIT\\ are rejected | |
21644 | with the error | |
21645 | .display asis | |
21646 | 554 Security failure | |
21647 | .endd | |
21648 | If a \\STARTTLS\\ command is issued within an existing TLS session, it is | |
21649 | rejected with a 554 error code. | |
21650 | ||
21651 | To enable TLS operations on a server, you must set \tls@_advertise@_hosts\ to | |
21652 | match some hosts. You can, of course, set it to $*$ to match all hosts. | |
21653 | However, this is not all you need to do. TLS sessions to a server won't work | |
21654 | without some further configuration at the server end. | |
21655 | ||
21656 | It is rumoured that all existing clients that support TLS/SSL use RSA | |
21657 | encryption. To make this work you need to set, in the server, | |
21658 | .display asis | |
21659 | tls_certificate = /some/file/name | |
21660 | tls_privatekey = /some/file/name | |
21661 | .endd | |
21662 | The first file contains the server's X509 certificate, and the second contains | |
21663 | the private key that goes with it. These files need to be readable by the Exim | |
21664 | user, and must always be given as full path names. They can be the same file if | |
21665 | both the certificate and the key are contained within it. If \tls@_privatekey\ | |
21666 | is not set, this is assumed to be the case. The certificate file may also | |
21667 | contain intermediate certificates that need to be sent to the client to enable | |
21668 | it to authenticate the server's certificate. | |
21669 | ||
21670 | If you do not understand about certificates and keys, please try to find a | |
21671 | source of this background information, which is not Exim-specific. (There are a | |
21672 | few comments below in section ~~SECTcerandall.) | |
21673 | ||
4964e932 PH |
21674 | \**Note**\: These options do not apply when Exim is operating as a client -- |
21675 | they apply only in the case of a server. For a client, you must set the options | |
495ae4b0 PH |
21676 | of the same name in an \%smtp%\ transport. |
21677 | ||
21678 | With just these options, Exim will work as a server with clients such as | |
21679 | Netscape. It does not require the client to have a certificate (but see below | |
21680 | for how to insist on this). There is one other option that may be needed in | |
21681 | other situations. If | |
21682 | .display asis | |
21683 | tls_dhparam = /some/file/name | |
21684 | .endd | |
21685 | is set, the SSL library is initialized for the use of Diffie-Hellman ciphers | |
4964e932 | 21686 | with the parameters contained in the file. This increases the set of cipher |
495ae4b0 PH |
21687 | suites that the server supports. See the command |
21688 | .display asis | |
21689 | openssl dhparam | |
21690 | .endd | |
21691 | for a way of generating this data. | |
4964e932 | 21692 | At present, \tls@_dhparam\ is used only when Exim is linked with OpenSSL. It is |
495ae4b0 PH |
21693 | ignored if GnuTLS is being used. |
21694 | ||
21695 | The strings supplied for these three options are expanded every time a client | |
21696 | host connects. It is therefore possible to use different certificates and keys | |
21697 | for different hosts, if you so wish, by making use of the client's IP address | |
21698 | in \$sender@_host@_address$\ to control the expansion. If a string expansion is | |
21699 | forced to fail, Exim behaves as if the option is not set. | |
21700 | ||
21701 | .index cipher||logging | |
21702 | .index log||TLS cipher | |
21703 | The variable \$tls@_cipher$\ is set to the cipher suite that was negotiated for | |
21704 | an incoming TLS connection. It is included in the ::Received:: header of an | |
21705 | incoming message (by default -- you can, of course, change this), and it is | |
21706 | also included in the log line that records a message's arrival, keyed by `X=', | |
21707 | unless the \tls@_cipher\ log selector is turned off. | |
4964e932 | 21708 | The \encrypted\ condition can be used to test for specific cipher suites in |
495ae4b0 PH |
21709 | ACLs. |
21710 | ||
21711 | The ACLs that run for subsequent SMTP commands can check the name of the cipher | |
21712 | suite and vary their actions accordingly. The cipher suite names are those used | |
21713 | by OpenSSL. These may differ from the names used elsewhere. For example, | |
21714 | OpenSSL uses the name DES-CBC3-SHA for the cipher suite which in other contexts | |
21715 | is known as TLS@_RSA@_WITH@_3DES@_EDE@_CBC@_SHA. Check the OpenSSL | |
21716 | documentation for more details. | |
21717 | ||
21718 | ||
21719 | .section Requesting and verifying client certificates | |
21720 | .index certificate||verification of client | |
21721 | .index TLS||client certificate verification | |
21722 | If you want an Exim server to request a certificate when negotiating a TLS | |
21723 | session with a client, you must set either \tls@_verify@_hosts\ or | |
21724 | \tls@_try@_verify@_hosts\. You can, of course, set either of them to $*$ to | |
21725 | apply to all TLS connections. For any host that matches one of these options, | |
21726 | Exim requests a certificate as part of the setup of the TLS session. The | |
21727 | contents of the certificate are verified by comparing it with a list of | |
21728 | expected certificates. These must be available in a file or, | |
495ae4b0 PH |
21729 | for OpenSSL only (not GnuTLS), a directory, identified by |
21730 | \tls@_verify@_certificates\. | |
495ae4b0 PH |
21731 | |
21732 | A file can contain multiple certificates, concatenated end to end. If a | |
4964e932 PH |
21733 | directory is used |
21734 | (OpenSSL only), | |
495ae4b0 PH |
21735 | each certificate must be in a separate file, with a name (or a symbolic link) |
21736 | of the form <<hash>>.0, where <<hash>> is a hash value constructed from the | |
21737 | certificate. You can compute the relevant hash by running the command | |
21738 | .display asis | |
21739 | openssl x509 -hash -noout -in /cert/file | |
21740 | .endd | |
21741 | where \(/cert/file)\ contains a single certificate. | |
21742 | ||
21743 | The difference between \tls@_verify@_hosts\ and \tls@_try@_verify@_hosts\ is | |
21744 | what happens if the client does not supply a certificate, or if the certificate | |
21745 | does not match any of the certificates in the collection named by | |
21746 | \tls@_verify@_certificates\. If the client matches \tls@_verify@_hosts\, the | |
21747 | attempt to set up a TLS session is aborted, and the incoming connection is | |
21748 | dropped. If the client matches \tls@_try@_verify@_hosts\, the (encrypted) SMTP | |
21749 | session continues. ACLs that run for subsequent SMTP commands can detect the | |
21750 | fact that no certificate was verified, and vary their actions accordingly. For | |
21751 | example, you can insist on a certificate before accepting a message for | |
21752 | relaying, but not when the message is destined for local delivery. | |
21753 | ||
21754 | When a client supplies a certificate (whether it verifies or not), the value of | |
21755 | the Distinguished Name of the certificate is made available in the variable | |
21756 | \$tls@_peerdn$\ during subsequent processing of the message. | |
21757 | .index log||distinguished name | |
21758 | Because it is often a long text string, it is not included in the log line or | |
21759 | ::Received:: header by default. You can arrange for it to be logged, keyed by | |
21760 | `DN=', by setting the \tls@_peerdn\ log selector, and you can use | |
21761 | \received@_header@_text\ to change the ::Received:: header. When no certificate | |
21762 | is supplied, \$tls@_peerdn$\ is empty. | |
21763 | ||
495ae4b0 PH |
21764 | .section Revoked certificates |
21765 | .index TLS||revoked certificates | |
21766 | .index revocation list | |
21767 | .index certificate||revocation list | |
21768 | Certificate issuing authorities issue Certificate Revocation Lists (CRLs) when | |
21769 | certificates are revoked. If you have such a list, you can pass it to an Exim | |
21770 | server using the global option called \tls@_crl\ and to an Exim client using an | |
21771 | identically named option for the \%smtp%\ transport. In each case, the value of | |
21772 | the option is expanded and must then be the name of a file that contains a CRL | |
21773 | in PEM format. | |
495ae4b0 PH |
21774 | |
21775 | .section Configuring an Exim client to use TLS | |
21776 | .index cipher||logging | |
21777 | .index log||TLS cipher | |
21778 | .index log||distinguished name | |
21779 | .index TLS||configuring an Exim client | |
21780 | The \tls@_cipher\ and \tls@_peerdn\ log selectors apply to outgoing SMTP | |
21781 | deliveries as well as to incoming, the latter one causing logging of the | |
21782 | server certificate's DN. The remaining client configuration for TLS is all | |
21783 | within the \%smtp%\ transport. | |
21784 | ||
21785 | It is not necessary to set any options to have TLS work in the \%smtp%\ | |
21786 | transport. If Exim is built with TLS support, and TLS is advertised by a | |
21787 | server, the \%smtp%\ transport always tries to start a TLS session. However, | |
21788 | this can be prevented by setting \hosts@_avoid@_tls\ (an option of the | |
21789 | transport) to a list of server hosts for which TLS should not be used. | |
21790 | ||
21791 | If you do not want Exim to attempt to send messages unencrypted when an attempt | |
21792 | to set up an encrypted connection fails in any way, you can set | |
21793 | \hosts@_require@_tls\ to a list of hosts for which encryption is mandatory. For | |
21794 | those hosts, delivery is always deferred if an encrypted connection cannot be | |
21795 | set up. If there are any other hosts for the address, they are tried in the | |
21796 | usual way. | |
21797 | ||
21798 | When the server host is not in \hosts@_require@_tls\, Exim may try to deliver | |
21799 | the message unencrypted. It always does this if the response to \\STARTTLS\\ is | |
21800 | a 5\*xx*\ code. For a temporary error code, or for a failure to negotiate a TLS | |
21801 | session after a success response code, what happens is controlled by the | |
21802 | \tls@_tempfail@_tryclear\ option of the \%smtp%\ transport. If it is false, | |
21803 | delivery to this host is deferred, and other hosts (if available) are tried. If | |
21804 | it is true, Exim attempts to deliver unencrypted after a 4\*xx*\ response to | |
21805 | \\STARTTLS\\, and if \\STARTTLS\\ is accepted, but the subsequent TLS | |
21806 | negotiation fails, Exim closes the current connection (because it is in an | |
21807 | unknown state), opens a new one to the same host, and then tries the delivery | |
21808 | unencrypted. | |
21809 | ||
21810 | ||
21811 | The \tls@_certificate\ and \tls@_privatekey\ options of the \%smtp%\ transport | |
21812 | provide the client with a certificate, which is passed to the server if it | |
21813 | requests it. If the server is Exim, it will request a certificate only if | |
21814 | \tls@_verify@_hosts\ or \tls@_try@_verify@_hosts\ matches the client. | |
4964e932 | 21815 | \**Note**\: these options must be set in the \%smtp%\ transport for Exim to use |
495ae4b0 PH |
21816 | TLS when it is operating as a client. Exim does not assume that a server |
21817 | certificate (set by the global options of the same name) should also be used | |
21818 | when operating as a client. | |
21819 | ||
21820 | If \tls@_verify@_certificates\ is set, it must name a file or, | |
495ae4b0 PH |
21821 | for OpenSSL only (not GnuTLS), a directory, that contains a collection of |
21822 | expected server certificates. The client verifies the server's certificate | |
21823 | against this collection, taking into account any revoked certificates that are | |
21824 | in the list defined by \tls@_crl\. | |
495ae4b0 PH |
21825 | |
21826 | If | |
21827 | \tls@_require@_ciphers\ is set on the \%smtp%\ transport, it must contain a | |
21828 | list of permitted cipher suites. If either of these checks fails, delivery to | |
21829 | the current host is abandoned, and the \%smtp%\ transport tries to deliver to | |
21830 | alternative hosts, if any. | |
21831 | ||
21832 | All the TLS options in the \%smtp%\ transport are expanded before use, with | |
21833 | \$host$\ and \$host@_address$\ containing the name and address of the server to | |
21834 | which the client is connected. Forced failure of an expansion causes Exim to | |
21835 | behave as if the relevant option were unset. | |
21836 | ||
21837 | ||
21838 | .section Multiple messages on the same encrypted TCP/IP connection | |
21839 | .rset SECTmulmessam "~~chapter.~~section" | |
21840 | .index multiple SMTP deliveries with TLS | |
21841 | .index TLS||multiple message deliveries | |
21842 | Exim sends multiple messages down the same TCP/IP connection by starting up | |
21843 | an entirely new delivery process for each message, passing the socket from | |
21844 | one process to the next. This implementation does not fit well with the use | |
21845 | of TLS, because there is quite a lot of state information associated with a TLS | |
21846 | connection, not just a socket identification. Passing all the state information | |
21847 | to a new process is not feasible. Consequently, Exim shuts down an existing TLS | |
21848 | session before passing the socket to a new process. The new process may then | |
21849 | try to start a new TLS session, and if successful, may try to re-authenticate | |
21850 | if \\AUTH\\ is in use, before sending the next message. | |
21851 | ||
21852 | The RFC is not clear as to whether or not an SMTP session continues in clear | |
4964e932 | 21853 | after TLS has been shut down, or whether TLS may be restarted again later, as |
495ae4b0 PH |
21854 | just described. However, if the server is Exim, this shutdown and |
21855 | reinitialization works. It is not known which (if any) other servers operate | |
21856 | successfully if the client closes a TLS session and continues with unencrypted | |
21857 | SMTP, but there are certainly some that do not work. For such servers, Exim | |
21858 | should not pass the socket to another process, because the failure of the | |
21859 | subsequent attempt to use it would cause Exim to record a temporary host error, | |
21860 | and delay other deliveries to that host. | |
21861 | ||
21862 | To test for this case, Exim sends an \\EHLO\\ command to the server after | |
4964e932 | 21863 | closing down the TLS session. If this fails in any way, the connection is |
495ae4b0 PH |
21864 | closed instead of being passed to a new delivery process, but no retry |
21865 | information is recorded. | |
21866 | ||
4964e932 PH |
21867 | There is also a manual override; you can set \hosts@_nopass@_tls\ on the |
21868 | \%smtp%\ transport to match those hosts for which Exim should not pass | |
495ae4b0 PH |
21869 | connections to new processes if TLS has been used. |
21870 | ||
21871 | ||
21872 | ||
21873 | .section Certificates and all that | |
21874 | .rset SECTcerandall "~~chapter.~~section" | |
21875 | .index certificate||references to discussion | |
21876 | In order to understand fully how TLS works, you need to know about | |
21877 | certificates, certificate signing, and certificate authorities. This is not the | |
21878 | place to give a tutorial, especially as I do not know very much about it | |
21879 | myself. Some helpful introduction can be found in the FAQ for the SSL addition | |
21880 | to Apache, currently at | |
21881 | .display rm | |
21882 | \?http://www.modssl.org/docs/2.7/ssl@_faq.html@#ToC24?\ | |
21883 | .endd | |
21884 | Other parts of the \*modssl*\ documentation are also helpful, and have | |
21885 | links to further files. | |
21886 | Eric Rescorla's book, \*SSL and TLS*\, published by Addison-Wesley (ISBN | |
4964e932 | 21887 | 0-201-61598-3), contains both introductory and more in-depth descriptions. |
495ae4b0 PH |
21888 | Some sample programs taken from the book are available from |
21889 | .display rm | |
21890 | \?http://www.rtfm.com/openssl-examples/?\ | |
21891 | .endd | |
21892 | ||
21893 | .section Certificate chains | |
21894 | The file named by \tls@_certificate\ may contain more than one | |
21895 | certificate. This is useful in the case where the certificate that is being | |
21896 | sent is validated by an intermediate certificate which the other end does | |
21897 | not have. Multiple certificates must be in the correct order in the file. | |
21898 | First the host's certificate itself, then the first intermediate | |
21899 | certificate to validate the issuer of the host certificate, then the next | |
21900 | intermediate certificate to validate the issuer of the first intermediate | |
21901 | certificate, and so on, until finally (optionally) the root certificate. | |
21902 | The root certificate must already be trusted by the recipient for | |
21903 | validation to succeed, of course, but if it's not preinstalled, sending the | |
21904 | root certificate along with the rest makes it available for the user to | |
21905 | install if the receiving end is a client MUA that can interact with a user. | |
21906 | ||
21907 | .section Self-signed certificates | |
21908 | .index certificate||self-signed | |
21909 | You can create a self-signed certificate using the \*req*\ command provided | |
21910 | with OpenSSL, like this: | |
21911 | .display asis | |
21912 | openssl req -x509 -newkey rsa:1024 -keyout file1 -out file2 \ | |
21913 | -days 9999 -nodes | |
21914 | .endd | |
21915 | \(file1)\ and \(file2)\ can be the same file; the key and the certificate are | |
21916 | delimited and so can be identified independently. The \-days-\ option | |
21917 | specifies a period for which the certificate is valid. The \-nodes-\ option is | |
21918 | important: if you do not set it, the key is encrypted with a passphrase | |
21919 | that you are prompted for, and any use that is made of the key causes more | |
21920 | prompting for the passphrase. This is not helpful if you are going to use | |
21921 | this certificate and key in an MTA, where prompting is not possible. | |
21922 | ||
21923 | A self-signed certificate made in this way is sufficient for testing, and | |
21924 | may be adequate for all your requirements if you are mainly interested in | |
21925 | encrypting transfers, and not in secure identification. | |
21926 | ||
21927 | However, many clients require that the certificate presented by the server be a | |
21928 | user (also called `leaf' or `site') certificate, and not a self-signed | |
21929 | certificate. In this situation, the self-signed certificate described above | |
21930 | must be installed on the client host as a trusted root \*certification | |
21931 | authority*\ (CA), and the certificate used by Exim must be a user certificate | |
21932 | signed with that self-signed certificate. | |
21933 | ||
21934 | For information on creating self-signed CA certificates and using them to sign | |
21935 | user certificates, see the \*General implementation overview*\ chapter of the | |
21936 | Open-source PKI book, available online at \?http://ospkibook.sourceforge.net/?\. | |
21937 | ||
21938 | ||
21939 | ||
21940 | . | |
21941 | . | |
21942 | . | |
21943 | . | |
21944 | . ============================================================================ | |
21945 | .chapter Access control lists | |
21946 | .set runningfoot "ACL" | |
21947 | .rset CHAPACL "~~chapter" | |
21948 | .index ~~ACL||description | |
21949 | .index control of incoming mail | |
21950 | .index message||controlling incoming | |
21951 | .index policy control||access control lists | |
21952 | Access Control Lists (ACLs) are defined in a separate section of the run time | |
21953 | configuration file, headed by `begin acl'. Each ACL definition starts with a | |
4964e932 | 21954 | name, terminated by a colon. Here is a complete ACL section that contains just |
495ae4b0 PH |
21955 | one very small ACL: |
21956 | .display asis | |
21957 | begin acl | |
21958 | ||
21959 | small_acl: | |
21960 | accept hosts = one.host.only | |
21961 | .endd | |
21962 | You can have as many lists as you like in the ACL section, and the order in | |
21963 | which they appear does not matter. The lists are self-terminating. | |
21964 | ||
21965 | The majority of ACLs are used to control Exim's behaviour when it receives | |
21966 | certain SMTP commands. This applies both to incoming TCP/IP connections, and | |
4964e932 PH |
21967 | when a local process submits a message using SMTP by specifying the \-bs-\ |
21968 | option. The most common use is for controlling which recipients are accepted | |
21969 | in incoming messages. In addition, you can define an ACL that is used to check | |
21970 | local non-SMTP messages. The default configuration file contains an example of | |
21971 | a realistic ACL for checking \\RCPT\\ commands. This is discussed in chapter | |
21972 | ~~CHAPdefconfil. | |
495ae4b0 PH |
21973 | |
21974 | .section Testing ACLs | |
21975 | The \-bh-\ command line option provides a way of testing your ACL configuration | |
21976 | locally by running a fake SMTP session with which you interact. The host | |
21977 | \*relay-test.mail-abuse.org*\ provides a service for checking your relaying | |
21978 | configuration (see section ~~SECTcheralcon for more details). | |
21979 | ||
21980 | ||
21981 | .section Specifying when ACLs are used | |
21982 | .index ~~ACL||options for specifying | |
21983 | In order to cause an ACL to be used, you have to name it in one of the relevant | |
21984 | options in the main part of the configuration. These options are: | |
21985 | .index \\AUTH\\||ACL for | |
4964e932 | 21986 | .index \\DATA\\, ACLs for |
495ae4b0 PH |
21987 | .index \\ETRN\\||ACL for |
21988 | .index \\EXPN\\||ACL for | |
21989 | .index \\HELO\\||ACL for | |
21990 | .index \\EHLO\\||ACL for | |
21991 | .index \\MAIL\\||ACL for | |
4964e932 | 21992 | .index \\QUIT\\, ACL for |
495ae4b0 PH |
21993 | .index \\RCPT\\||ACL for |
21994 | .index \\STARTTLS\\, ACL for | |
21995 | .index \\VRFY\\||ACL for | |
4964e932 PH |
21996 | .index SMTP||connection, ACL for |
21997 | .index non-smtp message, ACL for | |
495ae4b0 PH |
21998 | .display |
21999 | .tabs 20 | |
22000 | .if !~~sys.fancy | |
22001 | .tabs 24 | |
22002 | .fi | |
22003 | \acl@_not@_smtp\ $t $rm{ACL for non-SMTP messages} | |
22004 | \acl@_smtp@_auth\ $t $rm{ACL for \\AUTH\\} | |
22005 | \acl@_smtp@_connect\ $t $rm{ACL for start of SMTP connection} | |
4964e932 | 22006 | \acl@_smtp@_data\ $t $rm{ACL after \\DATA\\ is complete} |
495ae4b0 PH |
22007 | \acl@_smtp@_etrn\ $t $rm{ACL for \\ETRN\\} |
22008 | \acl@_smtp@_expn\ $t $rm{ACL for \\EXPN\\} | |
22009 | \acl@_smtp@_helo\ $t $rm{ACL for \\HELO\\ or \\EHLO\\} | |
22010 | \acl@_smtp@_mail\ $t $rm{ACL for \\MAIL\\} | |
495ae4b0 PH |
22011 | \acl@_smtp@_mailauth\ $t $rm{ACL for the \\AUTH\\ parameter of \\MAIL\\} |
22012 | .newline | |
4964e932 PH |
22013 | .em |
22014 | \acl@_smtp@_mime\ $t $rm{ACL for content-scanning MIME parts} | |
22015 | \acl@_smtp@_predata\ $t $rm{ACL at start of \\DATA\\ command} | |
22016 | \acl@_smtp@_quit\ $t $rm{ACL for \\QUIT\\} | |
22017 | .nem | |
22018 | .newline | |
495ae4b0 PH |
22019 | \acl@_smtp@_rcpt\ $t $rm{ACL for \\RCPT\\} |
22020 | \acl@_smtp@_starttls\ $t $rm{ACL for \\STARTTLS\\} | |
22021 | \acl@_smtp@_vrfy\ $t $rm{ACL for \\VRFY\\} | |
22022 | .endd | |
22023 | For example, if you set | |
22024 | .display asis | |
22025 | acl_smtp_rcpt = small_acl | |
22026 | .endd | |
22027 | the little ACL defined above is used whenever Exim receives a \\RCPT\\ command | |
22028 | in an SMTP dialogue. The majority of policy tests on incoming messages can be | |
22029 | done when \\RCPT\\ commands arrive. A rejection of \\RCPT\\ should cause the | |
22030 | sending MTA to give up on the recipient address contained in the \\RCPT\\ | |
4964e932 PH |
22031 | command, whereas rejection at other times may cause the client MTA to keep on |
22032 | trying to deliver the message. It is therefore recommended that you do as much | |
495ae4b0 PH |
22033 | testing as possible at \\RCPT\\ time. |
22034 | ||
d43194df PH |
22035 | .section The non-SMTP ACL |
22036 | .index non-smtp message, ACL for | |
22037 | The non-SMTP ACL applies to all non-interactive incoming messages, that is, it | |
22038 | applies to batch SMTP as well as to non-SMTP messages. (Batch SMTP is not | |
22039 | really SMTP.) This ACL is run just before the \*local@_scan()*\ function. Any | |
22040 | kind of rejection is treated as permanent, because there is no way of sending a | |
22041 | temporary error for these kinds of message. Many of the ACL conditions (for | |
22042 | example, host tests, and tests on the state of the SMTP connection such as | |
22043 | encryption and authentication) are not relevant and are forbidden in this ACL. | |
4964e932 PH |
22044 | |
22045 | .section The connect ACL | |
22046 | .index SMTP||connection, ACL for | |
22047 | The ACL test specified by \acl@_smtp@_connect\ happens after the test specified | |
495ae4b0 PH |
22048 | by \host__reject__connection\ (which is now an anomaly) and any TCP Wrappers |
22049 | testing (if configured). | |
22050 | ||
4964e932 | 22051 | .em |
d43194df PH |
22052 | .section The DATA ACLs |
22053 | .index \\DATA\\, ACLs for | |
22054 | Two ACLs are associated with the \\DATA\\ command, because it is two-stage | |
22055 | command, with two responses being sent to the client. | |
22056 | When the \\DATA\\ command is received, the ACL defined by \acl@_smtp@_predata\ | |
22057 | is obeyed. This gives you control after all the \\RCPT\\ commands, but before | |
22058 | the message itself is received. It offers the opportunity to give a negative | |
22059 | response to the \\DATA\\ command before the data is transmitted. Header lines | |
22060 | added by \\MAIL\\ or \\RCPT\\ ACLs are not visible at this time, but any that | |
22061 | are defined here are visible when the \acl@_smtp@_data\ ACL is run. | |
22062 | ||
22063 | You cannot test the contents of the message, for example, to verify addresses | |
22064 | in the headers, at \\RCPT\\ time or when the \\DATA\\ command is received. Such | |
22065 | tests have to appear in the ACL that is run after the message itself has been | |
22066 | received, before the final response to the \\DATA\\ command is sent. This is | |
22067 | the ACL specified by \acl@_smtp@_data\, which is the second ACL that is | |
22068 | associated with the \\DATA\\ command. | |
22069 | ||
22070 | For both of these ACLs, it is not possible to reject individual recipients. An | |
22071 | error response rejects the entire message. Unfortunately, it is known that some | |
22072 | MTAs do not treat hard (5$it{xx}) responses to the \\DATA\\ command (either | |
22073 | before or after the data) correctly -- they keep the message on their queues | |
22074 | and try again later, but that is their problem, though it does waste some of | |
22075 | your resources. | |
22076 | ||
22077 | .section The MIME ACL | |
22078 | The \acl@_smtp@_mime\ option is available only when Exim is compiled with the | |
22079 | content-scanning extension. For details, see chapter ~~CHAPexiscan. | |
22080 | ||
4964e932 PH |
22081 | .section The QUIT ACL |
22082 | .rset SECTQUITACL "~~chapter.~~section" | |
22083 | .index \\QUIT\\, ACL for | |
22084 | The ACL for the SMTP \\QUIT\\ command is anomalous, in that the | |
22085 | outcome of the ACL does not affect the response code to \\QUIT\\, | |
22086 | which is always 221. Thus, the ACL does not in fact control any access. | |
22087 | For this reason, the only verbs that are permitted are \accept\ and \warn\. | |
22088 | ||
22089 | This ACL can be used for tasks such as custom logging at the end of an SMTP | |
22090 | session. For example, you can use ACL variables in other ACLs to count | |
22091 | messages, recipients, etc., and log the totals at \\QUIT\\ time using one or | |
22092 | more \logwrite\ modifiers on a \warn\ verb. | |
22093 | ||
22094 | You do not need to have a final \accept\, but if you do, you can use a | |
22095 | \message\ modifier to specify custom text that is sent as part of the 221 | |
22096 | response to \\QUIT\\. | |
22097 | ||
22098 | This ACL is run only for a `normal' \\QUIT\\. For certain kinds of disastrous | |
22099 | failure (for example, failure to open a log file, or when Exim is bombing out | |
22100 | because it has detected an unrecoverable error), all SMTP commands from the | |
22101 | client are given temporary error responses until \\QUIT\\ is received or the | |
22102 | connection is closed. In these special cases, the \\QUIT\\ ACL does not run. | |
22103 | .nem | |
22104 | ||
4964e932 PH |
22105 | .section Finding an ACL to use |
22106 | .index ~~ACL||finding which to use | |
22107 | The value of an \acl@_smtp@_$it{xxx}\ option is expanded before use, so you can | |
22108 | use different ACLs in different circumstances. The resulting string does not | |
22109 | have to be the name of an ACL in the configuration file; there are other | |
22110 | possibilities. Having expanded the string, Exim searches for an ACL as follows: | |
22111 | .numberpars $. | |
22112 | If the string begins with a slash, Exim uses it as a file name, and reads its | |
22113 | contents as an ACL. The lines are processed in the same way as lines in the | |
22114 | Exim configuration file. In particular, continuation lines are supported, blank | |
22115 | lines are ignored, as are lines whose first non-whitespace character is `@#'. | |
22116 | If the file does not exist or cannot be read, an error occurs (typically | |
22117 | causing a temporary failure of whatever caused the ACL to be run). For example: | |
22118 | .display asis | |
22119 | acl_smtp_data = /etc/acls/\ | |
22120 | ${lookup{$sender_host_address}lsearch\ | |
22121 | {/etc/acllist}{$value}{default}} | |
22122 | .endd | |
22123 | This looks up an ACL file to use on the basis of the host's IP address, falling | |
22124 | back to a default if the lookup fails. If an ACL is successfully read from a | |
22125 | file, it is retained in memory for the duration of the Exim process, so that it | |
22126 | can be re-used without having to re-read the file. | |
22127 | .nextp | |
22128 | If the string does not start with a slash, and does not contain any spaces, | |
22129 | Exim searches the ACL section of the configuration for an ACL whose name | |
22130 | matches the string. | |
22131 | .nextp | |
22132 | If no named ACL is found, or if the string contains spaces, Exim parses | |
22133 | the string as an inline ACL. This can save typing in cases where you just | |
22134 | want to have something like | |
22135 | .display asis | |
22136 | acl_smtp_vrfy = accept | |
22137 | .endd | |
22138 | in order to allow free use of the \\VRFY\\ command. Such a string may contain | |
22139 | newlines; it is processed in the same way as an ACL that is read from a file. | |
22140 | .endp | |
22141 | ||
22142 | ||
495ae4b0 PH |
22143 | .section ACL return codes |
22144 | .index ~~ACL||return codes | |
4964e932 PH |
22145 | .em |
22146 | Except for the \\QUIT\\ ACL, which does not affect the SMTP return code (see | |
22147 | section ~~SECTQUITACL above), the | |
22148 | .nem | |
22149 | result of running an ACL is either `accept' or `deny', or, if some test | |
495ae4b0 PH |
22150 | cannot be completed (for example, if a database is down), `defer'. These |
22151 | results cause 2$it{xx}, 5$it{xx}, and 4$it{xx} return codes, respectively, to | |
22152 | be used in the SMTP dialogue. A fourth return, `error', occurs when there is an | |
22153 | error such as invalid syntax in the ACL. This also causes a 4$it{xx} return | |
22154 | code. | |
22155 | ||
4964e932 PH |
22156 | .em |
22157 | For the non-SMTP ACL, `defer' and `error' are treated in the same way as | |
22158 | `deny', because there is no mechanism for passing temporary errors to the | |
22159 | submitters of non-SMTP messages. | |
22160 | .nem | |
22161 | ||
22162 | ACLs that are relevant to message reception may also return `discard'. This | |
495ae4b0 PH |
22163 | has the effect of `accept', but causes either the entire message or an |
22164 | individual recipient address to be discarded. In other words, it is a | |
4964e932 | 22165 | blackholing facility. Use it with care. |
495ae4b0 PH |
22166 | |
22167 | If the ACL for \\MAIL\\ returns `discard', all recipients are discarded, and no | |
22168 | ACL is run for subsequent \\RCPT\\ commands. The effect of `discard' in a | |
4964e932 PH |
22169 | \\RCPT\\ ACL is to discard just the one recipient address. If there are no |
22170 | recipients left when the message's data is received, the \\DATA\\ ACL is not | |
22171 | run. A `discard' return from the \\DATA\\ or the non-SMTP ACL discards all the | |
495ae4b0 | 22172 | remaining recipients. |
4964e932 PH |
22173 | .em |
22174 | The `discard' return is not permitted for the \acl@_smtp@_predata\ ACL. | |
22175 | .nem | |
495ae4b0 | 22176 | |
4964e932 PH |
22177 | .index \*local@_scan()*\ function||when all recipients discarded |
22178 | The \*local@_scan()*\ function is always run, even if there are no remaining | |
495ae4b0 PH |
22179 | recipients; it may create new recipients. |
22180 | ||
22181 | ||
22182 | .section Unset ACL options | |
22183 | .index ~~ACL||unset options | |
495ae4b0 PH |
22184 | The default actions when any of the \acl@_$it{xxx}\ options are unset are not |
22185 | all the same. \**Note**\: These defaults apply only when the relevant ACL is | |
4964e932 | 22186 | not defined at all. For any defined ACL, the default action when control reaches |
495ae4b0 | 22187 | the end of the ACL statements is `deny'. |
495ae4b0 PH |
22188 | |
22189 | For \acl@_not@_smtp\, \acl@_smtp@_auth\, \acl@_smtp@_connect\, | |
22190 | \acl@_smtp@_data\, \acl@_smtp@_helo\, \acl__smtp__mail\, \acl@_smtp@_mailauth\, | |
495ae4b0 | 22191 | .em |
d43194df | 22192 | \acl@_smtp@_mime\, \acl@_smtp@_predata\, \acl@_smtp@_quit\, |
4964e932 | 22193 | .nem |
d43194df | 22194 | and \acl__smtp__starttls\, the action when the ACL is not defined is `accept'. |
495ae4b0 PH |
22195 | |
22196 | For the others (\acl@_smtp@_etrn\, \acl@_smtp@_expn\, \acl@_smtp@_rcpt\, and | |
22197 | \acl@_smtp@_vrfy\), the action when the ACL is not defined is `deny'. | |
495ae4b0 PH |
22198 | This means that \acl@_smtp@_rcpt\ must be defined in order to receive any |
22199 | messages over an SMTP connection. For an example, see the ACL in the default | |
22200 | configuration file. | |
22201 | ||
22202 | ||
22203 | ||
22204 | .section Data for message ACLs | |
22205 | .index ~~ACL||data for message ACL | |
d43194df PH |
22206 | .em |
22207 | When a \\MAIL\\ or \\RCPT\\ ACL, or either of the \\DATA\\ ACLs, is running, | |
22208 | the variables that contain information about the host and the message's sender | |
22209 | (for example, \$sender@_host@_address$\ and \$sender@_address$\) are set, and | |
22210 | can be used in ACL statements. In the case of \\RCPT\\ (but not \\MAIL\\ or | |
22211 | \\DATA\\), \$domain$\ and \$local@_part$\ are set from the argument address. | |
495ae4b0 | 22212 | |
d43194df | 22213 | When an ACL for the \\AUTH\\ parameter of \\MAIL\\ is running, the variables |
4964e932 | 22214 | that contain information about the host are set, but \$sender@_address$\ is not |
d43194df | 22215 | yet set. Section ~~SECTauthparamail contains a discussion of this parameter and |
4964e932 | 22216 | how it is used. |
495ae4b0 PH |
22217 | |
22218 | The \$message@_size$\ variable is set to the value of the \\SIZE\\ parameter on | |
d43194df PH |
22219 | the \\MAIL\\ command at \\MAIL\\, \\RCPT\\ and pre-data time, or to -1 if |
22220 | that parameter is not given. The value is updated to the true message size by | |
22221 | the time the final \\DATA\\ ACL is run (after the message data has been | |
22222 | received). | |
495ae4b0 PH |
22223 | |
22224 | The \$rcpt@_count$\ variable increases by one for each \\RCPT\\ command | |
22225 | received. The \$recipients@_count$\ variable increases by one each time a | |
22226 | \\RCPT\\ command is accepted, so while an ACL for \\RCPT\\ is being processed, | |
d43194df PH |
22227 | it contains the number of previously accepted recipients. At \\DATA\\ time (for |
22228 | both the \\DATA\\ ACLs), \$rcpt@_count$\ contains the total number of \\RCPT\\ | |
22229 | commands, and \$recipients@_count$\ contains the total number of accepted | |
22230 | recipients. | |
22231 | .nem | |
495ae4b0 PH |
22232 | |
22233 | ||
22234 | ||
22235 | .section Data for non-message ACLs | |
22236 | .rset SECTdatfornon "~~chapter.~~section" | |
22237 | .index ~~ACL||data for non-message ACL | |
4964e932 PH |
22238 | .em |
22239 | When an ACL is being run for \\AUTH\\, \\EHLO\\, \\ETRN\\, \\EXPN\\, \\HELO\\, | |
22240 | .nem | |
22241 | \\STARTTLS\\, or \\VRFY\\, the remainder of the SMTP command line is placed in | |
495ae4b0 PH |
22242 | \$smtp@_command@_argument$\. This can be tested using a \condition\ condition. |
22243 | For example, here is an ACL for use with \\AUTH\\, which insists that either | |
22244 | the session is encrypted, or the CRAM-MD5 authentication method is used. In | |
22245 | other words, it does not permit authentication methods that use cleartext | |
22246 | passwords on unencrypted connections. | |
22247 | .display asis | |
22248 | acl_check_auth: | |
22249 | accept encrypted = * | |
4964e932 PH |
22250 | .newline |
22251 | .em | |
495ae4b0 | 22252 | accept condition = ${if eq{${uc:$smtp_command_argument}}\ |
4964e932 PH |
22253 | {CRAM-MD5}} |
22254 | .nem | |
22255 | .newline | |
495ae4b0 PH |
22256 | deny message = TLS encryption or CRAM-MD5 required |
22257 | .endd | |
4964e932 PH |
22258 | (Another way of applying this restriction is to arrange for the authenticators |
22259 | that use cleartext passwords not to be advertised when the connection is not | |
22260 | encrypted. You can use the generic \server@_advertise@_condition\ authenticator | |
495ae4b0 PH |
22261 | option to do this.) |
22262 | ||
22263 | ||
495ae4b0 PH |
22264 | .section Format of an ACL |
22265 | .index ~~ACL||format of | |
22266 | .index ~~ACL||verbs, definition of | |
22267 | An individual ACL consists of a number of statements. Each statement starts | |
4964e932 PH |
22268 | with a verb, optionally followed by a number of conditions and `modifiers'. |
22269 | .em | |
22270 | Modifiers can change the way the verb operates, define error and log messages, | |
22271 | set variables, insert delays, and vary the processing of accepted messages. | |
22272 | .nem | |
22273 | ||
22274 | If all the conditions are met, the verb is obeyed. The same condition may be | |
22275 | used (with different arguments) more than once in the same statement. This | |
22276 | provides a means of specifying an `and' conjunction between conditions. For | |
22277 | example: | |
495ae4b0 PH |
22278 | .display asis |
22279 | deny dnslists = list1.example | |
22280 | dnslists = list2.example | |
22281 | .endd | |
4964e932 PH |
22282 | If there are no conditions, the verb is always obeyed. |
22283 | .em | |
22284 | Exim stops evaluating the conditions and modifiers when it reaches a condition | |
22285 | that fails. What happens then | |
22286 | .nem | |
22287 | depends on the verb (and in one case, on a special modifier). Not all the | |
22288 | conditions make sense at every testing point. For example, you cannot test a | |
22289 | sender address in the ACL that is run for a \\VRFY\\ command. | |
495ae4b0 | 22290 | |
4964e932 PH |
22291 | .section ACL verbs |
22292 | The ACL verbs are as follows: | |
495ae4b0 | 22293 | .numberpars $. |
f055f31e | 22294 | .index \accept\, ACL verb |
495ae4b0 PH |
22295 | \accept\: If all the conditions are met, the ACL returns `accept'. If any of |
22296 | the conditions are not met, what happens depends on whether \endpass\ appears | |
4964e932 PH |
22297 | among the conditions (for syntax see below). If the failing condition is before |
22298 | \endpass\, control is passed to the next ACL statement; if it is after | |
495ae4b0 PH |
22299 | \endpass\, the ACL returns `deny'. Consider this statement, used to check a |
22300 | \\RCPT\\ command: | |
22301 | .display asis | |
22302 | accept domains = +local_domains | |
22303 | endpass | |
22304 | verify = recipient | |
22305 | .endd | |
22306 | If the recipient domain does not match the \domains\ condition, control passes | |
22307 | to the next statement. If it does match, the recipient is verified, and the | |
22308 | command is accepted if verification succeeds. However, if verification fails, | |
22309 | the ACL yields `deny', because the failing condition is after \endpass\. | |
22310 | .nextp | |
f055f31e | 22311 | .index \defer\, ACL verb |
4964e932 PH |
22312 | \defer\: If all the conditions are met, the ACL returns `defer' which, in an |
22313 | SMTP session, causes a 4\*xx*\ response to be given. For a non-SMTP ACL, | |
495ae4b0 PH |
22314 | \defer\ is the same as \deny\, because there is no way of sending a temporary |
22315 | error. For a \\RCPT\\ command, \defer\ is much the same as using a | |
22316 | \%redirect%\ router and \":defer:"\ while verifying, but the \defer\ verb can | |
22317 | be used in any ACL, and even for a recipient it might be a simpler approach. | |
22318 | .nextp | |
f055f31e | 22319 | .index \deny\, ACL verb |
495ae4b0 PH |
22320 | \deny\: If all the conditions are met, the ACL returns `deny'. If any of the |
22321 | conditions are not met, control is passed to the next ACL statement. For | |
22322 | example, | |
22323 | .display asis | |
22324 | deny dnslists = blackholes.mail-abuse.org | |
22325 | .endd | |
22326 | rejects commands from hosts that are on a DNS black list. | |
22327 | .nextp | |
f055f31e | 22328 | .index \discard\, ACL verb |
4964e932 | 22329 | \discard\: This verb behaves like \accept\, except that it returns `discard' |
495ae4b0 PH |
22330 | from the ACL instead of `accept'. It is permitted only on ACLs that are |
22331 | concerned with receiving messages, and it causes recipients to be discarded. | |
4964e932 PH |
22332 | If the \log@_message\ modifier is set when \discard\ operates, its contents are |
22333 | added to the line that is automatically written to the log. | |
495ae4b0 PH |
22334 | |
22335 | If \discard\ is used in an ACL for \\RCPT\\, just the one recipient is | |
22336 | discarded; if used for \\MAIL\\, \\DATA\\ or in the non-SMTP ACL, all the | |
22337 | message's recipients are discarded. Recipients that are discarded before | |
22338 | \\DATA\\ do not appear in the log line when the \log@_recipients\ log selector | |
22339 | is set. | |
22340 | .nextp | |
f055f31e | 22341 | .index \drop\, ACL verb |
495ae4b0 PH |
22342 | \drop\: This verb behaves like \deny\, except that an SMTP connection is |
22343 | forcibly closed after the 5\*xx*\ error message has been sent. For example: | |
22344 | .display asis | |
22345 | drop message = I don't take more than 20 RCPTs | |
4964e932 PH |
22346 | .newline |
22347 | .em | |
22348 | condition = ${if > {$rcpt_count}{20}} | |
22349 | .nem | |
495ae4b0 PH |
22350 | .endd |
22351 | There is no difference between \deny\ and \drop\ for the connect-time ACL. The | |
22352 | connection is always dropped after sending a 550 response. | |
22353 | .nextp | |
f055f31e | 22354 | .index \require\, ACL verb |
495ae4b0 PH |
22355 | \require\: If all the conditions are met, control is passed to the next ACL |
22356 | statement. If any of the conditions are not met, the ACL returns `deny'. For | |
22357 | example, when checking a \\RCPT\\ command, | |
22358 | .display asis | |
22359 | require verify = sender | |
22360 | .endd | |
22361 | passes control to subsequent statements only if the message's sender can be | |
22362 | verified. Otherwise, it rejects the command. | |
22363 | .nextp | |
f055f31e | 22364 | .index \warn\, ACL verb |
495ae4b0 PH |
22365 | \warn\: If all the conditions are met, a header line is added to an incoming |
22366 | message and/or a line is written to Exim's main log. In all cases, control | |
22367 | passes to the next ACL statement. The text of the added header line and the log | |
22368 | line are specified by modifiers; if they are not present, a \warn\ verb just | |
22369 | checks its conditions and obeys any `immediate' modifiers such as \set\ and | |
22370 | \logwrite\. | |
4964e932 PH |
22371 | .em |
22372 | There is more about adding header lines in section ~~SECTaddheadwarn. | |
22373 | .nem | |
495ae4b0 PH |
22374 | |
22375 | If any condition on a \warn\ statement cannot be completed (that is, there is | |
4964e932 PH |
22376 | some sort of defer), no header lines are added and the configured log line is |
22377 | not written. No further conditions or modifiers in the \warn\ statement are | |
495ae4b0 PH |
22378 | processed. The incident is logged, but the ACL continues to be processed, from |
22379 | the next statement onwards. | |
22380 | ||
4964e932 | 22381 | If a \message\ modifier is present on a \warn\ verb in an ACL that is not |
495ae4b0 PH |
22382 | testing an incoming message, it is ignored, and the incident is logged. |
22383 | ||
4964e932 PH |
22384 | A \warn\ statement may use the \log@_message\ modifier to cause a line to be |
22385 | written to the main log when the statement's conditions are true. | |
22386 | If an identical log line is requested several times in the same message, only | |
22387 | one copy is actually written to the log. If you want to force duplicates to be | |
22388 | written, use the \logwrite\ modifier instead. | |
495ae4b0 PH |
22389 | |
22390 | When one of the \warn\ conditions is an address verification that fails, the | |
22391 | text of the verification failure message is in \$acl@_verify@_message$\. If you | |
22392 | want this logged, you must set it up explicitly. For example: | |
22393 | .display asis | |
22394 | warn !verify = sender | |
22395 | log_message = sender verify failed: $acl_verify_message | |
22396 | .endd | |
22397 | .endp | |
22398 | ||
22399 | At the end of each ACL there is an implicit unconditional \deny\. | |
22400 | ||
22401 | As you can see from the examples above, the conditions and modifiers are | |
22402 | written one to a line, with the first one on the same line as the verb, and | |
22403 | subsequent ones on following lines. If you have a very long condition, you can | |
4964e932 PH |
22404 | continue it onto several physical lines by the usual backslash continuation |
22405 | mechanism. It is conventional to align the conditions vertically. | |
495ae4b0 PH |
22406 | |
22407 | ||
22408 | .section ACL variables | |
22409 | .rset SECTaclvariables "~~chapter.~~section" | |
22410 | .index ~~ACL||variables | |
22411 | There are some special variables that can be set during ACL processing. They | |
4964e932 PH |
22412 | can be used to pass information between different ACLs, different invocations |
22413 | of the same ACL in the same SMTP connection, and between ACLs and the routers, | |
22414 | transports, and filters that are used to deliver a message. There are two sets | |
22415 | of these variables: | |
495ae4b0 PH |
22416 | .numberpars $. |
22417 | The values of \$acl@_c0$\ to \$acl@_c9$\ persist throughout an SMTP connection. | |
4964e932 | 22418 | They are never reset. Thus, a value that is set while receiving one message is |
495ae4b0 PH |
22419 | still available when receiving the next message on the same SMTP connection. |
22420 | .nextp | |
22421 | The values of \$acl@_m0$\ to \$acl@_m9$\ persist only while a message is being | |
22422 | received. They are reset afterwards. They are also reset by \\MAIL\\, \\RSET\\, | |
22423 | \\EHLO\\, \\HELO\\, and after starting up a TLS session. | |
22424 | .endp | |
4964e932 | 22425 | When a message is accepted, the current values of all the ACL variables are |
495ae4b0 | 22426 | preserved with the message and are subsequently made available at delivery |
4964e932 | 22427 | time. The ACL variables are set by modifier called \set\. For example: |
495ae4b0 PH |
22428 | .display asis |
22429 | accept hosts = whatever | |
22430 | set acl_m4 = some value | |
22431 | .endd | |
4964e932 | 22432 | \**Note**\: a leading dollar sign is not used when naming a variable that is to |
495ae4b0 | 22433 | be set. If you want to set a variable without taking any action, you can use a |
4964e932 | 22434 | \warn\ verb without any other modifiers or conditions. |
495ae4b0 PH |
22435 | |
22436 | ||
22437 | .section Condition and modifier processing | |
22438 | .index ~~ACL||conditions, processing | |
22439 | .index ~~ACL||modifiers, processing | |
22440 | An exclamation mark preceding a condition negates its result. For example, | |
22441 | .display asis | |
22442 | deny domains = *.dom.example | |
22443 | !verify = recipient | |
22444 | .endd | |
22445 | causes the ACL to return `deny' if the recipient domain ends in | |
4964e932 | 22446 | \*dom.example*\ and the recipient address cannot be verified. |
495ae4b0 PH |
22447 | |
22448 | The arguments of conditions and modifiers are expanded. A forced failure | |
22449 | of an expansion causes a condition to be ignored, that is, it behaves as if the | |
22450 | condition is true. Consider these two statements: | |
22451 | .display asis | |
22452 | accept senders = ${lookup{$host_name}lsearch\ | |
22453 | {/some/file}{$value}fail} | |
22454 | accept senders = ${lookup{$host_name}lsearch\ | |
22455 | {/some/file}{$value}{}} | |
22456 | .endd | |
22457 | Each attempts to look up a list of acceptable senders. If the lookup succeeds, | |
22458 | the returned list is searched, but if the lookup fails the behaviour is | |
22459 | different in the two cases. The \fail\ in the first statement causes the | |
22460 | condition to be ignored, leaving no further conditions. The \accept\ verb | |
22461 | therefore succeeds. The second statement, however, generates an empty list when | |
22462 | the lookup fails. No sender can match an empty list, so the condition fails, | |
22463 | and therefore the \accept\ also fails. | |
22464 | ||
22465 | ACL modifiers appear mixed in with conditions in ACL statements. Some of them | |
22466 | specify actions that are taken as the conditions for a statement are checked; | |
22467 | others specify text for messages that are used when access is denied or a | |
22468 | warning is generated. | |
4964e932 PH |
22469 | .em |
22470 | The \control\ modifier affects the way an incoming message is handled. | |
22471 | .nem | |
495ae4b0 PH |
22472 | |
22473 | The positioning of the modifiers in an ACL statement important, because the | |
22474 | processing of a verb ceases as soon as its outcome is known. Only those | |
4964e932 PH |
22475 | modifiers that have already been encountered will take effect. For example, |
22476 | consider this use of the \message\ modifier: | |
495ae4b0 PH |
22477 | .display asis |
22478 | require message = Can't verify sender | |
22479 | verify = sender | |
22480 | message = Can't verify recipient | |
22481 | verify = recipient | |
22482 | message = This message cannot be used | |
22483 | .endd | |
4964e932 PH |
22484 | If sender verification fails, Exim knows that the result of the statement is |
22485 | `deny', so it goes no further. The first \message\ modifier has been seen, so | |
495ae4b0 PH |
22486 | its text is used as the error message. If sender verification succeeds, but |
22487 | recipient verification fails, the second message is used. If recipient | |
22488 | verification succeeds, the third message becomes `current', but is never used | |
22489 | because there are no more conditions to cause failure. | |
22490 | ||
22491 | For the \deny\ verb, on the other hand, it is always the last \message\ | |
4964e932 PH |
22492 | modifier that is used, because all the conditions must be true for rejection to |
22493 | happen. Specifying more than one \message\ modifier does not make sense, and | |
495ae4b0 PH |
22494 | the message can even be specified after all the conditions. For example: |
22495 | .display asis | |
22496 | deny hosts = ... | |
22497 | !senders = *@my.domain.example | |
22498 | message = Invalid sender from client host | |
22499 | .endd | |
4964e932 | 22500 | The `deny' result does not happen until the end of the statement is reached, by |
495ae4b0 PH |
22501 | which time Exim has set up the message. |
22502 | ||
22503 | ||
22504 | .section ACL modifiers | |
22505 | .rset SECTACLmodi "~~chapter.~~section" | |
22506 | .index ~~ACL||modifiers, list of | |
22507 | The ACL modifiers are as follows: | |
22508 | ||
22509 | .startitems | |
22510 | ||
22511 | .item "control = <<text>>" | |
f055f31e | 22512 | .index \control\, ACL modifier |
495ae4b0 | 22513 | .em |
4964e932 | 22514 | This modifier affects the subsequent processing of the SMTP connection or of an |
d43194df PH |
22515 | incoming message that is accepted. The effect of the first type of control |
22516 | lasts for the duration of the connection, whereas the effect of the second type | |
22517 | lasts only until the current message has been received. The message-specific | |
22518 | controls always apply to the whole message, not to individual recipients, | |
22519 | even if the \control\ modifier appears in a \\RCPT\\ ACL. | |
22520 | ||
22521 | As there are now quite a few controls that can be applied, they are described | |
22522 | separately in section ~~SECTcontrols. | |
495ae4b0 | 22523 | .nem |
d43194df | 22524 | The \control\ modifier can be used in several different ways. For example: |
495ae4b0 PH |
22525 | .numberpars $. |
22526 | It can be at the end of an \accept\ statement: | |
22527 | .display asis | |
4964e932 | 22528 | accept ...some conditions |
495ae4b0 PH |
22529 | control = queue_only |
22530 | .endd | |
4964e932 PH |
22531 | In this case, the control is applied when this statement yields `accept', in |
22532 | other words, when the conditions are all true. | |
495ae4b0 PH |
22533 | .nextp |
22534 | It can be in the middle of an \accept\ statement: | |
22535 | .display asis | |
22536 | accept ...some conditions... | |
22537 | control = queue_only | |
22538 | ...some more conditions... | |
22539 | .endd | |
4964e932 | 22540 | If the first set of conditions are true, the control is applied, even if the |
495ae4b0 PH |
22541 | statement does not accept because one of the second set of conditions is false. |
22542 | In this case, some subsequent statement must yield `accept' for the control to | |
22543 | be relevant. | |
22544 | .nextp | |
22545 | It can be used with \warn\ to apply the control, leaving the | |
22546 | decision about accepting or denying to a subsequent verb. For | |
22547 | example: | |
22548 | .display asis | |
22549 | warn ...some conditions... | |
22550 | control = freeze | |
22551 | accept ... | |
22552 | .endd | |
495ae4b0 PH |
22553 | This example of \warn\ does not contain \message\, \log@_message\, or |
22554 | \logwrite\, so it does not add anything to the message and does not write a log | |
22555 | entry. | |
d43194df PH |
22556 | .nextp |
22557 | .em | |
22558 | If you want to apply a control unconditionally, you can use it with a \require\ | |
22559 | verb. For example: | |
22560 | .display asis | |
22561 | require control = no_multiline_response | |
22562 | .nem | |
22563 | .endd | |
495ae4b0 PH |
22564 | .endp |
22565 | ||
22566 | .item "delay = <<time>>" | |
f055f31e | 22567 | .index \delay\, ACL modifier |
495ae4b0 PH |
22568 | .index \-bh-\ option |
22569 | This modifier causes Exim to wait for the time interval before proceeding. The | |
22570 | time is given in the usual Exim notation. This modifier may appear in any ACL. | |
4964e932 PH |
22571 | The delay happens as soon as the modifier is processed. However, when testing |
22572 | Exim using the \-bh-\ option, the delay is not actually imposed (an appropriate | |
22573 | message is output instead). | |
495ae4b0 PH |
22574 | |
22575 | Like \control\, \delay\ can be used with \accept\ or | |
22576 | \deny\, for example: | |
22577 | .display asis | |
22578 | deny ...some conditions... | |
22579 | delay = 30s | |
22580 | .endd | |
4964e932 | 22581 | The delay happens if all the conditions are true, before the statement returns |
495ae4b0 PH |
22582 | `deny'. Compare this with: |
22583 | .display asis | |
22584 | deny delay = 30s | |
22585 | ...some conditions... | |
22586 | .endd | |
22587 | which waits for 30s before processing the conditions. The \delay\ modifier can | |
22588 | also be used with \warn\ and together with \control\: | |
22589 | .display | |
22590 | warn ...some conditions... | |
22591 | delay = 2m | |
22592 | control = freeze | |
22593 | accept ... | |
22594 | .endd | |
22595 | ||
22596 | .item endpass | |
f055f31e | 22597 | .index \endpass\, ACL modifier |
495ae4b0 PH |
22598 | This modifier, which has no argument, is recognized only in \accept\ |
22599 | statements. It marks the boundary between the conditions whose failure causes | |
22600 | control to pass to the next statement, and the conditions whose failure causes | |
22601 | the ACL to return `deny'. See the description of \accept\ above. | |
22602 | ||
22603 | .item "log@_message = <<text>>" | |
f055f31e | 22604 | .index \log@_message\, ACL modifier |
495ae4b0 | 22605 | This modifier sets up a message that is used as part of the log message if the |
4964e932 | 22606 | ACL denies access or a \warn\ statement's conditions are true. For example: |
495ae4b0 PH |
22607 | .display asis |
22608 | require log_message = wrong cipher suite $tls_cipher | |
22609 | encrypted = DES-CBC3-SHA | |
22610 | .endd | |
22611 | \log@_message\ adds to any underlying error message that may exist because of | |
22612 | the condition failure. For example, while verifying a recipient address, a | |
22613 | :::fail:: redirection might have already set up a message. Although the message | |
22614 | is usually defined before the conditions to which it applies, the expansion | |
22615 | does not happen until Exim decides that access is to be denied. This means that | |
22616 | any variables that are set by the condition are available for inclusion in the | |
22617 | message. For example, the \$dnslist@_<<xxx>>$\ variables are set after a DNS | |
4964e932 | 22618 | black list lookup succeeds. If the expansion of \log@_message\ fails, or if the |
495ae4b0 PH |
22619 | result is an empty string, the modifier is ignored. |
22620 | ||
22621 | If you want to use a \warn\ statement to log the result of an address | |
22622 | verification, you can use \$acl__verify__message$\ to include the verification | |
22623 | error message. | |
22624 | ||
495ae4b0 PH |
22625 | If \log@_message\ is used with a \warn\ statement, `Warning:' is added to the |
22626 | start of the logged message. If the same warning log message is requested more | |
22627 | than once while receiving a single email message, only one copy is actually | |
22628 | logged. If you want to log multiple copies, use \logwrite\ instead of | |
22629 | \log@_message\. In the absence of \log@_message\ and \logwrite\, nothing is | |
22630 | logged for a succesful \warn\ statement. | |
495ae4b0 PH |
22631 | |
22632 | If \log@_message\ is not present and there is no underlying error message (for | |
22633 | example, from the failure of address verification), but \message\ is present, | |
22634 | the \message\ text is used for logging rejections. However, if any text for | |
22635 | logging contains newlines, only the first line is logged. In the absence of | |
22636 | both \log@_message\ and \message\, a default built-in message is used for | |
22637 | logging rejections. | |
22638 | ||
22639 | .item "logwrite = <<text>>" | |
f055f31e | 22640 | .index \logwrite\, ACL modifier |
495ae4b0 PH |
22641 | .index log||in ACL, immediate |
22642 | This modifier writes a message to a log file as soon as it is encountered when | |
4964e932 PH |
22643 | processing an ACL. (Compare \log@_message\, which, except in the case of |
22644 | \warn\, is used only if the ACL statement denies access.) The \logwrite\ | |
22645 | modifier can be used to log special incidents in ACLs. For example: | |
22646 | .display | |
495ae4b0 PH |
22647 | accept <<some special conditions>> |
22648 | control = freeze | |
22649 | logwrite = froze message because ... | |
22650 | .endd | |
22651 | By default, the message is written to the main log. However, it may begin | |
22652 | with a colon, followed by a comma-separated list of log names, and then | |
22653 | another colon, to specify exactly which logs are to be written. For | |
22654 | example: | |
22655 | .display asis | |
22656 | logwrite = :main,reject: text for main and reject logs | |
22657 | logwrite = :panic: text for panic log only | |
22658 | .endd | |
22659 | ||
22660 | .item "message = <<text>>" | |
f055f31e | 22661 | .index \message\, ACL modifier |
495ae4b0 | 22662 | This modifier sets up a text string that is expanded and used as an error |
4964e932 PH |
22663 | message if the current statement causes the ACL to deny access. The expansion |
22664 | happens at the time Exim decides that access is to be denied, not at the time | |
495ae4b0 PH |
22665 | it processes \message\. If the expansion fails, or generates an empty string, |
22666 | the modifier is ignored. For ACLs that are triggered by SMTP commands, the | |
22667 | message is returned as part of the SMTP error response. | |
22668 | ||
22669 | The \message\ modifier is also used with the \warn\ verb to specify one or more | |
4964e932 PH |
22670 | header lines to be added to an incoming message when all the conditions are |
22671 | true. See section ~~SECTaddheadwarn for more details. If \message\ is used with | |
22672 | \warn\ in an ACL that is not concerned with receiving a message, it has no | |
22673 | effect. | |
495ae4b0 PH |
22674 | |
22675 | The text is literal; any quotes are taken as literals, but because the string | |
22676 | is expanded, backslash escapes are processed anyway. If the message contains | |
22677 | newlines, this gives rise to a multi-line SMTP response. Like \log@_message\, | |
22678 | the contents of \message\ are not expanded until after a condition has failed. | |
22679 | ||
4964e932 PH |
22680 | If \message\ is used on a statement that verifies an address, the message |
22681 | specified overrides any message that is generated by the verification process. | |
495ae4b0 PH |
22682 | However, the original message is available in the variable |
22683 | \$acl@_verify@_message$\, so you can incorporate it into your message if you | |
22684 | wish. In particular, if you want the text from \:fail:\ items in \%redirect%\ | |
22685 | routers to be passed back as part of the SMTP response, you should either not | |
22686 | use a \message\ modifier, or make use of \$acl@_verify@_message$\. | |
22687 | ||
22688 | .item "set <<acl@_name>> = <<value>>" | |
f055f31e | 22689 | .index \set\, ACL modifier |
4964e932 | 22690 | This modifier puts a value into one of the ACL variables (see section |
495ae4b0 PH |
22691 | ~~SECTaclvariables). |
22692 | ||
22693 | .enditems | |
22694 | ||
22695 | ||
4964e932 PH |
22696 | .em |
22697 | .section Use of the control modifier | |
22698 | .rset SECTcontrols "~~chapter.~~section" | |
f055f31e | 22699 | .index \control\, ACL modifier |
4964e932 PH |
22700 | The \control\ modifier supports the following settings: |
22701 | ||
22702 | .startitems | |
22703 | ||
22704 | .item "control = caseful@_local@_part" | |
22705 | .item "control = caselower@_local@_part" | |
22706 | .index ~~ACL||case of local part in | |
22707 | .index case of local parts | |
22708 | These two controls are permitted only in the ACL specified by \acl@_smtp@_rcpt\ | |
22709 | (that is, during \\RCPT\\ processing). By default, the contents of | |
22710 | \$local@_part$\ are lower cased before ACL processing. If | |
22711 | `caseful@_local@_part' is specified, any uppercase letters in the original | |
22712 | local part are restored in \$local@_part$\ for the rest of the ACL, or until a | |
d43194df PH |
22713 | control that sets `caselower@_local@_part' is encountered. |
22714 | ||
22715 | This control affects only the current recipient. Moreover, it applies only to | |
22716 | local part handling that takes place directly in the ACL (for example, as a key | |
22717 | in lookups). If a test to verify the recipient is obeyed, the case-related | |
22718 | handling of the local part during the verification is controlled by the router | |
22719 | configuration (see the \caseful@_local@_part\ generic router option). | |
4964e932 PH |
22720 | |
22721 | This facility could be used, for example, to add a spam score to local parts | |
22722 | containing upper case letters. For example, using \$acl@_m4$\ to accumulate the | |
22723 | spam score: | |
22724 | .display asis | |
22725 | warn control = caseful_local_part | |
22726 | set acl_m4 = ${eval:\ | |
22727 | $acl_m4 + \ | |
22728 | ${if match{$local_part}{[A-Z]}{1}{0}}\ | |
22729 | } | |
22730 | control = caselower_local_part | |
22731 | .endd | |
22732 | Notice that we put back the lower cased version afterwards, assuming that | |
22733 | is what is wanted for subsequent tests. | |
22734 | ||
22735 | .item "control = enforce@_sync" | |
22736 | .item "control = no@_enforce@_sync" | |
22737 | .index SMTP||synchronization checking | |
22738 | .index synchronization checking in SMTP | |
22739 | These controls make it possible to be selective about when SMTP synchronization | |
22740 | is enforced. The global option \smtp@_enforce@_sync\ specifies the initial | |
22741 | state of the switch (it is true by default). See the description of this option | |
22742 | in chapter ~~CHAPmainconfig for details of SMTP synchronization checking. | |
22743 | ||
d43194df PH |
22744 | The effect of these two controls lasts for the remainder of the SMTP |
22745 | connection. They can appear in any ACL except the one for the non-SMTP | |
4964e932 PH |
22746 | messages. The most straightforward place to put them is in the ACL defined by |
22747 | \acl@_smtp@_connect\, which is run at the start of an incoming SMTP connection, | |
22748 | before the first synchronization check. The expected use is to turn off the | |
22749 | synchronization checks for badly-behaved hosts that you nevertheless need to | |
22750 | work with. | |
22751 | ||
22752 | .item "control = fakereject/<<message>>" | |
22753 | .index fake rejection | |
22754 | .index rejection, fake | |
22755 | This control is permitted only for the \\MAIL\\, \\RCPT\\, and \\DATA\\ ACLs, | |
22756 | in other words, only when an SMTP message is being received. If Exim accepts | |
22757 | the message, instead the final 250 response, a 550 rejection message is sent. | |
d43194df PH |
22758 | However, Exim proceeds to deliver the message as normal. The control applies |
22759 | only to the current message, not to any subsequent ones that may be received in | |
22760 | the same SMTP connection. | |
4964e932 PH |
22761 | |
22762 | The text for the 550 response is taken from the \control\ modifier. If no | |
22763 | message is supplied, the following is used: | |
22764 | .display asis | |
22765 | 550-Your message has been rejected but is being | |
22766 | 550-kept for evaluation. | |
d43194df | 22767 | 550-If it was a legitimate message, it may still be |
4964e932 PH |
22768 | 550 delivered to the target recipient(s). |
22769 | .endd | |
22770 | This facilty should be used with extreme caution. | |
22771 | ||
22772 | ||
22773 | .item "control = freeze" | |
22774 | .index frozen messages||forcing in ACL | |
22775 | This control is permitted only for the \\MAIL\\, \\RCPT\\, \\DATA\\, and | |
22776 | non-SMTP ACLs, in other words, only when a message is being received. If the | |
d43194df PH |
22777 | message is accepted, it is placed on Exim's queue and frozen. The control |
22778 | applies only to the current message, not to any subsequent ones that may be | |
22779 | received in the same SMTP connection. | |
22780 | ||
22781 | ||
22782 | .item "control = no@_mbox@_unspool" | |
22783 | This control is available when Exim is compiled with the content scanning | |
22784 | extension. Content scanning may require a copy of the current message, or parts | |
22785 | of it, to be written in `mbox format' to a spool file, for passing to a virus | |
22786 | or spam scanner. Normally, such copies are deleted when they are no longer | |
22787 | needed. If this control is set, the copies are not deleted. The control | |
22788 | applies only to the current message, not to any subsequent ones that may be | |
22789 | received in the same SMTP connection. It is provided for debugging purposes and | |
22790 | is unlikely to be useful in production. | |
4964e932 PH |
22791 | |
22792 | ||
22793 | .item "control = no@_multiline@_response" | |
22794 | .index multiline responses, suppressing | |
22795 | This control is permitted for any ACL except the one for non-SMTP messages. | |
22796 | It seems that there are broken clients in use that cannot handle multiline | |
22797 | SMTP responses, despite the fact that RFC 821 defined them over 20 years ago. | |
22798 | ||
22799 | If this control is set, multiline SMTP responses from ACL rejections are | |
22800 | suppressed. One way of doing this would have been to put out these responses as | |
22801 | one long line. However, RFC 2821 specifies a maximum of 512 bytes per response | |
22802 | (`use multiline responses for more' it says -- ha!), and some of the responses | |
22803 | might get close to that. So this facility, which is after all only a sop to | |
22804 | broken clients, is implemented by doing two very easy things: | |
22805 | .numberpars | |
d43194df PH |
22806 | Extra information that is normally output as part of a rejection caused by |
22807 | sender verification failure is omitted. Only the final line (typically `sender | |
22808 | verification failed') is sent. | |
4964e932 PH |
22809 | .nextp |
22810 | If a \message\ modifier supplies a multiline response, only the first | |
22811 | line is output. | |
22812 | .endp | |
22813 | The setting of the switch can, of course, be made conditional on the | |
d43194df | 22814 | calling host. Its effect lasts until the end of the SMTP connection. |
4964e932 PH |
22815 | |
22816 | ||
22817 | .item "control = queue@_only" | |
22818 | .index \queue@_only\ | |
22819 | .index queueing incoming messages | |
22820 | This control is permitted only for the \\MAIL\\, \\RCPT\\, \\DATA\\, and | |
22821 | non-SMTP ACLs, in other words, only when a message is being received. If the | |
22822 | message is accepted, it is placed on Exim's queue and left there for delivery | |
22823 | by a subsequent queue runner. No immediate delivery process is started. In | |
d43194df PH |
22824 | other words, it has the effect as the \queue@_only\ global option. However, the |
22825 | control applies only to the current message, not to any subsequent ones that | |
22826 | may be received in the same SMTP connection. | |
4964e932 PH |
22827 | |
22828 | ||
22829 | .item "control = submission/<<options>>" | |
22830 | .index message||submission | |
22831 | .index submission mode | |
22832 | This control is permitted only for the \\MAIL\\, \\RCPT\\, and start of data | |
22833 | ACLs (the latter is the one defined by \acl@_smtp@_predata\). Setting it tells | |
d43194df PH |
22834 | Exim that the current message is a submission from a local MUA. In this case, |
22835 | Exim operates in `submission mode', and applies certain fixups to the message | |
22836 | if necessary. For example, it add a ::Date:: header line if one is not present. | |
22837 | This control is not permitted in the \acl@_smtp@_data\ ACL, because that is too | |
22838 | late (the message has already been created). | |
4964e932 PH |
22839 | |
22840 | Chapter ~~CHAPmsgproc describes the processing that Exim applies to messages. | |
22841 | Section ~~SECTsubmodnon covers the processing that happens in submission mode; | |
d43194df PH |
22842 | the available options for this control are described there. The control applies |
22843 | only to the current message, not to any subsequent ones that may be received in | |
22844 | the same SMTP connection. | |
4964e932 PH |
22845 | |
22846 | .enditems | |
22847 | .nem | |
22848 | ||
22849 | ||
22850 | .em | |
22851 | .section Adding header lines with the warn verb | |
22852 | .rset SECTaddheadwarn "~~chapter.~~section" | |
22853 | .index header lines||adding in an ACL | |
22854 | .index header lines||position of added lines | |
f055f31e PH |
22855 | .index \warn\, ACL verb |
22856 | .index \message\, ACL modifier | |
4964e932 PH |
22857 | The \message\ modifier can be used on a \warn\ statement to add an extra header |
22858 | line to an incoming message, as in this example: | |
22859 | .display asis | |
22860 | warn message = X-blacklisted-at: $dnslist_domain | |
22861 | dnslists = sbl.spamhaus.org : \ | |
22862 | dialup.mail-abuse.org | |
22863 | .endd | |
22864 | If an identical header line is requested several times (provoked, for example, | |
22865 | by multiple \\RCPT\\ commands), only one copy is actually added to the message. | |
22866 | If the text of the \message\ modifier contains one or more newlines that are | |
22867 | not followed by a space or a tab, it is assumed to contain multiple header | |
22868 | lines. Each one is checked for valid syntax; \"X-ACL-Warn:"\ is added to the | |
22869 | front of any line that is not a valid header line. | |
22870 | ||
22871 | By default, new lines are added at the end of the existing header lines. | |
22872 | However, you can specify that any particular header line should be added right | |
22873 | at the start (before all the ::Received:: lines), immediately after the first | |
22874 | block of ::Received:: lines, or immediately before any line that is not a | |
22875 | ::Received:: or ::Resent-something:: header. | |
22876 | ||
22877 | This is done by specifying `:at@_start:', `:after@_received:', or | |
22878 | `:at@_start@_rfc:' (or, for completeness, `:at@_end:') before the text of the | |
22879 | header line, respectively. (Header text cannot start with a colon, as there has | |
22880 | to be a header name first.) For example: | |
22881 | .display asis | |
22882 | warn message = :after_received:X-My-Header: something or other... | |
22883 | .endd | |
22884 | ||
22885 | If more than one header is supplied in a single warn statement, each one is | |
22886 | treated independently and can therefore be placed differently. If you add | |
22887 | more than one line at the start, or after the Received: block, they will | |
22888 | end up in reverse order. | |
22889 | ||
22890 | \**Warning**\: This facility currently applies only to header lines that are | |
22891 | added in an ACL. It does NOT work for header lines that are added in a | |
22892 | system filter or in a router or transport. | |
22893 | ||
22894 | .index header lines||added, visibility of | |
22895 | Header lines that are added by an ACL at \\MAIL\\ or \\RCPT\\ time are not | |
22896 | visible in string expansions in ACLs for subsequent \\RCPT\\ commands or in the | |
22897 | \acl@_smtp@_predata\ ACL. However, they are visible in string expansions in the | |
22898 | ACL that is run after \\DATA\\ is complete (the \acl@_smtp@_data\ ACL). This is | |
22899 | also true for header lines that are added in the \acl@_smtp@_predata\ ACL. | |
22900 | If a message is rejected after \\DATA\\, all added header lines are included in | |
22901 | the entry that is written to the reject log. | |
22902 | ||
22903 | If you want to preserve data between \\MAIL\\, \\RCPT\\, and the | |
22904 | \acl@_smtp@_predata\ ACLs, you can use ACL variables, as described in section | |
22905 | ~~SECTaclvariables. | |
22906 | .nem | |
22907 | ||
495ae4b0 PH |
22908 | |
22909 | ||
22910 | .section ACL conditions | |
22911 | .rset SECTaclconditions "~~chapter.~~section" | |
22912 | .index ~~ACL||conditions, list of | |
4964e932 PH |
22913 | .em |
22914 | Some of conditions listed in this section are available only when Exim is | |
22915 | compiled with the content-scanning extension. They are included here briefly | |
22916 | for completeness. More detailed descriptions can be found in the discussion on | |
22917 | content scanning in chapter ~~CHAPexiscan. | |
22918 | .nem | |
22919 | ||
495ae4b0 PH |
22920 | Not all conditions are relevant in all circumstances. For example, testing |
22921 | senders and recipients does not make sense in an ACL that is being run as the | |
22922 | result of the arrival of an \\ETRN\\ command, and checks on message headers can | |
4964e932 PH |
22923 | be done only in the ACLs specified by \acl@_smtp@_data\ and \acl__not__smtp\. |
22924 | You can use the same condition (with different parameters) more than once in | |
22925 | the same ACL statement. This provides a way of specifying an `and' conjunction. | |
495ae4b0 PH |
22926 | The conditions are as follows: |
22927 | ||
22928 | .startitems | |
22929 | ||
22930 | .item "acl = <<name of acl or ACL string or file name >>" | |
22931 | .index ~~ACL||nested | |
22932 | .index ~~ACL||indirect | |
f055f31e | 22933 | .index \acl\, ACL condition |
495ae4b0 PH |
22934 | The possible values of the argument are the same as for the |
22935 | \acl@_smtp@_$it{xxx}\ options. The named or inline ACL is run. If it returns | |
4964e932 PH |
22936 | `accept' the condition is true; if it returns `deny' the condition is false. If |
22937 | it returns `defer', the current ACL returns `defer' | |
22938 | .em | |
22939 | unless the condition is on a \warn\ verb. In that case, a `defer' return makes | |
22940 | the condition false. This means that further processing of the \warn\ verb | |
22941 | ceases, but processing of the ACL continues. | |
22942 | .nem | |
22943 | ||
22944 | If the nested \acl\ returns `drop' and the outer condition denies access, | |
22945 | the connection is dropped. If it returns `discard', the verb must be \accept\ | |
22946 | or \discard\, and the action is taken immediately -- no further conditions are | |
22947 | tested. | |
495ae4b0 PH |
22948 | |
22949 | ACLs may be nested up to 20 deep; the limit exists purely to catch runaway | |
4964e932 | 22950 | loops. This condition allows you to use different ACLs in different |
495ae4b0 PH |
22951 | circumstances. For example, different ACLs can be used to handle \\RCPT\\ |
22952 | commands for different local users or different local domains. | |
22953 | ||
22954 | .item "authenticated = <<string list>>" | |
f055f31e | 22955 | .index \authenticated\, ACL condition |
495ae4b0 PH |
22956 | .index authentication||ACL checking |
22957 | .index ~~ACL||testing for authentication | |
22958 | If the SMTP connection is not authenticated, the condition is false. Otherwise, | |
22959 | the name of the authenticator is tested against the list. To test for | |
22960 | authentication by any authenticator, you can set | |
22961 | .display asis | |
22962 | authenticated = * | |
22963 | .endd | |
22964 | ||
22965 | .item "condition = <<string>>" | |
f055f31e | 22966 | .index \condition\, ACL condition |
495ae4b0 PH |
22967 | .index customizing||ACL condition |
22968 | .index ~~ACL||customized test | |
d43194df | 22969 | .index ~~ACL||testing, customized |
495ae4b0 PH |
22970 | This feature allows you to make up custom conditions. If the result of |
22971 | expanding the string is an empty string, the number zero, or one of the strings | |
22972 | `no' or `false', the condition is false. If the result is any non-zero number, | |
22973 | or one of the strings `yes' or `true', the condition is true. For any other | |
22974 | values, some error is assumed to have occured, and the ACL returns `defer'. | |
22975 | ||
4964e932 PH |
22976 | |
22977 | .em | |
22978 | .item "decode = <<location>>" | |
f055f31e | 22979 | .index \decode\, ACL condition |
4964e932 PH |
22980 | This condition is available only when Exim is compiled with the |
22981 | content-scanning extension, and it is allowed only the the ACL defined by | |
22982 | \acl@_smtp@_mime\. It causes the current MIME part to be decoded into a file. | |
22983 | For details, see chapter ~~CHAPexiscan. | |
22984 | .nem | |
22985 | ||
22986 | ||
495ae4b0 | 22987 | .item "dnslists = <<list of domain names and other data>>" |
f055f31e | 22988 | .index \dnslists\, ACL condition |
495ae4b0 PH |
22989 | .index DNS list||in ACL |
22990 | .index black list (DNS) | |
22991 | .index ~~ACL||testing a DNS list | |
22992 | This condition checks for entries in DNS black lists. These are also known as | |
22993 | `RBL lists', after the original Realtime Blackhole List, but note that the use | |
4964e932 PH |
22994 | of the lists at \*mail-abuse.org*\ now carries a charge. |
22995 | There are too many different variants of this condition to describe briefly | |
495ae4b0 PH |
22996 | here. See sections ~~SECTmorednslists--~~SECTmorednslistslast for details. |
22997 | ||
22998 | .item "domains = <<domain list>>" | |
f055f31e | 22999 | .index \domains\, ACL condition |
495ae4b0 PH |
23000 | .index domain||ACL checking |
23001 | .index ~~ACL||testing a recipient domain | |
23002 | This condition is relevant only after a \\RCPT\\ command. It checks that the | |
23003 | domain of the recipient address is in the domain list. If percent-hack | |
23004 | processing is enabled, it is done before this test is done. If the check | |
23005 | succeeds with a lookup, the result of the lookup is placed in \$domain@_data$\ | |
23006 | until the next \domains\ test. | |
23007 | ||
23008 | .item "encrypted = <<string list>>" | |
f055f31e | 23009 | .index \encrypted\, ACL condition |
495ae4b0 PH |
23010 | .index encryption||checking in an ACL |
23011 | .index ~~ACL||testing for encryption | |
23012 | If the SMTP connection is not encrypted, the condition is false. Otherwise, the | |
23013 | name of the cipher suite in use is tested against the list. To test for | |
23014 | encryption without testing for any specific cipher suite(s), set | |
23015 | .display asis | |
23016 | encrypted = * | |
23017 | .endd | |
23018 | ||
23019 | .item "hosts = << host list>>" | |
f055f31e | 23020 | .index \hosts\, ACL condition |
495ae4b0 PH |
23021 | .index host||ACL checking |
23022 | .index ~~ACL||testing the client host | |
23023 | This condition tests that the calling host matches the host list. If you have | |
23024 | name lookups or wildcarded host names and IP addresses in the same host list, | |
23025 | you should normally put the IP addresses first. For example, you could have: | |
23026 | .display asis | |
23027 | accept hosts = 10.9.8.7 : dbm;/etc/friendly/hosts | |
23028 | .endd | |
23029 | The reason for this lies in the left-to-right way that Exim processes lists. | |
23030 | It can test IP addresses without doing any DNS lookups, but when it reaches an | |
23031 | item that requires a host name, it fails if it cannot find a host name to | |
23032 | compare with the pattern. If the above list is given in the opposite order, the | |
23033 | \accept\ statement fails for a host whose name cannot be found, even if its | |
23034 | IP address is 10.9.8.7. | |
23035 | ||
23036 | If you really do want to do the name check first, and still recognize the IP | |
23037 | address even if the name lookup fails, you can rewrite the ACL like this: | |
23038 | .display asis | |
23039 | accept hosts = dbm;/etc/friendly/hosts | |
23040 | accept hosts = 10.9.8.7 | |
23041 | .endd | |
23042 | The default action on failing to find the host name is to assume that the host | |
23043 | is not in the list, so the first \accept\ statement fails. The second statement | |
23044 | can then check the IP address. | |
23045 | ||
23046 | If a \hosts\ condition is satisfied by means of a lookup, the result | |
23047 | of the lookup is made available in the \$host@_data$\ variable. This | |
23048 | allows you, for example, to set up a statement like this: | |
23049 | .display asis | |
23050 | deny hosts = net-lsearch;/some/file | |
23051 | message = $host_data | |
23052 | .endd | |
23053 | which gives a custom error message for each denied host. | |
23054 | ||
23055 | .item "local@_parts = <<local part list>>" | |
f055f31e | 23056 | .index \local@_parts\, ACL condition |
495ae4b0 PH |
23057 | .index local part||ACL checking |
23058 | .index ~~ACL||testing a local part | |
23059 | This condition is relevant only after a \\RCPT\\ command. It checks that the | |
23060 | local part of the recipient address is in the list. If percent-hack processing | |
23061 | is enabled, it is done before this test. If the check succeeds with a lookup, | |
23062 | the result of the lookup is placed in \$local@_part@_data$\ until the next | |
23063 | \local@_parts\ test. | |
23064 | ||
4964e932 PH |
23065 | |
23066 | .em | |
23067 | .item "malware = <<option>>" | |
f055f31e | 23068 | .index \malware\, ACL condition |
d43194df PH |
23069 | .index ~~ACL||virus scanning |
23070 | .index ~~ACL||scanning for viruses | |
4964e932 PH |
23071 | This condition is available only when Exim is compiled with the |
23072 | content-scanning extension. It causes the incoming message to be scanned for | |
23073 | viruses. For details, see chapter ~~CHAPexiscan. | |
23074 | .nem | |
23075 | ||
23076 | ||
23077 | .em | |
23078 | .item "mime@_regex = <<list of regular expressions>>" | |
f055f31e | 23079 | .index \mime@_regex\, ACL condition |
d43194df | 23080 | .index ~~ACL||testing by regex matching |
4964e932 PH |
23081 | This condition is available only when Exim is compiled with the |
23082 | content-scanning extension, and it is allowed only the the ACL defined by | |
23083 | \acl@_smtp@_mime\. It causes the current MIME part to be scanned for a match | |
23084 | with any of the regular expressions. For details, see chapter ~~CHAPexiscan. | |
23085 | .nem | |
23086 | ||
23087 | ||
495ae4b0 | 23088 | .item "recipients = <<address list>>" |
f055f31e | 23089 | .index \recipients\, ACL condition |
495ae4b0 PH |
23090 | .index recipient||ACL checking |
23091 | .index ~~ACL||testing a recipient | |
23092 | This condition is relevant only after a \\RCPT\\ command. It checks the entire | |
23093 | recipient address against a list of recipients. | |
23094 | ||
4964e932 PH |
23095 | |
23096 | .em | |
23097 | .item "regex = <<list of regular expressions>>" | |
f055f31e | 23098 | .index \regex\, ACL condition |
d43194df | 23099 | .index ~~ACL||testing by regex matching |
4964e932 PH |
23100 | This condition is available only when Exim is compiled with the |
23101 | content-scanning extension. It causes the incoming message to be scanned | |
23102 | for a match with any of the regular expressions. For details, see chapter | |
23103 | ~~CHAPexiscan. | |
23104 | .nem | |
23105 | ||
23106 | ||
495ae4b0 | 23107 | .item "sender@_domains = <<domain list>>" |
f055f31e | 23108 | .index \sender@_domains\, ACL condition |
495ae4b0 PH |
23109 | .index sender||ACL checking |
23110 | .index ~~ACL||testing a sender domain | |
23111 | This condition tests the domain of the sender of the message against the given | |
23112 | domain list. | |
23113 | \**Note**\: the domain of the sender address is in | |
4964e932 PH |
23114 | \$sender@_address@_domain$\. It is \*not*\ put in \$domain$\ during the testing |
23115 | of this condition. This is an exception to the general rule for testing | |
23116 | domain lists. It is done this way so that, if this condition is used in an | |
495ae4b0 PH |
23117 | ACL for a \\RCPT\\ command, the recipient's domain (which is in \$domain$\) can |
23118 | be used to influence the sender checking. | |
23119 | ||
23120 | .item "senders = <<address list>>" | |
f055f31e | 23121 | .index \senders\, ACL condition |
495ae4b0 PH |
23122 | .index sender||ACL checking |
23123 | .index ~~ACL||testing a sender | |
23124 | This condition tests the sender of the message against the given list. To test | |
23125 | for a bounce message, which has an empty sender, set | |
23126 | .display asis | |
23127 | senders = : | |
23128 | .endd | |
23129 | ||
4964e932 PH |
23130 | |
23131 | .em | |
23132 | .item "spam = <<username>>" | |
f055f31e | 23133 | .index \spam\, ACL condition |
d43194df | 23134 | .index ~~ACL||scanning for spam |
4964e932 PH |
23135 | This condition is available only when Exim is compiled with the |
23136 | content-scanning extension. It causes the incoming message to be scanned by | |
23137 | SpamAssassin. For details, see chapter ~~CHAPexiscan. | |
23138 | .nem | |
23139 | ||
23140 | ||
495ae4b0 | 23141 | .item "verify = certificate" |
f055f31e | 23142 | .index \verify\, ACL condition |
495ae4b0 PH |
23143 | .index TLS||client certificate verification |
23144 | .index certificate||verification of client | |
23145 | .index ~~ACL||certificate verification | |
d43194df | 23146 | .index ~~ACL||testing a TLS certificate |
495ae4b0 PH |
23147 | This condition is true in an SMTP session if the session is encrypted, and a |
23148 | certificate was received from the client, and the certificate was verified. The | |
23149 | server requests a certificate only if the client matches \tls@_verify@_hosts\ | |
23150 | or \tls@_try@_verify@_hosts\ (see chapter ~~CHAPTLS). | |
23151 | ||
23152 | .item "verify = header@_sender/<<options>>" | |
f055f31e | 23153 | .index \verify\, ACL condition |
495ae4b0 PH |
23154 | .index ~~ACL||verifying sender in the header |
23155 | .index header lines||verifying the sender in | |
23156 | .index sender||verifying in header | |
23157 | .index verifying||sender in header | |
23158 | This condition is relevant only in an ACL that is run after a message has been | |
4964e932 PH |
23159 | received, that is, in an ACL specified by \acl@_smtp@_data\ |
23160 | .em | |
23161 | or \acl@_not@_smtp\. It checks that there is a verifiable address in at least | |
23162 | one of the ::Sender::, ::Reply-To::, or ::From:: header lines. Such an address | |
23163 | is loosely thought of as a `sender' address (hence the name of the test). | |
23164 | However, an address that appears in one of these headers need not be an address | |
23165 | that accepts bounce messages; only sender addresses in envelopes are required | |
23166 | to accept bounces. Therefore, if you use the callout option on this check, you | |
23167 | might want to arrange for a non-empty address in the \\MAIL\\ command. | |
23168 | .nem | |
23169 | ||
23170 | Details of address verification and the options are given later, starting at | |
23171 | section ~~SECTaddressverification (callouts are described in section | |
23172 | ~~SECTcallver). You can combine this condition with the \senders\ condition to | |
23173 | restrict it to bounce messages only: | |
495ae4b0 PH |
23174 | .display asis |
23175 | deny senders = : | |
23176 | message = A valid sender header is required for bounces | |
23177 | !verify = header_sender | |
23178 | .endd | |
23179 | ||
23180 | .item "verify = header@_syntax" | |
f055f31e | 23181 | .index \verify\, ACL condition |
495ae4b0 PH |
23182 | .index ~~ACL||verifying header syntax |
23183 | .index header lines||verifying syntax | |
23184 | .index verifying||header syntax | |
23185 | This condition is relevant only in an ACL that is run after a message has been | |
23186 | received, that is, in an ACL specified by \acl@_smtp@_data\ | |
23187 | or \acl@_not@_smtp\. | |
23188 | It checks the syntax of all header lines that can contain lists of addresses | |
4964e932 | 23189 | (::Sender::, ::From::, ::Reply-To::, ::To::, ::Cc::, and ::Bcc::). |
495ae4b0 PH |
23190 | Unqualified addresses (local parts without domains) are permitted only in |
23191 | locally generated messages and from hosts that match | |
23192 | \sender@_unqualified@_hosts\ or \recipient@_unqualified@_hosts\, as | |
23193 | appropriate. | |
23194 | ||
23195 | Note that this condition is a syntax check only. However, a common spamming | |
23196 | ploy is to send syntactically invalid headers such as | |
23197 | .display asis | |
23198 | To: @ | |
23199 | .endd | |
23200 | and this condition can be used to reject such messages. | |
23201 | ||
23202 | .item "verify = helo" | |
f055f31e | 23203 | .index \verify\, ACL condition |
495ae4b0 PH |
23204 | .index ~~ACL||verifying HELO/EHLO |
23205 | .index \\HELO\\||verifying | |
23206 | .index \\EHLO\\||verifying | |
23207 | .index verifying||\\EHLO\\ | |
23208 | .index verifying||\\HELO\\ | |
23209 | This condition is true if a \\HELO\\ or \\EHLO\\ command has been received from | |
23210 | the client host, and its contents have been verified. Verification of these | |
23211 | commands does not happen by default. See the description of the | |
23212 | \helo@_verify@_hosts\ and \helo@_try@_verify@_hosts\ options for details of how | |
23213 | to request it. | |
23214 | ||
23215 | .item "verify = recipient/<<options>>" | |
f055f31e | 23216 | .index \verify\, ACL condition |
495ae4b0 PH |
23217 | .index ~~ACL||verifying recipient |
23218 | .index recipient||verifying | |
23219 | .index verifying||recipient | |
23220 | This condition is relevant only after a \\RCPT\\ command. It verifies the | |
23221 | current recipient. Details of address verification are given later, starting at | |
23222 | section ~~SECTaddressverification. After a recipient has been verified, the | |
23223 | value of \$address@_data$\ is the last value that was set while routing the | |
23224 | address. This applies even if the verification fails. When an address that is | |
23225 | being verified is redirected to a single address, verification continues with | |
23226 | the new address, and in that case, the subsequent value of \$address@_data$\ is | |
23227 | the value for the child address. | |
23228 | ||
23229 | ||
23230 | .item "verify = reverse@_host@_lookup" | |
f055f31e | 23231 | .index \verify\, ACL condition |
495ae4b0 PH |
23232 | .index ~~ACL||verifying host reverse lookup |
23233 | .index host||verifying reverse lookup | |
23234 | This condition ensures that a verified host name has been looked up from the IP | |
23235 | address of the client host. (This may have happened already if the host name | |
23236 | was needed for checking a host list, or if the host matched \host@_lookup\.) | |
23237 | Verification ensures that the host name obtained from a reverse DNS lookup, or | |
23238 | one of its aliases, does, when it is itself looked up in the DNS, yield the | |
23239 | original IP address. | |
23240 | ||
4964e932 | 23241 | If this condition is used for a locally generated message (that is, when there |
495ae4b0 PH |
23242 | is no client host involved), it always succeeds. |
23243 | ||
23244 | ||
23245 | .item "verify = sender/<<options>>" | |
f055f31e | 23246 | .index \verify\, ACL condition |
495ae4b0 PH |
23247 | .index ~~ACL||verifying sender |
23248 | .index sender||verifying | |
23249 | .index verifying||sender | |
d43194df PH |
23250 | This condition is relevant only after a \\MAIL\\ or \\RCPT\\ command, or after |
23251 | a message has been received (the \acl@_smtp@_data\ or \acl@_not@_smtp\ ACLs). | |
495ae4b0 | 23252 | If the message's sender is empty (that is, this is a bounce message), the |
d43194df PH |
23253 | condition is true. Otherwise, the sender address is verified. |
23254 | .em | |
23255 | If there is data in the \$address@_data$\ variable at the end of routing, its | |
23256 | value is placed in \$sender__address__data$\ at the end of verification. This | |
23257 | value can be used in subsequent conditions and modifiers in the same ACL | |
23258 | statement. It does not persist after the end of the current statement. If you | |
23259 | want to preserve the value for longer, you can save it in an ACL variable. | |
23260 | ||
23261 | Details of verification are given later, starting at section | |
23262 | ~~SECTaddressverification. Exim caches the result of sender verification, to | |
23263 | avoid doing it more than once per message. | |
495ae4b0 | 23264 | |
8408f763 | 23265 | .item "verify = sender=<<address>>/<<options>>" |
f055f31e | 23266 | .index \verify\, ACL condition |
495ae4b0 PH |
23267 | This is a variation of the previous option, in which a modified address is |
23268 | verified as a sender. | |
23269 | ||
23270 | .enditems | |
23271 | ||
23272 | ||
23273 | ||
23274 | .section Using DNS lists | |
23275 | .rset SECTmorednslists "~~chapter.~~section" | |
23276 | .index DNS list||in ACL | |
23277 | .index black list (DNS) | |
23278 | .index ~~ACL||testing a DNS list | |
23279 | In its simplest form, the \dnslists\ condition tests whether the calling host | |
4964e932 PH |
23280 | is on at least one of a number of DNS lists by looking up the inverted IP |
23281 | address in one or more DNS domains. For example, if the calling host's IP | |
23282 | address is 192.168.62.43, and the ACL statement is | |
495ae4b0 PH |
23283 | .display asis |
23284 | deny dnslists = blackholes.mail-abuse.org : \ | |
23285 | dialups.mail-abuse.org | |
23286 | .endd | |
4964e932 | 23287 | the following records are looked up: |
495ae4b0 PH |
23288 | .display asis |
23289 | 43.62.168.192.blackholes.mail-abuse.org | |
4964e932 PH |
23290 | 43.62.168.192.dialups.mail-abuse.org |
23291 | .endd | |
23292 | .em | |
23293 | As soon as Exim finds an existing DNS record, processing of the list stops. | |
23294 | Thus, multiple entries on the list provide an `or' conjunction. If you want to | |
23295 | test that a host is on more than one list (an `and' conjunction), you can use | |
23296 | two separate conditions: | |
23297 | .display asis | |
23298 | deny dnslists = blackholes.mail-abuse.org | |
23299 | dnslists = dialups.mail-abuse.org | |
495ae4b0 | 23300 | .endd |
4964e932 | 23301 | .nem |
495ae4b0 | 23302 | If a DNS lookup times out or otherwise fails to give a decisive answer, Exim |
4964e932 PH |
23303 | behaves as if the host |
23304 | .em | |
23305 | does not match the list item, that is, as if the DNS record does not exist. If | |
23306 | there are further items in the DNS list, they are processed. | |
23307 | .nem | |
23308 | This is usually the required action when \dnslists\ is used with \deny\ (which | |
23309 | is the most common usage), because it prevents a DNS failure from blocking | |
23310 | mail. However, you can change this behaviour by putting one of the following | |
23311 | special items in the list: | |
495ae4b0 PH |
23312 | .index \"+include@_unknown"\ |
23313 | .index \"+exclude@_unknown"\ | |
23314 | .index \"+defer@_unknown"\ | |
23315 | .display | |
23316 | +include@_unknown $rm{behave as if the item is on the list} | |
23317 | +exclude@_unknown $rm{behave as if the item is not on the list (default)} | |
23318 | +defer@_unknown $rm{give a temporary error} | |
23319 | .endd | |
23320 | Each of these applies to any subsequent items on the list. For example: | |
23321 | .display asis | |
23322 | deny dnslists = +defer_unknown : foo.bar.example | |
23323 | .endd | |
23324 | ||
23325 | Testing the list of domains stops as soon as a match is found. If you want to | |
23326 | warn for one list and block for another, you can use two different statements: | |
23327 | .display asis | |
23328 | deny dnslists = blackholes.mail-abuse.org | |
23329 | warn message = X-Warn: sending host is on dialups list | |
23330 | dnslists = dialups.mail-abuse.org | |
23331 | .endd | |
23332 | ||
23333 | DNS list lookups are cached by Exim for the duration of the SMTP session, | |
23334 | so a lookup based on the IP address is done at most once for any incoming | |
23335 | connection. Exim does not share information between multiple incoming | |
23336 | connections (but your local name server cache should be active). | |
23337 | ||
23338 | ||
4964e932 PH |
23339 | .em |
23340 | .section Specifying the IP address for a DNS list lookup | |
23341 | .index DNS list||keyed by explicit IP address | |
23342 | By default, the IP address that is used in a DNS list lookup is the IP address | |
23343 | of the calling host. However, you can specify another IP address by listing it | |
23344 | after the domain name, introduced by a slash. For example: | |
23345 | .display asis | |
23346 | deny dnslists = black.list.tls/192.168.1.2 | |
23347 | .endd | |
23348 | This feature is not very helpful with explicit IP addresses; it is intended for | |
23349 | use with IP addresses that are looked up, for example, the IP addresses of the | |
23350 | MX hosts or nameservers of an email sender address. For an example, see section | |
23351 | ~~SECTmulkeyfor below. | |
23352 | .nem | |
23353 | ||
23354 | ||
495ae4b0 | 23355 | .section DNS lists keyed on domain names |
4964e932 | 23356 | .index DNS list||keyed by domain name |
495ae4b0 PH |
23357 | There are some lists that are keyed on domain names rather than inverted IP |
23358 | addresses (see for example the \*domain based zones*\ link at | |
4964e932 PH |
23359 | \?http://www.rfc-ignorant.org/?\). No reversing of components is used with |
23360 | these lists. You can change the name that is looked up in a DNS list by listing | |
23361 | it after the domain name, introduced by a slash. For example, | |
495ae4b0 PH |
23362 | .display asis |
23363 | deny message = Sender's domain is listed at $dnslist_domain | |
23364 | dnslists = dsn.rfc-ignorant.org/$sender_address_domain | |
23365 | .endd | |
23366 | This particular example is useful only in ACLs that are obeyed after the | |
23367 | \\RCPT\\ or \\DATA\\ commands, when a sender address is available. If (for | |
23368 | example) the message's sender is \*user@@tld.example*\ the name that is looked | |
23369 | up by this example is | |
23370 | .display asis | |
23371 | tld.example.dsn.rfc-ignorant.org | |
23372 | .endd | |
4964e932 PH |
23373 | .em |
23374 | A single \dnslists\ condition can contain entries for both names and IP | |
23375 | addresses. For example: | |
23376 | .display asis | |
23377 | deny dnslists = sbl.spamhaus.org : \ | |
23378 | dsn.rfc-ignorant.org/$sender_address_domain | |
23379 | .endd | |
23380 | The first item checks the sending host's IP address; the second checks a domain | |
23381 | name. The whole condition is true if either of the DNS lookups succeeds. | |
23382 | .nem | |
23383 | ||
23384 | ||
23385 | .em | |
23386 | .section Multiple explicit keys for a DNS list | |
23387 | .rset SECTmulkeyfor "~~chapter.~~section" | |
23388 | .index DNS list||multiple keys for | |
23389 | The syntax described above for looking up explicitly-defined values (either | |
23390 | names or IP addresses) in a DNS blacklist is a simplification. After the domain | |
23391 | name for the DNS list, what follows the slash can in fact be a list of items. | |
23392 | As with all lists in Exim, the default separator is a colon. However, because | |
23393 | this is a sublist within the list of DNS blacklist domains, it is necessary | |
23394 | either to double the separators like this: | |
23395 | .display asis | |
23396 | dnslists = black.list.tld/name.1::name.2 | |
23397 | .endd | |
23398 | or to change the separator character, like this: | |
23399 | .display asis | |
23400 | dnslists = black.list.tld/<;name.1;name.2 | |
23401 | .endd | |
23402 | If an item in the list is an IP address, it is inverted before the DNS | |
23403 | blacklist domain is appended. If it is not an IP address, no inversion | |
23404 | occurs. Consider this condition: | |
23405 | .display asis | |
23406 | dnslists = black.list.tld/<;192.168.1.2;a.domain | |
23407 | .endd | |
23408 | The DNS lookups that occur are: | |
23409 | .display asis | |
23410 | 2.1.168.192.black.list.tld | |
23411 | a.domain.black.list.tld | |
23412 | .endd | |
23413 | Once a DNS record has been found (that matches a specific IP return | |
23414 | address, if specified -- see section ~~SECTaddmatcon), no further lookups are | |
23415 | done. If there is a temporary DNS error, the rest of the sublist of domains or | |
23416 | IP addresses is tried. A temporary error for the whole dnslists item occurs | |
23417 | only if no other DNS lookup in this sublist succeeds. In other words, a | |
23418 | successful lookup for any of the items in the sublist overrides a temporary | |
23419 | error for a previous item. | |
23420 | ||
23421 | The ability to supply a list of items after the slash is in some sense just a | |
23422 | syntactic convenience. These two examples have the same effect: | |
23423 | .display asis | |
23424 | dnslists = black.list.tld/a.domain : black.list.tld/b.domain | |
23425 | dnslists = black.list.tld/a.domain::b.domain | |
23426 | .endd | |
23427 | However, when the data for the list is obtained from a lookup, the second form | |
23428 | is usually much more convenient. Consider this example: | |
23429 | .display asis | |
23430 | deny message = The mail servers for the domain \ | |
23431 | $sender_address_domain \ | |
23432 | are listed at $dnslist_domain ($dnslist_value); \ | |
23433 | see $dnslist_text. | |
23434 | dnslists = sbl.spamhaus.org/<|${lookup dnsdb {>|a=<|\ | |
23435 | ${lookup dnsdb {>|mxh=\ | |
23436 | $sender_address_domain} }} } | |
23437 | .endd | |
23438 | Note the use of \">|"\ in the dnsdb lookup to specify the separator for | |
23439 | multiple DNS records. The inner dnsdb lookup produces a list of MX hosts | |
23440 | and the outer dnsdb lookup finds the IP addresses for these hosts. The result | |
23441 | of expanding the condition might be something like this: | |
23442 | .display asis | |
23443 | dnslists = sbl.spahmaus.org/<|192.168.2.3|192.168.5.6|... | |
23444 | .endd | |
23445 | Thus, this example checks whether or not the IP addresses of the sender | |
23446 | domain's mail servers are on the Spamhaus black list. | |
23447 | .nem | |
23448 | ||
23449 | ||
495ae4b0 PH |
23450 | |
23451 | .section Data returned by DNS lists | |
4964e932 | 23452 | .index DNS list||data returned from |
495ae4b0 PH |
23453 | DNS lists are constructed using address records in the DNS. The original RBL |
23454 | just used the address 127.0.0.1 on the right hand side of each record, but the | |
23455 | RBL+ list and some other lists use a number of values with different meanings. | |
23456 | The values used on the RBL+ list are: | |
23457 | .display rm | |
23458 | .tabs 12 | |
23459 | 127.1.0.1 $t RBL | |
23460 | 127.1.0.2 $t DUL | |
23461 | 127.1.0.3 $t DUL and RBL | |
23462 | 127.1.0.4 $t RSS | |
23463 | 127.1.0.5 $t RSS and RBL | |
23464 | 127.1.0.6 $t RSS and DUL | |
23465 | 127.1.0.7 $t RSS and DUL and RBL | |
23466 | .endd | |
23467 | Some DNS lists may return more than one address record. | |
23468 | ||
23469 | .section Variables set from DNS lists | |
4964e932 | 23470 | .index DNS list||variables set from |
495ae4b0 PH |
23471 | When an entry is found in a DNS list, the variable \$dnslist@_domain$\ |
23472 | contains the name of the domain that matched, \$dnslist@_value$\ contains the | |
23473 | data from the entry, and \$dnslist@_text$\ contains the contents of any | |
23474 | associated TXT record. If more than one address record is returned by the DNS | |
23475 | lookup, all the IP addresses are included in \$dnslist@_value$\, separated by | |
23476 | commas and spaces. | |
23477 | ||
23478 | You can use these variables in \message\ or \log@_message\ modifiers -- | |
23479 | although these appear before the condition in the ACL, they are not expanded | |
23480 | until after it has failed. For example: | |
23481 | .display asis | |
23482 | deny hosts = !+local_networks | |
23483 | message = $sender_host_address is listed \ | |
23484 | at $dnslist_domain | |
23485 | dnslists = rbl-plus.mail-abuse.example | |
23486 | .endd | |
23487 | ||
23488 | ||
23489 | .section Additional matching conditions for DNS lists | |
4964e932 PH |
23490 | .rset SECTaddmatcon "~~chapter.~~section" |
23491 | .index DNS list||matching specific returned data | |
23492 | You can add an equals sign and an IP address after a \dnslists\ domain name in | |
23493 | order to restrict its action to DNS records with a matching right hand side. | |
23494 | For example, | |
495ae4b0 PH |
23495 | .display asis |
23496 | deny dnslists = rblplus.mail-abuse.org=127.0.0.2 | |
23497 | .endd | |
23498 | rejects only those hosts that yield 127.0.0.2. Without this additional data, | |
23499 | any address record is considered to be a match. If more than one address record | |
23500 | is found on the list, they are all checked for a matching right-hand side. | |
23501 | ||
495ae4b0 PH |
23502 | More than one IP address may be given for checking, using a comma as a |
23503 | separator. These are alternatives -- if any one of them matches, the \dnslists\ | |
23504 | condition is true. For example: | |
23505 | .display asis | |
23506 | deny dnslists = a.b.c=127.0.0.2,127.0.0.3 | |
23507 | .endd | |
23508 | ||
4964e932 PH |
23509 | If you want to specify a constraining address list and also specify names or IP |
23510 | addresses to be looked up, the constraining address list must be specified | |
23511 | first. For example: | |
23512 | .display asis | |
23513 | deny dnslists = dsn.rfc-ignorant.org\ | |
23514 | =127.0.0.2/$sender_address_domain | |
23515 | .endd | |
23516 | ||
495ae4b0 PH |
23517 | If the character `&' is used instead of `=', the comparison for each listed |
23518 | IP address is done by a bitwise `and' instead of by an equality test. In | |
23519 | other words, the listed addresses are used as bit masks. The comparison is | |
23520 | true if all the bits in the mask are present in the address that is being | |
23521 | tested. For example: | |
23522 | .display asis | |
23523 | dnslists = a.b.c&0.0.0.3 | |
23524 | .endd | |
23525 | matches if the address is \*x.x.x.*\3, \*x.x.x.*\7, \*x.x.x.*\11, etc. If you | |
23526 | want to test whether one bit or another bit is present (as opposed to both | |
23527 | being present), you must use multiple values. For example: | |
23528 | .display asis | |
23529 | dnslists = a.b.c&0.0.0.1,0.0.0.2 | |
23530 | .endd | |
23531 | matches if the final component of the address is an odd number or two times | |
23532 | an odd number. | |
23533 | ||
23534 | ||
23535 | .section Negated DNS matching conditions | |
23536 | You can supply a negative list of IP addresses as part of a \dnslists\ | |
23537 | condition. Whereas | |
23538 | .display asis | |
23539 | deny dnslists = a.b.c=127.0.0.2,127.0.0.3 | |
23540 | .endd | |
23541 | means `deny if the host is in the black list at the domain \*a.b.c*\ and the IP | |
23542 | address yielded by the list is either 127.0.0.2 or 127.0.0.3', | |
23543 | .display asis | |
23544 | deny dnslists = a.b.c!=127.0.0.2,127.0.0.3 | |
23545 | .endd | |
23546 | means `deny if the host is in the black list at the domain \*a.b.c*\ and the IP | |
23547 | address yielded by the list is not 127.0.0.2 and not 127.0.0.3'. In other | |
23548 | words, the result of the test is inverted if an exclamation mark appears before | |
23549 | the `=' (or the `&') sign. | |
23550 | ||
23551 | \**Note**\: this kind of negation is not the same as negation in a domain, | |
23552 | host, or address list (which is why the syntax is different). | |
23553 | ||
23554 | If you are using just one list, the negation syntax does not gain you much. The | |
23555 | previous example is precisely equivalent to | |
23556 | .display asis | |
23557 | deny dnslists = a.b.c | |
23558 | !dnslists = a.b.c=127.0.0.2,127.0.0.3 | |
23559 | .endd | |
23560 | However, if you are using multiple lists, the negation syntax is clearer. | |
23561 | Consider this example: | |
23562 | .display asis | |
23563 | deny dnslists = sbl.spamhaus.org : \ | |
23564 | list.dsbl.org : \ | |
23565 | dnsbl.njabl.org!=127.0.0.3 : \ | |
23566 | relays.ordb.org | |
23567 | .endd | |
23568 | Using only positive lists, this would have to be: | |
23569 | .display asis | |
23570 | deny dnslists = sbl.spamhaus.org : \ | |
23571 | list.dsbl.org | |
23572 | deny dnslists = dnsbl.njabl.org | |
23573 | !dnslists = dnsbl.njabl.org=127.0.0.3 | |
23574 | deny dnslists = relays.ordb.org | |
23575 | .endd | |
23576 | which is less clear, and harder to maintain. | |
23577 | ||
23578 | ||
23579 | ||
23580 | .section DNS lists and IPv6 | |
23581 | .rset SECTmorednslistslast "~~chapter.~~section" | |
4964e932 PH |
23582 | .index IPv6||DNS black lists |
23583 | .index DNS list||IPv6 usage | |
23584 | If Exim is asked to do a dnslist lookup for an IPv6 address, it inverts it | |
495ae4b0 PH |
23585 | nibble by nibble. For example, if the calling host's IP address is |
23586 | 3ffe:ffff:836f:0a00:000a:0800:200a:c031, Exim might look up | |
23587 | .display asis | |
23588 | 1.3.0.c.a.0.0.2.0.0.8.0.a.0.0.0.0.0.a.0.f.6.3.8. | |
23589 | f.f.f.f.e.f.f.3.blackholes.mail-abuse.org | |
23590 | .endd | |
23591 | (split over two lines here to fit on the page). Unfortunately, some of the DNS | |
23592 | lists contain wildcard records, intended for IPv4, that interact badly with | |
23593 | IPv6. For example, the DNS entry | |
23594 | .display asis | |
23595 | *.3.some.list.example. A 127.0.0.1 | |
23596 | .endd | |
4964e932 PH |
23597 | is probably intended to put the entire 3.0.0.0/8 IPv4 network on the list. |
23598 | Unfortunately, it also matches the entire 3@:@:/4 IPv6 network. | |
495ae4b0 | 23599 | |
4964e932 | 23600 | You can exclude IPv6 addresses from DNS lookups by making use of a suitable |
495ae4b0 PH |
23601 | \condition\ condition, as in this example: |
23602 | .display asis | |
4964e932 PH |
23603 | .newline |
23604 | .em | |
23605 | deny condition = ${if isip4{$sender_host_address}} | |
23606 | .nem | |
23607 | .newline | |
23608 | dnslists = some.list.example | |
495ae4b0 PH |
23609 | .endd |
23610 | ||
23611 | ||
23612 | .section Address verification | |
23613 | .rset SECTaddressverification "~~chapter.~~section" | |
23614 | .index verifying||address, options for | |
23615 | .index policy control||address verification | |
23616 | Several of the \verify\ conditions described in section ~~SECTaclconditions | |
23617 | cause addresses to be verified. These conditions can be followed by options | |
23618 | that modify the verification process. The options are separated from the | |
23619 | keyword and from each other by slashes, and some of them contain parameters. | |
23620 | For example: | |
23621 | .display asis | |
23622 | verify = sender/callout | |
23623 | verify = recipient/defer_ok/callout=10s,defer_ok | |
23624 | .endd | |
4964e932 PH |
23625 | .em |
23626 | The first stage of address verification, which always happens, is to run the | |
23627 | address through the routers, in `verify mode'. Routers can detect the | |
23628 | difference between verification and routing for delivery, and their actions can | |
23629 | be varied by a number of generic options such as \verify\ and \verify@_only\ | |
23630 | (see chapter ~~CHAProutergeneric). If routing fails, verification fails. | |
23631 | The available options are as follows: | |
23632 | .numberpars $. | |
23633 | If the \callout\ option is specified, successful routing to one or more remote | |
23634 | hosts is followed by a `callout' to those hosts as an additional check. | |
23635 | Callouts and their sub-options are discussed in the next section. | |
23636 | .nextp | |
23637 | If there is a defer error while doing verification routing, the ACL | |
495ae4b0 | 23638 | normally returns `defer'. However, if you include \defer@_ok\ in the options, |
4964e932 PH |
23639 | the condition is forced to be true instead. Note that this is a main |
23640 | verification option as well as a suboption for callouts. | |
23641 | .nextp | |
23642 | The \no@_details\ option is covered in section ~~SECTsenaddver, which discusses | |
23643 | the reporting of sender address verification failures. | |
23644 | .endp | |
23645 | ||
23646 | .index verifying||address, differentiating failures | |
23647 | After an address verification failure, \$sender@_verify@_failure$\ or | |
23648 | \$recipient@_verify@_failure$\ (as appropriate) contains one of the following | |
23649 | words: | |
23650 | .numberpars $. | |
23651 | \qualify\: The address was unqualified (no domain), and the message | |
23652 | was neither local nor came from an exempted host. | |
23653 | .nextp | |
23654 | \route\: Routing failed. | |
23655 | .nextp | |
23656 | \mail\: Routing succeeded, and a callout was attempted; rejection | |
23657 | occurred at or before the \\MAIL\\ command (that is, on initial | |
23658 | connection, \\HELO\\, or \\MAIL\\). | |
23659 | .nextp | |
23660 | \recipient\: The \\RCPT\\ command in a callout was rejected. | |
23661 | .nextp | |
23662 | \postmaster\: The postmaster check in a callout was rejected. | |
23663 | .endp | |
23664 | ||
23665 | The main use of these variables is expected to be to distinguish between | |
23666 | rejections of \\MAIL\\ and rejections of \\RCPT\\ in callouts. | |
23667 | ||
23668 | .nem | |
23669 | ||
495ae4b0 PH |
23670 | |
23671 | .section Callout verification | |
23672 | .rset SECTcallver "~~chapter.~~section" | |
23673 | .index verifying||address, by callout | |
23674 | .index callout||verification | |
23675 | .index SMTP||callout verification | |
23676 | For non-local addresses, routing verifies the domain, but is unable to do any | |
23677 | checking of the local part. There are situations where some means of verifying | |
23678 | the local part is desirable. One way this can be done is to make an SMTP | |
23679 | \*callback*\ to the sending host (for a sender address) or a \*callforward*\ to | |
23680 | a subsequent host (for a recipient address), to see if the host accepts the | |
23681 | address. We use the term \*callout*\ to cover both cases. This facility should | |
23682 | be used with care, because it can add a lot of resource usage to the cost of | |
23683 | verifying an address. However, Exim does cache the results of callouts, which | |
23684 | helps to reduce the cost. Details of caching are in the next section. | |
23685 | ||
4964e932 PH |
23686 | Recipient callouts are usually used only between hosts that are controlled by |
23687 | the same administration. For example, a corporate gateway host could use | |
495ae4b0 | 23688 | callouts to check for valid recipients on an internal mailserver. |
4964e932 PH |
23689 | A successful callout does not guarantee that a real delivery to the address |
23690 | would succeed; on the other hand, a failing callout does guarantee that | |
495ae4b0 PH |
23691 | a delivery would fail. |
23692 | ||
23693 | If the \callout\ option is present on a condition that verifies an address, a | |
23694 | second stage of verification occurs if the address is successfully routed to | |
23695 | one or more remote hosts. The usual case is routing by a \%dnslookup%\ or a | |
4964e932 PH |
23696 | \%manualroute%\ router, where the router specifies the hosts. However, if a |
23697 | router that does not set up hosts routes to an \%smtp%\ transport with a | |
495ae4b0 PH |
23698 | \hosts\ setting, the transport's hosts are used. If an \%smtp%\ transport has |
23699 | \hosts@_override\ set, its hosts are always used, whether or not the router | |
23700 | supplies a host list. | |
23701 | ||
23702 | The port that is used is taken from the transport, if it is specified and is a | |
23703 | remote transport. (For routers that do verification only, no transport need be | |
4964e932 PH |
23704 | specified.) Otherwise, the default SMTP port is used. If a remote transport |
23705 | specifies an outgoing interface, this is used; otherwise the interface is not | |
495ae4b0 PH |
23706 | specified. |
23707 | ||
23708 | For a sender callout check, Exim makes SMTP connections to the remote hosts, to | |
23709 | test whether a bounce message could be delivered to the sender address. The | |
23710 | following SMTP commands are sent: | |
23711 | .display | |
4964e932 PH |
23712 | .newline |
23713 | .em | |
23714 | HELO <<smtp active host name>> | |
23715 | .nem | |
23716 | .newline | |
495ae4b0 PH |
23717 | MAIL FROM:@<@> |
23718 | RCPT TO:<<the address to be tested>> | |
23719 | QUIT | |
23720 | .endd | |
23721 | \\LHLO\\ is used instead of \\HELO\\ if the transport's \protocol\ option is | |
4964e932 | 23722 | set to `lmtp'. |
495ae4b0 | 23723 | |
4964e932 PH |
23724 | A recipient callout check is similar. By default, it also uses an empty address |
23725 | for the sender. This default is chosen because most hosts do not make use of | |
23726 | the sender address when verifying a recipient. Using the same address means | |
23727 | that a single cache entry can be used for each recipient. Some sites, however, | |
23728 | do make use of the sender address when verifying. These are catered for by the | |
23729 | \use@_sender\ and \use@_postmaster\ options, described in the next section. | |
495ae4b0 PH |
23730 | |
23731 | If the response to the \\RCPT\\ command is a 2$it{xx} code, the verification | |
23732 | succeeds. If it is 5$it{xx}, the verification fails. For any other condition, | |
23733 | Exim tries the next host, if any. If there is a problem with all the remote | |
23734 | hosts, the ACL yields `defer', unless the \defer@_ok\ parameter of the | |
23735 | \callout\ option is given, in which case the condition is forced to succeed. | |
23736 | ||
23737 | ||
4964e932 PH |
23738 | |
23739 | ||
495ae4b0 PH |
23740 | .section Additional parameters for callouts |
23741 | .rset CALLaddparcall "~~chapter.~~section" | |
4964e932 | 23742 | .index callout||additional parameters for |
495ae4b0 PH |
23743 | The \callout\ option can be followed by an equals sign and a number of optional |
23744 | parameters, separated by commas. For example: | |
23745 | .display asis | |
23746 | verify = recipient/callout=10s,defer_ok | |
23747 | .endd | |
23748 | The old syntax, which had \callout@_defer@_ok\ and \check@_postmaster\ as | |
23749 | separate verify options, is retained for backwards compatibility, but is now | |
23750 | deprecated. The additional parameters for \callout\ are as follows: | |
23751 | ||
4964e932 PH |
23752 | .startitems |
23753 | ||
23754 | .item "<<a time interval>>" | |
23755 | .index callout||timeout, specifying | |
23756 | This specifies the timeout that applies for the callout attempt to each host. | |
23757 | For example: | |
495ae4b0 PH |
23758 | .display asis |
23759 | verify = sender/callout=5s | |
23760 | .endd | |
23761 | The default is 30 seconds. The timeout is used for each response from the | |
23762 | remote host. | |
4964e932 PH |
23763 | .em |
23764 | It is also used for the intial connection, unless overridden by the \connect\ | |
23765 | parameter. | |
23766 | .nem | |
23767 | ||
23768 | .em | |
23769 | .item "connect = <<time interval>>" | |
23770 | .index callout||connection timeout, specifying | |
23771 | This parameter makes it possible to set a different (usually | |
23772 | smaller) timeout for making the SMTP connection. | |
23773 | For example: | |
23774 | .display asis | |
23775 | verify = sender/callout=5s,connect=1s | |
23776 | .endd | |
23777 | If not specified, this timeout defaults to the general timeout value. | |
23778 | .nem | |
23779 | ||
23780 | .item "defer@_ok" | |
495ae4b0 | 23781 | .index callout||defer, action on |
4964e932 PH |
23782 | When this parameter is present, failure to contact any host, or any other kind |
23783 | of temporary error, is treated as success by the ACL. However, the cache is not | |
23784 | updated in this circumstance. | |
23785 | ||
23786 | .em | |
23787 | .item "mailfrom = <<email address>>" | |
23788 | .index callout||sender when verifying header | |
23789 | When verifying addresses in header lines using the \header@_sender\ | |
23790 | verification option, Exim behaves by default as if the addresses are envelope | |
23791 | sender addresses from a message. Callout verification therefore tests to see | |
23792 | whether a bounce message could be delivered, by using an empty address in the | |
23793 | \\MAIL\\ command. However, it is arguable that these addresses might never be | |
23794 | used as envelope senders, and could therefore justifiably reject bounce | |
23795 | messages (empty senders). The \mailfrom\ callout parameter allows you to | |
23796 | specify what address to use in the \\MAIL\\ command. For example: | |
23797 | .display asis | |
23798 | require verify = header_sender/callout=mailfrom=abcd@x.y.z | |
23799 | .endd | |
23800 | This parameter is available only for the \header@_sender\ verification option. | |
23801 | .nem | |
23802 | ||
23803 | .em | |
23804 | .item "maxwait = <<time interval>>" | |
23805 | .index callout||overall timeout, specifying | |
23806 | This parameter sets an overall timeout for performing a callout verification. | |
23807 | For example: | |
23808 | .display asis | |
23809 | verify = sender/callout=5s,maxwait=30s | |
23810 | .endd | |
23811 | This timeout defaults to four times the callout timeout for individual SMTP | |
23812 | commands. The overall timeout applies when there is more than one host that can | |
23813 | be tried. The timeout is checked before trying the next host. This prevents | |
23814 | very long delays if there are a large number of hosts and all are timing out | |
23815 | (for example, when network connections are timing out). | |
23816 | .nem | |
23817 | ||
23818 | .item "no@_cache" | |
495ae4b0 PH |
23819 | .index callout||cache, suppressing |
23820 | .index caching||callout, suppressing | |
4964e932 PH |
23821 | When this parameter is given, the callout cache is neither read nor updated. |
23822 | ||
23823 | .item "postmaster" | |
495ae4b0 | 23824 | .index callout||postmaster, checking |
4964e932 PH |
23825 | When this parameter is set, a sucessful callout check is followed by a similar |
23826 | check for the local part \*postmaster*\ at the same domain. If this address is | |
23827 | rejected, the callout fails. The result of the postmaster check is recorded in | |
23828 | a cache record; if it is a failure, this is used to fail subsequent callouts | |
23829 | for the domain without a connection being made, until the cache record expires. | |
23830 | ||
23831 | .em | |
23832 | .item "postmaster@_mailfrom = <<email address>>" | |
23833 | The postmaster check uses an empty sender in the \\MAIL\\ command by default. | |
23834 | You can use this parameter to do a postmaster check using a different address. | |
23835 | For example: | |
23836 | .display asis | |
23837 | require verify = sender/callout=postmaster_mailfrom=abc@x.y.z | |
23838 | .endd | |
23839 | If both \postmaster\ and \postmaster@_mailfrom\ are present, the rightmost one | |
23840 | overrides. The \postmaster\ parameter is equivalent to this example: | |
23841 | .display asis | |
23842 | require verify = sender/callout=postmaster_mailfrom= | |
23843 | .endd | |
23844 | \**Warning**\: The caching arrangements for postmaster checking do not take | |
23845 | account of the sender address. It is assumed that either the empty address or | |
23846 | a fixed non-empty address will be used. All that Exim remembers is that the | |
23847 | postmaster check for the domain succeeded or failed. | |
23848 | .nem | |
23849 | ||
23850 | .item "random" | |
495ae4b0 | 23851 | .index callout||`random' check |
4964e932 | 23852 | When this parameter is set, before doing the normal callout check, Exim does a |
495ae4b0 PH |
23853 | check for a `random' local part at the same domain. The local part is not |
23854 | really random -- it is defined by the expansion of the option | |
23855 | \callout@_random@_local@_part\, which defaults to | |
23856 | .display asis | |
23857 | $primary_host_name-$tod_epoch-testing | |
23858 | .endd | |
23859 | The idea here is to try to determine whether the remote host accepts all local | |
23860 | parts without checking. If it does, there is no point in doing callouts for | |
23861 | specific local parts. If the `random' check succeeds, the result is saved in | |
23862 | a cache record, and used to force the current and subsequent callout checks to | |
23863 | succeed without a connection being made, until the cache record expires. | |
4964e932 PH |
23864 | |
23865 | .item "use@_postmaster" | |
495ae4b0 | 23866 | .index callout||sender for recipient check |
4964e932 | 23867 | This parameter applies to recipient callouts only. For example: |
495ae4b0 PH |
23868 | .display asis |
23869 | deny !verify = recipient/callout=use_postmaster | |
23870 | .endd | |
23871 | It causes a non-empty postmaster address to be used in the \\MAIL\\ command | |
23872 | when performing the callout. The local part of the address is \"postmaster"\ | |
23873 | and the domain is the contents of \$qualify@_domain$\. | |
4964e932 PH |
23874 | |
23875 | .item "use@_sender" | |
23876 | This option applies to recipient callouts only. For example: | |
495ae4b0 PH |
23877 | .display asis |
23878 | require verify = recipient/callout=use_sender | |
23879 | .endd | |
23880 | It causes the message's actual sender address to be used in the \\MAIL\\ | |
4964e932 PH |
23881 | command when performing the callout, instead of an empty address. There is no |
23882 | need to use this option unless you know that the called hosts make use of the | |
23883 | sender when checking recipients. If used indiscriminately, it reduces the | |
23884 | usefulness of callout caching. | |
23885 | ||
23886 | .enditems | |
23887 | ||
23888 | .em | |
23889 | If you use any of the parameters that set a non-empty sender for the \\MAIL\\ | |
23890 | command (\mailfrom\, \postmaster@_mailfrom\, \use@_postmaster\, or | |
23891 | \use@_sender\), you should think about possible loops. Recipient checking is | |
23892 | usually done between two hosts that are under the same management, and the host | |
23893 | that receives the callouts is not normally configured to do callouts itself. | |
23894 | Therefore, it is normally safe to use \use@_postmaster\ or \use@_sender\ in | |
23895 | these circumstances. | |
23896 | ||
23897 | However, if you use a non-empty sender address for a callout to an arbitrary | |
23898 | host, there is the likelihood that the remote host will itself initiate a | |
23899 | callout check back to your host. As it is checking what appears to be a message | |
23900 | sender, it is likely to use an empty address in \\MAIL\\, thus avoiding a | |
23901 | callout loop. However, to be on the safe side it would be best to set up your | |
23902 | own ACLs so that they do not do sender verification checks when the recipient | |
23903 | is the address you use for header sender or postmaster callout checking. | |
23904 | ||
23905 | Another issue to think about when using non-empty senders for callouts is | |
23906 | caching. When you set \mailfrom\ or \use@_sender\, the cache record is keyed by | |
23907 | the sender/recipient combination; thus, for any given recipient, many more | |
23908 | actual callouts are performed than when an empty sender or postmaster is used. | |
23909 | ||
495ae4b0 | 23910 | .nem |
495ae4b0 PH |
23911 | |
23912 | ||
23913 | .section Callout caching | |
23914 | .rset SECTcallvercache "~~chapter.~~section" | |
23915 | .index hints database||callout cache | |
23916 | .index callout||caching | |
23917 | .index caching||callout | |
4964e932 | 23918 | Exim caches the results of callouts in order to reduce the amount of resources |
495ae4b0 | 23919 | used, unless you specify the \no@_cache\ parameter with the \callout\ option. |
4964e932 PH |
23920 | A hints database called `callout' is used for the cache. Two different record |
23921 | types are used: one records the result of a callout check for a specific | |
495ae4b0 PH |
23922 | address, and the other records information that applies to the entire domain |
23923 | (for example, that it accepts the local part \*postmaster*\). | |
23924 | ||
23925 | When an original callout fails, a detailed SMTP error message is given about | |
23926 | the failure. However, for subsequent failures use the cache data, this message | |
23927 | is not available. | |
23928 | ||
23929 | The expiry times for negative and positive address cache records are | |
23930 | independent, and can be set by the global options \callout@_negative@_expire\ | |
23931 | (default 2h) and \callout@_positive@_expire\ (default 24h), respectively. | |
23932 | ||
23933 | If a host gives a negative response to an SMTP connection, or rejects any | |
4964e932 | 23934 | commands up to and including |
495ae4b0 PH |
23935 | .display asis |
23936 | MAIL FROM:<> | |
23937 | .endd | |
495ae4b0 | 23938 | (but not including the \\MAIL\\ command with a non-empty address), |
495ae4b0 PH |
23939 | any callout attempt is bound to fail. Exim remembers such failures in a |
23940 | domain cache record, which it uses to fail callouts for the domain without | |
23941 | making new connections, until the domain record times out. There are two | |
23942 | separate expiry times for domain cache records: | |
23943 | \callout@_domain@_negative@_expire\ (default 3h) and | |
23944 | \callout__domain__positive@_expire\ (default 7d). | |
23945 | ||
23946 | Domain records expire when the negative expiry time is reached if callouts | |
23947 | cannot be made for the domain, or if the postmaster check failed. | |
23948 | Otherwise, they expire when the positive expiry time is reached. This | |
23949 | ensures that, for example, a host that stops accepting `random' local parts | |
23950 | will eventually be noticed. | |
23951 | ||
4964e932 PH |
23952 | The callout caching mechanism is based on the domain of the address that is |
23953 | being tested. If the domain routes to several hosts, it is assumed that their | |
23954 | behaviour will be the same. | |
495ae4b0 PH |
23955 | |
23956 | ||
23957 | .section Sender address verification reporting | |
4964e932 | 23958 | .rset SECTsenaddver "~~chapter.~~section" |
495ae4b0 PH |
23959 | .index verifying||suppressing error details |
23960 | When sender verification fails in an ACL, the details of the failure are | |
23961 | given as additional output lines before the 550 response to the relevant | |
23962 | SMTP command (\\RCPT\\ or \\DATA\\). For example, if sender callout is in use, | |
23963 | you might see: | |
23964 | .display asis | |
23965 | MAIL FROM:<xyz@abc.example> | |
23966 | 250 OK | |
23967 | RCPT TO:<pqr@def.example> | |
23968 | 550-Verification failed for <xyz@abc.example> | |
23969 | 550-Called: 192.168.34.43 | |
23970 | 550-Sent: RCPT TO:<xyz@abc.example> | |
23971 | 550-Response: 550 Unknown local part xyz in <xyz@abc.example> | |
23972 | 550 Sender verification failed | |
23973 | .endd | |
23974 | If more than one \\RCPT\\ command fails in the same way, the details are given | |
23975 | only for the first of them. However, some administrators do not want to send | |
23976 | out this much information. You can suppress the details by adding | |
23977 | `/no@_details' to the ACL statement that requests sender verification. For | |
23978 | example: | |
23979 | .display asis | |
23980 | verify = sender/no_details | |
23981 | .endd | |
23982 | ||
23983 | ||
23984 | .section Redirection while verifying | |
23985 | .index verifying||redirection while | |
23986 | .index address redirection||while verifying | |
23987 | A dilemma arises when a local address is redirected by aliasing or forwarding | |
23988 | during verification: should the generated addresses themselves be verified, | |
23989 | or should the successful expansion of the original address be enough to verify | |
23990 | it? Exim takes the following pragmatic approach: | |
23991 | .numberpars $. | |
23992 | When an incoming address is redirected to just one child address, verification | |
23993 | continues with the child address, and if that fails to verify, the original | |
23994 | verification also fails. | |
23995 | .nextp | |
23996 | When an incoming address is redirected to more than one child address, | |
23997 | verification does not continue. A success result is returned. | |
23998 | .endp | |
23999 | This seems the most reasonable behaviour for the common use of aliasing as a | |
24000 | way of redirecting different local parts to the same mailbox. It means, for | |
24001 | example, that a pair of alias entries of the form | |
24002 | .display asis | |
24003 | A.Wol: aw123 | |
24004 | aw123: :fail: Gone away, no forwarding address | |
24005 | .endd | |
4964e932 PH |
24006 | work as expected, with both local parts causing verification failure. When a |
24007 | redirection generates more than one address, the behaviour is more like a | |
24008 | mailing list, where the existence of the alias itself is sufficient for | |
24009 | verification to succeed. | |
24010 | ||
24011 | ||
24012 | .section Using an ACL to control relaying | |
24013 | .rset SECTrelaycontrol "~~chapter.~~section" | |
24014 | .index ~~ACL||relay control | |
24015 | .index relaying||control by ACL | |
24016 | .index policy control||relay control | |
24017 | An MTA is said to \*relay*\ a message if it receives it from some host and | |
24018 | delivers it directly to another host as a result of a remote address contained | |
24019 | within it. Redirecting a local address via an alias or forward file and then | |
24020 | passing the message on to another host is not relaying, | |
24021 | .index `percent hack' | |
24022 | but a redirection as a result of the `percent hack' is. | |
24023 | ||
24024 | Two kinds of relaying exist, which are termed `incoming' and `outgoing'. A host | |
24025 | which is acting as a gateway or an MX backup is concerned with incoming | |
24026 | relaying from arbitrary hosts to a specific set of domains. On the other hand, | |
24027 | a host which is acting as a smart host for a number of clients is concerned | |
24028 | with outgoing relaying from those clients to the Internet at large. Often the | |
24029 | same host is fulfilling both functions, as illustrated in the diagram below, | |
24030 | but in principle these two kinds of relaying are entirely independent. What is | |
24031 | not wanted is the transmission of mail from arbitrary remote hosts through your | |
24032 | system to arbitrary domains. | |
24033 | .if ~~sys.fancy | |
24034 | .figure "Controlled relaying" rm | |
24035 | .indent 0 | |
24036 | .call aspic -sgcal -nv | |
24037 | centre ~~sys.linelength; | |
24038 | magnify 0.8; | |
24039 | boundingbox 30; | |
24040 | textdepth 16; | |
24041 | boxwidth 120; | |
24042 | boxdepth 44; | |
24043 | A: box "Arbitrary" "remote hosts"; | |
24044 | C: ibox; | |
24045 | D: box "Arbitrary" "domains"; | |
24046 | iline down 50 from bottom of C; | |
24047 | H: box width 180 "Local host"; | |
24048 | iline down 50; | |
24049 | E: ibox; | |
24050 | SH: box "Specific" "hosts"; | |
24051 | SD: box join right to E "Specific" "domains"; | |
24052 | arcarrow clockwise from top of SH to bottom of D plus (-10,-4) | |
24053 | via right of H plus (-20,0); | |
24054 | arcarrow clockwise from bottom of A to top of SD plus (10,4) | |
24055 | via left of H plus (20,0); | |
24056 | ||
24057 | ibox join left to right of H "$it{Outgoing}"; | |
24058 | goto H; | |
24059 | ibox join right to left of H "$it{Incoming}"; | |
24060 | ||
24061 | L: line dashed from right of A to top of H plus (-15,0); | |
24062 | arc dashed to top of H plus (15,0); | |
24063 | arrow dashed to left of D plus (-2,0); | |
24064 | ||
24065 | arrow dashed back up 72 right 32 from middle of L plus (8,0); | |
24066 | text at end plus (0, 4) "$it{Not wanted}"; | |
24067 | .endcall | |
24068 | .endfigure | |
24069 | .elif !~~html | |
24070 | .display asis | |
24071 | -------------- ----------- | |
24072 | | Arbitrary | |Arbitrary| | |
24073 | |remote hosts| | domains | | |
24074 | -------------- ----------- | |
24075 | I v ^ O | |
24076 | n v ^ u | |
24077 | c ---v----------------^--- t | |
24078 | o | v Local ^ | g | |
24079 | m | v host ^ | o | |
24080 | i ---v----------------^--- i | |
24081 | n v ^ n | |
24082 | g v ^ g | |
24083 | Specific Specific | |
24084 | domains hosts | |
24085 | .endd | |
24086 | .else | |
24087 | [(IMG SRC="relaying.gif" alt="Controlled relaying")][(br)] | |
24088 | .fi | |
24089 | ||
24090 | You can implement relay control by means of suitable statements in the ACL that | |
24091 | runs for each \\RCPT\\ command. For convenience, it is often easiest to use | |
24092 | Exim's named list facility to define the domains and hosts involved. For | |
24093 | example, suppose you want to do the following: | |
24094 | .numberpars $. | |
24095 | Deliver a number of domains to mailboxes on the local host (or process them | |
24096 | locally in some other way). Let's say these are \*my.dom1.example*\ and | |
24097 | \*my.dom2.example*\. | |
24098 | .nextp | |
24099 | Relay mail for a number of other domains for which you are the secondary MX. | |
24100 | These might be \*friend1.example*\ and \*friend2.example*\. | |
24101 | .nextp | |
24102 | Relay mail from the hosts on your local LAN, to whatever domains are involved. | |
24103 | Suppose your LAN is 192.168.45.0/24. | |
24104 | .endp | |
24105 | In the main part of the configuration, you put the following definitions: | |
24106 | .display asis | |
24107 | domainlist local_domains = my.dom1.example : my.dom2.example | |
24108 | domainlist relay_domains = friend1.example : friend2.example | |
24109 | hostlist relay_hosts = 192.168.45.0/24 | |
24110 | .endd | |
24111 | Now you can use these definitions in the ACL that is run for every \\RCPT\\ | |
24112 | command: | |
24113 | .display asis | |
24114 | acl_check_rcpt: | |
24115 | accept domains = +local_domains : +relay_domains | |
24116 | accept hosts = +relay_hosts | |
24117 | .endd | |
24118 | The first statement accepts any \\RCPT\\ command that contains an address in | |
24119 | the local or relay domains. For any other domain, control passes to the second | |
24120 | statement, which accepts the command only if it comes from one of the relay | |
24121 | hosts. In practice, you will probably want to make your ACL more sophisticated | |
24122 | than this, for example, by including sender and recipient verification. The | |
24123 | default configuration includes a more comprehensive example, which is described | |
24124 | in chapter ~~CHAPdefconfil. | |
24125 | ||
24126 | ||
24127 | .section Checking a relay configuration | |
24128 | .rset SECTcheralcon "~~chapter.~~section" | |
24129 | .index relaying||checking control of | |
24130 | You can check the relay characteristics of your configuration in the same way | |
24131 | that you can test any ACL behaviour for an incoming SMTP connection, by using | |
24132 | the \-bh-\ option to run a fake SMTP session with which you interact. | |
24133 | ||
24134 | For specifically testing for unwanted relaying, the host | |
24135 | \*relay-test.mail-abuse.org*\ provides a useful service. If you telnet to this | |
24136 | host from the host on which Exim is running, using the normal telnet port, you | |
24137 | will see a normal telnet connection message and then quite a long delay. Be | |
24138 | patient. The remote host is making an SMTP connection back to your host, and | |
24139 | trying a number of common probes to test for open relay vulnerability. The | |
24140 | results of the tests will eventually appear on your terminal. | |
24141 | ||
24142 | ||
24143 | ||
24144 | ||
24145 | . | |
24146 | . | |
24147 | . | |
24148 | . | |
24149 | . ============================================================================ | |
d43194df | 24150 | .chapter Content scanning |
4964e932 PH |
24151 | .set runningfoot "content scanning" |
24152 | .rset CHAPexiscan "~~chapter" | |
24153 | .index content scanning | |
24154 | .em | |
d43194df PH |
24155 | The content-scanning extension of Exim, formerly known as `exiscan', was |
24156 | originally implemented as a patch by Tom Kistner. The code was integrated into | |
24157 | the main source for Exim release 4.50, and Tom continues to maintain it. Most | |
24158 | of the wording of this chapter is taken from Tom's specification. | |
4964e932 PH |
24159 | |
24160 | If you want to include the content-scanning features when you compile Exim, you | |
24161 | need to arrange for \\WITH@_CONTENT@_SCAN\\ to be defined in your | |
24162 | \(Local/Makefile)\. When you do that, the Exim binary is built with: | |
24163 | .numberpars $. | |
24164 | An additional ACL (\acl@_smtp@_mime\) that is run for all MIME parts. | |
24165 | .nextp | |
24166 | Additional ACL conditions and modifiers: \decode\, \malware\, \mime@_regex\, | |
24167 | \regex\, and \spam\. These can be used in the ACL that is run at the end of | |
24168 | message reception (the \acl@_smtp@_data\ ACL). | |
24169 | .nextp | |
d43194df PH |
24170 | An additional control feature (`no@_mbox@_unspool') that saves spooled copies |
24171 | of messages, or parts of messages, for debugging purposes. | |
24172 | .nextp | |
4964e932 PH |
24173 | Additional expansion variables that are set in the new ACL and by the new |
24174 | conditions. | |
24175 | .nextp | |
24176 | Two new main configuration options: \av@_scanner\ and \spamd@_address\. | |
24177 | .endp | |
24178 | There is another content-scanning configuration option for \(Local/Makefile)\, | |
24179 | called \\WITH@_OLD@_DEMIME\\. If this is set, the old, deprecated \demime\ ACL | |
24180 | condition is compiled, in addition to all the other content-scanning features. | |
24181 | ||
24182 | Content-scanning is continually evolving, and new features are still being | |
24183 | added. While such features are still unstable and liable to incompatible | |
24184 | changes, they are made available in Exim by setting options whose names begin | |
24185 | \\EXPERIMENTAL@_\\ in \(Local/Makefile)\. Such features are not documented in | |
24186 | this manual. You can find out about them by reading the file called | |
24187 | \(doc/experimental.txt)\. | |
24188 | ||
24189 | All the content-scanning facilites work on a MBOX copy of the message that is | |
24190 | temporarily created in a file called: | |
24191 | .display | |
24192 | <<spool@_directory>>/scan/<<message@_id>>/<<message@_id>>.eml | |
24193 | .endd | |
24194 | The \(.eml)\ extension is a friendly hint to virus scanners that they can | |
24195 | expect an MBOX-like structure inside that file. The file is created when the | |
9cc891cb TK |
24196 | first content scanning facility is called. Subsequent calls to content |
24197 | scanning conditions open the same file again. The directory is recursively | |
d43194df PH |
24198 | removed when the \acl@_smtp@_data\ ACL has finished running, unless |
24199 | .display asis | |
24200 | control = no_mbox_unspool | |
24201 | .endd | |
24202 | has been encountered. When the MIME ACL decodes files, they are put into the | |
24203 | same directory by default. | |
4964e932 PH |
24204 | |
24205 | ||
24206 | .section Scanning for viruses | |
24207 | .rset SECTscanvirus "~~chapter.~~section" | |
24208 | .index virus scanning | |
24209 | .index content scanning||for viruses | |
24210 | .index content scanning||the \malware\ condition | |
24211 | The \malware\ ACL condition lets you connect virus scanner software to Exim. It | |
24212 | supports a `generic' interface to scanners called via the shell, and | |
24213 | specialized interfaces for `daemon' type virus scanners, which are resident in | |
24214 | memory and thus are much faster. | |
24215 | ||
24216 | .index \av@_scanner\ | |
24217 | You can set the \av@_scanner\ option in first part of the Exim configuration | |
24218 | file to specify which scanner to use, together with any additional options that | |
24219 | are needed. The basic syntax is as follows: | |
24220 | .display | |
24221 | av@_scanner = <<scanner-type>>:<<option1>>:<<option2>>:[...] | |
24222 | .endd | |
24223 | If you do not set \av@_scanner\, it defaults to | |
24224 | .display asis | |
24225 | av_scanner = sophie:/var/run/sophie | |
24226 | .endd | |
24227 | If the value of \av@_scanner\ starts with dollar character, it is expanded | |
24228 | before use. | |
24229 | ||
24230 | The following scanner types are supported in this release: | |
24231 | .numberpars $. | |
24232 | .index virus scanners||Kaspersky | |
24233 | \aveserver\: This is the scanner daemon of Kaspersky Version 5. You can get a | |
24234 | trial version at \?http://www.kaspersky.com?\. This scanner type takes one | |
24235 | option, which is the path to the daemon's UNIX socket. The default is shown in | |
24236 | this example: | |
24237 | .display asis | |
24238 | av_scanner = aveserver:/var/run/aveserver | |
24239 | .endd | |
24240 | ||
24241 | .nextp | |
24242 | .index virus scanners||clamd | |
24243 | \clamd\: This daemon-type scanner is GPL and free. You can get it at | |
d43194df PH |
24244 | \?http://www.clamav.net/?\. Clamd does not seem to unpack MIME containers, so |
24245 | it is recommended to unpack MIME attachments in the MIME ACL. It takes one | |
24246 | option: either the path and name of a UNIX socket file, or a hostname or IP | |
24247 | number, and a port, separated by space, as in the second of these examples: | |
4964e932 PH |
24248 | .display asis |
24249 | av_scanner = clamd:/opt/clamd/socket | |
24250 | av_scanner = clamd:192.168.2.100 1234 | |
24251 | .endd | |
d43194df PH |
24252 | If the option is unset, the default is \(/tmp/clamd)\. Thanks to David Saez for |
24253 | contributing the code for this scanner. | |
4964e932 PH |
24254 | |
24255 | .nextp | |
24256 | .index virus scanners||command line interface | |
24257 | \cmdline\: This is the keyword for the generic command line scanner interface. | |
24258 | It can be used to attach virus scanners that are invoked from the shell. This | |
8e669ac1 | 24259 | scanner type takes 3 mandatory options: |
4964e932 PH |
24260 | .numberpars |
24261 | The full path and name of the scanner binary, with all command line options, | |
24262 | and a placeholder (%s) for the directory to scan. | |
24263 | .nextp | |
24264 | A regular expression to match against the STDOUT and STDERR output of the virus | |
24265 | scanner. If the expression matches, a virus was found. You must make absolutely | |
24266 | sure that this expression matches on `virus found'. This is called the | |
24267 | `trigger' expression. | |
24268 | .nextp | |
d43194df PH |
24269 | Another regular expression, containing exactly one pair of parentheses, to |
24270 | match the name of the virus found in the scanners output. This is called the | |
24271 | `name' expression. | |
4964e932 PH |
24272 | .endp |
24273 | For example, Sophos Sweep reports a virus on a line like this: | |
24274 | .display asis | |
24275 | Virus 'W32/Magistr-B' found in file ./those.bat | |
24276 | .endd | |
24277 | For the trigger expression, we can just match the word `found'. For the name | |
24278 | expression, we want to extract the W32/Magistr-B string, so we can match for | |
24279 | the single quotes left and right of it. Altogether, this makes the | |
24280 | configuration setting: | |
24281 | .display asis | |
24282 | av_scanner = cmdline:\ | |
24283 | /path/to/sweep -all -rec -archive %s:\ | |
24284 | found:'(.+)' | |
24285 | .endd | |
24286 | ||
24287 | .nextp | |
24288 | .index virus scanners||DrWeb | |
24289 | \drweb\: The DrWeb daemon scanner (\?http://www.sald.com/?\) interface | |
24290 | takes one argument, either a full path to a UNIX socket, or an IP address and | |
24291 | port separated by whitespace, as in these examples: | |
24292 | .display asis | |
24293 | av_scanner = drweb:/var/run/drwebd.sock | |
24294 | av_scanner = drweb:192.168.2.20 31337 | |
24295 | .endd | |
24296 | If you omit the argument, the default path \(/usr/local/drweb/run/drwebd.sock)\ | |
24297 | is used. Thanks to Alex Miller for contributing the code for this scanner. | |
24298 | ||
24299 | .nextp | |
24300 | .index virus scanners||F-Secure | |
24301 | \fsecure\: The F-Secure daemon scanner (\?http://www.f-secure.com?\) takes one | |
24302 | argument which is the path to a UNIX socket. For example: | |
24303 | .display asis | |
24304 | av_scanner = fsecure:/path/to/.fsav | |
24305 | .endd | |
24306 | If no argument is given, the default is \(/var/run/.fsav)\. Thanks to Johan | |
24307 | Thelmen for contributing the code for this scanner. | |
24308 | ||
24309 | .nextp | |
24310 | .index virus scanners||Kaspersky | |
24311 | \kavdaemon\: This is the scanner daemon of Kaspersky Version 4. This version of | |
24312 | the Kaspersky scanner is outdated. Please upgrade (see \aveserver\ above). This | |
24313 | scanner type takes one option, which is the path to the daemon's UNIX socket. | |
24314 | For example: | |
24315 | .display asis | |
24316 | av_scanner = kavdaemon:/opt/AVP/AvpCtl | |
24317 | .endd | |
24318 | The default path is \(/var/run/AvpCtl)\. | |
24319 | ||
24320 | .nextp | |
24321 | .index virus scanners||mksd | |
24322 | \mksd\: This is a daemon type scanner that is aimed mainly at Polish users, | |
24323 | though some parts of documentation are now available in English. You can get it | |
24324 | at \?http://linux.mks.com.pl/?\. The only option for this scanner type is the | |
24325 | maximum number of processes used simultaneously to scan the attachments, | |
24326 | provided that the demime facility is employed and also provided that mksd has | |
24327 | been run with at least the same number of child processes. For example: | |
24328 | .display asis | |
24329 | av_scanner = mksd:2 | |
24330 | .endd | |
24331 | You can safely omit this option (the default value is 1). | |
24332 | ||
24333 | .nextp | |
24334 | .index virus scanners||Sophos and Sophie | |
24335 | \sophie\: Sophie is a daemon that uses Sophos' \libsavi\ library to scan for | |
24336 | viruses. You can get Sophie at \?http://www.vanja.com/tools/sophie/?\. The only | |
24337 | option for this scanner type is the path to the UNIX socket that Sophie uses | |
24338 | for client communication. For example: | |
24339 | .display asis | |
24340 | av_scanner = sophie:/tmp/sophie | |
24341 | .endd | |
24342 | The default path is \(/var/run/sophie)\, so if you are using this, you can omit | |
24343 | the option. | |
24344 | .endp | |
24345 | ||
9cc891cb | 24346 | When \av@_scanner\ is correctly set, you can use the \malware\ condition in the |
d43194df PH |
24347 | \\DATA\\ ACL. The \av@_scanner\ option is expanded each time \malware\ is |
24348 | called. This makes it possible to use different scanners. See further below for | |
24349 | an example. The \malware\ condition caches its results, so when you use it | |
24350 | multiple times for the same message, the actual scanning process is only | |
24351 | carried out once. However, using expandable items in \av@_scanner\ disables | |
24352 | this caching, in which case each use of the \malware\ condition causes a new | |
24353 | scan of the message. | |
24354 | ||
24355 | The \malware\ condition takes a right-hand argument that is expanded before | |
4964e932 PH |
24356 | use. It can then be one of |
24357 | .numberpars $. | |
24358 | `true', `*', or `1', in which case the message is scanned for viruses. The | |
24359 | condition succeeds if a virus was found, and fail otherwise. This is the | |
24360 | recommended usage. | |
24361 | .nextp | |
24362 | `false' or `0', in which case no scanning is done and the condition fails | |
24363 | immediately. | |
24364 | .nextp | |
24365 | A regular expression, in which case the message is scanned for viruses. The | |
24366 | condition succeeds if a virus is found and its name matches the regular | |
24367 | expression. This allows you to take special actions on certain types of virus. | |
24368 | .endp | |
24369 | You can append \"/defer@_ok"\ to the \malware\ condition to accept messages even | |
24370 | if there is a problem with the virus scanner. | |
24371 | ||
24372 | .index \$malware@_name$\ | |
24373 | When a virus is found, the condition sets up an expansion variable called | |
24374 | \$malware@_name$\ that contains the name of the virus. You can use it in a | |
24375 | \message\ modifier that specifies the error returned to the sender, and/or in | |
24376 | logging data. | |
24377 | ||
4964e932 PH |
24378 | If your virus scanner cannot unpack MIME and TNEF containers itself, you should |
24379 | use the \demime\ condition (see section ~~SECTdemimecond) before the \malware\ | |
24380 | condition. | |
24381 | ||
24382 | Here is a very simple scanning example: | |
24383 | .display asis | |
24384 | deny message = This message contains malware ($malware_name) | |
24385 | demime = * | |
24386 | malware = * | |
24387 | .endd | |
24388 | The next example accepts messages when there is a problem with the scanner: | |
24389 | .display asis | |
24390 | deny message = This message contains malware ($malware_name) | |
24391 | demime = * | |
24392 | malware = */defer_ok | |
24393 | .endd | |
24394 | The next example shows how to use an ACL variable to scan with both sophie and | |
24395 | aveserver. It assumes you have set: | |
24396 | .display asis | |
24397 | av_scanner = $acl_m0 | |
24398 | .endd | |
24399 | in the main Exim configuration. | |
24400 | .display asis | |
24401 | deny message = This message contains malware ($malware_name) | |
24402 | set acl_m0 = sophie | |
24403 | malware = * | |
24404 | ||
24405 | deny message = This message contains malware ($malware_name) | |
24406 | set acl_m0 = aveserver | |
24407 | malware = * | |
24408 | .endd | |
4964e932 PH |
24409 | |
24410 | ||
24411 | .section Scanning with SpamAssassin | |
24412 | .rset SECTscanspamass "~~chapter.~~section" | |
24413 | .index content scanning||for spam | |
24414 | .index spam scanning | |
24415 | .index SpamAssassin, scanning with | |
24416 | The \spam\ ACL condition calls SpamAssassin's \spamd\ daemon to get a spam | |
24417 | score and a report for the message. You can get SpamAssassin at | |
24418 | \?http://www.spamassassin.org?\, or, if you have a working Perl installation, | |
24419 | you can use CPAN by running: | |
24420 | .display asis | |
24421 | perl -MCPAN -e 'install Mail::SpamAssassin' | |
24422 | .endd | |
24423 | SpamAssassin has its own set of configuration files. Please review its | |
24424 | documentation to see how you can tweak it. The default installation should work | |
24425 | nicely, however. | |
24426 | ||
24427 | .index \spamd@_address\ | |
24428 | After having installed and configured SpamAssassin, start the \spamd\ daemon. | |
24429 | By default, it listens on 127.0.0.1, TCP port 783. If you use another host or | |
24430 | port for \spamd\, you must set the \spamd@_address\ option in the global part | |
24431 | of the Exim configuration as follows (example): | |
24432 | .display asis | |
24433 | spamd_address = 192.168.99.45 387 | |
24434 | .endd | |
24435 | You do not need to set this option if you use the default. As of version 2.60, | |
24436 | \spamd\ also supports communication over UNIX sockets. If you want to use | |
24437 | these, supply \spamd@_address\ with an absolute file name instead of a | |
24438 | address/port pair: | |
24439 | .display asis | |
24440 | spamd_address = /var/run/spamd_socket | |
24441 | .endd | |
24442 | ||
24443 | You can have multiple \spamd\ servers to improve scalability. These can reside | |
24444 | on other hardware reachable over the network. To specify multiple \spamd\ | |
24445 | servers, put multiple address/port pairs in the \spamd@_address\ option, | |
24446 | separated with colons: | |
24447 | .display asis | |
24448 | spamd_address = 192.168.2.10 783 : \ | |
24449 | 192.168.2.11 783 : \ | |
24450 | 192.168.2.12 783 | |
24451 | .endd | |
24452 | Up to 32 \spamd\ servers are supported. The servers are | |
24453 | queried in a random fashion. When a server fails to respond | |
24454 | to the connection attempt, all other servers are tried | |
24455 | until one succeeds. If no server responds, the \spam\ | |
24456 | condition defers. | |
24457 | ||
24458 | \**Warning**\: It is not possible to use the UNIX socket connection method with | |
24459 | multiple \spamd\ servers. | |
24460 | ||
24461 | Here is a simple example of the use of the \spam\ condition in a DATA ACL: | |
24462 | .display asis | |
24463 | deny message = This message was classified as SPAM | |
24464 | spam = joe | |
24465 | .endd | |
24466 | The right-hand side of the \spam\ condition specifies the username that | |
24467 | SpamAssassin should scan for. If you do not want to scan for a particular user, | |
24468 | but rather use the SpamAssassin system-wide default profile, you can scan for | |
24469 | an unknown user, or simply use `nobody'. However, you must put something on the | |
24470 | right-hand side. | |
24471 | ||
24472 | The username allows you to use per-domain or per-user antispam profiles. The | |
24473 | right-hand side is expanded before being used, so you can put lookups or | |
24474 | conditions there. When the right-hand side evaluates to `0' or `false', no | |
24475 | scanning is done and the condition fails immediately. | |
24476 | ||
24477 | The \spam\ condition returns true if the threshold specified in the user's | |
24478 | SpamAssassin profile has been matched or exceeded. If you want to use the | |
24479 | \spam\ condition for its side effects (see the variables below), you can make | |
24480 | it always return `true' by appending \":true"\ to the username. | |
24481 | ||
24482 | .index spam scanning||returned variables | |
24483 | When the \spam\ condition is run, it sets up the following expansion | |
24484 | variables: | |
24485 | ||
24486 | .push | |
24487 | .indent 2em | |
24488 | ||
24489 | .tempindent 0 | |
24490 | \$spam@_score$\: The spam score of the message, for example `3.4' or `30.5'. | |
24491 | This is useful for inclusion in log or reject messages. | |
24492 | ||
24493 | .tempindent 0 | |
24494 | \$spam@_score@_int$\: The spam score of the message, multiplied by ten, as an | |
24495 | integer value. For example `34' or `305'. This is useful for numeric | |
24496 | comparisons in conditions. This variable is special; it is saved with the | |
24497 | message, and written to Exim's spool file. This means that it can be used | |
d43194df | 24498 | during the whole life of the message on your Exim system, in particular, in |
4964e932 PH |
24499 | routers or transports during the later delivery phase. |
24500 | ||
24501 | .tempindent 0 | |
24502 | \$spam@_bar$\: A string consisting of a number of `+' or `@-' characters, | |
24503 | representing the integer part of the spam score value. A spam score of 4.4 | |
24504 | would have a \$spam@_bar$\ value of `++++'. This is useful for inclusion in | |
24505 | warning headers, since MUAs can match on such strings. | |
24506 | ||
24507 | .tempindent 0 | |
24508 | \$spam@_report$\: A multiline text table, containing the full SpamAssassin | |
24509 | report for the message. Useful for inclusion in headers or reject messages. | |
24510 | ||
24511 | .pop | |
24512 | ||
24513 | The \spam\ condition caches its results. If you call it again with the same user | |
24514 | name, it does not scan again, but rather returns the same values as before. | |
24515 | ||
24516 | The \spam\ condition returns DEFER if there is any error while running the | |
24517 | message through SpamAssassin. If you want to treat DEFER as FAIL (to pass on to | |
24518 | the next ACL statement block), append \"/defer@_ok"\ to the right-hand side of | |
24519 | the spam condition, like this: | |
24520 | .display asis | |
24521 | deny message = This message was classified as SPAM | |
24522 | spam = joe/defer_ok | |
24523 | .endd | |
24524 | This causes messages to be accepted even if there is a | |
24525 | problem with \spamd\. | |
24526 | ||
24527 | Here is a longer, commented example of the use of the \spam\ | |
24528 | condition: | |
24529 | .display asis | |
24530 | # put headers in all messages (no matter if spam or not) | |
24531 | warn message = X-Spam-Score: $spam_score ($spam_bar) | |
24532 | spam = nobody:true | |
24533 | warn message = X-Spam-Report: $spam_report | |
24534 | spam = nobody:true | |
24535 | ||
24536 | # add second subject line with *SPAM* marker when message | |
24537 | # is over threshold | |
24538 | warn message = Subject: *SPAM* $h_Subject: | |
24539 | spam = nobody | |
24540 | ||
24541 | # reject spam at high scores (> 12) | |
24542 | deny message = This message scored $spam_score spam points. | |
24543 | spam = nobody:true | |
24544 | condition = ${if >{$spam_score_int}{120}{1}{0}} | |
24545 | .endd | |
24546 | ||
24547 | ||
24548 | ||
24549 | .section Scanning MIME parts | |
24550 | .rset SECTscanmimepart "~~chapter.~~section" | |
24551 | .index content scanning||MIME parts | |
24552 | .index MIME content scanning | |
24553 | .index \acl@_smtp@_mime\ | |
24554 | The \acl@_smtp@_mime\ global option defines an ACL that is called once for each | |
24555 | MIME part of a message, including multipart types, in the sequence of their | |
24556 | position in the message. | |
24557 | ||
24558 | This ACL is called (possibly many times) just before the \acl@_smtp@_data\ ACL, | |
24559 | but only if the message has a ::MIME-Version:: header. When a call to the MIME | |
24560 | ACL does not yield `accept', ACL processing is aborted and the appropriate | |
24561 | result code is sent to the remote client. The \acl@_smtp@_data\ ACL is not | |
24562 | called in this circumstance. | |
24563 | ||
24564 | At the start of the MIME ACL, a number of variables are set from the header | |
24565 | information for the relevant MIME part. These are described below. The contents | |
24566 | of the MIME part are not by default decoded into a disk file except for MIME | |
24567 | parts whose content-type is `message/rfc822'. If you want to decode a MIME part | |
24568 | into a disk file, you can use the \decode\ modifier. The general syntax is: | |
24569 | .display | |
24570 | decode = [/<<path>>/]<<filename>> | |
24571 | .endd | |
24572 | The right hand side is expanded before use. After expansion, | |
24573 | the value can be: | |
24574 | .numberpars | |
24575 | `0' or `false', in which case no decoding is done. | |
24576 | .nextp | |
24577 | The string `default'. In that case, the file is put in the temporary `default' | |
24578 | directory \(<<spool@_directory>>/scan/<<message@_id>>/)\ with a sequential file | |
24579 | name consisting of the message id and a sequence number. The full path and name | |
24580 | is available in \$mime@_decoded@_filename$\ after decoding. | |
24581 | .nextp | |
24582 | A full path name starting with a slash. If the full name is an existing | |
24583 | directory, it is used as a replacement for the default directory. The filename | |
24584 | is then sequentially assigned. If the path does not exist, it is used as | |
24585 | the full path and file name. | |
24586 | .nextp | |
24587 | If the string does not start with a slash, it is used as the | |
24588 | filename, and the default path is then used. | |
24589 | .endp | |
24590 | You can easily decode a file with its original, proposed | |
24591 | filename using | |
24592 | .display asis | |
24593 | decode = $mime_filename | |
24594 | .endd | |
24595 | However, you should keep in mind that \$mime@_filename$\ might contain | |
24596 | anything. If you place files outside of the default path, they are not | |
24597 | automatically unlinked. | |
24598 | ||
24599 | For RFC822 attachments (these are messages attached to messages, with a | |
24600 | content-type of `message/rfc822'), the ACL is called again in the same manner | |
24601 | as for the primary message, only that the \$mime@_is@_rfc822$\ expansion | |
24602 | variable is set (see below). Attached messages are always decoded to disk | |
24603 | before being checked, and the files are unlinked once the check is done. | |
24604 | ||
24605 | The MIME ACL supports the \regex\ and \mime@_regex\ conditions. These can be | |
24606 | used to match regular expressions against raw and decoded MIME parts, | |
24607 | respectively. They are described in section ~~SECTscanregex. | |
24608 | ||
24609 | .index MIME content scanning||returned variables | |
24610 | The following list describes all expansion variables that are | |
24611 | available in the MIME ACL: | |
24612 | ||
24613 | .push | |
24614 | .indent 2em | |
24615 | ||
24616 | .tempindent 0 | |
24617 | \$mime@_boundary$\: | |
24618 | If the current part is a multipart (see \$mime@_is@_multipart$\) below, it | |
24619 | should have a boundary string, which is stored in this variable. If the current | |
24620 | part has no boundary parameter in the ::Content-Type:: header, this variable | |
24621 | contains the empty string. | |
24622 | ||
24623 | .tempindent 0 | |
24624 | \$mime@_charset$\: | |
24625 | This variable contains the character set identifier, if one was found in the | |
24626 | ::Content-Type:: header. Examples for charset identifiers are: | |
24627 | .display asis | |
24628 | us-ascii | |
24629 | gb2312 (Chinese) | |
24630 | iso-8859-1 | |
24631 | .endd | |
24632 | Please note that this value is not normalized, so you should do matches | |
24633 | case-insensitively. | |
495ae4b0 | 24634 | |
4964e932 PH |
24635 | .tempindent 0 |
24636 | \$mime@_content@_description$\: | |
24637 | This variable contains the normalized content of the ::Content-Description:: | |
24638 | header. It can contain a human-readable description of the parts content. Some | |
24639 | implementations repeat the filename for attachments here, but they are | |
24640 | usually only used for display purposes. | |
495ae4b0 | 24641 | |
4964e932 PH |
24642 | .tempindent 0 |
24643 | \$mime@_content@_disposition$\: | |
24644 | This variable contains the normalized content of the ::Content-Disposition:: | |
24645 | header. You can expect strings like `attachment' or `inline' here. | |
495ae4b0 | 24646 | |
4964e932 PH |
24647 | .tempindent 0 |
24648 | \$mime@_content@_id$\: | |
24649 | This variable contains the normalized content of the ::Content-ID:: header. | |
24650 | This is a unique ID that can be used to reference a part from another part. | |
495ae4b0 | 24651 | |
4964e932 PH |
24652 | .tempindent 0 |
24653 | \$mime@_content@_size$\: | |
24654 | This variable is set only after the \decode\ modifier (see above) has been | |
24655 | successfully run. It contains the size of the decoded part in kilobytes. The | |
24656 | size is always rounded up to full kilobytes, so only a completely empty part | |
24657 | has a \$mime@_content@_size$\ of zero. | |
495ae4b0 | 24658 | |
4964e932 PH |
24659 | .tempindent 0 |
24660 | \$mime@_content@_transfer@_encoding$\: | |
24661 | This variable contains the normalized content of the | |
24662 | ::Content-transfer-encoding:: header. This is a symbolic name for an encoding | |
24663 | type. Typical values are `base64' and `quoted-printable'. | |
495ae4b0 | 24664 | |
4964e932 PH |
24665 | .tempindent 0 |
24666 | \$mime@_content@_type$\: If the MIME part has a ::Content-Type:: header, this | |
24667 | variable contains its value, lowercased, and without any options (like `name' | |
24668 | or `charset'). Here are some examples of popular MIME types, as they may appear | |
24669 | in this variable: | |
495ae4b0 | 24670 | .display asis |
4964e932 PH |
24671 | text/plain |
24672 | text/html | |
24673 | application/octet-stream | |
24674 | image/jpeg | |
24675 | audio/midi | |
495ae4b0 | 24676 | .endd |
4964e932 PH |
24677 | If the MIME part has no ::Content-Type:: header, this variable contains the |
24678 | empty string. | |
495ae4b0 | 24679 | |
4964e932 PH |
24680 | .tempindent 0 |
24681 | \$mime@_decoded@_filename$\: | |
24682 | This variable is set only after the \decode\ modifier (see above) has been | |
24683 | successfully run. It contains the full path and file name of the file | |
24684 | containing the decoded data. | |
24685 | ||
24686 | .tempindent 0 | |
24687 | \$mime@_filename$\: This is perhaps the most important of the MIME variables. | |
24688 | It contains a proposed filename for an attachment, if one was found in either | |
24689 | the ::Content-Type:: or ::Content-Disposition:: headers. The filename will be | |
24690 | RFC2047 decoded, but no additional sanity checks are done. If no filename was | |
24691 | found, this variable contains the empty string. | |
24692 | ||
24693 | .tempindent 0 | |
24694 | \$mime@_is@_coverletter$\: | |
24695 | This variable attempts to differentiate the `cover letter' of an e-mail from | |
24696 | attached data. It can be used to clamp down on flashy or unneccessarily encoded | |
24697 | content in the cover letter, while not restricting attachments at all. | |
24698 | ||
24699 | The variable contains 1 (true) for a MIME part believed to be part of the | |
24700 | cover letter, and 0 (false) for an attachment. At present, the algorithm is as | |
24701 | follows: | |
24702 | .numberpars | |
d43194df | 24703 | The outermost MIME part of a message is always a cover letter. |
495ae4b0 | 24704 | .nextp |
4964e932 PH |
24705 | If a multipart/alternative or multipart/related MIME part is a cover letter, so |
24706 | are all MIME subparts within that multipart. | |
495ae4b0 | 24707 | .nextp |
4964e932 PH |
24708 | If any other multipart is a cover letter, the first subpart is a cover letter, |
24709 | and the rest are attachments. | |
24710 | .nextp | |
24711 | All parts contained within an attachment multipart are attachments. | |
495ae4b0 | 24712 | .endp |
4964e932 PH |
24713 | |
24714 | As an example, the following will ban `HTML mail' (including that sent with | |
9cc891cb TK |
24715 | alternative plain text), while allowing HTML files to be attached. HTML |
24716 | coverletter mail attached to non-HMTL coverletter mail will also be allowed: | |
495ae4b0 | 24717 | .display asis |
4964e932 | 24718 | deny message = HTML mail is not accepted here |
9cc891cb | 24719 | !condition = $mime_is_rfc822 |
4964e932 PH |
24720 | condition = $mime_is_coverletter |
24721 | condition = ${if eq{$mime_content_type}{text/html}{1}{0}} | |
495ae4b0 | 24722 | .endd |
4964e932 | 24723 | |
9cc891cb | 24724 | |
4964e932 PH |
24725 | .tempindent 0 |
24726 | \$mime@_is@_multipart$\: | |
24727 | This variable has the value 1 (true) when the current part has the main type | |
24728 | `multipart', for example `multipart/alternative' or `multipart/mixed'. Since | |
24729 | multipart entities only serve as containers for other parts, you may not want | |
24730 | to carry out specific actions on them. | |
24731 | ||
24732 | .tempindent 0 | |
24733 | \$mime@_is@_rfc822$\: | |
24734 | This variable has the value 1 (true) if the current part is not a part of the | |
24735 | checked message itself, but part of an attached message. Attached message | |
24736 | decoding is fully recursive. | |
24737 | ||
24738 | .tempindent 0 | |
24739 | \$mime@_part@_count$\: | |
24740 | This variable is a counter that is raised for each processed MIME part. It | |
24741 | starts at zero for the very first part (which is usually a multipart). The | |
24742 | counter is per-message, so it is reset when processing RFC822 attachments (see | |
24743 | \$mime@_is@_rfc822$\). The counter stays set after \acl@_smtp@_mime\ is | |
24744 | complete, so you can use it in the DATA ACL to determine the number of MIME | |
24745 | parts of a message. For non-MIME messages, this variable contains the value -1. | |
24746 | ||
24747 | .pop | |
24748 | ||
24749 | ||
4964e932 PH |
24750 | .section Scanning with regular expressions |
24751 | .rset SECTscanregex "~~chapter.~~section" | |
24752 | .index content scanning||with regular expressions | |
24753 | .index regular expressions||content scanning with | |
24754 | You can specify your own custom regular expression matches on the full body of | |
24755 | the message, or on individual MIME parts. | |
24756 | ||
24757 | The \regex\ condition takes one or more regular expressions as arguments and | |
24758 | matches them against the full message (when called in the DATA ACL) or a raw | |
24759 | MIME part (when called in the MIME ACL). The \regex\ condition matches | |
24760 | linewise, with a maximum line length of 32K characters. That means you cannot | |
24761 | have multiline matches with the \regex\ condition. | |
24762 | ||
24763 | The \mime@_regex\ condition can be called only in the MIME ACL. It matches up | |
24764 | to 32K of decoded content (the whole content at once, not linewise). If the | |
24765 | part has not been decoded with the \decode\ modifier earlier in the ACL, it is | |
24766 | decoded automatically when \mime@_regex\ is executed (using default path and | |
24767 | filename values). If the decoded data is larger than 32K, only the first 32K | |
24768 | characters are checked. | |
24769 | ||
24770 | The regular expressions are passed as a colon-separated list. To include a | |
24771 | literal colon, you must double it. Since the whole right-hand side string is | |
24772 | expanded before being used, you must also escape dollar signs and backslashes | |
24773 | with more backslashes, or use the \"@\N"\ facility to disable expansion. | |
24774 | Here is a simple example that contains two regular expressions: | |
495ae4b0 | 24775 | .display asis |
4964e932 PH |
24776 | deny message = contains blacklisted regex ($regex_match_string) |
24777 | regex = [Mm]ortgage : URGENT BUSINESS PROPOSAL | |
495ae4b0 | 24778 | .endd |
4964e932 PH |
24779 | The conditions returns true if any one of the regular expressions matches. The |
24780 | \$regex@_match@_string$\ expansion variable is then set up and contains the | |
24781 | matching regular expression. | |
495ae4b0 | 24782 | |
4964e932 PH |
24783 | \**Warning**\: With large messages, these conditions can be fairly |
24784 | CPU-intensive. | |
495ae4b0 | 24785 | |
495ae4b0 | 24786 | |
495ae4b0 | 24787 | |
4964e932 PH |
24788 | .section The demime condition |
24789 | .rset SECTdemimecond "~~chapter.~~section" | |
24790 | .index content scanning||MIME checking | |
24791 | .index MIME content scanning | |
24792 | The \demime\ ACL condition provides MIME unpacking, sanity checking and file | |
24793 | extension blocking. It uses a simpler interface to MIME decoding than the MIME | |
9cc891cb TK |
24794 | ACL functionality, but provides no additional facilities. Please note that this |
24795 | condition is deprecated and kept only for for backward compatibility. You must | |
d43194df PH |
24796 | set the \\WITH@_OLD@_DEMIME\\ option in \(Local/Makefile)\ at build time to be |
24797 | able to use the \demime\ condition. | |
4964e932 PH |
24798 | |
24799 | The \demime\ condition unpacks MIME containers in the message. It detects | |
24800 | errors in MIME containers and can match file extensions found in the message | |
24801 | against a list. Using this facility produces files containing the unpacked MIME | |
24802 | parts of the message in the temporary scan directory. If you do antivirus | |
24803 | scanning, it is recommened that you use the \demime\ condition before the | |
24804 | antivirus (\malware\) condition. | |
24805 | ||
24806 | On the right-hand side of the \demime\ condition you can pass a colon-separated | |
24807 | list of file extensions that it should match against. For example: | |
24808 | .display asis | |
24809 | deny message = Found blacklisted file attachment | |
24810 | demime = vbs:com:bat:pif:prf:lnk | |
24811 | .endd | |
24812 | If one of the file extensions is found, the condition is true, otherwise it is | |
24813 | false. If there is a temporary error while demimeing (for example, `disk | |
24814 | full'), the condition defers, and the message is temporarily rejected (unless | |
24815 | the condition is on a \warn\ verb). | |
24816 | ||
24817 | The right-hand side is expanded before being treated as a list, so you can have | |
24818 | conditions and lookups there. If it expands to an empty string, `false', or | |
24819 | zero (`0'), no demimeing is done and the condition is false. | |
24820 | ||
24821 | The \demime\ condition set the following variables: | |
24822 | ||
24823 | .push | |
24824 | .indent 2em | |
24825 | ||
24826 | .tempindent 0 | |
24827 | \$demime@_errorlevel$\: When an error is detected in a MIME container, this | |
24828 | variable contains the severity of the error, as an integer number. The higher | |
24829 | the value, the more severe the error. If this variable is unset or zero, no | |
24830 | error occurred. | |
24831 | ||
24832 | .tempindent 0 | |
24833 | \$demime@_reason$\: When \$demime@_errorlevel$\ is greater than zero, this | |
24834 | variable contains a human-readable text string describing the MIME error that | |
24835 | occurred. | |
24836 | ||
24837 | .tempindent 0 | |
24838 | \$found@_extension$\: When the \demime\ condition is true, this variable | |
24839 | contains the file extension it found. | |
24840 | ||
24841 | .pop | |
24842 | ||
24843 | Both \$demime@_errorlevel$\ and \$demime@_reason$\ are set by the first call of | |
24844 | the \demime\ condition, and are not changed on subsequent calls. | |
24845 | ||
24846 | If you do not want to check for file extensions, but rather use the \demime\ | |
24847 | condition for unpacking or error checking purposes, pass `*' as the | |
24848 | right-hand side value. Here is a more elaborate example of how to use this | |
24849 | facility: | |
24850 | .display asis | |
24851 | # Reject messages with serious MIME container errors | |
24852 | deny message = Found MIME error ($demime_reason). | |
24853 | demime = * | |
24854 | condition = ${if >{$demime_errorlevel}{2}{1}{0}} | |
24855 | ||
24856 | # Reject known virus spreading file extensions. | |
24857 | # Accepting these is pretty much braindead. | |
24858 | deny message = contains $found_extension file (blacklisted). | |
24859 | demime = com:vbs:bat:pif:scr | |
24860 | ||
24861 | # Freeze .exe and .doc files. Postmaster can | |
24862 | # examine them and eventually thaw them. | |
24863 | deny log_message = Another $found_extension file. | |
24864 | demime = exe:doc | |
24865 | control = freeze | |
24866 | .endd | |
24867 | ||
24868 | ||
24869 | .nem | |
495ae4b0 PH |
24870 | |
24871 | ||
24872 | ||
24873 | . | |
24874 | . | |
24875 | . | |
24876 | . | |
24877 | . ============================================================================ | |
24878 | .chapter Adding a local scan function to Exim | |
24879 | .set runningfoot "local scan function" | |
24880 | .rset CHAPlocalscan "~~chapter" | |
24881 | .index \*local@_scan()*\ function||description of | |
24882 | .index customizing||input scan using C function | |
24883 | .index policy control||by local scan function | |
24884 | ||
24885 | In these days of email worms, viruses, and ever-increasing spam, some sites | |
d43194df PH |
24886 | want to apply a lot of checking to messages before accepting them. |
24887 | .em | |
24888 | The content scanning extension (chapter ~~CHAPexiscan) has facilities for | |
24889 | passing messages to external virus and spam scanning software. You can also do | |
24890 | .nem | |
24891 | a certain amount in Exim itself through string expansions and the \condition\ | |
24892 | condition in the ACL that runs after the SMTP \\DATA\\ command or the ACL for | |
24893 | non-SMTP messages (see chapter ~~CHAPACL), but this has its limitations. | |
495ae4b0 | 24894 | |
d43194df PH |
24895 | To allow for further customization to a site's own requirements, there is the |
24896 | possibility of linking Exim with a private message scanning function, written | |
24897 | in C. If you want to run code that is written in something other than C, you | |
24898 | can of course use a little C stub to call it. | |
495ae4b0 | 24899 | |
4964e932 | 24900 | The local scan function is run once for every incoming message, at the point |
495ae4b0 PH |
24901 | when Exim is just about to accept the message. |
24902 | It can therefore be used to control non-SMTP messages from local processes as | |
24903 | well as messages arriving via SMTP. | |
24904 | ||
24905 | Exim applies a timeout to calls of the local scan function, and there is an | |
24906 | option called \local@_scan@_timeout\ for setting it. The default is 5 minutes. | |
4964e932 | 24907 | Zero means `no timeout'. |
495ae4b0 PH |
24908 | Exim also sets up signal handlers for SIGSEGV, SIGILL, SIGFPE, and SIGBUS |
24909 | before calling the local scan function, so that the most common types of crash | |
24910 | are caught. If the timeout is exceeded or one of those signals is caught, the | |
24911 | incoming message is rejected with a temporary error if it is an SMTP message. | |
24912 | For a non-SMTP message, the message is dropped and Exim ends with a non-zero | |
24913 | code. The incident is logged on the main and reject logs. | |
24914 | ||
24915 | ||
24916 | .section Building Exim to use a local scan function | |
24917 | .index \*local@_scan()*\ function||building Exim to use | |
24918 | To make use of the local scan function feature, you must tell Exim where your | |
24919 | function is before building Exim, by setting \\LOCAL@_SCAN@_SOURCE\\ in your | |
24920 | \(Local/Makefile)\. A recommended place to put it is in the \(Local)\ | |
24921 | directory, so you might set | |
24922 | .display asis | |
24923 | LOCAL_SCAN_SOURCE=Local/local_scan.c | |
24924 | .endd | |
24925 | for example. The function must be called \*local@_scan()*\. It is called by | |
24926 | Exim after it has received a message, when the success return code is about to | |
24927 | be sent. This is after all the ACLs have been run. The return code from your | |
24928 | function controls whether the message is actually accepted or not. There is a | |
24929 | commented template function (that just accepts the message) in the file | |
24930 | \(src/local@_scan.c)\. | |
24931 | ||
4964e932 | 24932 | If you want to make use of Exim's run time configuration file to set options |
495ae4b0 PH |
24933 | for your \*local@_scan()*\ function, you must also set |
24934 | .display asis | |
24935 | LOCAL_SCAN_HAS_OPTIONS=yes | |
24936 | .endd | |
24937 | in \(Local/Makefile)\ (see section ~~SECTconoptloc below). | |
24938 | ||
24939 | ||
24940 | ||
24941 | .section API for local@_scan() | |
24942 | .rset SECTapiforloc "~~chapter.~~section" | |
24943 | .index \*local@_scan()*\ function||API description | |
24944 | You must include this line near the start of your code: | |
24945 | .display asis | |
24946 | #include "local_scan.h" | |
24947 | .endd | |
24948 | This header file defines a number of variables and other values, and the | |
24949 | prototype for the function itself. Exim is coded to use unsigned char values | |
24950 | almost exclusively, and one of the things this header defines is a shorthand | |
4964e932 PH |
24951 | for \"unsigned char"\ called \"uschar"\. |
24952 | It also contains the following macro definitions, to simplify casting character | |
495ae4b0 PH |
24953 | strings and pointers to character strings: |
24954 | .display asis | |
24955 | #define CS (char *) | |
24956 | #define CCS (const char *) | |
24957 | #define CSS (char **) | |
24958 | #define US (unsigned char *) | |
24959 | #define CUS (const unsigned char *) | |
24960 | #define USS (unsigned char **) | |
24961 | .endd | |
24962 | ||
24963 | The function prototype for \*local@_scan()*\ is: | |
24964 | .display asis | |
24965 | extern int local_scan(int fd, uschar **return_text); | |
24966 | .endd | |
24967 | The arguments are as follows: | |
24968 | .numberpars $. | |
24969 | \fd\ is a file descriptor for the file that contains the body of the message | |
4964e932 | 24970 | (the -D file). |
495ae4b0 PH |
24971 | The file is open for reading and writing, but updating it is not recommended. |
24972 | \**Warning**\: You must \*not*\ close this file descriptor. | |
24973 | ||
24974 | The descriptor is positioned at character 19 of the file, which is the first | |
24975 | character of the body itself, because the first 19 characters are the message | |
24976 | id followed by \"-D"\ and a newline. If you rewind the file, you should use the | |
24977 | macro \\SPOOL@_DATA@_START@_OFFSET\\ to reset to the start of the data, just in | |
24978 | case this changes in some future version. | |
24979 | ||
24980 | .nextp | |
24981 | \return@_text\ is an address which you can use to return a pointer to a text | |
24982 | string at the end of the function. The value it points to on entry is NULL. | |
24983 | .endp | |
24984 | The function must return an \int\ value which is one of the following macros: | |
24985 | .numberpars $. | |
24986 | \"LOCAL@_SCAN@_ACCEPT"\ | |
24987 | ||
24988 | The message is accepted. If you pass back a string of text, it is saved with | |
24989 | the message, and made available in the variable \$local@_scan@_data$\. No | |
24990 | newlines are permitted (if there are any, they are turned into spaces) and the | |
24991 | maximum length of text is 1000 characters. | |
24992 | .nextp | |
24993 | \"LOCAL@_SCAN@_ACCEPT@_FREEZE"\ | |
24994 | ||
4964e932 | 24995 | This behaves as \\LOCAL@_SCAN@_ACCEPT\\, except that the accepted message is |
495ae4b0 PH |
24996 | queued without immediate delivery, and is frozen. |
24997 | .nextp | |
24998 | \"LOCAL@_SCAN@_ACCEPT@_QUEUE"\ | |
24999 | ||
4964e932 | 25000 | This behaves as \\LOCAL@_SCAN@_ACCEPT\\, except that the accepted message is |
495ae4b0 PH |
25001 | queued without immediate delivery. |
25002 | .nextp | |
25003 | \"LOCAL@_SCAN@_REJECT"\ | |
25004 | ||
25005 | The message is rejected; the returned text is used as an error message which is | |
25006 | passed back to the sender and which is also logged. Newlines are permitted -- | |
25007 | they cause a multiline response for SMTP rejections, but are converted to | |
25008 | \"@\n"\ in log lines. | |
25009 | If no message is given, `Administrative prohibition' is used. | |
25010 | .nextp | |
25011 | \"LOCAL@_SCAN@_TEMPREJECT"\ | |
25012 | ||
25013 | The message is temporarily rejected; the returned text is used as an error | |
25014 | message as for \\LOCAL@_SCAN@_REJECT\\. If no message is given, `Temporary | |
25015 | local problem' is used. | |
25016 | .nextp | |
25017 | \"LOCAL@_SCAN@_REJECT@_NOLOGHDR"\ | |
25018 | ||
25019 | This behaves as \\LOCAL@_SCAN@_REJECT\\, except that the header of the rejected | |
25020 | message is not written to the reject log. It has the effect of unsetting the | |
25021 | \rejected@_header\ log selector for just this rejection. If \rejected@_header\ | |
25022 | is already unset (see the discussion of the \log@_selection\ option in section | |
25023 | ~~SECTlogselector), this code is the same as \\LOCAL@_SCAN@_REJECT\\. | |
25024 | ||
25025 | .nextp | |
25026 | \"LOCAL@_SCAN@_TEMPREJECT@_NOLOGHDR"\ | |
25027 | ||
25028 | This code is a variation of \\LOCAL@_SCAN@_TEMPREJECT\\ in the same way that | |
25029 | \\LOCAL__SCAN__REJECT__NOLOGHDR\\ is a variation of \\LOCAL@_SCAN@_REJECT\\. | |
25030 | .endp | |
25031 | ||
25032 | If the message is not being received by interactive SMTP, rejections are | |
25033 | reported by writing to \stderr\ or by sending an email, as configured by the | |
25034 | \-oe-\ command line options. | |
25035 | ||
25036 | ||
25037 | .section Configuration options for local@_scan() | |
25038 | .rset SECTconoptloc "~~chapter.~~section" | |
25039 | .index \*local@_scan()*\ function||configuration options | |
25040 | It is possible to have option settings in the main configuration file | |
25041 | that set values in static variables in the \*local@_scan()*\ module. If you | |
25042 | want to do this, you must have the line | |
25043 | .display asis | |
25044 | LOCAL_SCAN_HAS_OPTIONS=yes | |
25045 | .endd | |
25046 | in your \(Local/Makefile)\ when you build Exim. (This line is in | |
25047 | \(OS/Makefile-Default)\, commented out). Then, in the \*local@_scan()*\ source | |
25048 | file, you must define static variables to hold the option values, and a table to | |
4964e932 | 25049 | define them. |
495ae4b0 PH |
25050 | |
25051 | The table must be a vector called \local@_scan@_options\, of type | |
25052 | \"optionlist"\. Each entry is a triplet, consisting of a name, an option type, | |
25053 | and a pointer to the variable that holds the value. The entries must appear in | |
25054 | alphabetical order. Following \local@_scan@_options\ you must also define a | |
25055 | variable called \local@_scan@_options@_count\ that contains the number of | |
25056 | entries in the table. Here is a short example, showing two kinds of option: | |
25057 | .display asis | |
25058 | static int my_integer_option = 42; | |
25059 | static uschar *my_string_option = US"a default string"; | |
25060 | ||
25061 | optionlist local_scan_options[] = { | |
25062 | { "my_integer", opt_int, &my_integer_option }, | |
25063 | { "my_string", opt_stringptr, &my_string_option } | |
25064 | }; | |
25065 | int local_scan_options_count = | |
25066 | sizeof(local_scan_options)/sizeof(optionlist); | |
25067 | .endd | |
25068 | The values of the variables can now be changed from Exim's runtime | |
25069 | configuration file by including a local scan section as in this example: | |
25070 | .display asis | |
25071 | begin local_scan | |
25072 | my_integer = 99 | |
25073 | my_string = some string of text... | |
25074 | .endd | |
25075 | The available types of option data are as follows: | |
25076 | ||
25077 | .startitems | |
25078 | ||
25079 | .item opt@_bool | |
25080 | This specifies a boolean (true/false) option. The address should point to | |
4964e932 | 25081 | a variable of type \"BOOL"\, which will be set to \\TRUE\\ or \\FALSE\\, which |
495ae4b0 PH |
25082 | are macros that are defined as `1' and `0', respectively. If you want to detect |
25083 | whether such a variable has been set at all, you can initialize it to | |
25084 | \\TRUE@_UNSET\\. (BOOL variables are integers underneath, so can hold more than | |
25085 | two values.) | |
25086 | ||
25087 | .item "opt@_fixed" | |
25088 | This specifies a fixed point number, such as is used for load averages. | |
25089 | The address should point to a variable of type \"int"\. The value is stored | |
25090 | multiplied by 1000, so, for example, 1.4142 is truncated and stored as 1414. | |
25091 | ||
25092 | .item "opt@_int" | |
4964e932 | 25093 | This specifies an integer; the address should point to a variable of type |
495ae4b0 PH |
25094 | \"int"\. The value may be specified in any of the integer formats accepted by |
25095 | Exim. | |
25096 | ||
25097 | .item "opt@_mkint" | |
25098 | This is the same as \opt@_int\, except that when such a value is output in a | |
25099 | \-bP-\ listing, if it is an exact number of kilobytes or megabytes, it is | |
25100 | printed with the suffix K or M. | |
25101 | ||
25102 | .item "opt@_octint" | |
25103 | This also specifies an integer, but the value is always interpeted as an | |
25104 | octal integer, whether or not it starts with the digit zero, and it is | |
25105 | always output in octal. | |
25106 | ||
25107 | .item "opt@_stringptr" | |
25108 | This specifies a string value; the address must be a pointer to a | |
25109 | variable that points to a string (for example, of type \"uschar $*$"\). | |
25110 | ||
25111 | .item "opt@_time" | |
25112 | This specifies a time interval value. The address must point to a variable of | |
25113 | type \"int"\. The value that is placed there is a number of seconds. | |
25114 | ||
25115 | .enditems | |
25116 | ||
25117 | If the \-bP-\ command line option is followed by \"local@_scan"\, Exim prints | |
25118 | out the values of all the \*local@_scan()*\ options. | |
25119 | ||
25120 | ||
25121 | .section Available Exim variables | |
25122 | .index \*local@_scan()*\ function||available Exim variables | |
25123 | The header \(local@_scan.h)\ gives you access to a number of C variables. | |
25124 | These are the only ones that are guaranteed to be maintained from release to | |
25125 | release. Note, however, that you can obtain the value of any Exim variable by | |
25126 | calling \*expand@_string()*\. The exported variables are as follows: | |
25127 | ||
25128 | .startitems | |
25129 | ||
25130 | .item "unsigned int debug@_selector" | |
25131 | This variable is set to zero when no debugging is taking place. Otherwise, it | |
25132 | is a bitmap of debugging selectors. Two bits are identified for use in | |
25133 | \*local@_scan()*\; they are defined as macros: | |
25134 | .numberpars $. | |
25135 | The \"D@_v"\ bit is set when \-v-\ was present on the command line. This is a | |
25136 | testing option that is not privileged -- any caller may set it. All the | |
25137 | other selector bits can be set only by admin users. | |
25138 | .nextp | |
25139 | The \"D@_local@_scan"\ bit is provided for use by \*local@_scan()*\; it is set | |
25140 | by the \"+local@_scan"\ debug selector. It is not included in the default set | |
25141 | of debugging bits. | |
25142 | .endp | |
25143 | Thus, to write to the debugging output only when \"+local@_scan"\ has been | |
25144 | selected, you should use code like this: | |
25145 | .display asis | |
4964e932 | 25146 | if ((debug_selector & D_local_scan) != 0) |
495ae4b0 PH |
25147 | debug_printf("xxx", ...); |
25148 | .endd | |
25149 | ||
25150 | .item "uschar *expand@_string@_message" | |
25151 | After a failing call to \*expand@_string()*\ (returned value NULL), the | |
25152 | variable \expand__string__message\ contains the error message, zero-terminated. | |
25153 | ||
25154 | .item "header@_line *header@_list" | |
25155 | A pointer to a chain of header lines. The \header@_line\ structure is discussed | |
25156 | below. | |
25157 | ||
25158 | .item "header@_line *header@_last" | |
25159 | A pointer to the last of the header lines. | |
25160 | ||
25161 | .item "uschar *headers@_charset" | |
25162 | The value of the \headers@_charset\ configuration option. | |
25163 | ||
25164 | .item "BOOL host@_checking" | |
4964e932 | 25165 | This variable is TRUE during a host checking session that is initiated by the |
495ae4b0 PH |
25166 | \-bh-\ command line option. |
25167 | ||
25168 | .item "uschar *interface@_address" | |
25169 | The IP address of the interface that received the message, as a string. This | |
25170 | is NULL for locally submitted messages. | |
25171 | ||
25172 | .item "int interface@_port" | |
25173 | The port on which this message was received. | |
25174 | ||
25175 | .item "uschar *message@_id" | |
4964e932 | 25176 | This variable contains the message id for the incoming message as a |
495ae4b0 PH |
25177 | zero-terminated string. |
25178 | ||
25179 | ||
25180 | .item "uschar *received@_protocol" | |
25181 | The name of the protocol by which the message was received. | |
25182 | ||
25183 | .item "int recipients@_count" | |
25184 | The number of accepted recipients. | |
25185 | ||
25186 | .item "recipient@_item *recipients@_list" | |
25187 | .index recipient||adding in local scan | |
25188 | .index recipient||removing in local scan | |
25189 | The list of accepted recipients, held in a vector of length | |
25190 | \recipients@_count\. The \recipient@_item\ structure is discussed below. You | |
25191 | can add additional recipients by calling \*receive@_add@_recipient()*\ (see | |
25192 | below). You can delete recipients by removing them from the vector and adusting | |
25193 | the value in \recipients@_count\. In particular, by setting \recipients@_count\ | |
25194 | to zero you remove all recipients. If you then return the value | |
25195 | \"LOCAL@_SCAN@_ACCEPT"\, the message is accepted, but immediately blackholed. | |
4964e932 | 25196 | To replace the recipients, set \recipients@_count\ to zero and then call |
495ae4b0 PH |
25197 | \*receive@_add@_recipient()*\ as often as needed. |
25198 | ||
25199 | .item "uschar *sender@_address" | |
25200 | The envelope sender address. For bounce messages this is the empty string. | |
25201 | ||
25202 | .item "uschar *sender@_host@_address" | |
25203 | The IP address of the sending host, as a string. This is NULL for | |
25204 | locally-submitted messages. | |
25205 | ||
25206 | .item "uschar *sender@_host@_authenticated" | |
25207 | The name of the authentication mechanism that was used, or NULL if the message | |
25208 | was not received over an authenticated SMTP connection. | |
25209 | ||
25210 | .item "uschar *sender@_host@_name" | |
25211 | The name of the sending host, if known. | |
25212 | ||
25213 | .item "int sender@_host@_port" | |
25214 | The port on the sending host. | |
25215 | ||
25216 | .item "BOOL smtp@_input" | |
25217 | This variable is TRUE for all SMTP input, including BSMTP. | |
25218 | ||
25219 | .item "BOOL smtp@_batched@_input" | |
25220 | This variable is TRUE for BSMTP input. | |
25221 | ||
25222 | .item "int store@_pool" | |
4964e932 | 25223 | The contents of this variable control which pool of memory is used for new |
495ae4b0 PH |
25224 | requests. See section ~~SECTmemhanloc for details. |
25225 | ||
25226 | .enditems | |
25227 | ||
25228 | ||
25229 | .section Structure of header lines | |
25230 | The \header@_line\ structure contains the members listed below. | |
25231 | You can add additional header lines by calling the \*header@_add()*\ function | |
25232 | (see below). You can cause header lines to be ignored (deleted) by setting | |
25233 | their type to $*$. | |
25234 | ||
25235 | .startitems | |
25236 | ||
25237 | .item "struct header@_line *next" | |
25238 | A pointer to the next header line, or NULL for the last line. | |
25239 | ||
25240 | .item "int type" | |
25241 | A code identifying certain headers that Exim recognizes. The codes are printing | |
25242 | characters, and are documented in chapter ~~CHAPspool of this manual. Notice in | |
25243 | particular that any header line whose type is $*$ is not transmitted with the | |
25244 | message. This flagging is used for header lines that have been rewritten, or | |
25245 | are to be removed (for example, ::Envelope-sender:: header lines.) Effectively, | |
25246 | $*$ means `deleted'. | |
25247 | ||
25248 | .item "int slen" | |
25249 | The number of characters in the header line, including the terminating and any | |
25250 | internal newlines. | |
25251 | ||
25252 | .item "uschar *text" | |
25253 | A pointer to the text of the header. It always ends with a newline, followed by | |
25254 | a zero byte. Internal newlines are preserved. | |
25255 | ||
25256 | .enditems | |
25257 | ||
25258 | ||
25259 | ||
25260 | .section Structure of recipient items | |
25261 | The \recipient@_item\ structure contains these members: | |
25262 | ||
25263 | .startitems | |
25264 | ||
25265 | .item "uschar *address" | |
25266 | This is a pointer to the recipient address as it was received. | |
25267 | ||
25268 | .item "int pno" | |
25269 | This is used in later Exim processing when top level addresses are created | |
25270 | by the \one@_time\ option. It is not relevant at the time \*local@_scan()*\ is | |
4964e932 | 25271 | run and |
495ae4b0 PH |
25272 | must always contain -1 at this stage. |
25273 | ||
25274 | .item "uschar *errors@_to" | |
4964e932 | 25275 | If this value is not NULL, bounce messages caused by failing to deliver to the |
495ae4b0 PH |
25276 | recipient are sent to the address it contains. In other words, it overrides the |
25277 | envelope sender for this one recipient. (Compare the \errors@_to\ generic | |
4964e932 | 25278 | router option.) |
495ae4b0 PH |
25279 | If a \*local@_scan()*\ function sets an \errors@_to\ field to an unqualified |
25280 | address, Exim qualifies it using the domain from \qualify@_recipient\. | |
25281 | When \*local@_scan()*\ is called, the \errors@_to\ field is NULL for all | |
25282 | recipients. | |
25283 | .enditems | |
25284 | ||
25285 | ||
25286 | .section Available Exim functions | |
25287 | .index \*local@_scan()*\ function||available Exim functions | |
25288 | The header \(local@_scan.h)\ gives you access to a number of Exim functions. | |
25289 | These are the only ones that are guaranteed to be maintained from release to | |
25290 | release: | |
25291 | ||
25292 | .startitems | |
25293 | ||
25294 | .item "pid@_t child@_open(uschar **argv, uschar **envp, int newumask, int *infdptr, int *outfdptr, BOOL make@_leader)" | |
25295 | This function creates a child process that runs the command specified by | |
4964e932 | 25296 | \argv\. The environment for the process is specified by \envp\, which can be |
495ae4b0 PH |
25297 | NULL if no environment variables are to be passed. A new umask is supplied for |
25298 | the process in \newumask\. | |
25299 | ||
25300 | Pipes to the standard input and output of the new process are set up | |
25301 | and returned to the caller via the \infdptr\ and \outfdptr\ arguments. The | |
25302 | standard error is cloned to the standard output. If there are any file | |
4964e932 | 25303 | descriptors `in the way' in the new process, they are closed. If the final |
495ae4b0 PH |
25304 | argument is TRUE, the new process is made into a process group leader. |
25305 | ||
25306 | The function returns the pid of the new process, or -1 if things go wrong. | |
25307 | ||
25308 | ||
25309 | .item "int child@_close(pid@_t pid, int timeout)" | |
25310 | This function waits for a child process to terminate, or for a timeout (in | |
25311 | seconds) to expire. A timeout value of zero means wait as long as it takes. The | |
25312 | return value is as follows: | |
25313 | .numberpars $. | |
25314 | >= 0 | |
25315 | ||
25316 | The process terminated by a normal exit and the value is the process ending | |
25317 | status. | |
25318 | .nextp | |
25319 | < 0 and > --256 | |
25320 | ||
25321 | The process was terminated by a signal and the value is the negation of the | |
25322 | signal number. | |
25323 | .nextp | |
25324 | --256 | |
25325 | ||
25326 | The process timed out. | |
25327 | .nextp | |
25328 | --257 | |
25329 | ||
25330 | The was some other error in wait(); \errno\ is still set. | |
25331 | .endp | |
25332 | ||
25333 | ||
25334 | .item "pid@_t child@_open@_exim(int *fd)" | |
25335 | This function provide you with a means of submitting a new message to | |
25336 | Exim. (Of course, you can also call \(/usr/sbin/sendmail)\ yourself if you | |
25337 | want, but this packages it all up for you.) The function creates a pipe, | |
25338 | forks a subprocess that is running | |
25339 | .display asis | |
25340 | exim -t -oem -oi -f <> | |
25341 | .endd | |
25342 | and returns to you (via the \"int *"\ argument) a file descriptor for the pipe | |
25343 | that is connected to the standard input. The yield of the function is the PID | |
25344 | of the subprocess. You can then write a message to the file descriptor, with | |
4964e932 | 25345 | recipients in ::To::, ::Cc::, and/or ::Bcc:: header lines. |
495ae4b0 PH |
25346 | |
25347 | When you have finished, call \*child@_close()*\ to wait for the process to | |
25348 | finish and to collect its ending status. A timeout value of zero is usually | |
25349 | fine in this circumstance. Unless you have made a mistake with the recipient | |
25350 | addresses, you should get a return code of zero. | |
25351 | ||
25352 | .item "void debug@_printf(char *, ...)" | |
4964e932 | 25353 | This is Exim's debugging function, with arguments as for \*(printf()*\. The |
495ae4b0 | 25354 | output is written to the standard error stream. If no debugging is selected, |
4964e932 | 25355 | calls to \*debug@_printf()*\ have no effect. Normally, you should make calls |
495ae4b0 PH |
25356 | conditional on the \"local@_scan"\ debug selector by coding like this: |
25357 | .display asis | |
4964e932 | 25358 | if ((debug_selector & D_local_scan) != 0) |
495ae4b0 PH |
25359 | debug_printf("xxx", ...); |
25360 | .endd | |
25361 | ||
25362 | .item "uschar *expand@_string(uschar *string)" | |
25363 | This is an interface to Exim's string expansion code. The return value is the | |
25364 | expanded string, or NULL if there was an expansion failure. | |
4964e932 PH |
25365 | The C variable \expand@_string@_message\ contains an error message after an |
25366 | expansion failure. If expansion does not change the string, the return value is | |
495ae4b0 PH |
25367 | the pointer to the input string. Otherwise, the return value points to a new |
25368 | block of memory that was obtained by a call to \*store@_get()*\. See section | |
25369 | ~~SECTmemhanloc below for a discussion of memory handling. | |
25370 | ||
25371 | .item "void header@_add(int type, char *format, ...)" | |
d43194df PH |
25372 | .em |
25373 | This function allows you to an add additional header line at the end of the | |
25374 | existing ones. | |
25375 | .nem | |
25376 | The first argument is the type, and should normally be a space character. The | |
25377 | second argument is a format string and any number of substitution arguments as | |
25378 | for \*sprintf()*\. You may include internal newlines if you want, and you must | |
25379 | ensure that the string ends with a newline. | |
25380 | ||
25381 | .em | |
25382 | .item "void header@_add@_at@_position(BOOL after, uschar *name, BOOL topnot, int type, char *$nh{format}, ...)" | |
25383 | This function adds a new header line at a specified point in the header | |
25384 | chain. The header itself is specified as for \*header@_add()*\. | |
25385 | ||
25386 | If \name\ is NULL, the new header is added at the end of the chain if \after\ | |
25387 | is true, or at the start if \after\ is false. If \name\ is not NULL, the header | |
25388 | lines are searched for the first non-deleted header that matches the name. If | |
25389 | one is found, the new header is added before it if \after\ is false. If \after\ | |
25390 | is true, the new header is added after the found header and any adjacent | |
25391 | subsequent ones with the same name (even if marked `deleted'). If no matching | |
25392 | non-deleted header is found, the \topnot\ option controls where the header is | |
25393 | added. If it is true, addition is at the top; otherwise at the bottom. Thus, to | |
25394 | add a header after all the ::Received:: headers, or at the top if there are no | |
25395 | ::Received:: headers, you could use | |
25396 | .display asis | |
25397 | header_add_at_position(TRUE, US"Received", TRUE, | |
25398 | ' ', "X-xxx: ..."); | |
25399 | .endd | |
25400 | Normally, there is always at least one non-deleted ::Received:: header, but | |
25401 | there may not be if \received@_header@_text\ expands to an empty string. | |
25402 | ||
25403 | ||
25404 | .item "void header@_remove(int occurrence, uschar *name)" | |
25405 | This function removes header lines. If \occurrence\ is zero or negative, all | |
25406 | occurrences of the header are removed. If occurrence is greater than zero, that | |
25407 | particular instance of the header is removed. If no header(s) can be found that | |
25408 | match the specification, the function does nothing. | |
25409 | ||
25410 | ||
25411 | .item "BOOL header@_testname(header@_line *hdr, uschar *name, int length, BOOL notdel)" | |
25412 | This function tests whether the given header has the given name. It is not just | |
25413 | a string comparison, because whitespace is permitted between the name and the | |
25414 | colon. If the \notdel\ argument is true, a false return is forced for all | |
25415 | `deleted' headers; otherwise they are not treated specially. For example: | |
25416 | .display asis | |
25417 | if (header_testname(h, US"X-Spam", 6, TRUE)) ... | |
25418 | .endd | |
25419 | .nem | |
25420 | ||
495ae4b0 PH |
25421 | |
25422 | .item "uschar *lss@_b64encode(uschar *cleartext, int length)" | |
25423 | .index base64 encoding||functions for \*local@_scan()*\ use | |
25424 | This function base64-encodes a string, which is passed by address and length. | |
25425 | The text may contain bytes of any value, including zero. The result is passed | |
25426 | back in dynamic memory that is obtained by calling \*store@_get()*\. It is | |
25427 | zero-terminated. | |
25428 | ||
25429 | .item "int lss@_b64decode(uschar *codetext, uschar **cleartext)" | |
25430 | This function decodes a base64-encoded string. Its arguments are a | |
25431 | zero-terminated base64-encoded string and the address of a variable that is set | |
25432 | to point to the result, which is in dynamic memory. The length of the | |
25433 | decoded string is the yield of the function. If the input is invalid base64 | |
25434 | data, the yield is -1. A zero byte is added to the end of the output string to | |
25435 | make it easy to interpret as a C string (assuming it contains no zeros of its | |
25436 | own). The added zero byte is not included in the returned count. | |
25437 | ||
25438 | .item "int lss@_match@_domain(uschar *domain, uschar *list)" | |
25439 | This function checks for a match in a domain list. Domains are always | |
25440 | matched caselessly. The return value is one of the following: | |
25441 | .display | |
25442 | OK $rm{match succeeded} | |
25443 | FAIL $rm{match failed} | |
25444 | DEFER $rm{match deferred} | |
25445 | .endd | |
25446 | DEFER is usually caused by some kind of lookup defer, such as the | |
25447 | inability to contact a database. | |
25448 | ||
25449 | .item "int lss@_match@_local@_part(uschar *localpart, uschar *list, BOOL caseless)" | |
25450 | This function checks for a match in a local part list. The third argument | |
4964e932 | 25451 | controls case-sensitivity. The return values are as for |
495ae4b0 PH |
25452 | \*lss@_match@_domain()*\. |
25453 | ||
25454 | .item "int lss@_match@_address(uschar *address, uschar *list, BOOL caseless)" | |
25455 | This function checks for a match in an address list. The third argument | |
25456 | controls the case-sensitivity of the local part match. The domain is always | |
25457 | matched caselessly. The return values are as for \*lss@_match@_domain()*\. | |
25458 | ||
25459 | .item "int lss@_match@_host(uschar *host@_name, uschar *host@_address, uschar *list)" | |
25460 | This function checks for a match in a host list. The most common usage is | |
25461 | expected to be | |
25462 | .display asis | |
25463 | lss_match_host(sender_host_name, sender_host_address, ...) | |
25464 | .endd | |
25465 | An empty address field matches an empty item in the host list. If the | |
25466 | host name is NULL, the name corresponding to \$sender@_host@_address$\ is | |
25467 | automatically looked up if a host name is required to match an item in the | |
25468 | list. The return values are as for \*lss@_match@_domain()*\, but in addition, | |
25469 | \*lss@_match@_host()*\ returns ERROR in the case when it had to look up a host | |
25470 | name, but the lookup failed. | |
25471 | ||
25472 | .item "void log@_write(unsigned int selector, int which, char *format, ...)" | |
25473 | This function writes to Exim's log files. The first argument should be zero (it | |
25474 | is concerned with \log@_selector\). The second argument can be \"LOG@_MAIN"\ or | |
4964e932 | 25475 | \"LOG@_REJECT"\ or |
495ae4b0 PH |
25476 | \"LOG@_PANIC"\ or the inclusive `or' of any combination of them. It specifies |
25477 | to which log or logs the message is written. | |
25478 | The remaining arguments are a format and relevant insertion arguments. The | |
25479 | string should not contain any newlines, not even at the end. | |
25480 | ||
25481 | ||
25482 | .item "void receive@_add@_recipient(uschar *address, int pno)" | |
25483 | This function adds an additional recipient to the message. The first argument | |
25484 | is the recipient address. If it is unqualified (has no domain), it is qualified | |
25485 | with the \qualify@_recipient\ domain. The second argument must always be -1. | |
25486 | ||
4964e932 PH |
25487 | This function does not allow you to specify a private \errors@_to\ address (as |
25488 | described with the structure of \recipient@_item\ above), because it pre-dates | |
25489 | the addition of that field to the structure. However, it is easy to add such a | |
495ae4b0 PH |
25490 | value afterwards. For example: |
25491 | .display asis | |
25492 | receive_add_recipient(US"monitor@mydom.example", -1); | |
4964e932 | 25493 | recipients_list[recipients_count-1].errors_to = |
495ae4b0 PH |
25494 | US"postmaster@mydom.example"; |
25495 | .endd | |
25496 | ||
d43194df PH |
25497 | .em |
25498 | .item "BOOL receive@_remove@_recipient(uschar *recipient)" | |
25499 | This is a convenience function to remove a named recipient from the | |
25500 | list of recipients. It returns true if a recipient was removed, and | |
25501 | false if no matching recipient could be found. The argument must be a | |
25502 | complete email address. | |
25503 | .nem | |
25504 | ||
25505 | ||
495ae4b0 PH |
25506 | .item "uschar *rfc2047@_decode(uschar *string, BOOL lencheck, uschar *target, int zeroval, int *lenptr, uschar **error)" |
25507 | This function decodes strings that are encoded according to RFC 2047. Typically | |
25508 | these are the contents of header lines. First, each encoded `word' is decoded | |
25509 | from the Q or B encoding into a byte-string. Then, if provided with the name of | |
25510 | a charset encoding, and if the \*iconv()*\ function is available, an attempt is | |
25511 | made to translate the result to the named character set. If this fails, the | |
25512 | binary string is returned with an error message. | |
25513 | ||
4964e932 PH |
25514 | The first argument is the string to be decoded. If \lencheck\ is TRUE, the |
25515 | maximum MIME word length is enforced. The third argument is the target | |
495ae4b0 | 25516 | encoding, or NULL if no translation is wanted. |
4964e932 | 25517 | |
495ae4b0 PH |
25518 | .index binary zero||in RFC 2047 decoding |
25519 | If a binary zero is encountered in the decoded string, it is replaced by the | |
25520 | contents of the \zeroval\ argument. For use with Exim headers, the value must | |
25521 | not be 0 because header lines are handled as zero-terminated strings. | |
25522 | ||
25523 | The function returns the result of processing the string, zero-terminated; if | |
25524 | \lenptr\ is not NULL, the length of the result is set in the variable to which | |
25525 | it points. When \zeroval\ is 0, \lenptr\ should not be NULL. | |
25526 | ||
4964e932 PH |
25527 | If an error is encountered, the function returns NULL and uses the \error\ |
25528 | argument to return an error message. The variable pointed to by \error\ is set | |
25529 | to NULL if there is no error; it may be set non-NULL even when the function | |
25530 | returns a non-NULL value if decoding was successful, but there was a problem | |
495ae4b0 PH |
25531 | with translation. |
25532 | ||
25533 | ||
25534 | .item "int smtp@_fflush(void)" | |
4964e932 | 25535 | This function is used in conjunction with \*smtp@_printf()*\, as described |
495ae4b0 PH |
25536 | below. |
25537 | ||
25538 | .item "void smtp@_printf(char *, ...)" | |
25539 | The arguments of this function are like \*printf()*\; it writes to the SMTP | |
25540 | output stream. You should use this function only when there is an SMTP output | |
25541 | stream, that is, when the incoming message is being received via interactive | |
25542 | SMTP. This is the case when \smtp@_input\ is TRUE and \smtp@_batched@_input\ is | |
25543 | FALSE. If you want to test for an incoming message from another host (as | |
25544 | opposed to a local process that used the \-bs-\ command line option), you can | |
25545 | test the value of \sender@_host@_address\, which is non-NULL when a remote host | |
25546 | is involved. | |
25547 | ||
25548 | If an SMTP TLS connection is established, \*smtp@_printf()*\ uses the TLS | |
25549 | output function, so it can be used for all forms of SMTP connection. | |
25550 | ||
25551 | Strings that are written by \*smtp@_printf()*\ from within \*local@_scan()*\ | |
25552 | must start with an appropriate response code: 550 if you are going to return | |
25553 | \\LOCAL@_SCAN@_REJECT\\, 451 if you are going to return | |
25554 | \\LOCAL@_SCAN@_TEMPREJECT\\, and 250 otherwise. Because you are writing the | |
25555 | initial lines of a multi-line response, the code must be followed by a hyphen | |
25556 | to indicate that the line is not the final response line. You must also ensure | |
25557 | that the lines you write terminate with CRLF. For example: | |
25558 | .display asis | |
25559 | smtp_printf("550-this is some extra info\r\n"); | |
25560 | return LOCAL_SCAN_REJECT; | |
25561 | .endd | |
25562 | Note that you can also create multi-line responses by including newlines in | |
25563 | the data returned via the \return@_text\ argument. The added value of using | |
25564 | \*smtp@_printf()*\ is that, for instance, you could introduce delays between | |
25565 | multiple output lines. | |
25566 | ||
25567 | The \*smtp@_printf()*\ function does not return any error indication, because it | |
25568 | does not automatically flush pending output, and therefore does not test | |
25569 | the state of the stream. (In the main code of Exim, flushing and error | |
25570 | detection is done when Exim is ready for the next SMTP input command.) If | |
25571 | you want to flush the output and check for an error (for example, the | |
25572 | dropping of a TCP/IP connection), you can call \*smtp@_fflush()*\, which has no | |
25573 | arguments. It flushes the output stream, and returns a non-zero value if there | |
25574 | is an error. | |
25575 | ||
25576 | .item "void *store@_get(int)" | |
25577 | This function accesses Exim's internal store (memory) manager. It gets a new | |
25578 | chunk of memory whose size is given by the argument. Exim bombs out if it ever | |
25579 | runs out of memory. See the next section for a discussion of memory handling. | |
25580 | ||
25581 | .item "void *store@_get@_perm(int)" | |
4964e932 | 25582 | This function is like \*store@_get()*\, but it always gets memory from the |
495ae4b0 PH |
25583 | permanent pool. See the next section for a discussion of memory handling. |
25584 | ||
25585 | .item "uschar *string@_copy(uschar *string)" | |
25586 | .item "uschar *string@_copyn(uschar *string, int length)" 0 | |
25587 | .item "uschar *string@_sprintf(char *format, ...)" 0 | |
25588 | These three functions create strings using Exim's dynamic memory facilities. | |
25589 | The first makes a copy of an entire string. The second copies up to a maximum | |
25590 | number of characters, indicated by the second argument. The third uses a format | |
25591 | and insertion arguments to create a new string. In each case, the result is a | |
25592 | pointer to a new string | |
25593 | in the current memory pool. See the next section for more discussion. | |
25594 | ||
25595 | .enditems | |
25596 | ||
25597 | ||
25598 | ||
25599 | .section More about Exim's memory handling | |
25600 | .rset SECTmemhanloc "~~chapter.~~section" | |
25601 | .index \*local@_scan()*\ function||memory handling | |
4964e932 | 25602 | No function is provided for freeing memory, because that is never needed. |
495ae4b0 | 25603 | The dynamic memory that Exim uses when receiving a message is automatically |
4964e932 PH |
25604 | recycled if another message is received by the same process (this applies only |
25605 | to incoming SMTP connections -- other input methods can supply only one message | |
495ae4b0 PH |
25606 | at a time). After receiving the last message, a reception process terminates. |
25607 | ||
25608 | Because it is recycled, the normal dynamic memory cannot be used for holding | |
25609 | data that must be preserved over a number of incoming messages on the same SMTP | |
25610 | connection. However, Exim in fact uses two pools of dynamic memory; the second | |
25611 | one is not recycled, and can be used for this purpose. | |
25612 | ||
4964e932 | 25613 | If you want to allocate memory that remains available for subsequent messages |
495ae4b0 PH |
25614 | in the same SMTP connection, you should set |
25615 | .display asis | |
25616 | store_pool = POOL_PERM | |
25617 | .endd | |
4964e932 PH |
25618 | before calling the function that does the allocation. There is no need to |
25619 | restore the value if you do not need to; however, if you do want to revert to | |
495ae4b0 PH |
25620 | the normal pool, you can either restore the previous value of \store@_pool\ or |
25621 | set it explicitly to \\POOL@_MAIN\\. | |
25622 | ||
25623 | The pool setting applies to all functions that get dynamic memory, including | |
25624 | \*expand@_string()*\, \*store@_get()*\, and the \*string@_xxx()*\ functions. | |
d43194df | 25625 | There is also a convenience function called \*store__get__perm()*\ that gets a |
495ae4b0 PH |
25626 | block of memory from the permanent pool while preserving the value of |
25627 | \store@_pool\. | |
25628 | ||
25629 | ||
25630 | ||
25631 | ||
25632 | ||
25633 | . | |
25634 | . | |
25635 | . | |
25636 | . | |
25637 | . ============================================================================ | |
25638 | .chapter System-wide message filtering | |
25639 | .set runningfoot "system filtering" | |
25640 | .rset CHAPsystemfilter "~~chapter" | |
25641 | .index filter||system filter | |
25642 | .index filtering all mail | |
25643 | .index system filter | |
25644 | The previous chapters (on ACLs and the local scan function) describe checks | |
25645 | that can be applied to messages before they are accepted by a host. There is | |
25646 | also a mechanism for checking messages once they have been received, but before | |
25647 | they are delivered. This is called the $it{system filter}. | |
25648 | ||
25649 | The system filter operates in a similar manner to users' filter files, but it | |
4964e932 PH |
25650 | is run just once per message (however many recipients the message has). |
25651 | It should not normally be used as a substitute for routing, because \deliver\ | |
495ae4b0 PH |
25652 | commands in a system router provide new envelope recipient addresses. |
25653 | The system filter must be an Exim filter. It cannot be a Sieve filter. | |
25654 | ||
25655 | The system filter is run at the start of a delivery attempt, before any routing | |
25656 | is done. If a message fails to be completely delivered at the first attempt, | |
25657 | the system filter is run again at the start of every retry. | |
25658 | If you want your filter to do something only once per message, you can make use | |
4964e932 | 25659 | of the \first@_delivery\ condition in an \if\ command in the filter to prevent |
495ae4b0 PH |
25660 | it happening on retries. |
25661 | ||
25662 | \**Warning**\: Because the system filter runs just once, variables that are | |
25663 | specific to individual recipient addresses, such as \$local@_part$\ and | |
25664 | \$domain$\, are not set, and the `personal' condition is not meaningful. If you | |
25665 | want to run a centrally-specified filter for each recipient address | |
25666 | independently, you can do so by setting up a suitable \%redirect%\ router, as | |
25667 | described in section ~~SECTperaddfil below. | |
25668 | ||
25669 | .section Specifying a system filter | |
25670 | .index uid (user id)||system filter | |
25671 | .index gid (group id)||system filter | |
25672 | The name of the file that contains the system filter must be specified by | |
25673 | setting \system@_filter\. If you want the filter to run under a uid and gid | |
25674 | other than root, you must also set \system@_filter@_user\ and | |
25675 | \system@_filter@_group\ as appropriate. For example: | |
25676 | .display asis | |
25677 | system_filter = /etc/mail/exim.filter | |
25678 | system_filter_user = exim | |
25679 | .endd | |
25680 | If a system filter generates any deliveries directly to files or pipes (via the | |
25681 | \save\ or \pipe\ commands), transports to handle these deliveries must be | |
25682 | specified by setting \system@_filter@_file@_transport\ and | |
25683 | \system@_filter@_pipe@_transport\, respectively. Similarly, | |
25684 | \system@_filter@_reply@_transport\ must be set to handle any messages generated | |
25685 | by the \reply\ command. | |
25686 | ||
25687 | .section Testing a system filter | |
25688 | You can run simple tests of a system filter in the same way as for a user | |
25689 | filter, but you should use \-bF-\ rather than \-bf-\, so that features that | |
25690 | are permitted only in system filters are recognized. | |
d43194df PH |
25691 | .em |
25692 | If you want to test the combined effect of a system filter and a user filter, | |
25693 | you can use both \-bF-\ and \-bf-\ on the same command line. | |
25694 | .nem | |
495ae4b0 PH |
25695 | |
25696 | .section Contents of a system filter | |
25697 | The language used to specify system filters is the same as for users' filter | |
25698 | files. It is described in the separate end-user document \*Exim's interface to | |
25699 | mail filtering*\. However, there are some additional features that are | |
25700 | available only in system filters; these are described in subsequent sections. | |
25701 | If they are encountered in a user's filter file or when testing with \-bf-\, | |
25702 | they cause errors. | |
25703 | ||
25704 | .index frozen messages||manual thaw, testing in filter | |
25705 | There are two special conditions which, though available in users' filter | |
25706 | files, are designed for use in system filters. The condition \first@_delivery\ | |
25707 | is true only for the first attempt at delivering a message, and | |
25708 | \manually@_thawed\ is true only if the message has been frozen, and | |
25709 | subsequently thawed by an admin user. An explicit forced delivery counts as a | |
25710 | manual thaw, but thawing as a result of the \auto__thaw\ setting does not. | |
25711 | ||
25712 | \**Warning**\: If a system filter uses the \first@_delivery\ condition to | |
25713 | specify an `unseen' (non-significant) delivery, and that delivery does not | |
25714 | succeed, it will not be tried again. | |
4964e932 | 25715 | If you want Exim to retry an unseen delivery until it succeeds, you should |
495ae4b0 PH |
25716 | arrange to set it up every time the filter runs. |
25717 | ||
25718 | When a system filter finishes running, the values of the variables \$n0$\ -- | |
25719 | \$n9$\ are copied into \$sn0$\ -- \$sn9$\ and are thereby made available to | |
25720 | users' filter files. Thus a system filter can, for example, set up `scores' to | |
25721 | which users' filter files can refer. | |
25722 | ||
25723 | ||
25724 | .section Additional variable for system filters | |
25725 | The expansion variable \$recipients$\, containing a list of all the recipients | |
25726 | of the message (separated by commas and white space), is available in system | |
25727 | filters. It is not available in users' filters for privacy reasons. | |
25728 | ||
25729 | ||
25730 | .section Defer, freeze, and fail commands for system filters | |
25731 | .index freezing messages | |
25732 | .index message||freezing | |
25733 | .index message||forced failure | |
25734 | .index \fail\||in system filter | |
25735 | .index \freeze\ in system filter | |
25736 | .index \defer\ in system filter | |
25737 | There are three extra commands (\defer\, \freeze\ and \fail\) which are always | |
25738 | available in system filters, but are not normally enabled in users' filters. | |
4964e932 | 25739 | (See the \allow@_defer\, |
495ae4b0 PH |
25740 | \allow@_freeze\ and \allow@_fail\ options for the \%redirect%\ router.) These |
25741 | commands can optionally be followed by the word \text\ and a string containing | |
25742 | an error message, for example: | |
25743 | .display asis | |
25744 | fail text "this message looks like spam to me" | |
25745 | .endd | |
4964e932 | 25746 | The keyword \text\ is optional if the next character is a double quote. |
495ae4b0 | 25747 | |
4964e932 | 25748 | The \defer\ command defers delivery of the original recipients of the message. |
495ae4b0 PH |
25749 | The \fail\ command causes all the original recipients to be failed, and a |
25750 | bounce message to be created. The \freeze\ command suspends all delivery | |
25751 | attempts for the original recipients. In all cases, any new deliveries that are | |
25752 | specified by the filter are attempted as normal after the filter has run. | |
25753 | ||
25754 | The \freeze\ command is ignored if the message has been manually unfrozen and | |
25755 | not manually frozen since. This means that automatic freezing by a system | |
25756 | filter can be used as a way of checking out suspicious messages. If a message | |
25757 | is found to be all right, manually unfreezing it allows it to be delivered. | |
25758 | ||
25759 | .index log||\fail\ command log line | |
25760 | .index \fail\||log line, reducing | |
25761 | The text given with a fail command is used as part of the bounce message as | |
25762 | well as being written to the log. If the message is quite long, this can fill | |
25763 | up a lot of log space when such failures are common. To reduce the size of the | |
25764 | log message, Exim interprets the text in a special way if it starts with the | |
25765 | two characters \"@<@<"\ and contains \"@>@>"\ later. The text between these two | |
25766 | strings is written to the log, and the rest of the text is used in the bounce | |
25767 | message. For example: | |
25768 | .display asis | |
25769 | fail "<<filter test 1>>Your message is rejected \ | |
25770 | because it contains attachments that we are \ | |
25771 | not prepared to receive." | |
25772 | .endd | |
25773 | ||
25774 | .index loop||caused by \fail\ | |
25775 | Take great care with the \fail\ command when basing the decision to fail on the | |
25776 | contents of the message, because the bounce message will of course include the | |
25777 | contents of the original message and will therefore trigger the \fail\ command | |
25778 | again (causing a mail loop) unless steps are taken to prevent this. Testing the | |
25779 | \error@_message\ condition is one way to prevent this. You could use, for | |
25780 | example | |
25781 | .display asis | |
25782 | if $message_body contains "this is spam" and not error_message | |
25783 | then fail text "spam is not wanted here" endif | |
25784 | .endd | |
25785 | though of course that might let through unwanted bounce messages. The | |
25786 | alternative is clever checking of the body and/or headers to detect bounces | |
25787 | generated by the filter. | |
25788 | ||
4964e932 PH |
25789 | The interpretation of a system filter file ceases after a |
25790 | \defer\, | |
495ae4b0 PH |
25791 | \freeze\, or \fail\ command is obeyed. However, any deliveries that were set up |
25792 | earlier in the filter file are honoured, so you can use a sequence such as | |
25793 | .display asis | |
25794 | mail ... | |
25795 | freeze | |
25796 | .endd | |
4964e932 | 25797 | to send a specified message when the system filter is freezing (or deferring or |
495ae4b0 PH |
25798 | failing) a message. The normal deliveries for the message do not, of course, |
25799 | take place. | |
25800 | ||
25801 | ||
25802 | .section Adding and removing headers in a system filter | |
d43194df PH |
25803 | .rset SECTaddremheasys "~~chapter.~~section" |
25804 | .index header lines||adding, in system filter | |
25805 | .index header lines||removing, in system filter | |
495ae4b0 PH |
25806 | .index filter||header lines, adding/removing |
25807 | Two filter commands that are available only in system filters are: | |
d43194df | 25808 | .display |
495ae4b0 PH |
25809 | headers add <<string>> |
25810 | headers remove <<string>> | |
25811 | .endd | |
d43194df | 25812 | The argument for the \headers add\ is a string that is expanded and then added |
495ae4b0 PH |
25813 | to the end of the message's headers. It is the responsibility of the filter |
25814 | maintainer to make sure it conforms to RFC 2822 syntax. Leading white space is | |
25815 | ignored, and if the string is otherwise empty, or if the expansion is forced to | |
25816 | fail, the command has no effect. | |
25817 | ||
495ae4b0 PH |
25818 | You can use `@\n' within the string, followed by white space, to specify |
25819 | continued header lines. More than one header may be added in one command by | |
25820 | including `@\n' within the string without any following white space. For | |
25821 | example: | |
25822 | .display asis | |
25823 | headers add "X-header-1: ....\n \ | |
25824 | continuation of X-header-1 ...\n\ | |
25825 | X-header-2: ...." | |
25826 | .endd | |
25827 | Note that the header line continuation white space after the first newline must | |
4964e932 | 25828 | be placed before the backslash that continues the input string, because white |
495ae4b0 PH |
25829 | space after input continuations is ignored. |
25830 | ||
495ae4b0 PH |
25831 | The argument for \headers remove\ is a colon-separated list of header names. |
25832 | This command applies only to those headers that are stored with the message; | |
25833 | those that are added at delivery time (such as ::Envelope-To:: and | |
d43194df PH |
25834 | ::Return-Path::) cannot be removed by this means. If there is more than one |
25835 | header with the same name, they are all removed. | |
25836 | ||
25837 | .em | |
25838 | The \headers\ command in a system filter makes an immediate change to the set | |
25839 | of header lines that was received with the message (with possible additions | |
25840 | from ACL processing). Subsequent commands in the system filter operate on the | |
25841 | modified set, which also forms the basis for subsequent message delivery. | |
25842 | Unless further modified during routing or transporting, this set of headers is | |
25843 | used for all recipients of the message. | |
25844 | ||
25845 | During routing and transporting, the variables that refer to the contents of | |
25846 | header lines refer only to those lines that are in this set. Thus, header lines | |
25847 | that are added by a system filter are visible to users' filter files and to all | |
25848 | routers and transports. This contrasts with the manipulation of header lines by | |
25849 | routers and transports, which is not immediate, but which instead is saved up | |
25850 | until the message is actually being written (see section ~~SECTheadersaddrem). | |
25851 | ||
25852 | If the message is not delivered at the first attempt, header lines that were | |
25853 | added by the system filter are stored with the message, and so are still | |
25854 | present at the next delivery attempt. Header lines that were removed are still | |
25855 | present, but marked `deleted' so that they are not transported with the | |
25856 | message. For this reason, it is usual to make the \headers\ command conditional | |
25857 | on \first@_delivery\ so that the set of header lines is not modified more than | |
25858 | once. | |
25859 | ||
25860 | Because header modification in a system filter acts immediately, you have to | |
25861 | use an indirect approach if you want to modify the contents of a header line. | |
25862 | For example: | |
25863 | .display asis | |
25864 | headers add "Old-Subject: $h_subject:" | |
25865 | headers remove "Subject" | |
25866 | headers add "Subject: new subject (was: $h_old-subject:)" | |
25867 | headers remove "Old-Subject" | |
25868 | .endd | |
25869 | .nem | |
25870 | ||
495ae4b0 PH |
25871 | |
25872 | ||
25873 | .section Setting an errors address in a system filter | |
25874 | .index envelope sender | |
25875 | In a system filter, if a \deliver\ command is followed by | |
25876 | .display | |
25877 | errors@_to <<some address>> | |
25878 | .endd | |
25879 | in order to change the envelope sender (and hence the error reporting) for that | |
25880 | delivery, any address may be specified. (In a user filter, only the current | |
25881 | user's address can be set.) For example, if some mail is being monitored, you | |
25882 | might use | |
25883 | .display asis | |
25884 | unseen deliver monitor@spying.example errors_to root@local.example | |
25885 | .endd | |
25886 | to take a copy which would not be sent back to the normal error reporting | |
25887 | address if its delivery failed. | |
25888 | ||
25889 | ||
25890 | .section Per-address filtering | |
25891 | .rset SECTperaddfil "~~chapter.~~section" | |
25892 | In contrast to the system filter, which is run just once per message for each | |
25893 | delivery attempt, it is also possible to set up a system-wide filtering | |
25894 | operation that runs once for each recipient address. In this case, variables | |
25895 | such as \$local@_part$\ and \$domain$\ can be used, and indeed, the choice of | |
25896 | filter file could be made dependent on them. This is an example of a router | |
25897 | which implements such a filter: | |
25898 | .display asis | |
25899 | central_filter: | |
25900 | .newline | |
495ae4b0 PH |
25901 | check_local_user |
25902 | .newline | |
495ae4b0 PH |
25903 | driver = redirect |
25904 | domains = +local_domains | |
25905 | file = /central/filters/$local_part | |
25906 | no_verify | |
25907 | allow_filter | |
25908 | allow_freeze | |
25909 | .endd | |
495ae4b0 | 25910 | The filter is run in a separate process under its own uid. Therefore, either |
4964e932 PH |
25911 | \check@_local@_user\ must be set (as above), in which case the filter is run as |
25912 | the local user, or the \user\ option must be used to specify which user to use. | |
495ae4b0 | 25913 | If both are set, \user\ overrides. |
495ae4b0 PH |
25914 | |
25915 | Care should be taken to ensure that none of the commands in the filter file | |
25916 | specify a significant delivery if the message is to go on to be delivered to | |
25917 | its intended recipient. The router will not then claim to have dealt with the | |
25918 | address, so it will be passed on to subsequent routers to be delivered in the | |
25919 | normal way. | |
25920 | ||
25921 | ||
25922 | ||
25923 | ||
25924 | ||
d43194df | 25925 | |
495ae4b0 PH |
25926 | . |
25927 | . | |
25928 | . | |
25929 | . | |
25930 | . ============================================================================ | |
d43194df PH |
25931 | .chapter Message processing |
25932 | .set runningfoot "message processing" | |
25933 | .rset CHAPmsgproc "~~chapter" | |
25934 | .index message||general processing | |
25935 | Exim performs various transformations on the sender and recipient addresses of | |
25936 | all messages that it handles, and also on the messages' header lines. Some of | |
25937 | these are optional and configurable, while others always take place. All of | |
25938 | this processing, except rewriting as a result of routing, and the addition or | |
25939 | removal of header lines while delivering, happens when a message is received, | |
25940 | before it is placed on Exim's queue. | |
495ae4b0 | 25941 | |
d43194df PH |
25942 | Some of the automatic processing takes place by default only for |
25943 | `locally-originated' messages. This adjective is used to describe messages that | |
25944 | are not received over TCP/IP, but instead are passed to an Exim process on its | |
25945 | standard input. This includes the interactive `local SMTP' case that is set up | |
25946 | by the \-bs-\ command line option. | |
25947 | ||
25948 | \**Note**\: messages received over TCP/IP on the loopback interface (127.0.0.1 | |
25949 | or @:@:1) are not considered to be locally-originated. Exim does not treat the | |
25950 | loopback interface specially in any way. | |
25951 | .em | |
25952 | If you want the loopback interface to be treated specially, you must ensure | |
25953 | that there are appropriate entries in your ACLs. | |
25954 | .nem | |
25955 | ||
25956 | ||
25957 | .section Submission mode for non-local messages | |
25958 | .rset SECTsubmodnon "~~chapter.~~section" | |
25959 | .index message||submission | |
25960 | .index submission mode | |
25961 | .em | |
25962 | Processing that happens automatically for locally-originated messages can also | |
25963 | be requested for other messages. The term `submission mode' is used to describe | |
25964 | this state. Submisssion mode is set by the modifier | |
495ae4b0 | 25965 | .display asis |
d43194df | 25966 | control = submission |
495ae4b0 | 25967 | .endd |
d43194df PH |
25968 | in a \\MAIL\\, \\RCPT\\, or pre-data ACL for an incoming SMTP message (see |
25969 | sections ~~SECTACLmodi and ~~SECTcontrols). This makes Exim treat the message | |
25970 | as a local submission, and is normally used when the source of the message is | |
25971 | known to be an MUA running on a client host (as opposed to an MTA). For | |
25972 | example, to set submission mode for messages originating on the IPv4 loopback | |
25973 | interface, you could include the following in the \\MAIL\\ ACL: | |
25974 | .display asis | |
25975 | warn hosts = 127.0.0.1 | |
25976 | control = submission | |
25977 | .endd | |
25978 | There are some options that can be used when setting submission mode. A slash | |
25979 | is used to separate options. For example: | |
25980 | .display asis | |
25981 | control = submission/sender_retain | |
25982 | .endd | |
25983 | Specifying \sender@_retain\ has the effect of setting \local@_sender@_retain\ | |
25984 | true and \local@_from@_check\ false for the current incoming message. The first | |
25985 | of these allows an existing ::Sender:: header in the message to remain, and the | |
25986 | second suppresses the check to ensure that ::From:: matches the authenticated | |
25987 | sender. With this setting, Exim still fixes up messages by adding ::Date:: and | |
25988 | ::Message-ID:: header lines if they are missing, but makes no attempt to check | |
25989 | sender authenticity in header lines. | |
495ae4b0 | 25990 | |
d43194df PH |
25991 | A submission mode setting may also specify a domain to be used when generating |
25992 | a ::From:: or ::Sender:: header. For example: | |
25993 | .display asis | |
25994 | control = submission/domain=some.domain | |
25995 | .endd | |
25996 | The domain may be empty. How this value is used is described in sections | |
25997 | ~~SECTthefrohea and ~~SECTthesenhea. | |
25998 | .nem | |
495ae4b0 | 25999 | |
495ae4b0 | 26000 | |
495ae4b0 | 26001 | |
d43194df PH |
26002 | .section Line endings |
26003 | .rset SECTlineendings "~~chapter.~~section" | |
26004 | .index line endings | |
26005 | .index carriage return | |
26006 | .index linefeed | |
26007 | RFC 2821 specifies that CRLF (two characters: carriage-return, followed by | |
26008 | linefeed) is the line ending for messages transmitted over the Internet using | |
26009 | SMTP over TCP/IP. However, within individual operating systems, different | |
26010 | conventions are used. For example, Unix-like systems use just LF, but others | |
26011 | use CRLF or just CR. | |
26012 | ||
26013 | Exim was designed for Unix-like systems, and internally, it stores messages | |
26014 | using the system's convention of a single LF as a line terminator. When | |
26015 | receiving a message, all line endings are translated to this standard format. | |
26016 | Originally, it was thought that programs that passed messages directly to an | |
26017 | MTA within an operating system would use that system's convention. Experience | |
26018 | has shown that this is not the case; for example, there are Unix applications | |
26019 | that use CRLF in this circumstance. For this reason, and for compatibility with | |
26020 | other MTAs, the way Exim handles line endings for all messages is now as | |
26021 | follows: | |
495ae4b0 | 26022 | .numberpars $. |
d43194df | 26023 | LF not preceded by CR is treated as a line ending. |
495ae4b0 | 26024 | .nextp |
d43194df PH |
26025 | CR is treated as a line ending; if it is immediately followed by LF, the LF |
26026 | is ignored. | |
495ae4b0 | 26027 | .nextp |
d43194df PH |
26028 | The sequence `CR, dot, CR' does not terminate an incoming SMTP message, |
26029 | nor a local message in the state where a line containing only a dot is a | |
26030 | terminator. | |
495ae4b0 | 26031 | .nextp |
d43194df PH |
26032 | If a bare CR is encountered within a header line, an extra space is added after |
26033 | the line terminator so as not to end the header line. The reasoning behind this | |
26034 | is that bare CRs in header lines are most likely either to be mistakes, or | |
26035 | people trying to play silly games. | |
495ae4b0 | 26036 | .nextp |
d43194df PH |
26037 | If the first header line received in a message ends with CRLF, a subsequent |
26038 | bare LF in a header line is treated in the same way as a bare CR in a header | |
26039 | line. | |
495ae4b0 | 26040 | .endp |
495ae4b0 | 26041 | |
495ae4b0 | 26042 | |
495ae4b0 | 26043 | |
d43194df PH |
26044 | .section Unqualified addresses |
26045 | .index unqualified addresses | |
26046 | .index address||qualification | |
26047 | By default, Exim expects every envelope address it receives from an external | |
26048 | host to be fully qualified. Unqualified addresses cause negative responses to | |
26049 | SMTP commands. However, because SMTP is used as a means of transporting | |
26050 | messages from MUAs running on personal workstations, there is sometimes a | |
26051 | requirement to accept unqualified addresses from specific hosts or IP networks. | |
495ae4b0 | 26052 | |
d43194df PH |
26053 | Exim has two options that separately control which hosts may send unqualified |
26054 | sender or receipient addresses in SMTP commands, namely | |
26055 | \sender__unqualified__hosts\ and \recipient__unqualified__hosts\. In both | |
26056 | cases, if an unqualified address is accepted, it is qualified by adding the | |
26057 | value of \qualify__domain\ or \qualify__recipient\, as appropriate. | |
26058 | .index \qualify@_domain\ | |
26059 | .index \qualify@_recipient\ | |
495ae4b0 | 26060 | |
d43194df PH |
26061 | .em |
26062 | Unqualified addresses in header lines are automatically qualified for messages | |
26063 | that are locally originated, unless the \-bnq-\ option is given on the command | |
26064 | line. For messages received over SMTP, unqualified addresses in header lines | |
26065 | are qualified only if unqualified addresses are permitted in SMTP commands. In | |
26066 | other words, such qualification is also controlled by | |
26067 | \sender__unqualified__hosts\ and \recipient__unqualified__hosts\, | |
26068 | .nem | |
495ae4b0 | 26069 | |
495ae4b0 | 26070 | |
d43194df PH |
26071 | .section The UUCP From line |
26072 | .index `From' line | |
26073 | .index UUCP||`From' line | |
26074 | .index sender||address | |
26075 | .index \uucp@_from@_pattern\ | |
26076 | .index \uucp@_from@_sender\ | |
26077 | .index envelope sender | |
26078 | .index Sendmail compatibility||`From' line | |
26079 | Messages that have come from UUCP (and some other applications) often begin | |
26080 | with a line containing the envelope sender and a timestamp, following the word | |
26081 | `From'. Examples of two common formats are: | |
26082 | .display asis | |
26083 | From a.oakley@berlin.mus Fri Jan 5 12:35 GMT 1996 | |
26084 | From f.butler@berlin.mus Fri, 7 Jan 97 14:00:00 GMT | |
26085 | .endd | |
26086 | This line precedes the RFC 2822 header lines. For compatibility with Sendmail, | |
26087 | Exim recognizes such lines at the start of messages that are submitted to it | |
26088 | via the command line (that is, on the standard input). It does not recognize | |
26089 | such lines in incoming SMTP messages, unless the sending host matches | |
26090 | \ignore@_fromline@_hosts\ or the \-bs-\ option was used for a local message and | |
26091 | \ignore@_fromline@_local\ is set. The recognition is controlled by a regular | |
26092 | expression that is defined by the \uucp@_from@_pattern\ option, whose default | |
26093 | value matches the two common cases shown above and puts the address that | |
26094 | follows `From' into \$1$\. | |
495ae4b0 | 26095 | |
d43194df PH |
26096 | .index numerical variables (\$1$\, \$2$\, etc)||in `From ' line handling |
26097 | When the caller of Exim for a non-SMTP message that contains a `From' line is a | |
26098 | trusted user, the message's sender address is constructed by expanding the | |
26099 | contents of \uucp@_sender@_address\, whose default value is `@$1'. This is then | |
26100 | parsed as an RFC 2822 address. If there is no domain, the local part is | |
26101 | qualified with \qualify@_domain\ unless it is the empty string. However, if the | |
26102 | command line \-f-\ option is used, it overrides the `From' line. | |
495ae4b0 | 26103 | |
d43194df PH |
26104 | If the caller of Exim is not trusted, the `From' line is recognized, but the |
26105 | sender address is not changed. This is also the case for incoming SMTP messages | |
26106 | that are permitted to contain `From' lines. | |
26107 | ||
26108 | Only one `From' line is recognized. If there is more than one, the second is | |
26109 | treated as a data line that starts the body of the message, as it is not valid | |
26110 | as a header line. This also happens if a `From' line is present in an incoming | |
26111 | SMTP message from a source that is not permitted to send them. | |
495ae4b0 PH |
26112 | |
26113 | ||
d43194df PH |
26114 | .section Resent- header lines |
26115 | .index \Resent@-\ header lines | |
26116 | RFC 2822 makes provision for sets of header lines starting with the string | |
26117 | \"Resent-"\ to be added to a message when it is resent by the original | |
26118 | recipient to somebody else. These headers are ::Resent-Date::, ::Resent-From::, | |
26119 | ::Resent-Sender::, ::Resent-To::, ::Resent-Cc::, ::Resent-Bcc:: and | |
26120 | ::Resent-Message-ID::. The RFC says: | |
495ae4b0 | 26121 | |
d43194df PH |
26122 | \*Resent fields are strictly informational. They MUST NOT be used in the normal |
26123 | processing of replies or other such automatic actions on messages.*\ | |
495ae4b0 | 26124 | |
d43194df PH |
26125 | This leaves things a bit vague as far as other processing actions such as |
26126 | address rewriting are concerned. Exim treats \Resent@-\ header lines as | |
26127 | follows: | |
26128 | .numberpars $. | |
26129 | A ::Resent-From:: line that just contains the login id of the submitting user | |
26130 | is automatically rewritten in the same way as ::From:: (see below). | |
26131 | .nextp | |
26132 | If there's a rewriting rule for a particular header line, it is also applied to | |
26133 | \Resent@-\ header lines of the same type. For example, a rule that rewrites | |
26134 | ::From:: also rewrites ::Resent-From::. | |
26135 | .nextp | |
26136 | For local messages, if ::Sender:: is removed on input, ::Resent-Sender:: is also | |
26137 | removed. | |
26138 | .nextp | |
26139 | For a locally-submitted message, | |
26140 | if there are any \Resent@-\ header lines but no ::Resent-Date::, | |
26141 | ::Resent-From::, or ::Resent-Message-Id::, they are added as necessary. It is | |
26142 | the contents of ::Resent-Message-Id:: (rather than ::Message-Id::) which are | |
26143 | included in log lines in this case. | |
26144 | .nextp | |
26145 | The logic for adding ::Sender:: is duplicated for ::Resent-Sender:: when any | |
26146 | \Resent@-\ header lines are present. | |
26147 | .endp | |
495ae4b0 PH |
26148 | |
26149 | ||
d43194df PH |
26150 | .section The Auto-Submitted: header line |
26151 | Whenever Exim generates a bounce or a delay warning message, it includes the | |
26152 | header line | |
495ae4b0 | 26153 | .display asis |
d43194df | 26154 | Auto-Submitted: auto-generated |
495ae4b0 | 26155 | .endd |
495ae4b0 PH |
26156 | |
26157 | ||
d43194df PH |
26158 | .section The Bcc: header line |
26159 | .index ::Bcc:: header line | |
26160 | If Exim is called with the \-t-\ option, to take recipient addresses from a | |
26161 | message's header, it removes any ::Bcc:: header line that may exist (after | |
26162 | extracting its addresses). If \-t-\ is not present on the command line, any | |
26163 | existing ::Bcc:: is not removed. | |
495ae4b0 | 26164 | |
d43194df PH |
26165 | .section The Date: header line |
26166 | .index ::Date:: header line | |
26167 | If a locally-generated | |
26168 | or submission-mode | |
26169 | message has no ::Date:: header line, Exim adds one, using the current date and | |
26170 | time. | |
495ae4b0 | 26171 | |
d43194df PH |
26172 | .section The Delivery-date: header line |
26173 | .index ::Delivery-date:: header line | |
26174 | .index \delivery@_date@_remove\ | |
26175 | ::Delivery-date:: header lines are not part of the standard RFC 2822 header | |
26176 | set. Exim can be configured to add them to the final delivery of messages. (See | |
26177 | the generic \delivery@_date@_add\ transport option.) They should not be present | |
26178 | in messages in transit. If the \delivery@_date@_remove\ configuration option is | |
26179 | set (the default), Exim removes ::Delivery-date:: header lines from incoming | |
26180 | messages. | |
495ae4b0 | 26181 | |
d43194df PH |
26182 | .section The Envelope-to: header line |
26183 | .index ::Envelope-to:: header line | |
26184 | .index \envelope@_to@_remove\ | |
26185 | ::Envelope-to:: header lines are not part of the standard RFC 2822 header set. | |
26186 | Exim can be configured to add them to the final delivery of messages. (See the | |
26187 | generic \envelope@_to@_add\ transport option.) They should not be present in | |
26188 | messages in transit. If the \envelope@_to@_remove\ configuration option is set | |
26189 | (the default), Exim removes ::Envelope-to:: header lines from incoming | |
26190 | messages. | |
495ae4b0 | 26191 | |
d43194df PH |
26192 | .section The From: header line |
26193 | .rset SECTthefrohea "~~chapter.~~section" | |
26194 | .index ::From:: header line | |
26195 | .index Sendmail compatibility||`From' line | |
26196 | .index message||submission | |
26197 | .index submission mode | |
26198 | If a submission-mode message does not contain a ::From:: header line, Exim adds | |
26199 | one if either of the following conditions is true: | |
26200 | .numberpars $. | |
26201 | The envelope sender address is not empty (that is, this is not a bounce | |
26202 | message). The added header line copies the envelope sender address. | |
26203 | .nextp | |
26204 | The SMTP session is authenticated and \$authenticated@_id$\ is not empty. | |
26205 | .em | |
26206 | .numberpars alpha | |
26207 | If no domain is specified by the submission control, the local part is | |
26208 | \$authenticated@_id$\ and the domain is \$qualify@_domain$\. | |
26209 | .nextp | |
26210 | If a non-empty domain is specified by the submission control, the local part is | |
26211 | \$authenticated@_id$\, and the the domain is the specified domain. | |
26212 | .nextp | |
26213 | If an empty domain is specified by the submission control, | |
26214 | \$authenticated@_id$\ is assumed to be the complete address. | |
26215 | .endp | |
26216 | .nem | |
26217 | .endp | |
26218 | A non-empty envelope sender takes precedence. | |
495ae4b0 | 26219 | |
d43194df PH |
26220 | If a locally-generated incoming message does not contain a ::From:: header |
26221 | line, Exim adds one containing the sender's address. The calling user's login | |
26222 | name and full name are used to construct the address, as described in section | |
26223 | ~~SECTconstr. They are obtained from the password data by calling | |
26224 | \*getpwuid()*\ (but see the \unknown@_login\ configuration option). The address | |
26225 | is qualified with \qualify@_domain\. | |
495ae4b0 | 26226 | |
d43194df PH |
26227 | For compatibility with Sendmail, if an incoming, non-SMTP message has a |
26228 | ::From:: header line containing just the unqualified login name of the calling | |
26229 | user, this is replaced by an address containing the user's login name and full | |
26230 | name as described in section ~~SECTconstr. | |
495ae4b0 | 26231 | |
d43194df PH |
26232 | .section The Message-ID: header line |
26233 | .index ::Message-ID:: header line | |
26234 | .index message||submission | |
26235 | If a locally-generated or submission-mode incoming message does not contain a | |
26236 | ::Message-ID:: or ::Resent-Message-ID:: header line, Exim adds one to the | |
26237 | message. If there are any ::Resent-:: headers in the message, it creates | |
26238 | ::Resent-Message-ID::. The id is constructed from Exim's internal message id, | |
26239 | preceded by the letter E to ensure it starts with a letter, and followed by @@ | |
26240 | and the primary host name. Additional information can be included in this | |
26241 | header line by setting the | |
26242 | .index \message@_id@_header@_text\ | |
26243 | \message@_id@_header@_text\ and/or \message__id__header__domain\ options. | |
495ae4b0 | 26244 | |
495ae4b0 | 26245 | |
d43194df PH |
26246 | .section The Received: header line |
26247 | .index ::Received:: header line | |
26248 | A ::Received:: header line is added at the start of every message. The contents | |
26249 | are defined by the \received@_header@_text\ configuration option, and Exim | |
26250 | automatically adds a semicolon and a timestamp to the configured string. | |
495ae4b0 | 26251 | |
d43194df PH |
26252 | The ::Received:: header is generated as soon as the message's header lines have |
26253 | been received. At this stage, the timestamp in the ::Received:: header line is | |
26254 | the time that the message started to be received. This is the value that is | |
26255 | seen by the \\DATA\\ ACL and by the \*local@_scan()*\ function. | |
495ae4b0 | 26256 | |
d43194df PH |
26257 | Once a message is accepted, the timestamp in the ::Received:: header line is |
26258 | changed to the time of acceptance, which is (apart from a small delay while the | |
26259 | -H spool file is written) the earliest time at which delivery could start. | |
495ae4b0 | 26260 | |
495ae4b0 | 26261 | |
d43194df PH |
26262 | .section The Return-path: header line |
26263 | .index ::Return-path:: header line | |
26264 | .index \return@_path@_remove\ | |
26265 | ::Return-path:: header lines are defined as something an MTA may insert when | |
26266 | it does the final delivery of messages. (See the generic \return@_path@_add\ | |
26267 | transport option.) Therefore, they should not be present in messages in | |
26268 | transit. If the \return@_path@_remove\ configuration option is set (the | |
26269 | default), Exim removes ::Return-path:: header lines from incoming messages. | |
495ae4b0 | 26270 | |
495ae4b0 | 26271 | |
d43194df PH |
26272 | .section The Sender: header line |
26273 | .rset SECTthesenhea "~~chapter.~~section" | |
26274 | .index ::Sender:: header line | |
26275 | .index message||submission | |
26276 | For a locally-originated message from an untrusted user, Exim may remove an | |
26277 | existing ::Sender:: header line, and it may add a new one. You can modify these | |
26278 | actions by setting \local@_sender@_retain\ true or \local@_from@_check\ false. | |
495ae4b0 | 26279 | |
d43194df PH |
26280 | When a local message is received from an untrusted user and |
26281 | \local@_from@_check\ is true (the default), a check is made to see if the | |
26282 | address given in the ::From:: header line is the correct (local) sender of the | |
26283 | message. The address that is expected has the login name as the local part and | |
26284 | the value of \qualify@_domain\ as the domain. Prefixes and suffixes for the | |
26285 | local part can be permitted by setting \local@_from@_prefix\ and | |
26286 | \local@_from@_suffix\ appropriately. If ::From:: does not contain the correct | |
26287 | sender, a ::Sender:: line is added to the message. | |
495ae4b0 | 26288 | |
d43194df PH |
26289 | If you set \local@_from@_check\ false, this checking does not occur. However, |
26290 | the removal of an existing ::Sender:: line still happens, unless you also set | |
26291 | \local@_sender@_retain\ to be true. It is not possible to set both of these | |
26292 | options true at the same time. | |
495ae4b0 | 26293 | |
d43194df PH |
26294 | .em |
26295 | .index submission mode | |
26296 | By default, no processing of ::Sender:: header lines is done for messages | |
26297 | received over TCP/IP or for messages submitted by trusted users. However, when | |
26298 | a message is received over TCP/IP in submission mode, and \sender@_retain\ is | |
26299 | not specified on the submission control, the following processing takes place: | |
495ae4b0 | 26300 | |
d43194df PH |
26301 | First, any existing ::Sender:: lines are removed. Then, if the SMTP session is |
26302 | authenticated, and \$authenticated@_id$\ is not empty, a sender address is | |
26303 | created as follows: | |
495ae4b0 | 26304 | .numberpars $. |
d43194df PH |
26305 | If no domain is specified by the submission control, the local part is |
26306 | \$authenticated@_id$\ and the domain is \$qualify@_domain$\. | |
495ae4b0 | 26307 | .nextp |
d43194df PH |
26308 | If a non-empty domain is specified by the submission control, the local part is |
26309 | \$authenticated@_id$\, and the the domain is the specified domain. | |
26310 | .nextp | |
26311 | If an empty domain is specified by the submission control, | |
26312 | \$authenticated@_id$\ is assumed to be the complete address. | |
495ae4b0 | 26313 | .endp |
d43194df PH |
26314 | This address is compared with the address in the ::From:: header line. If they |
26315 | are different, a ::Sender:: header line containing the created address is | |
26316 | added. Prefixes and suffixes for the local part in ::From:: can be permitted by | |
26317 | setting \local@_from@_prefix\ and \local@_from@_suffix\ appropriately. | |
26318 | .nem | |
26319 | ||
26320 | ||
26321 | .section Adding and removing header lines in routers and transports | |
26322 | .index header lines||adding, in router or transport | |
26323 | .index header lines||removing, in router or transport | |
26324 | .rset SECTheadersaddrem "~~chapter.~~section" | |
26325 | .em | |
26326 | When a message is delivered, the addition and removal of header lines can be | |
26327 | specified in a system filter, or on any of the routers and transports that | |
26328 | process the message. Section ~~SECTaddremheasys contains details about | |
26329 | modifying headers in a system filter. | |
26330 | ||
26331 | In contrast to what happens in a system filter, header modifications that are | |
26332 | specified on routers and transports apply only to the particular recipient | |
26333 | addresses that are being processed by those routers and transports. These | |
26334 | changes do not actually take place until a copy of the message is being | |
26335 | transported. Therefore, they do not affect the basic set of header lines, and | |
26336 | they do not affect the values of the variables that refer to header lines. | |
26337 | ||
26338 | For both routers and transports, the result of expanding a \headers@_add\ | |
26339 | option must be in the form of one or more RFC 2822 header lines, separated by | |
26340 | newlines (coded as `@\n'). For example: | |
495ae4b0 | 26341 | .display asis |
d43194df PH |
26342 | headers_add = X-added-header: added by $primary_hostname\n\ |
26343 | X-added-second: another added header line | |
495ae4b0 | 26344 | .endd |
d43194df | 26345 | Exim does not check the syntax of these added header lines. |
495ae4b0 | 26346 | |
d43194df PH |
26347 | The result of expanding \headers@_remove\ must consist of a colon-separated |
26348 | list of header names. This is confusing, because header names themselves are | |
26349 | often terminated by colons. In this case, the colons are the list separators, | |
26350 | not part of the names. For example: | |
495ae4b0 | 26351 | .display asis |
d43194df | 26352 | headers_remove = return-receipt-to:acknowledge-to |
495ae4b0 | 26353 | .endd |
d43194df PH |
26354 | |
26355 | When \headers@_add\ or \headers@_remove\ is specified on a router, its value is | |
26356 | expanded at routing time, and then associated with all addresses that are | |
26357 | accepted by that router, and also with any new addresses that it generates. If | |
26358 | an address passes through several routers as a result of aliasing or | |
26359 | forwarding, the changes are cumulative. | |
26360 | .index \unseen\ option | |
26361 | However, this does not apply to multiple routers that result from the use of | |
26362 | the \unseen\ option. Any header modifications that were specified by the | |
26363 | `unseen' router or its predecessors apply only to the `unseen' delivery. | |
26364 | ||
26365 | Addresses that end up with different \headers@_add\ or \headers@_remove\ | |
26366 | settings cannot be delivered together in a batch, so a transport is always | |
26367 | dealing with a set of addresses that have the same header-processing | |
26368 | requirements. | |
26369 | ||
26370 | The transport starts by writing the original set of header lines that arrived | |
26371 | with the message, possibly modified by the system filter. As it writes out | |
26372 | these lines, it consults the list of header names that were attached to the | |
26373 | recipient address(es) by \headers@_remove\ options in routers, and it also | |
26374 | consults the transport's own \headers@_remove\ option. Header lines whose names | |
26375 | are on either of these lists are not written out. If there are multiple | |
26376 | instances of any listed header, they are all skipped. | |
26377 | ||
26378 | After the remaining original header lines have been written, new header | |
26379 | lines that were specified by routers' \headers@_add\ options are written, in | |
26380 | the order in which they were attached to the address. These are followed by any | |
26381 | header lines specified by the transport's \headers@_add\ option. | |
26382 | ||
26383 | This way of handling header line modifications in routers and transports has | |
26384 | the following consequences: | |
26385 | .numberpars $. | |
26386 | The original set of header lines, possibly modified by the system filter, | |
26387 | remains `visible', in the sense that the \$header@_$\\*xxx*\ variables refer to | |
26388 | it, at all times. | |
26389 | .nextp | |
26390 | Header lines that are added by a router's | |
26391 | \headers@_add\ option are not accessible by means of the \$header@_$\\*xxx*\ | |
26392 | expansion syntax in subsequent routers or the transport. | |
26393 | .nextp | |
26394 | Conversely, header lines that are specified for removal by \headers@_remove\ in | |
26395 | a router remain visible to subsequent routers and the transport. | |
26396 | .nextp | |
26397 | Headers added to an address by \headers@_add\ in a router cannot be removed by | |
26398 | a later router or by a transport. | |
26399 | .nextp | |
26400 | An added header can refer to the contents of an original header that is to be | |
26401 | removed, even it has the same name as the added header. For example: | |
495ae4b0 | 26402 | .display asis |
d43194df PH |
26403 | headers_remove = subject |
26404 | headers_add = Subject: new subject (was: $h_subject:) | |
495ae4b0 | 26405 | .endd |
d43194df | 26406 | .endp |
495ae4b0 | 26407 | |
d43194df PH |
26408 | \**Warning**\: The \headers@_add\ and \headers@_remove\ options cannot be used |
26409 | for a \%redirect%\ router that has the \one@_time\ option set. | |
26410 | .nem | |
495ae4b0 PH |
26411 | |
26412 | ||
d43194df PH |
26413 | |
26414 | .section Constructed addresses | |
26415 | .rset SECTconstr "~~chapter.~~section" | |
26416 | .index address||constructed | |
26417 | .index constructed address | |
26418 | When Exim constructs a sender address for a locally-generated message, it uses | |
26419 | the form | |
26420 | .display | |
26421 | <<user name>> <$$<<login>>@@<<qualify@_domain>>$$> | |
495ae4b0 | 26422 | .endd |
d43194df | 26423 | For example: |
495ae4b0 | 26424 | .display asis |
d43194df | 26425 | Zaphod Beeblebrox <zaphod@end.univ.example> |
495ae4b0 | 26426 | .endd |
d43194df PH |
26427 | The user name is obtained from the \-F-\ command line option if set, or |
26428 | otherwise by looking up the calling user by \*getpwuid()*\ and extracting the | |
26429 | `gecos' field from the password entry. If the `gecos' field contains an | |
26430 | ampersand character, this is replaced by the login name with the first letter | |
26431 | upper cased, as is conventional in a number of operating systems. See the | |
26432 | \gecos@_name\ option for a way to tailor the handling of the `gecos' field. The | |
26433 | \unknown@_username\ option can be used to specify user names in cases when | |
26434 | there is no password file entry. | |
495ae4b0 | 26435 | |
d43194df PH |
26436 | In all cases, the user name is made to conform to RFC 2822 by quoting all or |
26437 | parts of it if necessary. In addition, if it contains any non-printing | |
26438 | characters, it is encoded as described in RFC 2047, which defines a way of | |
26439 | including non-ASCII characters in header lines. | |
26440 | The value of the \headers@_charset\ option specifies the name of the encoding | |
26441 | that is used (the characters are assumed to be in this encoding). | |
26442 | The setting of \print@_topbitchars\ controls whether characters with the top | |
26443 | bit set (that is, with codes greater than 127) count as printing characters or | |
26444 | not. | |
495ae4b0 PH |
26445 | |
26446 | ||
d43194df PH |
26447 | .section Case of local parts |
26448 | .index case of local parts | |
26449 | .index local part||case of | |
26450 | RFC 2822 states that the case of letters in the local parts of addresses cannot | |
26451 | be assumed to be non-significant. Exim preserves the case of local parts of | |
26452 | addresses, but by default it uses a lower-cased form when it is routing, | |
26453 | because on most Unix systems, usernames are in lower case and case-insensitive | |
26454 | routing is required. However, any particular router can be made to use the | |
26455 | original case for local parts by setting the \caseful@_local@_part\ generic | |
26456 | router option. | |
26457 | ||
26458 | .index mixed-case login names | |
26459 | If you must have mixed-case user names on your system, the best way to proceed, | |
26460 | assuming you want case-independent handling of incoming email, is to set up | |
26461 | your first router to convert incoming local parts in your domains to the | |
26462 | correct case by means of a file lookup. For example: | |
495ae4b0 | 26463 | .display asis |
d43194df PH |
26464 | correct_case: |
26465 | driver = redirect | |
26466 | domains = +local_domains | |
26467 | data = ${lookup{$local_part}cdb\ | |
26468 | {/etc/usercased.cdb}{$value}fail}\ | |
26469 | @$domain | |
495ae4b0 | 26470 | .endd |
d43194df PH |
26471 | For this router, the local part is forced to lower case by the default action |
26472 | (\caseful@_local@_part\ is not set). The lower-cased local part is used to look | |
26473 | up a new local part in the correct case. If you then set \caseful@_local@_part\ | |
26474 | on any subsequent routers which process your domains, they will operate on | |
26475 | local parts with the correct case in a case-sensitive manner. | |
495ae4b0 | 26476 | |
495ae4b0 | 26477 | |
d43194df PH |
26478 | .section Dots in local parts |
26479 | .index dot||in local part | |
26480 | .index local part||dots in | |
26481 | RFC 2822 forbids empty components in local parts. That is, an unquoted local | |
26482 | part may not begin or end with a dot, nor have two consecutive dots in the | |
26483 | middle. However, it seems that many MTAs do not enforce this, so Exim permits | |
26484 | empty components for compatibility. | |
495ae4b0 | 26485 | |
495ae4b0 | 26486 | |
d43194df PH |
26487 | .section Rewriting addresses |
26488 | .index rewriting||addresses | |
26489 | Rewriting of sender and recipient addresses, and addresses in headers, can | |
26490 | happen automatically, or as the result of configuration options, as described | |
26491 | in chapter ~~CHAPrewrite. The headers that may be affected by this are ::Bcc::, | |
26492 | ::Cc::, ::From::, ::Reply-To::, ::Sender::, and ::To::. | |
495ae4b0 | 26493 | |
d43194df PH |
26494 | Automatic rewriting includes qualification, as mentioned above. The other case |
26495 | in which it can happen is when an incomplete non-local domain is given. The | |
26496 | routing process may cause this to be expanded into the full domain name. For | |
26497 | example, a header such as | |
26498 | .display asis | |
26499 | To: hare@teaparty | |
26500 | .endd | |
26501 | might get rewritten as | |
26502 | .display asis | |
26503 | To: hare@teaparty.wonderland.fict.example | |
26504 | .endd | |
26505 | Rewriting as a result of routing is the one kind of message processing that | |
26506 | does not happen at input time, as it cannot be done until the address has | |
26507 | been routed. | |
495ae4b0 | 26508 | |
d43194df PH |
26509 | Strictly, one should not do $it{any} deliveries of a message until all its |
26510 | addresses have been routed, in case any of the headers get changed as a | |
26511 | result of routing. However, doing this in practice would hold up many | |
26512 | deliveries for unreasonable amounts of time, just because one address could not | |
26513 | immediately be routed. Exim therefore does not delay other deliveries when | |
26514 | routing of one or more addresses is deferred. | |
495ae4b0 PH |
26515 | |
26516 | ||
26517 | . | |
26518 | . | |
26519 | . | |
26520 | . | |
26521 | . ============================================================================ | |
26522 | .chapter SMTP processing | |
26523 | .set runningfoot "smtp processing" | |
26524 | .rset CHAPSMTP ~~chapter | |
26525 | .index SMTP||processing details | |
26526 | .index LMTP||processing details | |
26527 | Exim supports a number of different ways of using the SMTP protocol, and its | |
26528 | LMTP variant, which is an interactive protocol for transferring messages into a | |
26529 | closed mail store application. This chapter contains details of how SMTP is | |
26530 | processed. For incoming mail, the following are available: | |
26531 | .numberpars $. | |
26532 | SMTP over TCP/IP (Exim daemon or \*inetd*\); | |
26533 | .nextp | |
26534 | SMTP over the standard input and output (the \-bs-\ option); | |
26535 | .nextp | |
26536 | Batched SMTP on the standard input (the \-bS-\ option). | |
26537 | .endp | |
26538 | For mail delivery, the following are available: | |
26539 | .numberpars $. | |
26540 | SMTP over TCP/IP (the \%smtp%\ transport); | |
26541 | .nextp | |
26542 | LMTP over TCP/IP (the \%smtp%\ transport with the \protocol\ option set to | |
26543 | `lmtp'); | |
26544 | .nextp | |
26545 | LMTP over a pipe to a process running in the local host (the \%lmtp%\ | |
26546 | transport); | |
26547 | .nextp | |
26548 | Batched SMTP to a file or pipe (the \%appendfile%\ and \%pipe%\ transports with | |
26549 | the \use@_bsmtp\ option set). | |
26550 | .endp | |
26551 | \*Batched SMTP*\ is the name for a process in which batches of messages are | |
26552 | stored in or read from files (or pipes), in a format in which SMTP commands are | |
26553 | used to contain the envelope information. | |
26554 | ||
26555 | ||
26556 | .section Outgoing SMTP and LMTP over TCP/IP | |
26557 | .rset SECToutSMTPTCP "~~chapter.~~section" | |
26558 | .index SMTP||outgoing over TCP/IP | |
26559 | .index outgoing SMTP over TCP/IP | |
26560 | .index LMTP||over TCP/IP | |
26561 | .index outgoing LMTP over TCP/IP | |
26562 | .index \\EHLO\\ | |
26563 | .index \\HELO\\ | |
26564 | .index \\SIZE\\ option on \\MAIL\\ command | |
26565 | Outgoing SMTP and LMTP over TCP/IP is implemented by the \%smtp%\ transport. | |
26566 | The \protocol\ option selects which protocol is to be used, but the actual | |
26567 | processing is the same in both cases. | |
26568 | ||
26569 | If, in response to its \\EHLO\\ command, Exim is told that the \\SIZE\\ | |
26570 | parameter is supported, it adds \\SIZE\\=<<n>> to each subsequent \\MAIL\\ | |
26571 | command. The value of <<n>> is the message size plus the value of the | |
26572 | \size@_addition\ option (default 1024) to allow for additions to the message | |
26573 | such as per-transport header lines, or changes made in a | |
26574 | .index transport||filter | |
26575 | .index filter||transport filter | |
26576 | transport filter. If \size@_addition\ is set negative, the use of \\SIZE\\ is | |
26577 | suppressed. | |
26578 | ||
26579 | If the remote server advertises support for \\PIPELINING\\, Exim uses the | |
26580 | pipelining extension to SMTP (RFC 2197) to reduce the number of TCP/IP packets | |
26581 | required for the transaction. | |
26582 | ||
26583 | If the remote server advertises support for the \\STARTTLS\\ command, and Exim | |
26584 | was built to support TLS encryption, it tries to start a TLS session unless the | |
26585 | server matches \hosts@_avoid@_tls\. See chapter ~~CHAPTLS for more details. | |
26586 | ||
26587 | If the remote server advertises support for the \\AUTH\\ command, Exim scans | |
26588 | the authenticators configuration for any suitable client settings, as described | |
26589 | in chapter ~~CHAPSMTPAUTH. | |
26590 | ||
26591 | .index carriage return | |
26592 | .index linefeed | |
26593 | Responses from the remote host are supposed to be terminated by CR followed by | |
26594 | LF. However, there are known to be hosts that do not send CR characters, so in | |
26595 | order to be able to interwork with such hosts, Exim treats LF on its own as a | |
26596 | line terminator. | |
26597 | ||
26598 | If a message contains a number of different addresses, all those with the same | |
26599 | characteristics (for example, the same envelope sender) that resolve to the | |
26600 | same set of hosts, in the same order, are sent in a single SMTP transaction, | |
26601 | even if they are for different domains, unless there are more than the setting | |
26602 | of the \max@_rcpts\ option in the \%smtp%\ transport allows, in which case they | |
26603 | are split into groups containing no more than \max@_rcpts\ addresses each. If | |
26604 | \remote@_max@_parallel\ is greater than one, such groups may be sent in | |
26605 | parallel sessions. The order of hosts with identical MX values is not | |
26606 | significant when checking whether addresses can be batched in this way. | |
26607 | ||
26608 | When the \%smtp%\ transport suffers a temporary failure that is not | |
26609 | message-related, Exim updates its transport-specific database, which contains | |
26610 | records indexed by host name that remember which messages are waiting for each | |
26611 | particular host. It also updates the retry database with new retry times. | |
26612 | .index hints database||retry keys | |
26613 | Exim's retry hints are based on host name plus IP address, so if one address of | |
26614 | a multi-homed host is broken, it will soon be skipped most of the time. | |
26615 | See the next section for more detail about error handling. | |
26616 | ||
26617 | .index SMTP||passed connection | |
26618 | .index SMTP||batching over TCP/IP | |
26619 | When a message is successfully delivered over a TCP/IP SMTP connection, Exim | |
26620 | looks in the hints database for the transport to see if there are any queued | |
26621 | messages waiting for the host to which it is connected. If it finds one, it | |
26622 | creates a new Exim process using the \-MC-\ option (which can only be used by a | |
26623 | process running as root or the Exim user) and passes the TCP/IP socket to it so | |
26624 | that it can deliver another message using the same socket. The new process does | |
26625 | only those deliveries that are routed to the connected host, and may in turn | |
26626 | pass the socket on to a third process, and so on. | |
26627 | ||
26628 | The \connection@_max@_messages\ option of the \%smtp%\ transport can be used to | |
26629 | limit the number of messages sent down a single TCP/IP connection. | |
26630 | .index asterisk||after IP address | |
26631 | The second and subsequent messages delivered down an existing connection are | |
26632 | identified in the main log by the addition of an asterisk after the closing | |
26633 | square bracket of the IP address. | |
26634 | ||
26635 | ||
26636 | ||
26637 | .section Errors in outgoing SMTP | |
26638 | .rset SECToutSMTPerr "~~chapter.~~section" | |
26639 | .index error||in outgoing SMTP | |
26640 | .index SMTP||errors in outgoing | |
26641 | .index host||error | |
26642 | Three different kinds of error are recognized for outgoing SMTP: host errors, | |
26643 | message errors, and recipient errors. | |
26644 | .numberpars | |
26645 | A host error is not associated with a particular message or with a | |
26646 | particular recipient of a message. The host errors are: | |
26647 | .numberpars $. | |
26648 | Connection refused or timed out, | |
26649 | .nextp | |
26650 | Any error response code on connection, | |
26651 | .nextp | |
26652 | Any error response code to \\EHLO\\ or \\HELO\\, | |
26653 | .nextp | |
26654 | Loss of connection at any time, except after `.', | |
26655 | .nextp | |
26656 | I/O errors at any time, | |
26657 | .nextp | |
26658 | Timeouts during the session, other than in response to \\MAIL\\, \\RCPT\\ or | |
26659 | the `.' at the end of the data. | |
26660 | .endp | |
26661 | For a host error, a permanent error response on connection, or in response to | |
26662 | \\EHLO\\, causes all addresses routed to the host to be failed. Any other host | |
26663 | error causes all addresses to be deferred, and retry data to be created for the | |
26664 | host. It is not tried again, for any message, until its retry time arrives. If | |
26665 | the current set of addresses are not all delivered in this run (to some | |
26666 | alternative host), the message is added to the list of those waiting for this | |
26667 | host, so if it is still undelivered when a subsequent successful delivery is | |
26668 | made to the host, it will be sent down the same SMTP connection. | |
26669 | .nextp | |
26670 | .index message||error | |
26671 | A message error is associated with a particular message when sent to a | |
26672 | particular host, but not with a particular recipient of the message. The | |
26673 | message errors are: | |
26674 | .numberpars $. | |
26675 | Any error response code to \\MAIL\\, \\DATA\\, or the `.' that terminates | |
26676 | the data, | |
26677 | .nextp | |
26678 | Timeout after \\MAIL\\, | |
26679 | .nextp | |
26680 | Timeout | |
26681 | or loss of connection after the `.' that terminates the data. A timeout after | |
26682 | the \\DATA\\ command itself is treated as a host error, as is loss of | |
26683 | connection at any other time. | |
26684 | .endp | |
26685 | For a message error, a permanent error response (5$it{xx}) causes all addresses | |
26686 | to be failed, and a delivery error report to be returned to the sender. A | |
26687 | temporary error response (4$it{xx}), or one of the timeouts, causes all | |
26688 | addresses to be deferred. Retry data is not created for the host, but instead, | |
26689 | a retry record for the combination of host plus message id is created. The | |
26690 | message is not added to the list of those waiting for this host. This ensures | |
26691 | that the failing message will not be sent to this host again until the retry | |
26692 | time arrives. However, other messages that are routed to the host are not | |
26693 | affected, so if it is some property of the message that is causing the error, | |
26694 | it will not stop the delivery of other mail. | |
26695 | ||
26696 | If the remote host specified support for the \\SIZE\\ parameter in its response | |
26697 | to \\EHLO\\, Exim adds SIZE=$it{nnn} to the \\MAIL\\ command, so an | |
26698 | over-large message will cause a message error because the error arrives as a | |
26699 | response to \\MAIL\\. | |
26700 | .nextp | |
26701 | .index recipient||error | |
26702 | A recipient error is associated with a particular recipient of a message. The | |
26703 | recipient errors are: | |
26704 | .numberpars $. | |
26705 | Any error response to \\RCPT\\, | |
26706 | .nextp | |
26707 | Timeout after \\RCPT\\. | |
26708 | .endp | |
26709 | For a recipient error, a permanent error response (5$it{xx}) causes the | |
26710 | recipient address to be failed, and a bounce message to be returned to the | |
26711 | sender. A temporary error response (4$it{xx}) or a timeout causes the failing | |
26712 | address to be deferred, and routing retry data to be created for it. This is | |
26713 | used to delay processing of the address in subsequent queue runs, until its | |
26714 | routing retry time arrives. This applies to all messages, but because it | |
26715 | operates only in queue runs, one attempt will be made to deliver a new message | |
26716 | to the failing address before the delay starts to operate. This ensures that, | |
26717 | if the failure is really related to the message rather than the recipient | |
26718 | (`message too big for this recipient' is a possible example), other messages | |
26719 | have a chance of getting delivered. If a delivery to the address does succeed, | |
26720 | the retry information gets cleared, so all stuck messages get tried again, and | |
26721 | the retry clock is reset. | |
26722 | ||
26723 | The message is not added to the list of those waiting for this host. Use of the | |
26724 | host for other messages is unaffected, and except in the case of a timeout, | |
26725 | other recipients are processed independently, and may be successfully delivered | |
26726 | in the current SMTP session. After a timeout it is of course impossible to | |
26727 | proceed with the session, so all addresses get deferred. However, those other | |
26728 | than the one that failed do not suffer any subsequent retry delays. Therefore, | |
26729 | if one recipient is causing trouble, the others have a chance of getting | |
26730 | through when a subsequent delivery attempt occurs before the failing | |
26731 | recipient's retry time. | |
26732 | .endp | |
26733 | ||
26734 | In all cases, if there are other hosts (or IP addresses) available for the | |
26735 | current set of addresses (for example, from multiple MX records), they are | |
26736 | tried in this run for any undelivered addresses, subject of course to their | |
26737 | own retry data. In other words, recipient error retry data does not take effect | |
26738 | until the next delivery attempt. | |
26739 | ||
26740 | Some hosts have been observed to give temporary error responses to every | |
26741 | \\MAIL\\ command at certain times (`insufficient space' has been seen). It | |
26742 | would be nice if such circumstances could be recognized, and defer data for the | |
26743 | host itself created, but this is not possible within the current Exim design. | |
26744 | What actually happens is that retry data for every (host, message) combination | |
26745 | is created. | |
26746 | ||
26747 | The reason that timeouts after \\MAIL\\ and \\RCPT\\ are treated specially is | |
26748 | that these can sometimes arise as a result of the remote host's verification | |
26749 | procedures. Exim makes this assumption, and treats them as if a temporary error | |
26750 | response had been received. A timeout after `.' is treated specially because it | |
26751 | is known that some broken implementations fail to recognize the end of the | |
26752 | message if the last character of the last line is a binary zero. Thus, it is | |
26753 | helpful to treat this case as a message error. | |
26754 | ||
26755 | Timeouts at other times are treated as host errors, assuming a problem with the | |
26756 | host, or the connection to it. If a timeout after \\MAIL\\, \\RCPT\\, | |
26757 | or `.' is really a connection problem, the assumption is that at the next try | |
26758 | the timeout is likely to occur at some other point in the dialogue, causing it | |
26759 | then to be treated as a host error. | |
26760 | ||
26761 | There is experimental evidence that some MTAs drop the connection after the | |
26762 | terminating `.' if they do not like the contents of the message for some | |
26763 | reason, in contravention of the RFC, which indicates that a 5$it{xx} response | |
26764 | should be given. That is why Exim treats this case as a message rather than a | |
26765 | host error, in order not to delay other messages to the same host. | |
26766 | ||
26767 | ||
26768 | ||
26769 | ||
26770 | .section Variable Envelope Return Paths (VERP) | |
26771 | .index VERP | |
26772 | .index Variable Envelope Return Paths | |
26773 | .index envelope sender | |
26774 | Variable Envelope Return Paths -- see | |
26775 | \?ftp://koobera.math.uic.edu/www/proto/verp.txt?\ -- can be supported in Exim | |
26776 | by using the \return@_path\ generic transport option to rewrite the return path | |
26777 | at transport time. For example, the following could be used on an \%smtp%\ | |
26778 | transport: | |
26779 | .display asis | |
26780 | return_path = \ | |
26781 | ${if match {$return_path}{^(.+?)-request@your.dom.example\$}\ | |
26782 | {$1-request=$local_part%$domain@your.dom.example}fail} | |
26783 | .endd | |
26784 | This has the effect of rewriting the return path (envelope sender) on all | |
26785 | outgoing SMTP messages, if the local part of the original return path ends in | |
26786 | `-request', and the domain is \*your.dom.example*\. The rewriting inserts the | |
26787 | local part and domain of the recipient into the return path. Suppose, for | |
26788 | example, that a message whose return path has been set to | |
26789 | \*somelist-request@@your.dom.example*\ is sent to | |
26790 | \*subscriber@@other.dom.example*\. In the transport, the return path is | |
26791 | rewritten as | |
26792 | .display asis | |
26793 | somelist-request=subscriber%other.dom.example@your.dom.example | |
26794 | .endd | |
26795 | For this to work, you must arrange for outgoing messages that have `-request' | |
26796 | in their return paths to have just a single recipient. This can be done by | |
26797 | setting | |
26798 | .display asis | |
26799 | max_rcpt = 1 | |
26800 | .endd | |
26801 | in the \%smtp%\ transport. Otherwise a single copy of a message might be | |
26802 | addressed to several different recipients in the same domain, in which case | |
26803 | \$local@_part$\ is not available (because it is not unique). Of course, if you | |
26804 | do start sending out messages with this kind of return path, you must also | |
26805 | configure Exim to accept the bounce messages that come back to those paths. | |
26806 | Typically this would be done by setting an \local@_part@_suffix\ option for a | |
26807 | suitable router. | |
26808 | ||
26809 | The overhead incurred in using VERP depends very much on the size of the | |
26810 | message, the number of recipient addresses that resolve to the same remote | |
26811 | host, and the speed of the connection over which the message is being sent. If | |
26812 | a lot of addresses resolve to the same host and the connection is slow, sending | |
26813 | a separate copy of the message for each address may take substantially longer | |
26814 | than sending a single copy with many recipients (for which VERP cannot be | |
26815 | used). | |
26816 | ||
26817 | ||
26818 | .section Incoming SMTP messages over TCP/IP | |
26819 | .index SMTP||incoming over TCP/IP | |
26820 | .index incoming SMTP over TCP/IP | |
26821 | .index inetd | |
26822 | .index daemon | |
26823 | Incoming SMTP messages can be accepted in one of two ways: by running a | |
26824 | listening daemon, or by using \*inetd*\. In the latter case, the entry in | |
26825 | \(/etc/inetd.conf)\ should be like this: | |
26826 | .display asis | |
26827 | smtp stream tcp nowait exim /opt/exim/bin/exim in.exim -bs | |
26828 | .endd | |
26829 | Exim distinguishes between this case and the case of a locally running user | |
26830 | agent using the \-bs-\ option by checking whether or not the standard input is | |
26831 | a socket. When it is, either the port must be privileged (less than 1024), or | |
26832 | the caller must be root or the Exim user. If any other user passes a socket | |
26833 | with an unprivileged port number, Exim prints a message on the standard error | |
26834 | stream and exits with an error code. | |
26835 | ||
26836 | By default, Exim does not make a log entry when a remote host connects or | |
26837 | disconnects (either via the daemon or \*inetd*\), unless the disconnection is | |
26838 | unexpected. It can be made to write such log entries by setting the | |
26839 | \smtp@_connection\ log selector. | |
26840 | ||
26841 | .index carriage return | |
26842 | .index linefeed | |
26843 | Commands from the remote host are supposed to be terminated by CR followed by | |
26844 | LF. However, there are known to be hosts that do not send CR characters. In | |
26845 | order to be able to interwork with such hosts, Exim treats LF on its own as a | |
26846 | line terminator. | |
26847 | Furthermore, because common code is used for receiving messages from all | |
26848 | sources, a CR on its own is also interpreted as a line terminator. However, the | |
26849 | sequence `CR, dot, CR' does not terminate incoming SMTP data. | |
26850 | ||
26851 | .index \\EHLO\\||invalid data | |
26852 | .index \\HELO\\||invalid data | |
26853 | One area that sometimes gives rise to problems concerns the \\EHLO\\ or | |
26854 | \\HELO\\ commands. Some clients send syntactically invalid versions of these | |
26855 | commands, which Exim rejects by default. (This is nothing to do with verifying | |
26856 | the data that is sent, so \helo@_verify@_hosts\ is not relevant.) You can tell | |
26857 | Exim not to apply a syntax check by setting \helo@_accept@_junk@_hosts\ to | |
26858 | match the broken hosts that send invalid commands. | |
26859 | ||
26860 | .index \\SIZE\\ option on \\MAIL\\ command | |
26861 | .index \\MAIL\\||\\SIZE\\ option | |
26862 | The amount of disk space available is checked whenever \\SIZE\\ is received on | |
26863 | a \\MAIL\\ command, independently of whether \message@_size@_limit\ or | |
26864 | \check@_spool@_space\ is configured, unless \smtp__check__spool__space\ is set | |
26865 | false. A temporary error is given if there is not enough space. If | |
26866 | \check@_spool@_space\ is set, the check is for that amount of space plus the | |
26867 | value given with \\SIZE\\, that is, it checks that the addition of the incoming | |
26868 | message will not reduce the space below the threshold. | |
26869 | ||
26870 | When a message is successfully received, Exim includes the local message id in | |
26871 | its response to the final `.' that terminates the data. If the remote host logs | |
26872 | this text it can help with tracing what has happened to a message. | |
26873 | ||
26874 | The Exim daemon can limit the number of simultaneous incoming connections it is | |
26875 | prepared to handle (see the \smtp@_accept@_max\ option). It can also limit the | |
26876 | number of simultaneous incoming connections from a single remote host (see the | |
26877 | \smtp@_accept@_max@_per@_host\ option). Additional connection attempts are | |
26878 | rejected using the SMTP temporary error code 421. | |
26879 | ||
26880 | The Exim daemon does not rely on the \\SIGCHLD\\ signal to detect when a | |
26881 | subprocess has finished, as this can get lost at busy times. Instead, it looks | |
26882 | for completed subprocesses every time it wakes up. Provided there are other | |
26883 | things happening (new incoming calls, starts of queue runs), completed | |
26884 | processes will be noticed and tidied away. On very quiet systems you may | |
26885 | sometimes see a `defunct' Exim process hanging about. This is not a problem; it | |
26886 | will be noticed when the daemon next wakes up. | |
26887 | ||
26888 | When running as a daemon, Exim can reserve some SMTP slots for specific hosts, | |
26889 | and can also be set up to reject SMTP calls from non-reserved hosts at times of | |
26890 | high system load -- for details see the \smtp@_accept@_reserve\, | |
26891 | \smtp@_load@_reserve\, and \smtp@_reserve@_hosts\ options. The load check | |
26892 | applies in both the daemon and \*inetd*\ cases. | |
26893 | ||
26894 | Exim normally starts a delivery process for each message received, though this | |
26895 | can be varied by means of the \-odq-\ command line option and the | |
26896 | \queue@_only\, \queue@_only@_file\, and \queue@_only@_load\ options. The number | |
26897 | of simultaneously running delivery processes started in this way from SMTP | |
26898 | input can be limited by the \smtp__accept__queue\ and | |
26899 | \smtp__accept__queue__per__connection\ options. When either limit is reached, | |
26900 | subsequently received messages are just put on the input queue without starting | |
26901 | a delivery process. | |
26902 | ||
26903 | The controls that involve counts of incoming SMTP calls (\smtp@_accept@_max\, | |
26904 | \smtp@_accept@_queue\, \smtp__accept__reserve\) are not available when Exim is | |
26905 | started up from the \*inetd*\ daemon, because in that case each connection is | |
26906 | handled by an entirely independent Exim process. Control by load average is, | |
26907 | however, available with \*inetd*\. | |
26908 | ||
26909 | Exim can be configured to verify addresses in incoming SMTP commands as they | |
26910 | are received. See chapter ~~CHAPACL for details. It can also be configured to | |
26911 | rewrite addresses at this time -- before any syntax checking is done. See | |
26912 | section ~~SECTrewriteS. | |
26913 | ||
26914 | Exim can also be configured to limit the rate at which a client host submits | |
26915 | \\MAIL\\ and \\RCPT\\ commands in a single SMTP session. See the | |
26916 | \smtp@_ratelimit@_hosts\ option. | |
26917 | ||
26918 | ||
26919 | .section Unrecognized SMTP commands | |
26920 | .index SMTP||unrecognized commands | |
26921 | If Exim receives more than \smtp@_max@_unknown@_commands\ unrecognized SMTP | |
26922 | commands during a single SMTP connection, it drops the connection after sending | |
26923 | the error response to the last command. The default value for | |
26924 | \smtp@_max@_unknown@_commands\ is 3. This is a defence against some kinds of | |
26925 | abuse that subvert web servers into making connections to SMTP ports; in these | |
26926 | circumstances, a number of non-SMTP lines are sent first. | |
26927 | ||
26928 | .section Syntax and protocol errors in SMTP commands | |
26929 | .index SMTP||syntax errors | |
26930 | .index SMTP||protocol errors | |
4964e932 | 26931 | A syntax error is detected if an SMTP command is recognized, but there is |
495ae4b0 PH |
26932 | something syntactically wrong with its data, for example, a malformed email |
26933 | address in a \\RCPT\\ command. Protocol errors include invalid command | |
4964e932 PH |
26934 | sequencing such as \\RCPT\\ before \\MAIL\\. If Exim receives more than |
26935 | \smtp@_max@_synprot@_errors\ such commands during a single SMTP connection, it | |
26936 | drops the connection after sending the error response to the last command. The | |
26937 | default value for \smtp__max__synprot__errors\ is 3. This is a defence against | |
495ae4b0 PH |
26938 | broken clients that loop sending bad commands (yes, it has been seen). |
26939 | ||
26940 | ||
26941 | .section Use of non-mail SMTP commands | |
26942 | .index SMTP||non-mail commands | |
26943 | The `non-mail' SMTP commands are those other than \\MAIL\\, \\RCPT\\, and | |
26944 | \\DATA\\. Exim counts such commands, and drops the connection if there are too | |
26945 | many of them in a single SMTP session. This action catches some | |
26946 | denial-of-service attempts and things like repeated failing \\AUTH\\s, or a mad | |
26947 | client looping sending \\EHLO\\. The global option \smtp@_accept@_max@_nonmail\ | |
26948 | defines what `too many' means. Its default value is 10. | |
26949 | ||
26950 | When a new message is expected, one occurrence of \\RSET\\ is not counted. This | |
26951 | allows a client to send one \\RSET\\ between messages (this is not necessary, | |
26952 | but some clients do it). Exim also allows one uncounted occurence of \\HELO\\ | |
26953 | or \\EHLO\\, and one occurrence of \\STARTTLS\\ between messages. After | |
26954 | starting up a TLS session, another \\EHLO\\ is expected, and so it too is not | |
26955 | counted. | |
26956 | ||
26957 | The first occurrence of \\AUTH\\ in a connection, or immediately following | |
26958 | \\STARTTLS\\ is also not counted. Otherwise, all commands other than \\MAIL\\, | |
26959 | \\RCPT\\, \\DATA\\, and \\QUIT\\ are counted. | |
26960 | ||
26961 | You can control which hosts are subject to the limit set by | |
26962 | \smtp@_accept@_max@_nonmail\ by setting | |
4964e932 | 26963 | \smtp@_accept@_max@_nonmail@_hosts\. The default value is \"$*$"\, which makes |
495ae4b0 PH |
26964 | the limit apply to all hosts. This option means that you can exclude any |
26965 | specific badly-behaved hosts that you have to live with. | |
26966 | ||
26967 | ||
26968 | ||
26969 | .section The \\VRFY\\ and \\EXPN\\ commands | |
26970 | When Exim receives a \\VRFY\\ or \\EXPN\\ command on a TCP/IP connection, it | |
26971 | runs the ACL specified by \acl@_smtp@_vrfy\ or \acl@_smtp@_expn\ (as | |
26972 | appropriate) in order to decide whether the command should be accepted or not. | |
26973 | If no ACL is defined, the command is rejected. | |
26974 | ||
26975 | .index \\VRFY\\||processing | |
26976 | When \\VRFY\\ is accepted, it runs exactly the same code as when Exim is | |
26977 | called with the \-bv-\ option. | |
26978 | .index \\EXPN\\||processing | |
26979 | When \\EXPN\\ is accepted, a single-level expansion of the address is done. | |
26980 | \\EXPN\\ is treated as an `address test' (similar to the \-bt-\ option) rather | |
26981 | than a verification (the \-bv-\ option). If an unqualified local part is given | |
26982 | as the argument to \\EXPN\\, it is qualified with \qualify@_domain\. Rejections | |
26983 | of \\VRFY\\ and \\EXPN\\ commands are logged on the main and reject logs, and | |
26984 | \\VRFY\\ verification failures are logged on the main log for consistency with | |
26985 | \\RCPT\\ failures. | |
26986 | ||
26987 | ||
26988 | .section The \\ETRN\\ command | |
26989 | .rset SECTETRN "~~chapter.~~section" | |
26990 | .index \\ETRN\\||processing | |
26991 | RFC 1985 describes an SMTP command called \\ETRN\\ that is designed to | |
26992 | overcome the security problems of the \\TURN\\ command (which has fallen into | |
26993 | disuse). When Exim receives an \\ETRN\\ command on a TCP/IP connection, it runs | |
26994 | the ACL specified by \acl@_smtp@_etrn\ in order to decide whether the command | |
26995 | should be accepted or not. If no ACL is defined, the command is rejected. | |
26996 | ||
26997 | The \\ETRN\\ command is concerned with `releasing' messages that are awaiting | |
26998 | delivery to certain hosts. As Exim does not organize its message queue by host, | |
26999 | the only form of \\ETRN\\ that is supported by default is the one where the | |
27000 | text starts with the `@#' prefix, in which case the remainder of the text is | |
27001 | specific to the SMTP server. A valid \\ETRN\\ command causes a run of Exim with | |
27002 | the \-R-\ option to happen, with the remainder of the \\ETRN\\ text as its | |
27003 | argument. For example, | |
27004 | .display asis | |
27005 | ETRN #brigadoon | |
27006 | .endd | |
27007 | runs the command | |
27008 | .display asis | |
27009 | exim -R brigadoon | |
27010 | .endd | |
27011 | which causes a delivery attempt on all messages with undelivered addresses | |
27012 | containing the text `brigadoon'. When \smtp@_etrn@_serialize\ is set (the | |
27013 | default), Exim prevents the simultaneous execution of more than one queue run | |
27014 | for the same argument string as a result of an \\ETRN\\ command. This stops | |
27015 | a misbehaving client from starting more than one queue runner at once. | |
27016 | ||
27017 | .index hints database||\\ETRN\\ serialization | |
27018 | Exim implements the serialization by means of a hints database in which a | |
27019 | record is written whenever a process is started by \\ETRN\\, and deleted when | |
27020 | the process completes. However, Exim does not keep the SMTP session waiting for | |
27021 | the \\ETRN\\ process to complete. Once \\ETRN\\ is accepted, the client is sent | |
27022 | a `success' return code. Obviously there is scope for hints records to get left | |
27023 | lying around if there is a system or program crash. To guard against this, Exim | |
27024 | ignores any records that are more than six hours old. | |
27025 | ||
27026 | .index \smtp@_etrn@_command\ | |
27027 | For more control over what \\ETRN\\ does, the \smtp@_etrn@_command\ option can | |
27028 | used. This specifies a command that is run whenever \\ETRN\\ is received, | |
27029 | whatever the form of its argument. For | |
27030 | example: | |
27031 | .display asis | |
27032 | smtp_etrn_command = /etc/etrn_command $domain $sender_host_address | |
27033 | .endd | |
27034 | The string is split up into arguments which are independently expanded. The | |
27035 | expansion variable \$domain$\ is set to the argument of the \\ETRN\\ command, | |
27036 | and no syntax checking is done on the contents of this argument. Exim does not | |
27037 | wait for the command to complete, so its status code is not checked. Exim runs | |
27038 | under its own uid and gid when receiving incoming SMTP, so it is not possible | |
27039 | for it to change them before running the command. | |
27040 | ||
27041 | ||
27042 | .section Incoming local SMTP | |
27043 | .index SMTP||local incoming | |
27044 | Some user agents use SMTP to pass messages to their local MTA using the | |
27045 | standard input and output, as opposed to passing the envelope on the command | |
27046 | line and writing the message to the standard input. This is supported by the | |
27047 | \-bs-\ option. This form of SMTP is handled in the same way as incoming | |
27048 | messages over TCP/IP (including the use of ACLs), except that the envelope | |
27049 | sender given in a \\MAIL\\ command is ignored unless the caller is trusted. In | |
27050 | an ACL you can detect this form of SMTP input by testing for an empty host | |
27051 | identification. It is common to have this as the first line in the ACL that | |
27052 | runs for \\RCPT\\ commands: | |
27053 | .display asis | |
27054 | accept hosts = : | |
27055 | .endd | |
27056 | This accepts SMTP messages from local processes without doing any other tests. | |
27057 | ||
27058 | ||
27059 | .section Outgoing batched SMTP | |
27060 | .rset SECTbatchSMTP "~~chapter.~~section" | |
27061 | .index SMTP||batched outgoing | |
27062 | .index batched SMTP output | |
27063 | Both the \%appendfile%\ and \%pipe%\ transports can be used for handling batched | |
27064 | SMTP. Each has an option called \use@_bsmtp\ which causes messages to be output | |
27065 | in BSMTP format. No SMTP responses are possible for this form of delivery. All | |
27066 | it is doing is using SMTP commands as a way of transmitting the envelope along | |
27067 | with the message. | |
27068 | ||
27069 | The message is written to the file or pipe preceded by the SMTP commands | |
27070 | \\MAIL\\ and \\RCPT\\, and followed by a line containing a single dot. Lines in | |
27071 | the message that start with a dot have an extra dot added. The SMTP command | |
27072 | \\HELO\\ is not normally used. If it is required, the \message@_prefix\ option | |
27073 | can be used to specify it. | |
27074 | ||
27075 | Because \%appendfile%\ and \%pipe%\ are both local transports, they accept only | |
27076 | one recipient address at a time by default. However, you can arrange for them | |
27077 | to handle several addresses at once by setting the \batch@_max\ option. When | |
27078 | this is done for BSMTP, messages may contain multiple \\RCPT\\ commands. See | |
27079 | chapter ~~CHAPbatching for more details. | |
27080 | ||
27081 | When one or more addresses are routed to a BSMTP transport by a router that | |
27082 | sets up a host list, the name of the first host on the list is available to the | |
27083 | transport in the variable \$host$\. Here is an example of such a transport and | |
27084 | router: | |
27085 | .display asis | |
27086 | begin routers | |
27087 | route_append: | |
27088 | driver = manualroute | |
27089 | transport = smtp_appendfile | |
27090 | route_list = domain.example batch.host.example | |
27091 | ||
27092 | begin transports | |
27093 | smtp_appendfile: | |
27094 | driver = appendfile | |
27095 | directory = /var/bsmtp/$host | |
27096 | batch_max = 1000 | |
27097 | use_bsmtp | |
27098 | user = exim | |
27099 | .endd | |
27100 | This causes messages addressed to \*domain.example*\ to be written in BSMTP | |
27101 | format to \(/var/bsmtp/batch.host.example)\, with only a single copy of each | |
27102 | message (unless there are more than 1000 recipients). | |
27103 | ||
27104 | ||
27105 | .section Incoming batched SMTP | |
27106 | .rset SECTincomingbatchedSMTP "~~chapter.~~section" | |
27107 | .index SMTP||batched incoming | |
27108 | .index batched SMTP input | |
27109 | The \-bS-\ command line option causes Exim to accept one or more messages by | |
27110 | reading SMTP on the standard input, but to generate no responses. If the caller | |
27111 | is trusted, the senders in the \\MAIL\\ commands are believed; otherwise the | |
27112 | sender is always the caller of Exim. Unqualified senders and receivers are not | |
27113 | rejected (there seems little point) but instead just get qualified. \\HELO\\ | |
27114 | and \\EHLO\\ act as \\RSET\\; \\VRFY\\, \\EXPN\\, \\ETRN\\ and \\HELP\\, act | |
27115 | as \\NOOP\\; \\QUIT\\ quits. | |
27116 | ||
27117 | No policy checking is done for BSMTP input. That is, no ACL is run at anytime. | |
27118 | In this respect it is like non-SMTP local input. | |
27119 | ||
27120 | If an error is detected while reading a message, including a missing `.' at | |
27121 | the end, Exim gives up immediately. It writes details of the error to the | |
27122 | standard output in a stylized way that the calling program should be able to | |
27123 | make some use of automatically, for example: | |
27124 | .display asis | |
27125 | 554 Unexpected end of file | |
27126 | Transaction started in line 10 | |
27127 | Error detected in line 14 | |
27128 | .endd | |
27129 | It writes a more verbose version, for human consumption, to the standard error | |
27130 | file, for example: | |
27131 | .display asis | |
27132 | An error was detected while processing a file of BSMTP input. | |
27133 | The error message was: | |
27134 | ||
27135 | 501 '>' missing at end of address | |
27136 | ||
27137 | The SMTP transaction started in line 10. | |
27138 | The error was detected in line 12. | |
27139 | The SMTP command at fault was: | |
27140 | ||
27141 | rcpt to:<malformed@in.com.plete | |
27142 | ||
27143 | 1 previous message was successfully processed. | |
27144 | The rest of the batch was abandoned. | |
27145 | .endd | |
27146 | The return code from Exim is zero only if there were no errors. It is 1 if some | |
27147 | messages were accepted before an error was detected, and 2 if no messages were | |
27148 | accepted. | |
27149 | ||
27150 | ||
27151 | ||
495ae4b0 PH |
27152 | . |
27153 | . | |
27154 | . | |
27155 | . | |
27156 | . ============================================================================ | |
d43194df PH |
27157 | .chapter Customizing bounce and warning messages |
27158 | .set runningfoot "customizing messages" | |
27159 | .rset CHAPemsgcust "~~chapter" | |
27160 | When a message fails to be delivered, or remains on the queue for more than a | |
27161 | configured amount of time, Exim sends a message to the original sender, or | |
27162 | to an alternative configured address. The text of these messages is built into | |
27163 | the code of Exim, but it is possible to change it, either by adding a single | |
27164 | string, or by replacing each of the paragraphs by text supplied in a file. | |
495ae4b0 | 27165 | |
d43194df PH |
27166 | The ::From:: and ::To:: header lines are automatically generated; you can cause |
27167 | a ::Reply-To:: line to be added by setting the \errors@_reply@_to\ option. Exim | |
27168 | also adds the line | |
495ae4b0 | 27169 | .display asis |
d43194df | 27170 | Auto-Submitted: auto-generated |
495ae4b0 | 27171 | .endd |
d43194df | 27172 | to all warning and bounce messages, |
495ae4b0 | 27173 | |
d43194df PH |
27174 | .section Customizing bounce messages |
27175 | .index customizing||bounce message | |
27176 | .index bounce message||customizing | |
27177 | If \bounce@_message@_text\ is set, its contents are included in the default | |
27178 | message immediately after `This message was created automatically by mail | |
27179 | delivery software.' The string is not expanded. It is not used if | |
27180 | \bounce@_message@_file\ is set. | |
495ae4b0 | 27181 | |
d43194df PH |
27182 | When \bounce@_message@_file\ is set, it must point to a template file for |
27183 | constructing error messages. The file consists of a series of text items, | |
27184 | separated by lines consisting of exactly four asterisks. If the file cannot be | |
27185 | opened, default text is used and a message is written to the main and panic | |
27186 | logs. If any text item in the file is empty, default text is used for that | |
27187 | item. | |
495ae4b0 | 27188 | |
d43194df PH |
27189 | Each item of text that is read from the file is expanded, and there are two |
27190 | expansion variables which can be of use here: \$bounce@_recipient$\ is set to | |
27191 | the recipient of an error message while it is being created, and | |
27192 | \$return@_size@_limit$\ contains the value of the \return@_size@_limit\ option, | |
27193 | rounded to a whole number. | |
495ae4b0 | 27194 | |
d43194df | 27195 | The items must appear in the file in the following order: |
495ae4b0 | 27196 | .numberpars $. |
d43194df PH |
27197 | The first item is included in the headers, and should include at least a |
27198 | ::Subject:: header. Exim does not check the syntax of these headers. | |
495ae4b0 | 27199 | .nextp |
d43194df PH |
27200 | The second item forms the start of the error message. After it, Exim lists the |
27201 | failing addresses with their error messages. | |
495ae4b0 | 27202 | .nextp |
d43194df PH |
27203 | The third item is used to introduce any text from pipe transports that is to be |
27204 | returned to the sender. It is omitted if there is no such text. | |
495ae4b0 | 27205 | .nextp |
d43194df PH |
27206 | The fourth item is used to introduce the copy of the message that is returned |
27207 | as part of the error report. | |
495ae4b0 | 27208 | .nextp |
d43194df PH |
27209 | The fifth item is added after the fourth one if the returned message is |
27210 | truncated because it is bigger than \return@_size@_limit\. | |
27211 | .nextp | |
27212 | The sixth item is added after the copy of the original message. | |
495ae4b0 | 27213 | .endp |
d43194df PH |
27214 | The default state (\bounce@_message@_file\ unset) is equivalent to the |
27215 | following file, in which the sixth item is empty. The ::Subject:: line has been | |
27216 | split into two here in order to fit it on the page: | |
27217 | .if ~~sys.fancy | |
27218 | .display flow asis | |
27219 | .fontgroup 0 | |
27220 | .font 54 | |
27221 | .else | |
27222 | .rule | |
27223 | .display flow asis | |
27224 | .linelength 80em | |
27225 | .indent 0 | |
27226 | .fi | |
27227 | Subject: Mail delivery failed | |
27228 | ${if eq{$sender_address}{$bounce_recipient}{: returning message to sender}} | |
27229 | **** | |
27230 | This message was created automatically by mail delivery software. | |
495ae4b0 | 27231 | |
d43194df | 27232 | A message ${if eq{$sender_address}{$bounce_recipient}{that you sent }{sent by |
495ae4b0 | 27233 | |
d43194df | 27234 | <$sender_address> |
495ae4b0 | 27235 | |
d43194df PH |
27236 | }}could not be delivered to all of its recipients. |
27237 | The following address(es) failed: | |
27238 | **** | |
27239 | The following text was generated during the delivery attempt(s): | |
27240 | **** | |
27241 | ------ This is a copy of the message, including all the headers. ------ | |
27242 | **** | |
27243 | ------ The body of the message is $message_size characters long; only the first | |
27244 | ------ $return_size_limit or so are included here. | |
27245 | **** | |
27246 | .endd | |
27247 | .if !~~sys.fancy | |
27248 | .rule | |
27249 | .fi | |
495ae4b0 | 27250 | |
d43194df PH |
27251 | .section Customizing warning messages |
27252 | .rset SECTcustwarn "~~chapter.~~section" | |
27253 | .index customizing||warning message | |
27254 | .index warning of delay||customizing the message | |
27255 | The option | |
27256 | \warn@_message@_file\ | |
27257 | can be pointed at a template file for use when | |
27258 | warnings about message delays are created. In this case there are only three | |
27259 | text sections: | |
27260 | .numberpars $. | |
27261 | The first item is included in the headers, and should include at least a | |
27262 | ::Subject:: header. Exim does not check the syntax of these headers. | |
27263 | .nextp | |
27264 | The second item forms the start of the warning message. After it, Exim lists | |
27265 | the delayed addresses. | |
27266 | .nextp | |
27267 | The third item then ends the message. | |
27268 | .endp | |
27269 | The default state is equivalent to the following file, except that the line | |
27270 | starting `A message' has been split here, in order to fit it on the page: | |
27271 | .if ~~sys.fancy | |
495ae4b0 | 27272 | .display asis |
d43194df PH |
27273 | .fontgroup 0 |
27274 | .font 54 | |
27275 | .else | |
27276 | .rule | |
27277 | .display asis | |
27278 | .linelength 80em | |
27279 | .indent 0 | |
27280 | .fi | |
27281 | .newline | |
27282 | Subject: Warning: message $message_id delayed $warn_message_delay | |
27283 | **** | |
27284 | This message was created automatically by mail delivery software. | |
495ae4b0 | 27285 | |
d43194df PH |
27286 | A message ${if eq{$sender_address}{$warn_message_recipients} |
27287 | {that you sent }{sent by | |
495ae4b0 | 27288 | |
d43194df | 27289 | <$sender_address> |
495ae4b0 | 27290 | |
d43194df PH |
27291 | }}has not been delivered to all of its recipients after |
27292 | more than $warn_message_delay on the queue on $primary_hostname. | |
27293 | .newline | |
495ae4b0 | 27294 | |
d43194df PH |
27295 | The message identifier is: $message_id |
27296 | The subject of the message is: $h_subject | |
27297 | The date of the message is: $h_date | |
495ae4b0 | 27298 | |
d43194df PH |
27299 | The following address(es) have not yet been delivered: |
27300 | **** | |
27301 | No action is required on your part. Delivery attempts will continue for | |
27302 | some time, and this warning may be repeated at intervals if the message | |
27303 | remains undelivered. Eventually the mail delivery software will give up, | |
27304 | and when that happens, the message will be returned to you. | |
27305 | .endd | |
27306 | .if !~~sys.fancy | |
27307 | .rule | |
27308 | .fi | |
27309 | except that in the default state the subject and date lines are omitted if no | |
27310 | appropriate headers exist. During the expansion of this file, | |
27311 | \$warn@_message@_delay$\ | |
27312 | is set to the delay time in one of the forms `<<n>> minutes' | |
27313 | or `<<n>> hours', and | |
27314 | \$warn@_message@_recipients$\ | |
27315 | contains a list of recipients for the warning message. There may be more than | |
27316 | one if there are multiple addresses with different \errors@_to\ settings on the | |
27317 | routers that handled them. | |
495ae4b0 | 27318 | |
495ae4b0 | 27319 | |
495ae4b0 PH |
27320 | |
27321 | ||
d43194df PH |
27322 | . |
27323 | . | |
27324 | . | |
27325 | . ============================================================================ | |
27326 | .chapter Some common configuration requirements | |
27327 | .set runningfoot "common configuration requirements" | |
27328 | .rset CHAPcomconreq "~~chapter" | |
27329 | This chapter discusses some configuration requirements that seem to be fairly | |
27330 | common. More examples and discussion can be found in the Exim book. | |
27331 | ||
27332 | ||
27333 | .section Sending mail to a smart host | |
27334 | .index smart host||example router | |
27335 | If you want to send all mail for non-local domains to a `smart host', you | |
27336 | should replace the default \%dnslookup%\ router with a router which does the | |
27337 | routing explicitly: | |
495ae4b0 | 27338 | .display asis |
d43194df PH |
27339 | send_to_smart_host: |
27340 | driver = manualroute | |
27341 | route_list = !+local_domains smart.host.name | |
27342 | transport = remote_smtp | |
495ae4b0 | 27343 | .endd |
d43194df PH |
27344 | You can use the smart host's IP address instead of the name if you wish. |
27345 | .em | |
27346 | If you are using Exim only to submit messages to a smart host, and not for | |
27347 | receiving incoming messages, you can arrange for it to do the submission | |
27348 | synchronously by setting the \mua@_wrapper\ option (see chapter | |
27349 | ~~CHAPnonqueueing). | |
27350 | .nem | |
495ae4b0 PH |
27351 | |
27352 | ||
d43194df PH |
27353 | .section Using Exim to handle mailing lists |
27354 | .rset SECTmailinglists "~~chapter.~~section" | |
27355 | .index mailing lists | |
27356 | Exim can be used to run simple mailing lists, but for large and/or complicated | |
27357 | requirements, the use of additional specialized mailing list software such as | |
27358 | Majordomo or Mailman is recommended. | |
495ae4b0 | 27359 | |
d43194df PH |
27360 | The \%redirect%\ router can be used to handle mailing lists where each list |
27361 | is maintained in a separate file, which can therefore be managed by an | |
27362 | independent manager. The \domains\ router option can be used to run these | |
27363 | lists in a separate domain from normal mail. For example: | |
27364 | .display asis | |
27365 | lists: | |
27366 | driver = redirect | |
27367 | domains = lists.example | |
27368 | file = /usr/lists/$local_part | |
27369 | forbid_pipe | |
27370 | forbid_file | |
27371 | errors_to = $local_part-request@lists.example | |
27372 | no_more | |
27373 | .endd | |
27374 | This router is skipped for domains other than \*lists.example*\. For addresses | |
27375 | in that domain, it looks for a file that matches the local part. If there is no | |
27376 | such file, the router declines, but because \no@_more\ is set, no subsequent | |
27377 | routers are tried, and so the whole delivery fails. | |
495ae4b0 | 27378 | |
d43194df PH |
27379 | The \forbid@_pipe\ and \forbid@_file\ options prevent a local part from being |
27380 | expanded into a file name or a pipe delivery, which is usually inappropriate in | |
27381 | a mailing list. | |
495ae4b0 | 27382 | |
d43194df PH |
27383 | .index \errors@_to\ |
27384 | The \errors@_to\ option specifies that any delivery errors caused by addresses | |
27385 | taken from a mailing list are to be sent to the given address rather than the | |
27386 | original sender of the message. However, before acting on this, Exim verifies | |
27387 | the error address, and ignores it if verification fails. | |
495ae4b0 | 27388 | |
d43194df PH |
27389 | For example, using the configuration above, mail sent to |
27390 | \*dicts@@lists.example*\ is passed on to those addresses contained in | |
27391 | \(/usr/lists/dicts)\, with error reports directed to | |
27392 | \*dicts-request@@lists.example*\, provided that this address can be verified. | |
27393 | There could be a file called \(/usr/lists/dicts-request)\ containing | |
27394 | the address(es) of this particular list's manager(s), but other approaches, | |
27395 | such as setting up an earlier router (possibly using the \local@_part@_prefix\ | |
27396 | or \local@_part@_suffix\ options) to handle addresses of the form \owner-xxx\ | |
27397 | or \xxx-request\, are also possible. | |
495ae4b0 | 27398 | |
495ae4b0 | 27399 | |
d43194df PH |
27400 | .section Syntax errors in mailing lists |
27401 | .index mailing lists||syntax errors in | |
27402 | If an entry in redirection data contains a syntax error, Exim normally defers | |
27403 | delivery of the original address. That means that a syntax error in a mailing | |
27404 | list holds up all deliveries to the list. This may not be appropriate when a | |
27405 | list is being maintained automatically from data supplied by users, and the | |
27406 | addresses are not rigorously checked. | |
495ae4b0 | 27407 | |
d43194df PH |
27408 | If the \skip@_syntax@_errors\ option is set, the \%redirect%\ router just skips |
27409 | entries that fail to parse, noting the incident in the log. If in addition | |
27410 | \syntax@_errors@_to\ is set to a verifiable address, a message is sent to it | |
27411 | whenever a broken address is skipped. It is usually appropriate to set | |
27412 | \syntax@_errors@_to\ to the same address as \errors@_to\. | |
495ae4b0 PH |
27413 | |
27414 | ||
d43194df PH |
27415 | .section Re-expansion of mailing lists |
27416 | .index mailing lists||re-expansion of | |
27417 | Exim remembers every individual address to which a message has been delivered, | |
27418 | in order to avoid duplication, but it normally stores only the original | |
27419 | recipient addresses with a message. If all the deliveries to a mailing list | |
27420 | cannot be done at the first attempt, the mailing list is re-expanded when the | |
27421 | delivery is next tried. This means that alterations to the list are taken into | |
27422 | account at each delivery attempt, so addresses that have been added to | |
27423 | the list since the message arrived will therefore receive a copy of the | |
27424 | message, even though it pre-dates their subscription. | |
495ae4b0 | 27425 | |
d43194df PH |
27426 | If this behaviour is felt to be undesirable, the \one@_time\ option can be set |
27427 | on the \%redirect%\ router. If this is done, any addresses generated by the | |
27428 | router that fail to deliver at the first attempt are added to the message as | |
27429 | `top level' addresses, and the parent address that generated them is marked | |
27430 | `delivered'. Thus, expansion of the mailing list does not happen again at the | |
27431 | subsequent delivery attempts. The disadvantage of this is that if any of the | |
27432 | failing addresses are incorrect, correcting them in the file has no effect on | |
27433 | pre-existing messages. | |
495ae4b0 | 27434 | |
d43194df PH |
27435 | The original top-level address is remembered with each of the generated |
27436 | addresses, and is output in any log messages. However, any intermediate parent | |
27437 | addresses are not recorded. This makes a difference to the log only if the | |
27438 | \all@_parents\ selector is set, but for mailing lists there is normally only | |
27439 | one level of expansion anyway. | |
495ae4b0 PH |
27440 | |
27441 | ||
d43194df PH |
27442 | .section Closed mailing lists |
27443 | .index mailing lists||closed | |
27444 | The examples so far have assumed open mailing lists, to which anybody may | |
27445 | send mail. It is also possible to set up closed lists, where mail is accepted | |
27446 | from specified senders only. This is done by making use of the generic | |
27447 | \senders\ option to restrict the router that handles the list. | |
495ae4b0 | 27448 | |
d43194df PH |
27449 | The following example uses the same file as a list of recipients and as a list |
27450 | of permitted senders. It requires three routers: | |
27451 | .display asis | |
27452 | lists_request: | |
27453 | driver = redirect | |
27454 | domains = lists.example | |
27455 | local_part_suffix = -request | |
27456 | file = /usr/lists/$local_part$local_part_suffix | |
27457 | no_more | |
495ae4b0 | 27458 | |
d43194df PH |
27459 | lists_post: |
27460 | driver = redirect | |
27461 | domains = lists.example | |
27462 | senders = ${if exists {/usr/lists/$local_part}\ | |
27463 | {lsearch;/usr/lists/$local_part}{*}} | |
27464 | file = /usr/lists/$local_part | |
27465 | forbid_pipe | |
27466 | forbid_file | |
27467 | errors_to = $local_part-request@lists.example | |
27468 | no_more | |
495ae4b0 | 27469 | |
d43194df PH |
27470 | lists_closed: |
27471 | driver = redirect | |
27472 | domains = lists.example | |
27473 | allow_fail | |
27474 | data = :fail: $local_part@lists.example is a closed mailing list | |
27475 | .endd | |
27476 | All three routers have the same \domains\ setting, so for any other domains, | |
27477 | they are all skipped. The first router runs only if the local part ends in | |
27478 | \@-request\. It handles messages to the list manager(s) by means of an open | |
27479 | mailing list. | |
27480 | ||
27481 | The second router runs only if the \senders\ precondition is satisfied. It | |
27482 | checks for the existence of a list that corresponds to the local part, and then | |
27483 | checks that the sender is on the list by means of a linear search. It is | |
27484 | necessary to check for the existence of the file before trying to search it, | |
27485 | because otherwise Exim thinks there is a configuration error. If the file does | |
27486 | not exist, the expansion of \senders\ is $*$, which matches all senders. This | |
27487 | means that the router runs, but because there is no list, declines, and | |
27488 | \no@_more\ ensures that no further routers are run. The address fails with an | |
27489 | `unrouteable address' error. | |
27490 | ||
27491 | The third router runs only if the second router is skipped, which happens when | |
27492 | a mailing list exists, but the sender is not on it. This router forcibly fails | |
27493 | the address, giving a suitable error message. | |
27494 | ||
27495 | ||
27496 | ||
27497 | .section Virtual domains | |
27498 | .rset SECTvirtualdomains "~~chapter.~~section" | |
27499 | .index virtual domains | |
27500 | .index domain||virtual | |
27501 | The phrase \*virtual domain*\ is unfortunately used with two rather different | |
27502 | meanings: | |
27503 | .numberpars $. | |
27504 | A domain for which there are no real mailboxes; all valid local parts are | |
27505 | aliases for other email addresses. Common examples are organizational | |
27506 | top-level domains and `vanity' domains. | |
27507 | .nextp | |
27508 | One of a number of independent domains that are all handled by the same host, | |
27509 | with mailboxes on that host, but where the mailbox owners do not necessarily | |
27510 | have login accounts on that host. | |
27511 | .endp | |
27512 | The first usage is probably more common, and does seem more `virtual' than the | |
27513 | second. This kind of domain can be handled in Exim with a straightforward | |
27514 | aliasing router. One approach is to create a separate alias file for each | |
27515 | virtual domain. Exim can test for the existence of the alias file to determine | |
27516 | whether the domain exists. The \%dsearch%\ lookup type is useful here, leading | |
27517 | to a router of this form: | |
27518 | .display asis | |
27519 | virtual: | |
27520 | driver = redirect | |
27521 | domains = dsearch;/etc/mail/virtual | |
27522 | data = ${lookup{$local_part}lsearch{/etc/mail/virtual/$domain}} | |
27523 | no_more | |
27524 | .endd | |
27525 | The \domains\ option specifies that the router is to be skipped, unless there | |
27526 | is a file in the \(/etc/mail/virtual)\ directory whose name is the same as the | |
27527 | domain that is being processed. When the router runs, it looks up the local | |
27528 | part in the file to find a new address (or list of addresses). The \no@_more\ | |
27529 | setting ensures that if the lookup fails (leading to \data\ being an empty | |
27530 | string), Exim gives up on the address without trying any subsequent routers. | |
27531 | ||
27532 | This one router can handle all the virtual domains because the alias file names | |
27533 | follow a fixed pattern. Permissions can be arranged so that appropriate people | |
27534 | can edit the different alias files. A successful aliasing operation results in | |
27535 | a new envelope recipient address, which is then routed from scratch. | |
27536 | ||
27537 | The other kind of `virtual' domain can also be handled in a straightforward | |
27538 | way. One approach is to create a file for each domain containing a list of | |
27539 | valid local parts, and use it in a router like this: | |
27540 | .display asis | |
27541 | my_domains: | |
27542 | driver = accept | |
27543 | domains = dsearch;/etc/mail/domains | |
27544 | local_parts = lsearch;/etc/mail/domains/$domain | |
27545 | transport = my_mailboxes | |
27546 | .endd | |
27547 | The address is accepted if there is a file for the domain, and the local part | |
27548 | can be found in the file. The \domains\ option is used to check for the file's | |
27549 | existence because \domains\ is tested before the \local@_parts\ option (see | |
27550 | section ~~SECTrouprecon). You can't use \require@_files\, because that option | |
27551 | is tested after \local@_parts\. The transport is as follows: | |
27552 | .display asis | |
27553 | my_mailboxes: | |
27554 | driver = appendfile | |
27555 | file = /var/mail/$domain/$local_part | |
27556 | user = mail | |
27557 | .endd | |
27558 | This uses a directory of mailboxes for each domain. The \user\ setting is | |
27559 | required, to specify which uid is to be used for writing to the mailboxes. | |
27560 | ||
27561 | The configuration shown here is just one example of how you might support this | |
27562 | requirement. There are many other ways this kind of configuration can be set | |
27563 | up, for example, by using a database instead of separate files to hold all the | |
27564 | information about the domains. | |
27565 | ||
27566 | ||
27567 | .section Multiple user mailboxes | |
27568 | .rset SECTmulbox "~~chapter.~~section" | |
27569 | .index multiple mailboxes | |
27570 | .index mailbox||multiple | |
27571 | .index local part||prefix | |
27572 | .index local part||suffix | |
27573 | Heavy email users often want to operate with multiple mailboxes, into which | |
27574 | incoming mail is automatically sorted. A popular way of handling this is to | |
27575 | allow users to use multiple sender addresses, so that replies can easily be | |
27576 | identified. Users are permitted to add prefixes or suffixes to their local | |
27577 | parts for this purpose. The wildcard facility of the generic router options | |
27578 | \local@_part@_prefix\ and \local@_part@_suffix\ can be used for this. For | |
27579 | example, consider this router: | |
27580 | .display asis | |
27581 | userforward: | |
27582 | driver = redirect | |
27583 | check_local_user | |
27584 | file = $home/.forward | |
27585 | local_part_suffix = -* | |
27586 | local_part_suffix_optional | |
27587 | allow_filter | |
27588 | .endd | |
27589 | It runs a user's \(.forward)\ file for all local parts of the form | |
27590 | \*username-$*$*\. Within the filter file the user can distinguish different | |
27591 | cases by testing the variable \$local@_part@_suffix$\. For example: | |
27592 | .display asis | |
27593 | if $local_part_suffix contains -special then | |
27594 | save /home/$local_part/Mail/special | |
27595 | endif | |
27596 | .endd | |
27597 | If the filter file does not exist, or does not deal with such addresses, they | |
27598 | fall through to subsequent routers, and, assuming no subsequent use of the | |
27599 | \local@_part@_suffix\ option is made, they presumably fail. Thus, users have | |
27600 | control over which suffixes are valid. | |
27601 | ||
27602 | Alternatively, a suffix can be used to trigger the use of a different | |
27603 | \(.forward)\ file -- which is the way a similar facility is implemented in | |
27604 | another MTA: | |
27605 | .display asis | |
27606 | userforward: | |
27607 | driver = redirect | |
27608 | check_local_user | |
27609 | file = $home/.forward$local_part_suffix | |
27610 | local_part_suffix = -* | |
27611 | local_part_suffix_optional | |
27612 | allow_filter | |
27613 | .endd | |
27614 | If there is no suffix, \(.forward)\ is used; if the suffix is \*-special*\, for | |
27615 | example, \(.forward-special)\ is used. Once again, if the appropriate file | |
27616 | does not exist, or does not deal with the address, it is passed on to | |
27617 | subsequent routers, which could, if required, look for an unqualified | |
27618 | \(.forward)\ file to use as a default. | |
27619 | ||
27620 | ||
27621 | .section Simplified vacation processing | |
27622 | .index vacation processing | |
27623 | The traditional way of running the \*vacation*\ program is for a user to set up | |
27624 | a pipe command in a \(.forward)\ file | |
27625 | (see section ~~SECTspecitredli for syntax details). | |
27626 | This is prone to error by inexperienced users. There are two features of Exim | |
27627 | that can be used to make this process simpler for users: | |
27628 | .numberpars $. | |
27629 | A local part prefix such as `vacation-' can be specified on a router which | |
27630 | can cause the message to be delivered directly to the \*vacation*\ program, or | |
27631 | alternatively can use Exim's \%autoreply%\ transport. The contents of a user's | |
27632 | \(.forward)\ file are then much simpler. For example: | |
27633 | .display asis | |
27634 | spqr, vacation-spqr | |
27635 | .endd | |
27636 | .nextp | |
27637 | The \require@_files\ generic router option can be used to trigger a | |
27638 | vacation delivery by checking for the existence of a certain file in the | |
27639 | user's home directory. The \unseen\ generic option should also be used, to | |
27640 | ensure that the original delivery also proceeds. In this case, all the user has | |
27641 | to do is to create a file called, say, \(.vacation)\, containing a vacation | |
27642 | message. | |
27643 | .endp | |
27644 | Another advantage of both these methods is that they both work even when the | |
27645 | use of arbitrary pipes by users is locked out. | |
495ae4b0 | 27646 | |
495ae4b0 | 27647 | |
d43194df PH |
27648 | .section Taking copies of mail |
27649 | .index message||copying every | |
27650 | Some installations have policies that require archive copies of all messages to | |
27651 | be made. A single copy of each message can easily be taken by an appropriate | |
27652 | command in a system filter, which could, for example, use a different file for | |
27653 | each day's messages. | |
495ae4b0 | 27654 | |
d43194df PH |
27655 | There is also a shadow transport mechanism that can be used to take copies of |
27656 | messages that are successfully delivered by local transports, one copy per | |
27657 | delivery. This could be used, $it{inter alia}, to implement automatic | |
27658 | notification of delivery by sites that insist on doing such things. | |
495ae4b0 PH |
27659 | |
27660 | ||
d43194df PH |
27661 | .section Intermittently connected hosts |
27662 | .index intermittently connected hosts | |
27663 | It has become quite common (because it is cheaper) for hosts to connect to the | |
27664 | Internet periodically rather than remain connected all the time. The normal | |
27665 | arrangement is that mail for such hosts accumulates on a system that is | |
27666 | permanently connected. | |
495ae4b0 | 27667 | |
d43194df PH |
27668 | Exim was designed for use on permanently connected hosts, and so it is not |
27669 | particularly well-suited to use in an intermittently connected environment. | |
27670 | Nevertheless there are some features that can be used. | |
495ae4b0 | 27671 | |
d43194df PH |
27672 | .section Exim on the upstream server host |
27673 | It is tempting to arrange for incoming mail for the intermittently connected | |
27674 | host to remain on Exim's queue until the client connects. However, this | |
27675 | approach does not scale very well. Two different kinds of waiting message are | |
27676 | being mixed up in the same queue -- those that cannot be delivered because of | |
27677 | some temporary problem, and those that are waiting for their destination host | |
27678 | to connect. This makes it hard to manage the queue, as well as wasting | |
27679 | resources, because each queue runner scans the entire queue. | |
495ae4b0 | 27680 | |
d43194df PH |
27681 | A better approach is to separate off those messages that are waiting for an |
27682 | intermittently connected host. This can be done by delivering these messages | |
27683 | into local files in batch SMTP, `mailstore', or other envelope-preserving | |
27684 | format, from where they are transmitted by other software when their | |
27685 | destination connects. This makes it easy to collect all the mail for one host | |
27686 | in a single directory, and to apply local timeout rules on a per-message basis | |
27687 | if required. | |
495ae4b0 | 27688 | |
d43194df PH |
27689 | On a very small scale, leaving the mail on Exim's queue can be made to work. If |
27690 | you are doing this, you should configure Exim with a long retry period for the | |
27691 | intermittent host. For example: | |
27692 | .display | |
27693 | cheshire.wonderland.fict.example * F,5d,24h | |
495ae4b0 | 27694 | .endd |
d43194df PH |
27695 | This stops a lot of failed delivery attempts from occurring, but Exim remembers |
27696 | which messages it has queued up for that host. Once the intermittent host comes | |
27697 | online, forcing delivery of one message (either by using the \-M-\ or \-R-\ | |
27698 | options, or by using the \\ETRN\\ SMTP command (see section ~~SECTETRN) | |
27699 | causes all the queued up messages to be delivered, often down a single SMTP | |
27700 | connection. While the host remains connected, any new messages get delivered | |
27701 | immediately. | |
495ae4b0 | 27702 | |
d43194df PH |
27703 | If the connecting hosts do not have fixed IP addresses, that is, if a host is |
27704 | issued with a different IP address each time it connects, Exim's retry | |
27705 | mechanisms on the holding host get confused, because the IP address is normally | |
27706 | used as part of the key string for holding retry information. This can be | |
27707 | avoided by unsetting \retry__include__ip__address\ on the \%smtp%\ transport. | |
27708 | Since this has disadvantages for permanently connected hosts, it is best to | |
27709 | arrange a separate transport for the intermittently connected ones. | |
495ae4b0 PH |
27710 | |
27711 | ||
d43194df PH |
27712 | .section Exim on the intermittently connected client host |
27713 | The value of \smtp@_accept@_queue@_per@_connection\ should probably be | |
27714 | increased, or even set to zero (that is, disabled) on the intermittently | |
27715 | connected host, so that all incoming messages down a single connection get | |
27716 | delivered immediately. | |
495ae4b0 | 27717 | |
d43194df PH |
27718 | .index SMTP||passed connection |
27719 | .index SMTP||multiple deliveries | |
27720 | .index multiple SMTP deliveries | |
27721 | Mail waiting to be sent from an intermittently connected host will probably | |
27722 | not have been routed, because without a connection DNS lookups are not | |
27723 | possible. This means that if a normal queue run is done at connection time, | |
27724 | each message is likely to be sent in a separate SMTP session. This can be | |
27725 | avoided by starting the queue run with a command line option beginning with | |
27726 | \-qq-\ instead of \-q-\. In this case, the queue is scanned twice. In the first | |
27727 | pass, routing is done but no deliveries take place. The second pass is a normal | |
27728 | queue run; since all the messages have been previously routed, those destined | |
27729 | for the same host are likely to get sent as multiple deliveries in a single | |
27730 | SMTP connection. | |
495ae4b0 | 27731 | |
495ae4b0 PH |
27732 | |
27733 | ||
d43194df PH |
27734 | . |
27735 | . | |
27736 | . | |
27737 | . | |
27738 | . ============================================================================ | |
27739 | .chapter Using Exim as a non-queueing client | |
27740 | .set runningfoot "non-queueing client" | |
27741 | .rset CHAPnonqueueing "~~chapter" | |
27742 | .index client, non-queueing | |
27743 | .index smart host||queueing, suppressing | |
27744 | .em | |
27745 | On a personal computer, it is a common requirement for all | |
27746 | email to be sent to a `smart host'. There are plenty of MUAs that can be | |
27747 | configured to operate that way, for all the popular operating systems. | |
27748 | However, there are some MUAs for Unix-like systems that cannot be so | |
27749 | configured: they submit messages using the command line interface of | |
27750 | \(/usr/sbin/sendmail)\. Furthermore, utility programs such as \*cron*\ submit | |
27751 | messages this way. | |
27752 | ||
27753 | If the personal computer runs continuously, there is no problem, because it can | |
27754 | run a conventional MTA that handles delivery to the smart host, and deal with | |
27755 | any delays via its queueing mechanism. However, if the computer does not run | |
27756 | continuously or runs different operating systems at different times, queueing | |
27757 | email is not desirable. | |
27758 | ||
27759 | There is therefore a requirement for something that can provide the | |
27760 | \(/usr/sbin/sendmail)\ interface but deliver messages to a smart host without | |
27761 | any queueing or retrying facilities. Furthermore, the delivery to the smart | |
27762 | host should be synchronous, so that if it fails, the sending MUA is immediately | |
27763 | informed. In other words, we want something that extends an MUA that submits | |
27764 | to a local MTA via the command line so that it behaves like one that submits | |
27765 | to a remote smart host using TCP/SMTP. | |
27766 | ||
27767 | There are a number of applications (for example, there is one called \*ssmtp*\) | |
27768 | that do this job. However, people have found them to be lacking in various | |
27769 | ways. For instance, you might want to allow aliasing and forwarding to be done | |
27770 | before sending a message to the smart host. | |
27771 | ||
27772 | Exim already had the necessary infrastructure for doing this job. Just a few | |
27773 | tweaks were needed to make it behave as required, though it is somewhat of an | |
27774 | overkill to use a fully-featured MTA for this purpose. | |
27775 | ||
27776 | .index \mua@_wrapper\ | |
27777 | There is a Boolean global option called \mua@_wrapper\, defaulting false. | |
27778 | Setting \mua@_wrapper\ true causes Exim to run in a special mode where it | |
27779 | assumes that it is being used to `wrap' a command-line MUA in the manner | |
27780 | just described. As well as setting \mua@_wrapper\, you also need to provide a | |
27781 | compatible router and transport configuration. Typically there will be just one | |
27782 | router and one transport, sending everything to a smart host. | |
27783 | ||
27784 | When run in MUA wrapping mode, the behaviour of Exim changes in the | |
27785 | following ways: | |
27786 | .numberpars alpha | |
27787 | A daemon cannot be run, nor will Exim accept incoming messages from \*inetd*\. | |
27788 | In other words, the only way to submit messages is via the command line. | |
27789 | .nextp | |
27790 | Each message is synchonously delivered as soon as it is received (\-odi-\ is | |
27791 | assumed). All queueing options (\queue@_only\, \queue@_smtp@_domains\, | |
27792 | \control\ in an ACL, etc.) are quietly ignored. The Exim reception process does | |
27793 | not finish until the delivery attempt is complete. If the delivery is | |
27794 | successful, a zero return code is given. | |
27795 | .nextp | |
27796 | Address redirection is permitted, but the final routing for all addresses must | |
27797 | be to the same remote transport, and to the same list of hosts. Furthermore, | |
27798 | the return address (envelope sender) must be the same for all recipients, as | |
27799 | must any added or deleted header lines. In other words, it must be possible to | |
27800 | deliver the message in a single SMTP transaction, however many recipients there | |
27801 | are. | |
27802 | .nextp | |
27803 | If these conditions are not met, or if routing any address results in a failure | |
27804 | or defer status, or if Exim is unable to deliver all the recipients | |
27805 | successfully to one of the smart hosts, delivery of the entire message fails. | |
27806 | .nextp | |
27807 | Because no queueing is allowed, all failures are treated as permanent; there is | |
27808 | no distinction between 4\*xx*\ and 5\*xx*\ SMTP response codes from the smart | |
27809 | host. Furthermore, because only a single yes/no response can be given to the | |
27810 | caller, it is not possible to deliver to some recipients and not others. If | |
27811 | there is an error (temporary or permanent) for any recipient, all are failed. | |
27812 | .nextp | |
27813 | If more than one smart host is listed, Exim will try another host after a | |
27814 | connection failure or a timeout, in the normal way. However, if this kind of | |
27815 | failure happens for all the hosts, the delivery fails. | |
27816 | .nextp | |
27817 | When delivery fails, an error message is written to the standard error stream | |
27818 | (as well as to Exim's log), and Exim exits to the caller with a return code | |
27819 | value 1. The message is expunged from Exim's spool files. No bounce messages | |
27820 | are ever generated. | |
27821 | .nextp | |
27822 | No retry data is maintained, and any retry rules are ignored. | |
27823 | .nextp | |
27824 | A number of Exim options are overridden: \deliver@_drop@_privilege\ is forced | |
27825 | true, \max@_rcpt\ in the smtp transport is forced to `unlimited', | |
27826 | \remote@_max@_parallel\ is forced to one, and fallback hosts are ignored. | |
27827 | .endp | |
27828 | The overall effect is that Exim makes a single synchronous attempt to deliver | |
27829 | the message, failing if there is any kind of problem. Because no local | |
27830 | deliveries are done and no daemon can be run, Exim does not need root | |
27831 | privilege. It should be possible to run it setuid to \*exim*\ instead of setuid | |
27832 | to \*root*\. See section ~~SECTrunexiwitpri for a general discussion about the | |
27833 | advantages and disadvantages of running without root privilege. | |
27834 | .nem | |
495ae4b0 PH |
27835 | |
27836 | ||
27837 | ||
27838 | . | |
27839 | . | |
27840 | . | |
27841 | . | |
27842 | . ============================================================================ | |
27843 | .chapter Log files | |
27844 | .set runningfoot "log files" | |
27845 | .rset CHAPlog "~~chapter" | |
27846 | .index log||types of | |
27847 | .index log||general description | |
27848 | Exim writes three different logs, referred to as the main log, the reject log, | |
27849 | and the panic log: | |
27850 | .numberpars $. | |
27851 | .index main log | |
27852 | The main log records the arrival of each message and each delivery in a single | |
27853 | line in each case. The format is as compact as possible, in an attempt to keep | |
27854 | down the size of log files. Two-character flag sequences make it easy to pick | |
27855 | out these lines. A number of other events are recorded in the main log. Some of | |
27856 | them are optional, in which case the \log@_selector\ option controls whether | |
27857 | they are included or not. A Perl script called \*eximstats*\, which does simple | |
27858 | analysis of main log files, is provided in the Exim distribution (see section | |
27859 | ~~SECTmailstat). | |
27860 | .nextp | |
27861 | .index reject log | |
27862 | The reject log records information from messages that are rejected as a result | |
4964e932 | 27863 | of a configuration option (that is, for policy reasons). |
495ae4b0 PH |
27864 | The first line of each rejection is a copy of the line that is also written to |
27865 | the main log. Then, if the message's header has been read at the time the log | |
27866 | is written, its contents are written to this log. Only the original header | |
27867 | lines are available; header lines added by ACLs are not logged. You can use the | |
27868 | reject log to check that your policy controls are working correctly; on a busy | |
27869 | host this may be easier than scanning the main log for rejection messages. You | |
27870 | can suppress the writing of the reject log by setting \write@_rejectlog\ false. | |
495ae4b0 PH |
27871 | .nextp |
27872 | .index panic log | |
27873 | .index system log | |
27874 | When certain serious errors occur, Exim writes entries to its panic log. If the | |
27875 | error is sufficiently disastrous, Exim bombs out afterwards. Panic log entries | |
27876 | are usually written to the main log as well, but can get lost amid the mass of | |
27877 | other entries. The panic log should be empty under normal circumstances. It is | |
27878 | therefore a good idea to check it (or to have a \*cron*\ script check it) | |
27879 | regularly, in order to become aware of any problems. When Exim cannot open its | |
27880 | panic log, it tries as a last resort to write to the system log (syslog). This | |
27881 | is opened with LOG@_PID+LOG@_CONS and the facility code of LOG@_MAIL. The | |
27882 | message itself is written at priority LOG@_CRIT. | |
27883 | .endp | |
27884 | Every log line starts with a timestamp, in the format shown in this example: | |
27885 | .display asis | |
27886 | 2001-09-16 16:09:47 SMTP connection from [127.0.0.1] closed by QUIT | |
27887 | .endd | |
4964e932 | 27888 | By default, the timestamps are in the local timezone. There are two |
495ae4b0 PH |
27889 | ways of changing this: |
27890 | .numberpars $. | |
27891 | You can set the \timezone\ option to a different time zone; in particular, if | |
27892 | you set | |
27893 | .display asis | |
27894 | timezone = UTC | |
27895 | .endd | |
27896 | the timestamps will be in UTC (aka GMT). | |
27897 | .nextp | |
4964e932 | 27898 | If you set \log@_timezone\ true, the time zone is added to the timestamp, for |
495ae4b0 PH |
27899 | example: |
27900 | .display asis | |
27901 | 2003-04-25 11:17:07 +0100 Start queue run: pid=12762 | |
27902 | .endd | |
27903 | .endp | |
27904 | ||
27905 | ||
27906 | ||
27907 | .section Where the logs are written | |
27908 | .rset SECTwhelogwri "~~chapter.~~section" | |
27909 | .index log||destination | |
27910 | .index log||to file | |
27911 | .index log||to syslog | |
27912 | .index syslog | |
27913 | The logs may be written to local files, or to syslog, or both. However, it | |
27914 | should be noted that many syslog implementations use UDP as a transport, and | |
27915 | are therefore unreliable in the sense that messages are not guaranteed to | |
27916 | arrive at the loghost, nor is the ordering of messages necessarily maintained. | |
27917 | It has also been reported that on large log files (tens of megabytes) you may | |
27918 | need to tweak syslog to prevent it syncing the file with each write -- on Linux | |
27919 | this has been seen to make syslog take 90% plus of CPU time. | |
27920 | ||
27921 | The destination for Exim's logs is configured by setting \\LOG@_FILE@_PATH\\ in | |
27922 | \(Local/Makefile)\ or by setting \log@_file@_path\ in the run time | |
27923 | configuration. This latter string is expanded, so it can contain, for example, | |
27924 | references to the host name: | |
27925 | .display asis | |
27926 | log_file_path = /var/log/$primary_hostname/exim_%slog | |
27927 | .endd | |
27928 | It is generally advisable, however, to set the string in \(Local/Makefile)\ | |
27929 | rather than at run time, because then the setting is available right from the | |
27930 | start of Exim's execution. Otherwise, if there's something it wants to log | |
27931 | before it has read the configuration file (for example, an error in the | |
27932 | configuration file) it will not use the path you want, and may not be able to | |
27933 | log at all. | |
27934 | ||
27935 | The value of \\LOG@_FILE@_PATH\\ or \log@_file@_path\ is a colon-separated | |
27936 | list, currently limited to at most two items. This is one option where the | |
27937 | facility for changing a list separator may not be used. The list must always be | |
27938 | colon-separated. If an item in the list is `syslog' then syslog is used; | |
27939 | otherwise the item must either be an absolute path, containing \"%s"\ at the | |
27940 | point where `main', `reject', or `panic' is to be inserted, or be empty, | |
27941 | implying the use of a default path. | |
27942 | ||
27943 | When Exim encounters an empty item in the list, it searches the list defined by | |
27944 | \\LOG@_FILE@_PATH\\, and uses the first item it finds that is neither empty nor | |
27945 | `syslog'. This means that an empty item in \log@_file@_path\ can be used to | |
27946 | mean `use the path specified at build time'. It no such item exists, log files | |
27947 | are written in the \(log)\ subdirectory of the spool directory. This is | |
27948 | equivalent to the setting: | |
27949 | .display asis | |
27950 | log_file_path = $spool_directory/log/%slog | |
27951 | .endd | |
4964e932 | 27952 | If you do not specify anything at build time or run time, that is where the |
495ae4b0 PH |
27953 | logs are written. |
27954 | ||
27955 | A log file path may also contain \"%D"\ if datestamped log file names are in | |
27956 | use -- see section ~~SECTdatlogfil below. | |
27957 | ||
27958 | Here are some examples of possible settings: | |
27959 | .display | |
27960 | .tabs 42 | |
27961 | LOG@_FILE@_PATH=syslog $t $rm{syslog only} | |
27962 | LOG@_FILE@_PATH=:syslog $t $rm{syslog and default path} | |
27963 | LOG@_FILE@_PATH=syslog : /usr/log/exim@_%s $t $rm{syslog and specified path} | |
27964 | LOG@_FILE@_PATH=/usr/log/exim@_%s $t $rm{specified path only} | |
27965 | .endd | |
27966 | If there are more than two paths in the list, the first is used and a panic | |
27967 | error is logged. | |
27968 | ||
27969 | ||
27970 | .section Logging to local files that are periodically `cycled' | |
27971 | .index log||cycling local files | |
27972 | .index cycling logs | |
27973 | .index \*exicyclog*\ | |
27974 | .index log||local files, writing to | |
27975 | Some operating systems provide centralized and standardised methods for cycling | |
27976 | log files. For those that do not, a utility script called \*exicyclog*\ is | |
27977 | provided (see section ~~SECTcyclogfil). This renames and compresses the main | |
27978 | and reject logs each time it is called. The maximum number of old logs to keep | |
27979 | can be set. It is suggested this script is run as a daily \*cron*\ job. | |
27980 | ||
27981 | An Exim delivery process opens the main log when it first needs to write to it, | |
27982 | and it keeps the file open in case subsequent entries are required -- for | |
27983 | example, if a number of different deliveries are being done for the same | |
27984 | message. However, remote SMTP deliveries can take a long time, and this means | |
27985 | that the file may be kept open long after it is renamed if \*exicyclog*\ or | |
27986 | something similar is being used to rename log files on a regular basis. To | |
27987 | ensure that a switch of log files is noticed as soon as possible, Exim calls | |
27988 | \*stat()*\ on the main log's name before reusing an open file, and if the file | |
27989 | does not exist, or its inode has changed, the old file is closed and Exim | |
27990 | tries to open the main log from scratch. Thus, an old log file may remain open | |
27991 | for quite some time, but no Exim processes should write to it once it has been | |
27992 | renamed. | |
27993 | ||
27994 | ||
27995 | .section Datestamped log files | |
27996 | .rset SECTdatlogfil "~~chapter.~~section" | |
27997 | .index log||datestamped files | |
27998 | Instead of cycling the main and reject log files by renaming them | |
27999 | periodically, some sites like to use files whose names contain a datestamp, | |
28000 | for example, \(mainlog-20031225)\. The datestamp is in the form \(yyyymmdd)\. | |
28001 | Exim has support for this way of working. It is enabled by setting the | |
28002 | \log@_file@_path\ option to a path that includes \"%D"\ at the point where the | |
28003 | datestamp is required. For example: | |
28004 | .display asis | |
28005 | log_file_path = /var/spool/exim/log/%slog-%D | |
28006 | log_file_path = /var/log/exim-%s-%D.log | |
28007 | log_file_path = /var/spool/exim/log/%D-%slog | |
28008 | .endd | |
28009 | As before, \"%s"\ is replaced by `main' or `reject'; the following are examples | |
28010 | of names generated by the above examples: | |
28011 | .display asis | |
28012 | /var/spool/exim/log/mainlog-20021225 | |
28013 | /var/log/exim-reject-20021225.log | |
28014 | /var/spool/exim/log/20021225-mainlog | |
28015 | .endd | |
28016 | When this form of log file is specified, Exim automatically switches to new | |
28017 | files at midnight. It does not make any attempt to compress old logs; you | |
28018 | will need to write your own script if you require this. You should not | |
28019 | run \*exicyclog*\ with this form of logging. | |
28020 | ||
28021 | The location of the panic log is also determined by \log@_file@_path\, but it | |
28022 | is not datestamped, because rotation of the panic log does not make sense. | |
28023 | When generating the name of the panic log, \"%D"\ is removed from the string. | |
28024 | In addition, if it immediately follows a slash, a following non-alphanumeric | |
28025 | character is removed; otherwise a preceding non-alphanumeric character is | |
28026 | removed. Thus, the three examples above would give these panic log names: | |
28027 | .display asis | |
28028 | /var/spool/exim/log/paniclog | |
28029 | /var/log/exim-panic.log | |
28030 | /var/spool/exim/log/paniclog | |
28031 | .endd | |
28032 | ||
28033 | ||
28034 | .section Logging to syslog | |
28035 | .index log||syslog, writing to | |
28036 | The use of syslog does not change what Exim logs or the format of its messages, | |
28037 | except in one respect. If \syslog@_timestamp\ is set false, the timestamps on | |
28038 | Exim's log lines are omitted when these lines are sent to syslog. Apart from | |
28039 | that, the same strings are written to syslog as to log files. The syslog | |
28040 | `facility' is set to \\LOG@_MAIL\\, and the program name to `exim' | |
28041 | by default, but you can change these by setting the \syslog@_facility\ and | |
28042 | \syslog@_processname\ options, respectively. If Exim was compiled with | |
4964e932 | 28043 | \\SYSLOG@_LOG@_PID\\ set in \(Local/Makefile)\ (this is the default in |
495ae4b0 PH |
28044 | \(src/EDITME)\), then, on systems that permit it (all except ULTRIX), the |
28045 | \\LOG@_PID\\ flag is set so that the \*syslog()*\ call adds the pid as well as | |
28046 | the time and host name to each line. | |
28047 | The three log streams are mapped onto syslog priorities as follows: | |
28048 | .numberpars " " | |
28049 | \*mainlog*\ is mapped to \\LOG@_INFO\\ | |
28050 | .nextp | |
28051 | \*rejectlog*\ is mapped to \\LOG@_NOTICE\\ | |
28052 | .nextp | |
28053 | \*paniclog*\ is mapped to \\LOG@_ALERT\\ | |
28054 | .endp | |
4964e932 | 28055 | Many log lines are written to both \*mainlog*\ and \*rejectlog*\, and some are |
495ae4b0 | 28056 | written to both \*mainlog*\ and \*paniclog*\, so there will be duplicates if |
4964e932 | 28057 | these are routed by syslog to the same place. You can suppress this duplication |
495ae4b0 PH |
28058 | by setting \syslog@_duplication\ false. |
28059 | ||
28060 | Exim's log lines can sometimes be very long, and some of its \*rejectlog*\ | |
28061 | entries contain multiple lines when headers are included. To cope with both | |
28062 | these cases, entries written to syslog are split into separate \*syslog()*\ | |
4964e932 | 28063 | calls at each internal newline, and also after a maximum of |
495ae4b0 PH |
28064 | 870 data characters. (This allows for a total syslog line length of 1024, when |
28065 | additions such as timestamps are added.) If you are running a syslog | |
28066 | replacement that can handle lines longer than the 1024 characters allowed by | |
28067 | RFC 3164, you should set | |
28068 | .display asis | |
28069 | SYSLOG_LONG_LINES=yes | |
28070 | .endd | |
4964e932 | 28071 | in \(Local/Makefile)\ before building Exim. That stops Exim from splitting long |
495ae4b0 PH |
28072 | lines, but it still splits at internal newlines in \*reject*\ log entries. |
28073 | ||
28074 | To make it easy to re-assemble split lines later, each component of a split | |
28075 | entry starts with a string of the form `[<<n>>/<<m>>]' or `[<<n>>@\<<m>>]' | |
28076 | where <<n>> is the component number and <<m>> is the total number of components | |
28077 | in the entry. The / delimiter is used when the line was split because it was | |
28078 | too long; if it was split because of an internal newline, the @\ delimiter is | |
28079 | used. For example, supposing the length limit to be 70 instead of 1000, the | |
28080 | following would be the result of a typical rejection message to \*mainlog*\ | |
28081 | (LOG@_INFO), each line in addition being preceded by the time, host name, and | |
28082 | pid as added by syslog: | |
28083 | .display | |
28084 | .indent 0 | |
28085 | $smc{[1/3] 2002-09-16 16:09:43 16RdAL-0006pc-00 rejected from [127.0.0.1] (ph10): | |
28086 | [2/3] syntax error in 'From' header when scanning for sender: missing or ma | |
28087 | [3/3] lformed local part in "<>" (envelope sender is <ph10@@cam.example>)} | |
28088 | .endd | |
28089 | The same error might cause the following lines to be written to `rejectlog' | |
28090 | (LOG@_NOTICE): | |
28091 | .display flow | |
28092 | .indent 0 | |
28093 | $smc{[1/14] 2002-09-16 16:09:43 16RdAL-0006pc-00 rejected from [127.0.0.1] (ph10): | |
28094 | [2/14] syntax error in 'From' header when scanning for sender: missing or ma | |
28095 | [3@\14] lformed local part in "@<@>" (envelope sender is <ph10@@cam.example>) | |
28096 | [4@\14] Recipients: ph10@@some.domain.cam.example | |
28097 | [5@\14] P Received: from [127.0.0.1] (ident=ph10) | |
28098 | [6@\14] by xxxxx.cam.example with smtp (Exim 4.00) | |
28099 | [7@\14] id 16RdAL-0006pc-00 | |
28100 | [8@\14] for ph10@@cam.example; Mon, 16 Sep 2002 16:09:43 +0100 | |
28101 | [9@\14] F From: @<@> | |
28102 | [10@\14] Subject: this is a test header | |
28103 | [11@\14] X-something: this is another header | |
28104 | [12@\14] I Message-Id: <E16RdAL-0006pc-00@@xxxxx.cam.example> | |
28105 | [13@\14] B Bcc: | |
28106 | [14/14] Date: Mon, 16 Sep 2002 16:09:43 +0100} | |
28107 | .endd | |
28108 | Log lines that are neither too long nor contain newlines are written to syslog | |
28109 | without modification. | |
28110 | ||
28111 | If only syslog is being used, the Exim monitor is unable to provide a log tail | |
28112 | display, unless syslog is routing \*mainlog*\ to a file on the local host and | |
28113 | the environment variable \\EXIMON@_LOG@_FILE@_PATH\\ is set to tell the monitor | |
28114 | where it is. | |
28115 | ||
28116 | ||
28117 | .section Log line flags | |
28118 | One line is written to the main log for each message received, and for each | |
28119 | successful, unsuccessful, and delayed delivery. These lines can readily be | |
28120 | picked out by the distinctive two-character flags that immediately follow the | |
28121 | timestamp. The flags are: | |
28122 | .display | |
28123 | .tabs 6 | |
28124 | <= $t $rm{message arrival} | |
28125 | => $t $rm{normal message delivery} | |
28126 | -> $t $rm{additional address in same delivery} | |
28127 | *> $t $rm{delivery suppressed by \-N-\} | |
28128 | ** $t $rm{delivery failed; address bounced} | |
28129 | == $t $rm{delivery deferred; temporary problem} | |
28130 | .endd | |
28131 | ||
28132 | ||
28133 | .section Logging message reception | |
28134 | .index log||reception line | |
28135 | The format of the single-line entry in the main log that is written for every | |
28136 | message received is shown in the basic example below, which is split over | |
28137 | several lines in order to fit it on the page: | |
28138 | .display | |
28139 | .indent 0 | |
28140 | 2002-10-31 08:57:53 16ZCW1-0005MB-00 <= kryten@@dwarf.fict.example | |
28141 | H=mailer.fict.example [192.168.123.123] U=exim | |
28142 | P=smtp S=5678 id=<<incoming message id>> | |
28143 | .endd | |
28144 | The address immediately following `<=' is the envelope sender address. A bounce | |
28145 | message is shown with the sender address `<>', and if it is locally generated, | |
28146 | this is followed by an item of the form | |
28147 | .display | |
28148 | R=<<message id>> | |
28149 | .endd | |
28150 | which is a reference to the message that caused the bounce to be sent. | |
28151 | ||
28152 | .index \\HELO\\ | |
28153 | .index \\EHLO\\ | |
28154 | For messages from other hosts, the H and U fields identify the remote host and | |
28155 | record the RFC 1413 identity of the user that sent the message, if one was | |
28156 | received. The number given in square brackets is the IP address of the sending | |
28157 | host. If there is a single, unparenthesized host name in the H field, as | |
28158 | above, it has been verified to correspond to the IP address (see the | |
28159 | \host@_lookup\ option). If the name is in parentheses, it was the name quoted | |
28160 | by the remote host in the SMTP \\HELO\\ or \\EHLO\\ command, and has not been | |
28161 | verified. If verification yields a different name to that given for \\HELO\\ or | |
28162 | \\EHLO\\, the verified name appears first, followed by the \\HELO\\ or \\EHLO\\ | |
28163 | name in parentheses. | |
28164 | ||
28165 | Misconfigured hosts (and mail forgers) sometimes put an IP address, with or | |
28166 | without brackets, in the \\HELO\\ or \\EHLO\\ command, leading to entries in | |
28167 | the log containing text like these examples: | |
28168 | .display | |
28169 | H=(10.21.32.43) [192.168.8.34] | |
28170 | H=([10.21.32.43]) [192.168.8.34] | |
28171 | .endd | |
28172 | This can be confusing. Only the final address in square brackets can be relied | |
28173 | on. | |
28174 | ||
28175 | For locally generated messages (that is, messages not received over TCP/IP), | |
28176 | the H field is omitted, and the U field contains the login name of the caller | |
28177 | of Exim. | |
28178 | ||
28179 | .index authentication||logging | |
28180 | .index \\AUTH\\||logging | |
28181 | For all messages, the P field specifies the protocol used to receive the | |
d43194df PH |
28182 | message. This is set to |
28183 | .em | |
28184 | `esmtpa' | |
28185 | .nem | |
28186 | for messages received from hosts that have authenticated themselves using the | |
28187 | SMTP \\AUTH\\ command. In this case there is an additional item A= followed by | |
28188 | the name of the authenticator that was used. If an authenticated identification | |
28189 | was set up by the authenticator's \server@_set@_id\ option, this is logged too, | |
28190 | separated by a colon from the authenticator name. | |
495ae4b0 PH |
28191 | |
28192 | The id field records the existing message id, if present. | |
28193 | .index size||of message | |
28194 | The size of the received message is given by the S field. When the message is | |
28195 | delivered, headers may get removed or added, so that the size of delivered | |
28196 | copies of the message may not correspond with this value (and indeed may be | |
28197 | different to each other). | |
28198 | ||
28199 | The \log@_selector\ option can be used to request the logging of additional | |
28200 | data when a message is received. See section ~~SECTlogselector below. | |
28201 | ||
28202 | ||
28203 | .section Logging deliveries | |
28204 | .index log||delivery line | |
28205 | The format of the single-line entry in the main log that is written for every | |
28206 | delivery is shown in one of the examples below, for local and remote deliveries, | |
28207 | respectively. Each example has been split into two lines in order to fit | |
28208 | it on the page: | |
28209 | .display | |
28210 | .indent 0 | |
28211 | 2002-10-31 08:59:13 16ZCW1-0005MB-00 => marv <marv@@hitch.fict.example> | |
28212 | R=localuser T=local@_delivery | |
28213 | 2002-10-31 09:00:10 16ZCW1-0005MB-00 => monk@@holistic.fict.example | |
28214 | R=dnslookup T=remote@_smtp H=holistic.fict.example [192.168.234.234] | |
28215 | .endd | |
28216 | For ordinary local deliveries, the original address is given in angle brackets | |
28217 | after the final delivery address, which might be a pipe or a file. If | |
28218 | intermediate address(es) exist between the original and the final address, the | |
28219 | last of these is given in parentheses after the final address. The R and T | |
28220 | fields record the router and transport that were used to process the address. | |
28221 | ||
28222 | If a shadow transport was run after a successful local delivery, the log line | |
28223 | for the successful delivery has an item added on the end, of the form | |
28224 | .display | |
28225 | ST=<<shadow transport name>> | |
28226 | .endd | |
28227 | If the shadow transport did not succeed, the error message is put in | |
28228 | parentheses afterwards. | |
28229 | ||
28230 | When more than one address is included in a single delivery (for example, two | |
28231 | SMTP \\RCPT\\ commands in one transaction) the second and subsequent | |
28232 | addresses are flagged with `$tt{@-@>}' instead of `$tt{@=@>}'. When two or more | |
28233 | messages are delivered down a single SMTP connection, an asterisk follows the | |
28234 | IP address in the log lines for the second and subsequent messages. | |
28235 | ||
28236 | The generation of a reply message by a filter file gets logged as a `delivery' | |
28237 | to the addressee, preceded by `>'. | |
28238 | ||
28239 | The \log@_selector\ option can be used to request the logging of additional | |
28240 | data when a message is delivered. See section ~~SECTlogselector below. | |
28241 | ||
28242 | ||
28243 | .section Discarded deliveries | |
28244 | .index discarded messages | |
28245 | .index message||discarded | |
28246 | .index delivery||discarded, logging | |
28247 | When a message is discarded as a result of the command `seen finish' being | |
28248 | obeyed in a filter file which generates no deliveries, a log entry of the form | |
28249 | .display | |
28250 | 2002-12-10 00:50:49 16auJc-0001UB-00 => discarded | |
28251 | <low.club@@bridge.example> R=userforward | |
28252 | .endd | |
28253 | is written, to record why no deliveries are logged. When a message is discarded | |
28254 | because it is aliased to `:blackhole:' the log line is like this: | |
28255 | .display asis | |
28256 | 1999-03-02 09:44:33 10HmaX-0005vi-00 => :blackhole: | |
28257 | <hole@nowhere.example> R=blackhole_router | |
28258 | .endd | |
28259 | ||
28260 | ||
28261 | .section Deferred deliveries | |
28262 | When a delivery is deferred, a line of the following form is logged: | |
28263 | .display | |
28264 | .indent 0 | |
28265 | 2002-12-19 16:20:23 16aiQz-0002Q5-00 == marvin@@endrest.example | |
28266 | R=dnslookup T=smtp defer (146): Connection refused | |
28267 | .endd | |
28268 | In the case of remote deliveries, the error is the one that was given for the | |
28269 | last IP address that was tried. Details of individual SMTP failures are also | |
28270 | written to the log, so the above line would be preceded by something like | |
28271 | .display | |
28272 | .indent 0 | |
28273 | 2002-12-19 16:20:23 16aiQz-0002Q5-00 Failed to connect to | |
28274 | mail1.endrest.example [192.168.239.239]: Connection refused | |
28275 | .endd | |
28276 | When a deferred address is skipped because its retry time has not been reached, | |
28277 | a message is written to the log, but this can be suppressed by setting an | |
28278 | appropriate value in \log@_selector\. | |
28279 | ||
28280 | ||
28281 | .section Delivery failures | |
28282 | .index delivery||failure, logging | |
28283 | If a delivery fails because an address cannot be routed, a line of the | |
28284 | following form is logged: | |
28285 | .display asis | |
28286 | .indent 0 | |
28287 | 1995-12-19 16:20:23 0tRiQz-0002Q5-00 ** jim@trek99.example | |
28288 | <jim@trek99.example>: unknown mail domain | |
28289 | .endd | |
4964e932 | 28290 | If a delivery fails at transport time, the router and transport are shown, and |
495ae4b0 PH |
28291 | the response from the remote host is included, as in this example: |
28292 | .display asis | |
28293 | .indent 0 | |
28294 | 2002-07-11 07:14:17 17SXDU-000189-00 ** ace400@pb.example R=dnslookup | |
28295 | .newline | |
495ae4b0 PH |
28296 | T=remote_smtp: SMTP error from remote mailer after pipelined |
28297 | .newline | |
4964e932 PH |
28298 | RCPT TO:<ace400@pb.example>: host pbmail3.py.example |
28299 | [192.168.63.111]: 553 5.3.0 <ace400@pb.example>... | |
495ae4b0 PH |
28300 | Addressee unknown |
28301 | .endd | |
4964e932 PH |
28302 | The word `pipelined' indicates that the SMTP \\PIPELINING\\ extension was being |
28303 | used. See \hosts@_avoid@_esmtp\ in the \%smtp%\ transport for a way of | |
495ae4b0 | 28304 | disabling \\PIPELINING\\. |
495ae4b0 PH |
28305 | |
28306 | The log lines for all forms of delivery failure are flagged with \"**"\. | |
28307 | ||
28308 | ||
28309 | .section Fake deliveries | |
28310 | .index delivery||fake, logging | |
28311 | If a delivery does not actually take place because the \-N-\ option has been | |
28312 | used to suppress it, a normal delivery line is written to the log, except that | |
28313 | `=>' is replaced by `$*$>'. | |
28314 | ||
28315 | ||
28316 | .section Completion | |
28317 | A line of the form | |
28318 | .display | |
28319 | 2002-10-31 09:00:11 16ZCW1-0005MB-00 Completed | |
28320 | .endd | |
28321 | is written to the main log when a message is about to be removed from the spool | |
28322 | at the end of its processing. | |
28323 | ||
28324 | ||
28325 | ||
28326 | .section Summary of Fields in Log Lines | |
28327 | .index log||summary of fields | |
28328 | A summary of the field identifiers that are used in log lines is shown in | |
28329 | the following table: | |
28330 | .display flow | |
28331 | .tabs 8 | |
28332 | A $t $rm{authenticator name (and optional id)} | |
28333 | C $t $rm{SMTP confirmation on delivery} | |
495ae4b0 PH |
28334 | CV $t $rm{certificate verification status} |
28335 | DN $t $rm{distinguished name from peer certificate} | |
d43194df PH |
28336 | .newline |
28337 | .em | |
28338 | DT $t $rm{on \"=>"\ lines: time taken for a delivery} | |
28339 | .nem | |
495ae4b0 | 28340 | .newline |
495ae4b0 PH |
28341 | F $t $rm{sender address (on delivery lines)} |
28342 | H $t $rm{host name and IP address} | |
495ae4b0 | 28343 | I $t $rm{local interface used} |
495ae4b0 PH |
28344 | id $t $rm{message id for incoming message} |
28345 | P $t $rm{on \"<="\ lines: protocol used} | |
28346 | .newline | |
d43194df PH |
28347 | .em |
28348 | $t $rm{on \"=>"\ and \"**"\ lines: return path} | |
28349 | QT $t $rm{on \"=>"\ lines: time spent on queue so far} | |
28350 | $t $rm{on `Completed' lines: time spent on queue} | |
28351 | .nem | |
28352 | .newline | |
495ae4b0 | 28353 | R $t $rm{on \"<="\ lines: reference for local bounce} |
d43194df PH |
28354 | .newline |
28355 | .em | |
28356 | $t $rm{on \"=>"\ \"**"\ and \"=="\ lines: router name} | |
28357 | .nem | |
28358 | .newline | |
495ae4b0 PH |
28359 | S $t $rm{size of message} |
28360 | ST $t $rm{shadow transport name} | |
28361 | T $t $rm{on \"<="\ lines: message subject (topic)} | |
d43194df PH |
28362 | .newline |
28363 | .em | |
28364 | $t $rm{on \"=>"\ \"**"\ and \"=="\ lines: transport name} | |
28365 | .nem | |
28366 | .newline | |
495ae4b0 PH |
28367 | U $t $rm{local user or RFC 1413 identity} |
28368 | X $t $rm{TLS cipher suite} | |
28369 | .endd | |
28370 | ||
28371 | ||
28372 | .section Other log entries | |
28373 | Various other types of log entry are written from time to time. Most should be | |
28374 | self-explanatory. Among the more common are: | |
28375 | .numberpars $. | |
28376 | .index retry||time not reached | |
28377 | \*retry time not reached*\##An address previously suffered a temporary error | |
28378 | during routing or local delivery, and the time to retry has not yet arrived. | |
28379 | This message is not written to an individual message log file unless it happens | |
28380 | during the first delivery attempt. | |
28381 | .nextp | |
28382 | \*retry time not reached for any host*\##An address previously suffered | |
28383 | temporary errors during remote delivery, and the retry time has not yet arrived | |
28384 | for any of the hosts to which it is routed. | |
28385 | .nextp | |
28386 | .index spool directory||file locked | |
28387 | \*spool file locked*\##An attempt to deliver a message cannot proceed because | |
28388 | some other Exim process is already working on the message. This can be quite | |
28389 | common if queue running processes are started at frequent intervals. The | |
28390 | \*exiwhat*\ utility script can be used to find out what Exim processes are | |
28391 | doing. | |
28392 | .nextp | |
495ae4b0 | 28393 | .index error||ignored |
4964e932 | 28394 | \*error ignored*\##There are several circumstances that give rise to this |
495ae4b0 PH |
28395 | message: |
28396 | .numberpars " " | |
4964e932 | 28397 | Exim failed to deliver a bounce message whose age was greater than |
495ae4b0 PH |
28398 | \ignore__bounce__errors__after\. The bounce was discarded. |
28399 | .nextp | |
4964e932 | 28400 | A filter file set up a delivery using the `noerror' option, and the delivery |
495ae4b0 PH |
28401 | failed. The delivery was discarded. |
28402 | .nextp | |
4964e932 | 28403 | A delivery set up by a router configured with |
495ae4b0 PH |
28404 | .display asis |
28405 | errors_to = <> | |
28406 | .endd | |
28407 | failed. The delivery was discarded. | |
4964e932 | 28408 | .endp |
495ae4b0 PH |
28409 | .endp |
28410 | ||
28411 | ||
28412 | ||
28413 | .section Reducing or increasing what is logged | |
28414 | .rset SECTlogselector "~~chapter.~~section" | |
28415 | .index log||selectors | |
28416 | By setting the \log@_selector\ global option, you can disable some of Exim's | |
28417 | default logging, or you can request additional logging. The value of | |
28418 | \log@_selector\ is made up of names preceded by plus or minus characters. For | |
28419 | example: | |
28420 | .display asis | |
28421 | log_selector = +arguments -retry_defer | |
28422 | .endd | |
28423 | The list of optional log items is in the following table, with the default | |
28424 | selection marked by asterisks: | |
28425 | .display flow | |
28426 | .tabs 32 | |
28427 | address@_rewrite $t $rm{address rewriting} | |
28428 | all@_parents $t $rm{all parents in => lines} | |
28429 | arguments $t $rm{command line arguments} | |
28430 | *connection@_reject $t $rm{connection rejections} | |
4964e932 | 28431 | *delay@_delivery $t $rm{immediate delivery delayed} |
495ae4b0 | 28432 | deliver@_time $t $rm{time taken to perform delivery} |
495ae4b0 PH |
28433 | delivery@_size $t $rm{add S=nnn to => lines} |
28434 | *dnslist@_defer $t $rm{defers of DNS list (aka RBL) lookups} | |
28435 | *etrn $t $rm{ETRN commands} | |
28436 | *host@_lookup@_failed $t $rm{as it says} | |
495ae4b0 | 28437 | ident@_timeout $t $rm{timeout for ident connection} |
495ae4b0 PH |
28438 | incoming@_interface $t $rm{incoming interface on <= lines} |
28439 | incoming@_port $t $rm{incoming port on <= lines} | |
28440 | *lost@_incoming@_connection $t $rm{as it says (includes timeouts)} | |
495ae4b0 | 28441 | outgoing@_port $t $rm{add remote port to => lines} |
495ae4b0 PH |
28442 | *queue@_run $t $rm{start and end queue runs} |
28443 | .newline | |
d43194df PH |
28444 | .em |
28445 | queue@_time $t $rm{time on queue for one recipient} | |
28446 | queue@_time@_overall $t $rm{time on queue for whole message} | |
28447 | .nem | |
495ae4b0 | 28448 | .newline |
495ae4b0 PH |
28449 | received@_recipients $t $rm{recipients on <= lines} |
28450 | received@_sender $t $rm{sender on <= lines} | |
28451 | *rejected@_header $t $rm{header contents on reject log} | |
28452 | *retry@_defer $t $rm{`retry time not reached'} | |
495ae4b0 | 28453 | return@_path@_on@_delivery $t $rm{put return path on => and ** lines} |
495ae4b0 PH |
28454 | sender@_on@_delivery $t $rm{add sender to => lines} |
28455 | *size@_reject $t $rm{rejection because too big} | |
4964e932 | 28456 | *skip@_delivery $t $rm{delivery skipped in a queue run} |
495ae4b0 | 28457 | smtp@_confirmation $t $rm{SMTP confirmation on => lines} |
495ae4b0 PH |
28458 | smtp@_connection $t $rm{SMTP connections} |
28459 | smtp@_incomplete@_transaction $t $rm{incomplete SMTP transactions} | |
28460 | smtp@_protocol@_error $t $rm{SMTP protocol errors} | |
28461 | smtp@_syntax@_error $t $rm{SMTP syntax errors} | |
28462 | subject $t $rm{contents of ::Subject:: on <= lines} | |
495ae4b0 | 28463 | tls@_certificate@_verified $t $rm{certificate verification status} |
495ae4b0 PH |
28464 | *tls@_cipher $t $rm{TLS cipher suite on <= and => lines} |
28465 | tls@_peerdn $t $rm{TLS peer DN on <= and => lines} | |
28466 | ||
28467 | all $t $rm{all of the above} | |
28468 | .endd | |
28469 | More details on each of these items follows: | |
28470 | .numberpars $. | |
28471 | .index log||rewriting | |
28472 | .index rewriting||logging | |
28473 | \address@_rewrite\: This applies both to global rewrites and per-transport | |
28474 | rewrites, | |
4964e932 | 28475 | but not to rewrites in filters run as an unprivileged user (because such users |
495ae4b0 | 28476 | cannot access the log). |
495ae4b0 PH |
28477 | .nextp |
28478 | .index log||full parentage | |
28479 | \all@_parents\: Normally only the original and final addresses are logged on | |
28480 | delivery lines; with this selector, intermediate parents are given in | |
28481 | parentheses between them. | |
28482 | .nextp | |
28483 | .index log||Exim arguments | |
28484 | .index Exim arguments, logging | |
28485 | \arguments\: This causes Exim to write the arguments with which it was called | |
28486 | to the main log, | |
28487 | preceded by the current working directory. | |
28488 | This is a debugging feature, added to make it easier to find out how certain | |
28489 | MUAs call \(/usr/sbin/sendmail)\. The logging does not happen if Exim has given | |
4964e932 PH |
28490 | up root privilege because it was called with the \-C-\ or \-D-\ options. |
28491 | Arguments that are empty or that contain whitespace are quoted. Non-printing | |
495ae4b0 PH |
28492 | characters are shown as escape sequences. |
28493 | This facility cannot log unrecognized arguments, because the arguments are | |
28494 | checked before the configuration file is read. The only way to log such cases | |
28495 | is to interpose a script such as \(util/logargs.sh)\ between the caller and | |
28496 | Exim. | |
28497 | .nextp | |
28498 | .index log||connection rejections | |
28499 | \connection@_reject\: A log entry is written whenever an incoming SMTP | |
28500 | connection is rejected, for whatever reason. | |
28501 | .nextp | |
28502 | .index log||delayed delivery | |
28503 | .index delayed delivery, logging | |
28504 | \delay@_delivery\: A log entry is written whenever a delivery process is not | |
28505 | started for an incoming message because the load is too high or too many | |
28506 | messages were received on one connection. Logging does not occur if no delivery | |
28507 | process is started because \queue@_only\ is set or \-odq-\ was used. | |
28508 | .nextp | |
495ae4b0 PH |
28509 | .index log||delivery duration |
28510 | \deliver@_time\: For each delivery, the amount of real time it has taken to | |
28511 | perform the actual delivery is logged as DT=<<time>>, for example, \"DT=1s"\. | |
495ae4b0 PH |
28512 | .nextp |
28513 | .index log||message size on delivery | |
28514 | .index size||of message | |
28515 | \delivery@_size\: For each delivery, the size of message delivered is added to | |
28516 | the `=>' line, tagged with S=. | |
28517 | .nextp | |
28518 | .index log||dnslist defer | |
28519 | .index DNS list||logging defer | |
28520 | .index black list (DNS) | |
28521 | \dnslist@_defer\: A log entry is written if an attempt to look up a host in a | |
28522 | DNS black list suffers a temporary error. | |
28523 | .nextp | |
28524 | .index log||ETRN commands | |
28525 | .index \\ETRN\\||logging | |
28526 | \etrn\: Every legal ETRN command that is received is logged, before the ACL is | |
28527 | run to determine whether or not it is actually accepted. An invalid ETRN | |
28528 | command, or one received within a message transaction is not logged by this | |
28529 | selector (see \smtp@_syntax@_error\ and \smtp@_protocol@_error\). | |
28530 | .nextp | |
28531 | .index log||host lookup failure | |
28532 | \host@_lookup@_failed\: When a lookup of a host's IP addresses fails to find | |
28533 | any addresses, or when a lookup of an IP address fails to find a host name, a | |
28534 | log line is written. This logging does not apply to direct DNS lookups when | |
28535 | routing email addresses, but it does apply to `byname' lookups. | |
28536 | .nextp | |
495ae4b0 PH |
28537 | .index log||ident timeout |
28538 | .index RFC 1413||logging timeout | |
28539 | \ident@_timeout\: A log line is written whenever an attempt to connect to a | |
28540 | client's ident port times out. | |
495ae4b0 PH |
28541 | .nextp |
28542 | .index log||incoming interface | |
28543 | .index interface||logging | |
28544 | \incoming@_interface\: The interface on which a message was received is added | |
28545 | to the `<=' line as an IP address in square brackets, tagged by I= and followed | |
28546 | by a colon and the port number. | |
495ae4b0 PH |
28547 | The local interface and port are also added to other SMTP log |
28548 | lines, for example `SMTP connection from', and to rejection lines. | |
495ae4b0 PH |
28549 | .nextp |
28550 | .index log||incoming remote port | |
28551 | .index port||logging remote | |
28552 | .index TCP/IP||logging incoming remote port | |
28553 | \incoming@_port\: The remote port number from which a message was received is | |
28554 | added to log entries and ::Received:: header lines, following the IP address in | |
28555 | square brackets, and separated from it by a colon. This is implemented by | |
28556 | changing the value that is put in the \$sender@_fullhost$\ and | |
28557 | \$sender@_rcvhost$\ variables. Recording the remote port number has become more | |
28558 | important with the widening use of NAT (see RFC 2505). | |
28559 | .nextp | |
28560 | .index log||dropped connection | |
28561 | \lost@_incoming@_connection\: A log line is written when an incoming SMTP | |
28562 | connection is unexpectedly dropped. | |
28563 | .nextp | |
495ae4b0 PH |
28564 | .index log||outgoing remote port |
28565 | .index port||logging outgoint remote | |
28566 | .index TCP/IP||logging ougtoing remote port | |
28567 | \outgoing@_port\: The remote port number is added to delivery log lines (those | |
28568 | containing => tags) following the IP address. This option is not included in | |
28569 | the default setting, because for most ordinary configurations, the remote port | |
28570 | number is always 25 (the SMTP port). | |
495ae4b0 PH |
28571 | .nextp |
28572 | .index log||queue run | |
28573 | .index queue runner||logging | |
28574 | \queue@_run\: The start and end of every queue run are logged. | |
28575 | .nextp | |
495ae4b0 PH |
28576 | .index log||queue time |
28577 | \queue@_time\: The amount of time the message has been in the queue on the | |
d43194df PH |
28578 | local host is logged as QT=<<time>> |
28579 | .em | |
28580 | on delivery (\"=>"\) lines, for example, \"QT=3m45s"\. The clock starts when | |
28581 | Exim starts to receive the message, so it includes reception time as well as | |
28582 | the delivery time for the current address. This means that it may be longer | |
28583 | than the difference between the arrival and delivery log line times, because | |
28584 | the arrival log line is not written until the message has been successfully | |
28585 | received. | |
28586 | .nem | |
28587 | ||
28588 | .nextp | |
28589 | .em | |
28590 | \queue@_time@_overall\: The amount of time the message has been in the queue on | |
28591 | the local host is logged as QT=<<time>> on `Completed' lines, for | |
28592 | example, \"QT=3m45s"\. The clock starts when Exim starts to receive the | |
28593 | message, so it includes reception time as well as the total delivery time. | |
28594 | .nem | |
495ae4b0 PH |
28595 | .nextp |
28596 | .index log||recipients | |
28597 | \received@_recipients\: The recipients of a message are listed in the main log | |
28598 | as soon as the message is received. The list appears at the end of the log line | |
28599 | that is written when a message is received, preceded by the word `for'. The | |
28600 | addresses are listed after they have been qualified, but before any rewriting | |
28601 | has taken place. | |
28602 | Recipients that were discarded by an ACL for \\MAIL\\ or \\RCPT\\ do not appear | |
28603 | in the list. | |
28604 | .nextp | |
28605 | .index log||sender reception | |
28606 | \received@_sender\: The unrewritten original sender of a message is added to | |
28607 | the end of the log line that records the message's arrival, after the word | |
28608 | `from' (before the recipients if \received@_recipients\ is also set). | |
28609 | .nextp | |
28610 | .index log||header lines for rejection | |
28611 | \rejected@_header\: If a message's header has been received at the time a | |
28612 | rejection is written to the reject log, the complete header is added to the | |
28613 | log. Header logging can be turned off individually for messages that are | |
28614 | rejected by the \*local@_scan()*\ function (see section ~~SECTapiforloc). | |
28615 | .nextp | |
28616 | .index log||retry defer | |
28617 | \retry@_defer\: A log line is written if a delivery is deferred because a retry | |
28618 | time has not yet been reached. However, this `retry time not reached' message | |
28619 | is always omitted from individual message logs after the first delivery | |
28620 | attempt. | |
28621 | .nextp | |
28622 | .index log||return path | |
4964e932 | 28623 | \return@_path@_on@_delivery\: The return path that is being transmitted with |
495ae4b0 | 28624 | the message is included in delivery and bounce lines, using the tag P=. |
d43194df PH |
28625 | .em |
28626 | This is omitted if no delivery actually happens, for example, if routing fails, | |
28627 | or if delivery is to \(/dev/null)\ or to \":blackhole:"\. | |
28628 | .nem | |
495ae4b0 PH |
28629 | .nextp |
28630 | .index log||sender on delivery | |
28631 | \sender@_on@_delivery\: The message's sender address is added to every delivery | |
28632 | and bounce line, tagged by F= (for `from'). | |
4964e932 | 28633 | This is the original sender that was received with the message; it is not |
495ae4b0 | 28634 | necessarily the same as the outgoing return path. |
495ae4b0 PH |
28635 | .nextp |
28636 | .index log||size rejection | |
28637 | \size@_reject\: A log line is written whenever a message is rejected because it | |
28638 | is too big. | |
28639 | .nextp | |
28640 | .index log||frozen messages, skipped | |
28641 | .index frozen messages||logging skipping | |
28642 | \skip@_delivery\: A log line is written whenever a message is skipped during a | |
28643 | queue run because it is frozen or because another process is already delivering | |
28644 | it. | |
d43194df PH |
28645 | .em |
28646 | .index `spool file is locked' | |
28647 | The message that is written is `spool file is locked'. | |
28648 | .nem | |
495ae4b0 PH |
28649 | .nextp |
28650 | .index log||smtp confirmation | |
28651 | .index SMTP||logging confirmation | |
28652 | \smtp@_confirmation\: The response to the final `.' in the SMTP dialogue for | |
28653 | outgoing messages is added to delivery log lines in the form `C="<<text>>"'. A | |
28654 | number of MTAs (including Exim) return an identifying string in this response. | |
28655 | .nextp | |
28656 | .index log||SMTP connections | |
28657 | .index SMTP||logging connections | |
28658 | \smtp@_connection\: A log line is written whenever an SMTP connection is | |
d43194df PH |
28659 | established or closed, |
28660 | .em | |
28661 | unless the connection is from a host that matches \hosts@_connection@_nolog\. | |
28662 | .nem | |
28663 | (In contrast, \lost__incoming__connection\ applies only when the closure is | |
28664 | unexpected.) This applies to connections from local processes that use \-bs-\ | |
28665 | as well as to TCP/IP connections. If a connection is dropped in the middle of a | |
28666 | message, a log line is always written, whether or not this selector is set, but | |
28667 | otherwise nothing is written at the start and end of connections unless this | |
28668 | selector is enabled. | |
495ae4b0 PH |
28669 | |
28670 | For TCP/IP connections to an Exim daemon, the current number of connections is | |
28671 | included in the log message for each new connection, but note that the count is | |
28672 | reset if the daemon is restarted. | |
4964e932 PH |
28673 | Also, because connections are closed (and the closure is logged) in |
28674 | subprocesses, the count may not include connections that have been closed but | |
28675 | whose termination the daemon has not yet noticed. Thus, while it is possible to | |
28676 | match up the opening and closing of connections in the log, the value of the | |
495ae4b0 PH |
28677 | logged counts may not be entirely accurate. |
28678 | .nextp | |
28679 | .index log||SMTP transaction, incomplete | |
28680 | .index SMTP||logging incomplete transactions | |
28681 | \smtp@_incomplete@_transaction\: When a mail transaction is aborted by | |
28682 | \\RSET\\, \\QUIT\\, loss of connection, or otherwise, the incident is logged, | |
28683 | and the message sender plus any accepted recipients are included in the log | |
28684 | line. This can provide evidence of dictionary attacks. | |
28685 | .nextp | |
28686 | .index log||SMTP protocol error | |
28687 | .index SMTP||logging protocol error | |
28688 | \smtp@_protocol@_error\: A log line is written for every SMTP protocol error | |
28689 | encountered. | |
4964e932 PH |
28690 | Exim does not have perfect detection of all protocol errors because of |
28691 | transmission delays and the use of pipelining. If \\PIPELINING\\ has been | |
28692 | advertised to a client, an Exim server assumes that the client will use it, and | |
495ae4b0 PH |
28693 | therefore it does not count `expected' errors (for example, \\RCPT\\ received |
28694 | after rejecting \\MAIL\\) as protocol errors. | |
495ae4b0 PH |
28695 | .nextp |
28696 | .index SMTP||logging syntax errors | |
28697 | .index SMTP||syntax errors, logging | |
28698 | .index SMTP||unknown command, logging | |
28699 | .index log||unknown SMTP command | |
28700 | .index log||SMTP syntax error | |
28701 | \smtp@_syntax@_error\: A log line is written for every SMTP syntax error | |
28702 | encountered. An unrecognized command is treated as a syntax error. For an | |
28703 | external connection, the host identity is given; for an internal connection | |
28704 | using \-bs-\ the sender identification (normally the calling user) is given. | |
28705 | .nextp | |
28706 | .index log||subject | |
28707 | .index subject, logging | |
28708 | \subject\: The subject of the message is added to the arrival log line, | |
28709 | preceded by `T=' (T for `topic', since S is already used for `size'). | |
4964e932 PH |
28710 | Any MIME `words' in the subject are decoded. The \print@_topbitchars\ option |
28711 | specifies whether characters with values greater than 127 should be logged | |
495ae4b0 PH |
28712 | unchanged, or whether they should be rendered as escape sequences. |
28713 | .nextp | |
28714 | .index log||certificate verification | |
495ae4b0 PH |
28715 | \tls@_certificate@_verified\: An extra item is added to <= and => log lines |
28716 | when TLS is in use. The item is \"CV=yes"\ if the peer's certificate was | |
28717 | verified, and \"CV=no"\ if not. | |
495ae4b0 PH |
28718 | .nextp |
28719 | .index log||TLS cipher | |
28720 | .index TLS||logging cipher | |
28721 | \tls@_cipher\: When a message is sent or received over an encrypted connection, | |
28722 | the cipher suite used is added to the log line, preceded by X=. | |
28723 | .nextp | |
28724 | .index log||TLS peer DN | |
28725 | .index TLS||logging peer DN | |
28726 | \tls@_peerdn\: When a message is sent or received over an encrypted connection, | |
28727 | and a certificate is supplied by the remote host, the peer DN is added to the | |
28728 | log line, preceded by DN=. | |
28729 | .endp | |
28730 | ||
28731 | .section Message log | |
28732 | .index message||log file for | |
4964e932 | 28733 | .index log||message log, description of |
495ae4b0 PH |
28734 | In addition to the general log files, Exim writes a log file for each message |
28735 | that it handles. The names of these per-message logs are the message ids, and | |
28736 | .index \(msglog)\ directory | |
28737 | they are kept in the \(msglog)\ sub-directory of the spool directory. Each | |
28738 | message log contains copies of the log lines that apply to the message. This | |
28739 | makes it easier to inspect the status of an individual message without having | |
28740 | to search the main log. A message log is deleted when processing of the message | |
28741 | is complete, | |
28742 | .index \preserve@_message@_logs\ | |
28743 | unless \preserve__message__logs\ is set, but this should be used only with | |
28744 | great care because they can fill up your disk very quickly. | |
28745 | ||
4964e932 PH |
28746 | On a heavily loaded system, it may be desirable to disable the use of |
28747 | per-message logs, in order to reduce disk I/O. This can be done by setting the | |
495ae4b0 PH |
28748 | \message@_logs\ option false. |
28749 | ||
28750 | ||
28751 | ||
28752 | . | |
28753 | . | |
28754 | . | |
28755 | . ============================================================================ | |
28756 | .chapter Exim utilities | |
28757 | .set runningfoot "utilities" | |
28758 | .rset CHAPutils ~~chapter | |
28759 | .index utilities | |
28760 | A number of utility scripts and programs are supplied with Exim and are | |
28761 | described in this chapter. There is also the Exim Monitor, which is covered in | |
28762 | the next chapter. The utilities described here are: | |
28763 | ||
28764 | . This duplication seems to be the only way to arrange that the cross- | |
28765 | . references are omitted in the Texinfo version. They look horribly ugly. | |
28766 | ||
28767 | .if ~~texinfo | |
28768 | .display rm | |
28769 | .tabs 22 | |
28770 | \*exiwhat*\ $t $rm{list what Exim processes are doing} | |
28771 | .newline | |
28772 | \*exiqgrep*\ $t $rm{grep the queue} | |
28773 | .newline | |
28774 | \*exiqsumm*\ $t $rm{summarize the queue} | |
28775 | \*exigrep*\ $t $rm{search the main log} | |
28776 | \*exipick*\ $t $rm{select messages on various criteria} | |
28777 | \*exicyclog*\ $t $rm{cycle (rotate) log files} | |
28778 | \*eximstats*\ $t $rm{extract statistics from the log} | |
28779 | \*exim@_checkaccess*\ $t $rm{check address acceptance from given IP} | |
28780 | \*exim@_dbmbuild*\ $t $rm{build a DBM file} | |
28781 | \*exinext*\ $t $rm{extract retry information} | |
28782 | \*exim@_dumpdb*\ $t $rm{dump a hints database} | |
28783 | \*exim@_tidydb*\ $t $rm{clean up a hints database} | |
28784 | \*exim@_fixdb*\ $t $rm{patch a hints database} | |
28785 | \*exim@_lock*\ $t $rm{lock a mailbox file} | |
28786 | .endd | |
28787 | . | |
28788 | .else | |
28789 | . | |
28790 | .display rm | |
28791 | .tabs 22 | |
28792 | ~~SECTfinoutwha \*exiwhat*\ $t $rm{list what Exim processes are doing} | |
495ae4b0 | 28793 | ~~SECTgreptheque \*exiqgrep*\ $t $rm{grep the queue} |
495ae4b0 PH |
28794 | ~~SECTsumtheque \*exiqsumm*\ $t $rm{summarize the queue} |
28795 | ~~SECTextspeinf \*exigrep*\ $t $rm{search the main log} | |
495ae4b0 | 28796 | ~~SECTexipick \*exipick*\ $t $rm{select messages on various criteria} |
495ae4b0 PH |
28797 | ~~SECTcyclogfil \*exicyclog*\ $t $rm{cycle (rotate) log files} |
28798 | ~~SECTmailstat \*eximstats*\ $t $rm{extract statistics from the log} | |
28799 | ~~SECTcheckaccess \*exim@_checkaccess*\ $t $rm{check address acceptance from given IP} | |
28800 | ~~SECTdbmbuild \*exim@_dbmbuild*\ $t $rm{build a DBM file} | |
28801 | ~~SECTfinindret \*exinext*\ $t $rm{extract retry information} | |
28802 | ~~SECThindatmai \*exim@_dumpdb*\ $t $rm{dump a hints database} | |
28803 | ~~SECThindatmai \*exim@_tidydb*\ $t $rm{clean up a hints database} | |
28804 | ~~SECThindatmai \*exim@_fixdb*\ $t $rm{patch a hints database} | |
28805 | ~~SECTmailboxmaint \*exim@_lock*\ $t $rm{lock a mailbox file} | |
28806 | .endd | |
28807 | .fi | |
28808 | ||
28809 | .section Finding out what Exim processes are doing (exiwhat) | |
28810 | .rset SECTfinoutwha "~~chapter.~~section" | |
28811 | .index \*exiwhat*\ | |
28812 | .index process, querying | |
28813 | .index \\SIGUSR1\\ | |
28814 | On operating systems that can restart a system call after receiving a signal | |
28815 | (most modern OS), an Exim process responds to the \\SIGUSR1\\ signal by writing | |
28816 | a line describing what it is doing to the file \(exim-process.info)\ in the | |
28817 | Exim spool directory. The \*exiwhat*\ script sends the signal to all Exim | |
28818 | processes it can find, having first emptied the file. It then waits for one | |
d43194df PH |
28819 | second to allow the Exim processes to react before displaying the results. In |
28820 | order to run \*exiwhat*\ successfully you have to have sufficient privilege to | |
495ae4b0 PH |
28821 | send the signal to the Exim processes, so it is normally run as root. |
28822 | ||
d43194df PH |
28823 | .em |
28824 | \**Warning**\: This is not an efficient process. It is intended for occasional | |
28825 | use by system administrators. It is not sensible, for example, to set up a | |
28826 | script that sends \\SIGUSR1\\ signals to Exim processes at short intervals. | |
28827 | .nem | |
28828 | ||
28829 | Unfortunately, the \*ps*\ command that \*exiwhat*\ uses to find Exim processes | |
495ae4b0 PH |
28830 | varies in different operating systems. Not only are different options used, |
28831 | but the format of the output is different. For this reason, there are some | |
28832 | system configuration options that configure exactly how \*exiwhat*\ works. If it | |
28833 | doesn't seem to be working for you, check the following compile-time options: | |
28834 | .display | |
28835 | EXIWHAT@_PS@_CMD $rm{the command for running \*ps*\} | |
28836 | EXIWHAT@_PS@_ARG $rm{the argument for \*ps*\} | |
28837 | EXIWHAT@_EGREP@_ARG $rm{the argument for \*egrep*\ to select from \*ps*\ output} | |
28838 | EXIWHAT@_KILL@_ARG $rm{the argument for the \*kill*\ command} | |
28839 | .endd | |
28840 | An example of typical output from \*exiwhat*\ is | |
28841 | .display | |
28842 | .indent 0 | |
28843 | 164 daemon: -q1h, listening on port 25 | |
28844 | 10483 running queue: waiting for 0tAycK-0002ij-00 (10492) | |
28845 | 10492 delivering 0tAycK-0002ij-00 to mail.ref.example [10.19.42.42] | |
28846 | (editor@@ref.example) | |
28847 | 10592 handling incoming call from [192.168.243.242] | |
28848 | 10628 accepting a local non-SMTP message | |
28849 | .endd | |
28850 | The first number in the output line is the process number. The third line has | |
28851 | been split here, in order to fit it on the page. | |
28852 | ||
28853 | ||
28854 | .section Selective queue listing (exiqgrep) | |
28855 | .rset SECTgreptheque "~~chapter.~~section" | |
28856 | .index \*exiqgrep*\ | |
28857 | .index queue||grepping | |
28858 | This utility is a Perl script contributed by Matt Hubbard. It runs | |
28859 | .display asis | |
28860 | exim -bpu | |
28861 | .endd | |
4964e932 PH |
28862 | to obtain a queue listing with undelivered recipients only, and then greps the |
28863 | output to select messages that match given criteria. The following selection | |
495ae4b0 PH |
28864 | options are available: |
28865 | ||
28866 | .startoptions | |
28867 | ||
28868 | .option f <<regex>> | |
4964e932 PH |
28869 | Match the sender address. The field that is tested is enclosed in angle |
28870 | brackets, so you can test for bounce messages with | |
495ae4b0 PH |
28871 | .display asis |
28872 | exiqgrep -f '^<>$' | |
28873 | .endd | |
28874 | ||
28875 | .option r <<regex>> | |
4964e932 | 28876 | Match a recipient address. The field that is tested is not enclosed in angle |
495ae4b0 PH |
28877 | brackets. |
28878 | ||
28879 | .option s <<regex>> | |
28880 | Match against the size field. | |
28881 | ||
28882 | .option y <<seconds>> | |
28883 | Match messages that are younger than the given time. | |
28884 | ||
28885 | .option o <<seconds>> | |
28886 | Match messages that are older than the given time. | |
28887 | ||
28888 | .option z | |
28889 | Match only frozen messages. | |
28890 | ||
28891 | .option x | |
28892 | Match only non-frozen messages. | |
28893 | ||
28894 | .endoptions | |
28895 | ||
28896 | The following options control the format of the output: | |
28897 | ||
28898 | .startoptions | |
28899 | ||
28900 | .option c | |
28901 | Display only the count of matching messages. | |
28902 | ||
28903 | .option l | |
28904 | Long format -- display the full message information as output by Exim. This is | |
28905 | the default. | |
28906 | ||
28907 | .option i | |
28908 | Display message ids only. | |
28909 | ||
28910 | .option b | |
28911 | Brief format -- one line per message. | |
28912 | ||
28913 | .option R | |
28914 | Display messages in reverse order. | |
28915 | ||
28916 | .endoptions | |
28917 | ||
28918 | There is one more option, \-h-\, which outputs a list of options. | |
28919 | ||
28920 | ||
28921 | .section Summarising the queue (exiqsumm) | |
28922 | .rset SECTsumtheque "~~chapter.~~section" | |
28923 | .index \*exiqsumm*\ | |
28924 | .index queue||summary | |
28925 | The \*exiqsumm*\ utility is a Perl script which reads the output of \*exim | |
28926 | -bp*\ and produces a summary of the messages on the queue. Thus, you use it by | |
28927 | running a command such as | |
28928 | .display asis | |
28929 | exim -bp | exiqsumm | |
28930 | .endd | |
28931 | The output consists of one line for each domain that has messages waiting for | |
28932 | it, as in the following example: | |
28933 | .display asis | |
28934 | 3 2322 74m 66m msn.com.example | |
28935 | .endd | |
4964e932 | 28936 | Each line lists the number of |
495ae4b0 | 28937 | pending deliveries for a domain, their total volume, and the length of time |
4964e932 PH |
28938 | that the oldest and the newest messages have been waiting. Note that the number |
28939 | of pending deliveries is greater than the number of messages when messages | |
495ae4b0 PH |
28940 | have more than one recipient. |
28941 | ||
28942 | A summary line is output at the end. By default the output is sorted on the | |
28943 | domain name, but \*exiqsumm*\ has the options \-a-\ and \-c-\, which cause the | |
28944 | output to be sorted by oldest message and by count of messages, respectively. | |
28945 | ||
28946 | The output of \*exim -bp*\ contains the original addresses in the message, so | |
28947 | this also applies to the output from \*exiqsumm*\. No domains from addresses | |
28948 | generated by aliasing or forwarding are included (unless the \one@_time\ option | |
28949 | of the \%redirect%\ router has been used to convert them into `top level' | |
28950 | addresses). | |
28951 | ||
28952 | ||
28953 | ||
28954 | .section Extracting specific information from the log (exigrep) | |
28955 | .rset SECTextspeinf "~~chapter.~~section" | |
28956 | .index \*exigrep*\ | |
28957 | .index log||extracts, grepping for | |
28958 | The \*exigrep*\ utility is a Perl script that searches one or more main log | |
28959 | files for entries that match a given pattern. When it finds a match, it | |
28960 | extracts all the log entries for the relevant message, not just those that | |
28961 | match the pattern. Thus, \*exigrep*\ can extract complete log entries for a | |
28962 | given message, or all mail for a given user, or for a given host, for example. | |
28963 | ||
495ae4b0 PH |
28964 | If a matching log line is not associated with a specific message, it is always |
28965 | included in \*exigrep*\'s output. | |
495ae4b0 PH |
28966 | The usage is: |
28967 | .display asis | |
28968 | exigrep [-l] [-t<n>] <pattern> [<log file>] ... | |
28969 | .endd | |
4964e932 PH |
28970 | The \-t-\ argument specifies a number of seconds. It adds an additional |
28971 | condition for message selection. Messages that are complete are shown only if | |
495ae4b0 PH |
28972 | they spent more than <<n>> seconds on the queue. |
28973 | ||
28974 | The \-l-\ flag means `literal', that is, treat all characters in the | |
28975 | pattern as standing for themselves. Otherwise the pattern must be a Perl | |
28976 | regular expression. The pattern match is case-insensitive. If no file names are | |
28977 | given on the command line, the standard input is read. | |
28978 | ||
28979 | If the location of a \*zcat*\ command is known from the definition of | |
28980 | \\ZCAT@_COMMAND\\ in \(Local/Makefile)\, \*exigrep*\ automatically passes any | |
28981 | file whose name ends in \\COMPRESS@_SUFFIX\\ through \*zcat*\ as it searches | |
28982 | it. | |
28983 | ||
495ae4b0 PH |
28984 | .section Selecting messages by various criteria (exipick) |
28985 | .rset SECTexipick "~~chapter.~~section" | |
28986 | .index \*exipick*\ | |
28987 | John Jetmore's \*exipick*\ utility is included in the Exim distribution. It | |
28988 | lists messages from the queue according to a variety of criteria. For details, | |
28989 | run: | |
28990 | .display asis | |
28991 | exipick --help | |
28992 | .endd | |
495ae4b0 PH |
28993 | |
28994 | ||
28995 | .section Cycling log files (exicyclog) | |
28996 | .rset SECTcyclogfil "~~chapter.~~section" | |
28997 | .index log||cycling local files | |
28998 | .index cycling logs | |
28999 | .index \*exicyclog*\ | |
29000 | The \*exicyclog*\ script can be used to cycle (rotate) \*mainlog*\ and | |
d43194df PH |
29001 | \*rejectlog*\ files. This is not necessary if only syslog is being used, or if |
29002 | you are using log files with datestamps in their names (see section | |
29003 | ~~SECTdatlogfil). Some operating systems have their own standard mechanisms for | |
29004 | log cycling, and these can be used instead of \*exicyclog*\ if preferred. | |
29005 | ||
29006 | Each time \*exicyclog*\ is run the file names get `shuffled down' by one. If | |
29007 | the main log file name is \(mainlog)\ (the default) then when \*exicyclog*\ is | |
29008 | run \(mainlog)\ becomes \(mainlog.01)\, the previous \(mainlog.01)\ becomes | |
495ae4b0 | 29009 | \(mainlog.02)\ and so on, up to a limit which is set in the script, and which |
d43194df PH |
29010 | defaults to 10. |
29011 | .em | |
29012 | Log files whose numbers exceed the limit are discarded. | |
29013 | .nem | |
29014 | Reject logs are handled similarly. | |
29015 | ||
29016 | .em | |
29017 | If the limit is greater than 99, the script uses 3-digit numbers such as | |
29018 | \(mainlog.001)\, \(mainlog.002)\, etc. If you change from a number less than 99 | |
29019 | to one that is greater, or \*vice versa*\, you will have to fix the names of | |
29020 | any existing log files. | |
29021 | .nem | |
495ae4b0 PH |
29022 | |
29023 | If no \(mainlog)\ file exists, the script does nothing. Files that `drop off' | |
29024 | the end are deleted. All files with numbers greater than 01 are compressed, | |
29025 | using a compression command which is configured by the \\COMPRESS@_COMMAND\\ | |
29026 | setting in \(Local/Makefile)\. It is usual to run \*exicyclog*\ daily from a | |
29027 | root \crontab\ entry of the form | |
29028 | .display | |
29029 | 1 0 * * * su exim -c /usr/exim/bin/exicyclog | |
29030 | .endd | |
29031 | assuming you have used the name `exim' for the Exim user. You can run | |
29032 | \*exicyclog*\ as root if you wish, but there is no need. | |
29033 | ||
29034 | ||
29035 | .section Mail statistics (eximstats) | |
29036 | .rset SECTmailstat "~~chapter.~~section" | |
29037 | .index statistics | |
29038 | .index \*eximstats*\ | |
29039 | A Perl script called \*eximstats*\ is provided for extracting statistical | |
29040 | information from log files. The output is either plain text, or HTML. | |
4964e932 | 29041 | Exim log files are also suported by the \*Lire*\ system produced by the |
495ae4b0 PH |
29042 | LogReport Foundation (\?http://www.logreport.org?\). |
29043 | ||
29044 | The \*eximstats*\ script has been hacked about quite a bit over time. The | |
29045 | latest version is the result of some extensive revision by Steve Campbell. A | |
29046 | lot of information is given by default, but there are options for suppressing | |
29047 | various parts of it. Following any options, the arguments to the script are a | |
29048 | list of files, which should be main log files. For example: | |
29049 | .display asis | |
29050 | eximstats -nr /var/spool/exim/log/mainlog.01 | |
29051 | .endd | |
29052 | By default, \*eximstats*\ extracts information about the number and volume of | |
29053 | messages received from or delivered to various hosts. The information is sorted | |
29054 | both by message count and by volume, and the top fifty hosts in each category | |
29055 | are listed on the standard output. Similar information, based on email | |
29056 | addresses or domains instead of hosts can be requested by means of various | |
29057 | options. For messages delivered and received locally, similar statistics are | |
29058 | also produced per user. | |
29059 | ||
29060 | The output also includes total counts and statistics about delivery errors, and | |
29061 | histograms showing the number of messages received and deliveries made in each | |
29062 | hour of the day. A delivery with more than one address in its envelope (for | |
29063 | example, an SMTP transaction with more than one \\RCPT\\ command) is counted | |
29064 | as a single delivery by \*eximstats*\. | |
29065 | ||
29066 | Though normally more deliveries than receipts are reported (as messages may | |
29067 | have multiple recipients), it is possible for \*eximstats*\ to report more | |
29068 | messages received than delivered, even though the queue is empty at the start | |
29069 | and end of the period in question. If an incoming message contains no valid | |
29070 | recipients, no deliveries are recorded for it. A bounce message is handled as | |
29071 | an entirely separate message. | |
29072 | ||
29073 | \*eximstats*\ always outputs a grand total summary giving the volume and number | |
29074 | of messages received and deliveries made, and the number of hosts involved in | |
29075 | each case. It also outputs the number of messages that were delayed (that is, | |
29076 | not completely delivered at the first attempt), and the number that had at | |
29077 | least one address that failed. | |
29078 | ||
29079 | The remainder of the output is in sections that can be independently disabled | |
29080 | or modified by various options. It consists of a summary of deliveries by | |
29081 | transport, histograms of messages received and delivered per time interval | |
29082 | (default per hour), information about the time messages spent on the queue, | |
29083 | a list of relayed messages, lists of the top fifty sending hosts, local | |
29084 | senders, destination hosts, and destination local users by count and by volume, | |
29085 | and a list of delivery errors that occurred. | |
29086 | ||
29087 | The relay information lists messages that were actually relayed, that is, they | |
29088 | came from a remote host and were directly delivered to some other remote host, | |
29089 | without being processed (for example, for aliasing or forwarding) locally. | |
29090 | ||
29091 | The options for \*eximstats*\ are as follows: | |
29092 | ||
29093 | .startoptions | |
29094 | .index \*eximstats*\||options | |
29095 | .option bydomain | |
29096 | The `league tables' are computed on the basis of the superior domains of the | |
29097 | sending hosts instead of the sending and receiving hosts. This option may be | |
29098 | combined with \-byhost-\ and/or \-byemail-\. | |
29099 | ||
29100 | .option byedomain | |
29101 | This is a synonym for \-byemaildomain-\. | |
29102 | ||
29103 | .option byemail | |
29104 | The `league tables' are computed on the basis of complete email addresses, | |
29105 | instead of sending and receiving hosts. This option may be combined with | |
29106 | \-byhost-\ and/or \-bydomain-\. | |
29107 | ||
29108 | .option byemaildomain | |
4964e932 | 29109 | The `league tables' are computed on the basis of the sender's email domain |
495ae4b0 PH |
29110 | instead of the sending and receiving hosts. This option may be combined with |
29111 | \-byhost-\, \-bydomain-\, or \-byemail-\. | |
29112 | ||
29113 | .option byhost | |
29114 | The `league tables' are computed on the basis of sending and receiving hosts. | |
29115 | This is the default option. It may be combined with \-bydomain-\ and/or | |
29116 | \-byemail-\. | |
29117 | ||
29118 | .option cache | |
29119 | Cache results of \*timegm()*\ lookups. This results in a significant speedup | |
29120 | when processing hundreds of thousands of messages, at a cost of increasing the | |
29121 | memory utilisation. | |
29122 | ||
29123 | .option chartdir <<dir>> | |
29124 | When \-charts-\ is specified, create the charts in the directory <<dir>>. | |
29125 | ||
29126 | .option chartrel <<dir>> | |
29127 | When \-charts-\ is specified, this option specifies the relative directory for | |
29128 | the \"img src="\ tags from where to include the charts. | |
29129 | ||
29130 | .option charts | |
29131 | Create graphical charts to be displayed in HTML output. This requires the | |
29132 | \"GD"\, \"GDTextUtil"\, and \"GDGraph"\ Perl modules, which can be obtained | |
29133 | from \?http://www.cpan.org/modules/01modules.index.html?\. | |
29134 | ||
29135 | To install these, download and unpack them, then use the normal Perl | |
29136 | installation procedure: | |
29137 | .display asis | |
29138 | perl Makefile.PL | |
29139 | make | |
29140 | make test | |
29141 | make install | |
29142 | .endd | |
29143 | ||
29144 | .option d | |
29145 | This is a debug flag. It causes \*eximstats*\ to output the \*eval()*\'d parser | |
29146 | to the standard output, which makes it easier to trap errors in the eval | |
29147 | section. Remember to add one to the line numbers to allow for the title. | |
29148 | ||
29149 | ||
29150 | .option help | |
29151 | Show help information about \*eximstats*\' options. | |
29152 | ||
29153 | .option h <<n>> | |
29154 | This option controls the histograms of messages received and deliveries per | |
29155 | time interval. By default the time interval is one hour. If \-h0-\ is given, | |
29156 | the histograms are suppressed; otherwise the value of <<n>> gives the number of | |
29157 | divisions per hour. Valid values are 0, 1, 2, 3, 5, 10, 15, 20, 30 or 60, so | |
29158 | \-h2-\ sets an interval of 30 minutes, and the default is equivalent to \-h1-\. | |
29159 | ||
29160 | .option html | |
29161 | Output the results in HTML instead of plain text. | |
29162 | ||
29163 | .option merge | |
29164 | This option causes \*eximstats*\ to merge old reports into a combined report. | |
4964e932 | 29165 | When this option is used, the input files must be outputs from previous calls |
495ae4b0 PH |
29166 | to \*eximstats*\, not raw log files. For example, you could produce a set of |
29167 | daily reports and a weekly report by commands such as | |
29168 | .display asis | |
29169 | eximstats mainlog.sun > report.sun.txt | |
29170 | eximstats mainlog.mon > report.mon.txt | |
29171 | eximstats mainlog.tue > report.tue.txt | |
29172 | eximstats mainlog.wed > report.wed.txt | |
29173 | eximstats mainlog.thu > report.thu.txt | |
29174 | eximstats mainlog.fri > report.fri.txt | |
29175 | eximstats mainlog.sat > report.sat.txt | |
29176 | eximstats -merge -html report.*.txt > weekly_report.html | |
29177 | .endd | |
29178 | You can merge text or html reports and output the results as text or html. You | |
29179 | can use all the normal \*eximstats*\ output options, but only data included in | |
29180 | the original reports can be shown. When merging reports, some loss of accuracy | |
29181 | may occur in the `league tables', towards the ends of the lists. The order of | |
29182 | items in the `league tables' may vary when the data volumes round to the same | |
29183 | value. | |
29184 | ||
29185 | .option ne | |
29186 | Suppress the display of information about failed deliveries (errors). | |
29187 | ||
29188 | .option nr | |
29189 | Suppress information about messages relayed through this host. | |
29190 | ||
29191 | .option nr /pattern/ | |
29192 | Suppress information about relayed messages that match the pattern, which is | |
29193 | matched against a string of the following form (split over two lines here in | |
29194 | order to fit it on the page): | |
29195 | .display asis | |
29196 | H=<host> [<ip address>] A=<sender address> => | |
29197 | H=<host> A=<recipient address> | |
29198 | .endd | |
29199 | for example | |
29200 | .display asis | |
29201 | H=in.host [1.2.3.4] A=from@some.where.example => | |
29202 | H=out.host A=to@else.where.example | |
29203 | .endd | |
29204 | The sending host name appears in parentheses if it has not been verified as | |
29205 | matching the IP address. The mail addresses are taken from the envelope, not | |
29206 | the headers. This option allows you to screen out hosts whom you are happy to | |
29207 | have using your host as a relay. | |
29208 | ||
29209 | .option nt | |
29210 | Suppress the statistics about delivery by transport. | |
29211 | ||
29212 | .option nt/<<pattern>>/ | |
4964e932 PH |
29213 | Suppress the statistics about delivery by any transport whose name matches the |
29214 | pattern. If you are using one transport to send all messages to a scanning | |
29215 | mechanism before doing the real delivery, this feature can be used to omit that | |
495ae4b0 PH |
29216 | transport from your normal statistics (on the grounds that it is of no |
29217 | interest). | |
29218 | ||
29219 | ||
29220 | .option "pattern" "#<<description>>#/<<pattern>>/" | |
29221 | Count lines matching specified patterns and show them in | |
29222 | the results. For example: | |
29223 | .display asis | |
29224 | -pattern 'Refused connections' '/refused connection/' | |
29225 | .endd | |
4964e932 | 29226 | This option can be specified multiple times. |
495ae4b0 PH |
29227 | |
29228 | .option q0 | |
29229 | Suppress information about times messages spend on the queue. | |
29230 | ||
29231 | .option q <<n1>>... | |
29232 | This option sets an alternative list of time intervals for the queueing | |
29233 | information. The values are separated by commas and are in seconds, but can | |
29234 | involve arithmetic multipliers, so for example you can set 3$*$60 to specify 3 | |
29235 | minutes. A setting such as | |
29236 | .display asis | |
29237 | -q60,5*60,10*60 | |
29238 | .endd | |
29239 | causes \*eximstats*\ to give counts of messages that stayed on the queue for less | |
29240 | than one minute, less than five minutes, less than ten minutes, and over ten | |
29241 | minutes. | |
29242 | ||
29243 | .option t <<n>> | |
29244 | Sets the `top' count to <<n>>. This controls the listings of the `top <<n>>' | |
29245 | hosts and users by count and volume. The default is 50, and setting 0 | |
29246 | suppresses the output altogether. | |
29247 | ||
29248 | .option tnl | |
29249 | Omit local information from the `top' listings. | |
29250 | ||
29251 | .option t@_remote@_users | |
29252 | Include remote users in the `top' listings. | |
29253 | ||
29254 | .endoptions | |
29255 | ||
29256 | ||
29257 | .section Checking access policy (exim@_checkaccess) | |
29258 | .rset SECTcheckaccess "~~chapter.~~section" | |
29259 | .index \*exim@_checkaccess*\ | |
29260 | .index policy control||checking access | |
29261 | .index checking access | |
29262 | The \-bh-\ command line argument allows you to run a fake SMTP session with | |
29263 | debugging output, in order to check what Exim is doing when it is applying | |
29264 | policy controls to incoming SMTP mail. However, not everybody is sufficiently | |
29265 | familiar with the SMTP protocol to be able to make full use of \-bh-\, and | |
29266 | sometimes you just want to answer the question \*Does this address have | |
29267 | access?*\ without bothering with any further details. | |
29268 | ||
29269 | The \*exim@_checkaccess*\ utility is a `packaged' version of \-bh-\. It takes | |
29270 | two arguments, an IP address and an email address: | |
29271 | .display asis | |
29272 | exim_checkaccess 10.9.8.7 A.User@a.domain.example | |
29273 | .endd | |
29274 | The utility runs a call to Exim with the \-bh-\ option, to test whether the | |
29275 | given email address would be accepted in a \\RCPT\\ command in a TCP/IP | |
29276 | connection from the host with the given IP address. The output of the utility | |
29277 | is either the word `accepted', or the SMTP error response, for example: | |
29278 | .display asis | |
29279 | Rejected: | |
29280 | 550 Relay not permitted | |
29281 | .endd | |
29282 | When running this test, the utility uses \"<>"\ as the envelope sender address | |
29283 | for the \\MAIL\\ command, but you can change this by providing additional | |
29284 | options. These are passed directly to the Exim command. For example, to specify | |
29285 | that the test is to be run with the sender address \*himself@@there.example*\ | |
29286 | you can use: | |
29287 | .display asis | |
29288 | exim_checkaccess 10.9.8.7 A.User@a.domain.example \ | |
29289 | -f himself@there.example | |
29290 | .endd | |
29291 | Note that these additional Exim command line items must be given after the two | |
29292 | mandatory arguments. | |
29293 | ||
29294 | Because the \exim@_checkaccess\ uses \-bh-\, it does not perform callouts while | |
4964e932 | 29295 | running its checks. You can run checks that include callouts by using \-bhc-\, |
495ae4b0 PH |
29296 | but this is not yet available in a `packaged' form. |
29297 | ||
29298 | ||
29299 | .section Making DBM files (exim@_dbmbuild) | |
29300 | .rset SECTdbmbuild "~~chapter.~~section" | |
29301 | .index DBM||building dbm files | |
29302 | .index building DBM files | |
29303 | .index \*exim@_dbmbuild*\ | |
29304 | .index lower casing | |
29305 | .index binary zero||in lookup key | |
29306 | The \*exim@_dbmbuild*\ program reads an input file containing keys and data in | |
29307 | the format used by the \%lsearch%\ lookup (see section ~~SECTsinglekeylookups). | |
29308 | It writes a DBM file using the lower-cased alias names as keys and the | |
29309 | remainder of the information as data. The lower-casing can be prevented by | |
29310 | calling the program with the \-nolc-\ option. | |
29311 | ||
29312 | A terminating zero is included as part of the key string. This is expected by | |
29313 | the \%dbm%\ lookup type. However, if the option \-nozero-\ is given, | |
29314 | \*exim@_dbmbuild*\ creates files without terminating zeroes in either the key | |
29315 | strings or the data strings. The \%dbmnz%\ lookup type can be used with such | |
29316 | files. | |
29317 | ||
29318 | The program requires two arguments: the name of the input file (which can be a | |
29319 | single hyphen to indicate the standard input), and the name of the output file. | |
29320 | It creates the output under a temporary name, and then renames it if all went | |
29321 | well. | |
29322 | .index \\USE@_DB\\ | |
29323 | If the native DB interface is in use (\\USE@_DB\\ is set in a compile-time | |
29324 | configuration file -- this is common in free versions of Unix) the two file | |
29325 | names must be different, because in this mode the Berkeley DB functions create | |
29326 | a single output file using exactly the name given. For example, | |
29327 | .display asis | |
29328 | exim_dbmbuild /etc/aliases /etc/aliases.db | |
29329 | .endd | |
29330 | reads the system alias file and creates a DBM version of it in | |
29331 | \(/etc/aliases.db)\. | |
29332 | ||
29333 | In systems that use the \*ndbm*\ routines (mostly proprietary versions of Unix), | |
29334 | two files are used, with the suffixes \(.dir)\ and \(.pag)\. In this | |
29335 | environment, the suffixes are added to the second argument of | |
29336 | \*exim@_dbmbuild*\, so it can be the same as the first. This is also the case | |
29337 | when the Berkeley functions are used in compatibility mode (though this is not | |
29338 | recommended), because in that case it adds a \(.db)\ suffix to the file name. | |
29339 | ||
29340 | If a duplicate key is encountered, the program outputs a warning, and when it | |
29341 | finishes, its return code is 1 rather than zero, unless the \-noduperr-\ option | |
29342 | is used. By default, only the first of a set of duplicates is used -- this | |
29343 | makes it compatible with \%lsearch%\ lookups. There is an option \-lastdup-\ | |
29344 | which causes it to use the data for the last duplicate instead. There is also | |
29345 | an option \-nowarn-\, which stops it listing duplicate keys to \stderr\. For | |
29346 | other errors, where it doesn't actually make a new file, the return code is 2. | |
29347 | ||
29348 | ||
29349 | ||
29350 | .section Finding individual retry times (exinext) | |
29351 | .rset SECTfinindret "~~chapter.~~section" | |
29352 | .index retry||times | |
29353 | .index \*exinext*\ | |
29354 | A utility called \*exinext*\ (mostly a Perl script) provides the ability to fish | |
29355 | specific information out of the retry database. Given a mail domain (or a | |
29356 | complete address), it looks up the hosts for that domain, and outputs any retry | |
29357 | information for the hosts or for the domain. At present, the retry information | |
29358 | is obtained by running \*exim@_dumpdb*\ (see below) and post-processing the | |
29359 | output. For example: | |
29360 | .display asis | |
29361 | $ exinext piglet@milne.fict.example | |
29362 | kanga.milne.fict.example:192.168.8.1 error 146: Connection refused | |
29363 | first failed: 21-Feb-1996 14:57:34 | |
29364 | last tried: 21-Feb-1996 14:57:34 | |
29365 | next try at: 21-Feb-1996 15:02:34 | |
29366 | roo.milne.fict.example:192.168.8.3 error 146: Connection refused | |
29367 | first failed: 20-Jan-1996 13:12:08 | |
29368 | last tried: 21-Feb-1996 11:42:03 | |
29369 | next try at: 21-Feb-1996 19:42:03 | |
29370 | past final cutoff time | |
29371 | .endd | |
29372 | You can also give \*exinext*\ a local part, without a domain, and it | |
29373 | will give any retry information for that local part in your default domain. | |
29374 | A message id can be used to obtain retry information pertaining to a specific | |
29375 | message. This exists only when an attempt to deliver a message to a remote host | |
29376 | suffers a message-specific error (see section ~~SECToutSMTPerr). \*exinext*\ is | |
29377 | not particularly efficient, but then it isn't expected to be run very often. | |
29378 | ||
495ae4b0 PH |
29379 | The \*exinext*\ utility calls Exim to find out information such as the location |
29380 | of the spool directory. The utility has \-C-\ and \-D-\ options, which are | |
29381 | passed on to the \*exim*\ commands. The first specifies an alternate Exim | |
29382 | configuration file, and the second sets macros for use within the configuration | |
29383 | file. These features are mainly to help in testing, but might also be useful in | |
29384 | environments where more than one configuration file is in use. | |
495ae4b0 PH |
29385 | |
29386 | ||
29387 | ||
29388 | .section Hints database maintenance (exim@_dumpdb, exim@_fixdb, exim@_tidydb) | |
29389 | .rset SECThindatmai "~~chapter.~~section" | |
29390 | .index hints database||maintenance | |
29391 | .index maintaining Exim's hints database | |
29392 | Three utility programs are provided for maintaining the DBM files that Exim | |
29393 | uses to contain its delivery hint information. Each program requires two | |
29394 | arguments. The first specifies the name of Exim's spool directory, and the | |
29395 | second is the name of the database it is to operate on. These are as | |
29396 | follows: | |
29397 | .numberpars $. | |
29398 | \*retry*\: the database of retry information | |
29399 | .nextp | |
29400 | \*wait-*\<<transport name>>: databases of information about messages waiting | |
29401 | for remote hosts | |
29402 | .nextp | |
495ae4b0 | 29403 | \*callout*\: the callout cache |
495ae4b0 | 29404 | .nextp |
4964e932 | 29405 | \*misc*\: other hints data |
495ae4b0 | 29406 | .endp |
495ae4b0 PH |
29407 | The \*misc*\ database is used for |
29408 | .numberpars alpha | |
29409 | Serializing \\ETRN\\ runs (when \smtp@_etrn@_serialize\ is set) | |
29410 | .nextp | |
4964e932 | 29411 | Serializing delivery to a specific host (when \serialize@_hosts\ is set in an |
495ae4b0 PH |
29412 | \%smtp%\ transport) |
29413 | .endp | |
d43194df PH |
29414 | |
29415 | .section exim@_dumpdb | |
495ae4b0 PH |
29416 | .index \*exim@_dumpdb*\ |
29417 | The entire contents of a database are written to the standard output by the | |
29418 | \*exim@_dumpdb*\ program, which has no options or arguments other than the | |
29419 | spool and database names. For example, to dump the retry database: | |
29420 | .display asis | |
29421 | exim_dumpdb /var/spool/exim retry | |
29422 | .endd | |
29423 | Two lines of output are produced for each entry: | |
29424 | .display | |
29425 | T:mail.ref.example:192.168.242.242 146 77 Connection refused | |
29426 | 31-Oct-1995 12:00:12 02-Nov-1995 12:21:39 02-Nov-1995 20:21:39 * | |
29427 | .endd | |
29428 | The first item on the first line is the key of the record. It starts with one | |
29429 | of the letters R, or T, depending on whether it refers to a routing or | |
29430 | transport retry. For a local delivery, the next part is the local address; for | |
29431 | a remote delivery it is the name of the remote host, followed by its failing IP | |
29432 | address (unless \no@_retry@_include@_ip@_address\ is set on the \%smtp%\ | |
d43194df PH |
29433 | transport). If the remote port is not the standard one (port 25), it is added |
29434 | to the IP address. Then there follows an error code, an additional error code, | |
29435 | and a textual description of the error. | |
495ae4b0 PH |
29436 | |
29437 | The three times on the second line are the time of first failure, the time of | |
29438 | the last delivery attempt, and the computed time for the next attempt. The line | |
29439 | ends with an asterisk if the cutoff time for the last retry rule has been | |
29440 | exceeded. | |
29441 | ||
29442 | Each output line from \*exim@_dumpdb*\ for the \*wait-*\$it{xxx} databases | |
29443 | consists of a host name followed by a list of ids for messages that are or were | |
29444 | waiting to be delivered to that host. If there are a very large number for any | |
29445 | one host, continuation records, with a sequence number added to the host name, | |
29446 | may be seen. The data in these records is often out of date, because a message | |
29447 | may be routed to several alternative hosts, and Exim makes no effort to keep | |
29448 | cross-references. | |
29449 | ||
d43194df PH |
29450 | |
29451 | .section exim@_tidydb | |
495ae4b0 PH |
29452 | .index \*exim@_tidydb*\ |
29453 | The \*exim@_tidydb*\ utility program is used to tidy up the contents of the | |
29454 | hints databases. If run with no options, it removes all records from a database | |
29455 | that are more than 30 days old. The cutoff date can be altered by means of the | |
29456 | \-t-\ option, which must be followed by a time. For example, to remove all | |
29457 | records older than a week from the retry database: | |
29458 | .display asis | |
29459 | exim_tidydb -t 7d /var/spool/exim retry | |
29460 | .endd | |
29461 | Both the \*wait-*\$it{xxx} and \*retry*\ databases contain items that involve | |
29462 | message ids. In the former these appear as data in records keyed by host -- | |
29463 | they were messages that were waiting for that host -- and in the latter they | |
29464 | are the keys for retry information for messages that have suffered certain | |
29465 | types of error. When \*exim@_tidydb*\ is run, a check is made to ensure that | |
29466 | message ids in database records are those of messages that are still on the | |
29467 | queue. Message ids for messages that no longer exist are removed from | |
29468 | \*wait-*\$it{xxx} records, and if this leaves any records empty, they are | |
d43194df PH |
29469 | deleted. For the \*retry*\ database, records whose keys are non-existent |
29470 | message ids are removed. The \*exim@_tidydb*\ utility outputs comments on the | |
29471 | standard output whenever it removes information from the database. | |
495ae4b0 | 29472 | |
d43194df PH |
29473 | .em |
29474 | Certain records are automatically removed by Exim when they are no longer | |
29475 | needed, but others are not. For example, if all the MX hosts for a domain are | |
29476 | down, a retry record is created for each one. If the primary MX host comes back | |
29477 | first, its record is removed when Exim successfully delivers to it, but the | |
29478 | records for the others remain because Exim has not tried to use those hosts. | |
29479 | ||
29480 | It is important, therefore, to run \*exim@_tidydb*\ periodically on all the | |
29481 | hints databases. You should do this at a quiet time of day, because it requires | |
29482 | a database to be locked (and therefore inaccessible to Exim) while it does its | |
29483 | work. Removing records from a DBM file does not normally make the file smaller, | |
29484 | but all the common DBM libraries are able to re-use the space that is released. | |
29485 | After an initial phase of increasing in size, the databases normally reach a | |
29486 | point at which they no longer get any bigger, as long as they are regularly | |
29487 | tidied. | |
29488 | ||
29489 | \**Warning**\: If you never run \*exim@_tidydb*\, the space used by the hints | |
29490 | databases is likely to keep on increasing. | |
29491 | .nem | |
495ae4b0 | 29492 | |
d43194df PH |
29493 | |
29494 | .section exim@_fixdb | |
495ae4b0 PH |
29495 | .index \*exim@_fixdb*\ |
29496 | The \*exim@_fixdb*\ program is a utility for interactively modifying databases. | |
29497 | Its main use is for testing Exim, but it might also be occasionally useful for | |
29498 | getting round problems in a live system. It has no options, and its interface | |
29499 | is somewhat crude. On entry, it prompts for input with a right angle-bracket. A | |
29500 | key of a database record can then be entered, and the data for that record is | |
29501 | displayed. | |
29502 | ||
29503 | If `d' is typed at the next prompt, the entire record is deleted. For all | |
29504 | except the \*retry*\ database, that is the only operation that can be carried | |
29505 | out. For the \*retry*\ database, each field is output preceded by a number, and | |
29506 | data for individual fields can be changed by typing the field number followed | |
29507 | by new data, for example: | |
29508 | .display asis | |
29509 | > 4 951102:1000 | |
29510 | .endd | |
29511 | resets the time of the next delivery attempt. Time values are given as a | |
29512 | sequence of digit pairs for year, month, day, hour, and minute. Colons can be | |
29513 | used as optional separators. | |
29514 | ||
29515 | ||
29516 | ||
29517 | .section Mailbox maintenance (exim@_lock) | |
29518 | .rset SECTmailboxmaint "~~chapter.~~section" | |
29519 | .index mailbox||maintenance | |
29520 | .index \*exim@_lock*\ | |
29521 | .index locking mailboxes | |
29522 | The \*exim@_lock*\ utility locks a mailbox file using the same algorithm as | |
29523 | Exim. For a discussion of locking issues, see section ~~SECTopappend. | |
29524 | \*Exim@_lock*\ can be used to prevent any modification of a mailbox by Exim or | |
29525 | a user agent while investigating a problem. The utility requires the name of | |
29526 | the file as its first argument. If the locking is successful, the second | |
29527 | argument is run as a command (using C's \*system()*\ function); if there is no | |
29528 | second argument, the value of the SHELL environment variable is used; if this | |
29529 | is unset or empty, \(/bin/sh)\ is run. When the command finishes, the mailbox | |
29530 | is unlocked and the utility ends. The following options are available: | |
29531 | ||
29532 | .startoptions | |
29533 | ||
29534 | .option fcntl | |
29535 | Use \*fcntl()*\ locking on the open mailbox. | |
29536 | ||
29537 | .option flock | |
4964e932 | 29538 | Use \*flock()*\ locking on the open mailbox, provided the operating system |
495ae4b0 PH |
29539 | supports it. |
29540 | ||
29541 | .option interval | |
29542 | This must be followed by a number, which is a number of seconds; it sets the | |
29543 | interval to sleep between retries (default 3). | |
29544 | ||
29545 | .option lockfile | |
29546 | Create a lock file before opening the mailbox. | |
29547 | ||
29548 | .option mbx | |
29549 | Lock the mailbox using MBX rules. | |
29550 | ||
29551 | .option q | |
29552 | Suppress verification output. | |
29553 | ||
29554 | .option retries | |
29555 | This must be followed by a number; it sets the number of times to try to get | |
29556 | the lock (default 10). | |
29557 | ||
29558 | .option restore@_time | |
29559 | This option causes \exim@_lock\ to restore the modified and read times to the | |
29560 | locked file before exiting. This allows you to access a locked mailbox (for | |
29561 | example, to take a backup copy) without disturbing the times that the user | |
29562 | subsequently sees. | |
29563 | ||
29564 | .option timeout | |
29565 | This must be followed by a number, which is a number of seconds; it sets a | |
29566 | timeout to be used with a blocking \*fcntl()*\ lock. If it is not set (the | |
29567 | default), a non-blocking call is used. | |
29568 | ||
29569 | .option v | |
29570 | Generate verbose output. | |
29571 | ||
29572 | .endoptions | |
29573 | ||
4964e932 | 29574 | If none of \-fcntl-\, |
495ae4b0 PH |
29575 | \-flock-\, |
29576 | \-lockfile-\ or \-mbx-\ are given, the default is to create a lock file and | |
29577 | also to use \*fcntl()*\ locking on the mailbox, which is the same as Exim's | |
4964e932 PH |
29578 | default. The use of |
29579 | \-flock-\ | |
495ae4b0 PH |
29580 | or \-fcntl-\ requires that the file be writeable; the use of |
29581 | \-lockfile-\ requires that the directory containing the file be writeable. | |
29582 | Locking by lock file does not last for ever; Exim assumes that a lock file is | |
29583 | expired if it is more than 30 minutes old. | |
29584 | ||
4964e932 | 29585 | The \-mbx-\ option can be used with either or both of \-fcntl-\ or \-flock-\. |
495ae4b0 PH |
29586 | It assumes \-fcntl-\ by default. |
29587 | MBX locking causes a shared lock to be taken out on the open mailbox, and an | |
29588 | exclusive lock on the file \(/tmp/.$it{n}.$it{m})\ where $it{n} and $it{m} are | |
29589 | the device number and inode number of the mailbox file. When the locking is | |
29590 | released, if an exclusive lock can be obtained for the mailbox, the file in | |
29591 | \(/tmp)\ is deleted. | |
29592 | ||
29593 | The default output contains verification of the locking that takes place. The | |
29594 | \-v-\ option causes some additional information to be given. The \-q-\ option | |
29595 | suppresses all output except error messages. | |
29596 | ||
29597 | A command such as | |
29598 | .display asis | |
29599 | exim_lock /var/spool/mail/spqr | |
29600 | .endd | |
29601 | runs an interactive shell while the file is locked, whereas | |
29602 | .display | |
29603 | exim@_lock -q /var/spool/mail/spqr @<@<End | |
29604 | <<some commands>> | |
29605 | End | |
29606 | .endd | |
29607 | runs a specific non-interactive sequence of commands while the file is locked, | |
29608 | suppressing all verification output. A single command can be run by a command | |
29609 | such as | |
29610 | .display asis | |
29611 | exim_lock -q /var/spool/mail/spqr \ | |
29612 | "cp /var/spool/mail/spqr /some/where" | |
29613 | .endd | |
29614 | Note that if a command is supplied, it must be entirely contained within the | |
29615 | second argument -- hence the quotes. | |
29616 | ||
29617 | ||
29618 | ||
29619 | . | |
29620 | . | |
29621 | . | |
29622 | . | |
29623 | . ============================================================================ | |
29624 | .chapter The Exim monitor | |
29625 | .set runningfoot "monitor" | |
29626 | .rset CHAPeximon ~~chapter | |
29627 | .index monitor | |
29628 | .index Exim monitor | |
29629 | .index X-windows | |
29630 | .index \*eximon*\ | |
29631 | .index Local/eximon.conf | |
29632 | .index \(exim@_monitor/EDITME)\ | |
29633 | The Exim monitor is an application which displays in an X window information | |
29634 | about the state of Exim's queue and what Exim is doing. An admin user can | |
29635 | perform certain operations on messages from this GUI interface; however all | |
29636 | such facilities are also available from the command line, and indeed, the | |
29637 | monitor itself makes use of the command line to perform any actions requested. | |
29638 | ||
29639 | ||
29640 | .section Running the monitor | |
29641 | The monitor is started by running the script called \*eximon*\. This is a shell | |
29642 | script that sets up a number of environment variables, and then runs the | |
29643 | binary called \(eximon.bin)\. The default appearance of the monitor window can | |
29644 | be changed by editing the \(Local/eximon.conf)\ file created by editing | |
29645 | \(exim@_monitor/EDITME)\. Comments in that file describe what the various | |
29646 | parameters are for. | |
29647 | ||
29648 | The parameters that get built into the \*eximon*\ script can be overridden for a | |
29649 | particular invocation by setting up environment variables of the same names, | |
29650 | preceded by `$tt{EXIMON@_}'. For example, a shell command such as | |
29651 | .display asis | |
29652 | EXIMON_LOG_DEPTH=400 eximon | |
29653 | .endd | |
29654 | (in a Bourne-compatible shell) runs \*eximon*\ with an overriding setting of the | |
29655 | \\LOG@_DEPTH\\ parameter. If \\EXIMON@_LOG@_FILE@_PATH\\ is set in the | |
29656 | environment, it overrides the Exim log file configuration. This makes it | |
29657 | possible to have \*eximon*\ tailing log data that is written to syslog, provided | |
29658 | that MAIL.INFO syslog messages are routed to a file on the local host. | |
29659 | ||
29660 | X resources can be used to change the appearance of the window in the normal | |
29661 | way. For example, a resource setting of the form | |
29662 | .display asis | |
29663 | Eximon*background: gray94 | |
29664 | .endd | |
29665 | changes the colour of the background to light grey rather than white. The | |
29666 | stripcharts are drawn with both the data lines and the reference lines in | |
29667 | black. This means that the reference lines are not visible when on top of the | |
29668 | data. However, their colour can be changed by setting a resource called | |
29669 | `highlight' (an odd name, but that's what the Athena stripchart widget uses). | |
29670 | For example, if your X server is running Unix, you could set up lighter | |
29671 | reference lines in the stripcharts by obeying | |
29672 | .display asis | |
29673 | xrdb -merge <<End | |
29674 | Eximon*highlight: gray | |
29675 | End | |
29676 | .endd | |
29677 | ||
29678 | .index admin user | |
29679 | In order to see the contents of messages on the queue, and to operate on them, | |
29680 | \*eximon*\ must either be run as root or by an admin user. | |
29681 | ||
29682 | The monitor's window is divided into three parts. The first contains one or | |
29683 | more stripcharts and two action buttons, the second contains a `tail' of the | |
29684 | main log file, and the third is a display of the queue of messages awaiting | |
29685 | delivery, with two more action buttons. The following sections describe these | |
29686 | different parts of the display. | |
29687 | ||
29688 | ||
29689 | ||
29690 | .section The stripcharts | |
29691 | .index stripchart | |
29692 | The first stripchart is always a count of messages on the queue. Its name can | |
29693 | be configured by setting \\QUEUE@_STRIPCHART@_NAME\\ in the | |
29694 | \(Local/eximon.conf)\ file. The remaining stripcharts are defined in the | |
29695 | configuration script by regular expression matches on log file entries, making | |
29696 | it possible to display, for example, counts of messages delivered to certain | |
29697 | hosts or using certain transports. The supplied defaults display counts of | |
29698 | received and delivered messages, and of local and SMTP deliveries. The default | |
29699 | period between stripchart updates is one minute; this can be adjusted by a | |
29700 | parameter in the \(Local/eximon.conf)\ file. | |
29701 | ||
29702 | The stripchart displays rescale themselves automatically as the value they are | |
29703 | displaying changes. There are always 10 horizontal lines in each chart; the | |
29704 | title string indicates the value of each division when it is greater than one. | |
29705 | For example, `x2' means that each division represents a value of 2. | |
29706 | ||
29707 | It is also possible to have a stripchart which shows the percentage fullness of | |
29708 | a particular disk partition, which is useful when local deliveries are confined | |
29709 | to a single partition. | |
29710 | .index \statvfs\ function | |
29711 | This relies on the availability of the \*statvfs()*\ function or equivalent in | |
29712 | the operating system. Most, but not all versions of Unix that support Exim have | |
29713 | this. For this particular stripchart, the top of the chart always represents | |
29714 | 100%, and the scale is given as `x10%'. This chart is configured by setting | |
29715 | \\SIZE@_STRIPCHART\\ and (optionally) \\SIZE@_STRIPCHART@_NAME\\ in the | |
29716 | \(Local/eximon.conf)\ file. | |
29717 | ||
29718 | ||
29719 | ||
29720 | .section Main action buttons | |
29721 | .index size||of monitor window | |
29722 | .index monitor window size | |
29723 | .index window size | |
29724 | Below the stripcharts there is an action button for quitting the monitor. Next | |
29725 | to this is another button marked `Size'. They are placed here so that shrinking | |
29726 | the window to its default minimum size leaves just the queue count stripchart | |
29727 | and these two buttons visible. Pressing the `Size' button causes the window to | |
29728 | expand to its maximum size, unless it is already at the maximum, in which case | |
29729 | it is reduced to its minimum. | |
29730 | ||
29731 | When expanding to the maximum, if the window cannot be fully seen where it | |
29732 | currently is, it is moved back to where it was the last time it was at full | |
29733 | size. When it is expanding from its minimum size, the old position is | |
29734 | remembered, and next time it is reduced to the minimum it is moved back there. | |
29735 | ||
29736 | The idea is that you can keep a reduced window just showing one or two | |
29737 | stripcharts at a convenient place on your screen, easily expand it to show | |
29738 | the full window when required, and just as easily put it back to what it was. | |
29739 | The idea is copied from what the \*twm*\ window manager does for its | |
29740 | \*f.fullzoom*\ action. The minimum size of the window can be changed by setting | |
29741 | the \\MIN@_HEIGHT\\ and \\MIN@_WIDTH\\ values in \(Local/eximon.conf)\. | |
29742 | ||
29743 | Normally, the monitor starts up with the window at its full size, but it can be | |
29744 | built so that it starts up with the window at its smallest size, by setting | |
29745 | \\START@_SMALL\\=yes in \(Local/eximon.conf)\. | |
29746 | ||
29747 | ||
29748 | .section The log display | |
29749 | .index log||tail of, in monitor | |
29750 | The second section of the window is an area in which a display of the tail of | |
4964e932 | 29751 | the main log is maintained. |
495ae4b0 PH |
29752 | To save space on the screen, the timestamp on each log line is shortened by |
29753 | removing the date and, if \log@_timezone\ is set, the timezone. | |
29754 | The log tail is not available when the only destination for logging data is | |
29755 | syslog, unless the syslog lines are routed to a local file whose name is passed | |
29756 | to \*eximon*\ via the \\EXIMON@_LOG@_FILE@_PATH\\ environment variable. | |
29757 | ||
29758 | The log sub-window has a scroll bar at its lefthand side which can be used to | |
29759 | move back to look at earlier text, and the up and down arrow keys also have a | |
29760 | scrolling effect. The amount of log that is kept depends on the setting of | |
29761 | \\LOG@_BUFFER\\ in \(Local/eximon.conf)\, which specifies the amount of memory | |
29762 | to use. When this is full, the earlier 50% of data is discarded -- this is much | |
29763 | more efficient than throwing it away line by line. The sub-window also has a | |
29764 | horizontal scroll bar for accessing the ends of long log lines. This is the | |
29765 | only means of horizontal scrolling; the right and left arrow keys are not | |
29766 | available. Text can be cut from this part of the window using the mouse in the | |
29767 | normal way. The size of this subwindow is controlled by parameters in the | |
29768 | configuration file \(Local/eximon.conf)\. | |
29769 | ||
29770 | Searches of the text in the log window can be carried out by means of the ^R | |
29771 | and ^S keystrokes, which default to a reverse and a forward search, | |
29772 | respectively. The search covers only the text that is displayed in the window. | |
29773 | It cannot go further back up the log. | |
29774 | ||
29775 | The point from which the search starts is indicated by a caret marker. This is | |
29776 | normally at the end of the text in the window, but can be positioned explicitly | |
29777 | by pointing and clicking with the left mouse button, and is moved automatically | |
29778 | by a successful search. If new text arrives in the window when it is scrolled | |
29779 | back, the caret remains where it is, but if the window is not scrolled back, | |
29780 | the caret is moved to the end of the new text. | |
29781 | ||
29782 | Pressing ^R or ^S pops up a window into which the search text can be typed. | |
29783 | There are buttons for selecting forward or reverse searching, for carrying out | |
29784 | the search, and for cancelling. If the `Search' button is pressed, the search | |
29785 | happens and the window remains so that further searches can be done. If the | |
29786 | `Return' key is pressed, a single search is done and the window is closed. If | |
29787 | ^C is typed the search is cancelled. | |
29788 | ||
29789 | The searching facility is implemented using the facilities of the Athena text | |
29790 | widget. By default this pops up a window containing both `search' and `replace' | |
29791 | options. In order to suppress the unwanted `replace' portion for eximon, a | |
29792 | modified version of the \TextPop\ widget is distributed with Exim. However, the | |
29793 | linkers in BSDI and HP-UX seem unable to handle an externally provided version | |
29794 | of \TextPop\ when the remaining parts of the text widget come from the standard | |
29795 | libraries. The compile-time option \\EXIMON@_TEXTPOP\\ can be unset to cut out | |
29796 | the modified \TextPop\, making it possible to build Eximon on these systems, at | |
29797 | the expense of having unwanted items in the search popup window. | |
29798 | ||
29799 | ||
29800 | .section The queue display | |
29801 | .index queue||display in monitor | |
29802 | The bottom section of the monitor window contains a list of all messages that | |
29803 | are on the queue, which includes those currently being received or delivered, | |
29804 | as well as those awaiting delivery. The size of this subwindow is controlled by | |
29805 | parameters in the configuration file \(Local/eximon.conf)\, and the frequency | |
29806 | at which it is updated is controlled by another parameter in the same file -- | |
29807 | the default is 5 minutes, since queue scans can be quite expensive. However, | |
29808 | there is an `Update' action button just above the display which can be used to | |
29809 | force an update of the queue display at any time. | |
29810 | ||
29811 | When a host is down for some time, a lot of pending mail can build up for it, | |
29812 | and this can make it hard to deal with other messages on the queue. To help | |
29813 | with this situation there is a button next to `Update' called `Hide'. If | |
29814 | pressed, a dialogue box called `Hide addresses ending with' is put up. If you | |
29815 | type anything in here and press `Return', the text is added to a chain of such | |
29816 | texts, and if every undelivered address in a message matches at least one | |
29817 | of the texts, the message is not displayed. | |
29818 | ||
29819 | If there is an address that does not match any of the texts, all the addresses | |
29820 | are displayed as normal. The matching happens on the ends of addresses so, for | |
29821 | example, \*cam.ac.uk*\ specifies all addresses in Cambridge, while | |
29822 | \*xxx@@foo.com.example*\ specifies just one specific address. When any hiding | |
29823 | has been set up, a button called `Unhide' is displayed. If pressed, it cancels | |
29824 | all hiding. Also, to ensure that hidden messages do not get forgotten, a hide | |
29825 | request is automatically cancelled after one hour. | |
29826 | ||
29827 | While the dialogue box is displayed, you can't press any buttons or do anything | |
29828 | else to the monitor window. For this reason, if you want to cut text from the | |
29829 | queue display to use in the dialogue box, you have to do the cutting before | |
29830 | pressing the `Hide' button. | |
29831 | ||
29832 | The queue display contains, for each unhidden queued message, the length of | |
29833 | time it has been on the queue, the size of the message, the message id, the | |
29834 | message sender, and the first undelivered recipient, all on one line. If it is | |
29835 | a bounce message, the sender is shown as `<>'. If there is more than one | |
29836 | recipient to which the message has not yet been delivered, subsequent ones are | |
29837 | listed on additional lines, up to a maximum configured number, following which | |
29838 | an ellipsis is displayed. Recipients that have already received the message are | |
29839 | not shown. | |
29840 | .index frozen messages||display | |
29841 | If a message is frozen, an asterisk is displayed at the left-hand side. | |
29842 | ||
29843 | The queue display has a vertical scroll bar, and can also be scrolled by means | |
29844 | of the arrow keys. Text can be cut from it using the mouse in the normal way. | |
29845 | The text searching facilities, as described above for the log window, are also | |
29846 | available, but the caret is always moved to the end of the text when the queue | |
29847 | display is updated. | |
29848 | ||
29849 | ||
29850 | .section The queue menu | |
29851 | .index queue||menu in monitor | |
29852 | If the \shift\ key is held down and the left button is clicked when the mouse | |
29853 | pointer is over the text for any message, an action menu pops up, and the first | |
29854 | line of the queue display for the message is highlighted. This does not affect | |
29855 | any selected text. | |
29856 | ||
29857 | If you want to use some other event for popping up the menu, you can set the | |
29858 | \\MENU@_EVENT\\ parameter in \(Local/eximon.conf)\ to change the default, or | |
29859 | set \\EXIMON@_MENU@_EVENT\\ in the environment before starting the monitor. The | |
29860 | value set in this parameter is a standard X event description. For example, to | |
29861 | run eximon using \ctrl\ rather than \shift\ you could use | |
29862 | .display asis | |
29863 | EXIMON_MENU_EVENT='Ctrl<Btn1Down>' eximon | |
29864 | .endd | |
29865 | The title of the menu is the message id, and it contains entries which act as | |
29866 | follows: | |
29867 | .numberpars $. | |
29868 | \*message log*\: The contents of the message log for the message are displayed in | |
29869 | a new text window. | |
29870 | .nextp | |
29871 | \*headers*\: Information from the spool file that contains the envelope | |
29872 | information and headers is displayed in a new text window. See chapter | |
29873 | ~~CHAPspool for a description of the format of spool files. | |
29874 | .nextp | |
29875 | \*body*\: The contents of the spool file containing the body of the message are | |
29876 | displayed in a new text window. There is a default limit of 20,000 bytes to the | |
29877 | amount of data displayed. This can be changed by setting the \\BODY@_MAX\\ | |
29878 | option at compile time, or the \\EXIMON@_BODY@_MAX\\ option at run time. | |
29879 | .nextp | |
29880 | \*deliver message*\: A call to Exim is made using the \-M-\ option to request | |
29881 | delivery of the message. This causes an automatic thaw if the message is | |
29882 | frozen. The \-v-\ option is also set, and the output from Exim is displayed in | |
29883 | a new text window. The delivery is run in a separate process, to avoid holding | |
29884 | up the monitor while the delivery proceeds. | |
29885 | .nextp | |
29886 | \*freeze message*\: A call to Exim is made using the \-Mf-\ option to request | |
29887 | that the message be frozen. | |
29888 | .nextp | |
29889 | .index thawing messages | |
29890 | .index unfreezing messages | |
29891 | .index frozen messages||thawing | |
29892 | \*thaw message*\: A call to Exim is made using the \-Mt-\ option to request that | |
29893 | the message be thawed. | |
29894 | .nextp | |
29895 | .index delivery||forcing failure | |
29896 | \*give up on msg*\: A call to Exim is made using the \-Mg-\ option to request | |
29897 | that Exim gives up trying to deliver the message. A bounce message is generated | |
29898 | for any remaining undelivered addresses. | |
29899 | .nextp | |
29900 | \*remove message*\: A call to Exim is made using the \-Mrm-\ option to request | |
29901 | that the message be deleted from the system without generating a bounce | |
29902 | message. | |
29903 | .nextp | |
29904 | \*add recipient*\: A dialog box is displayed into which a recipient address can | |
29905 | be typed. If the address is not qualified and the \\QUALIFY@_DOMAIN\\ parameter | |
29906 | is set in \(Local/eximon.conf)\, the address is qualified with that domain. | |
29907 | Otherwise it must be entered as a fully qualified address. Pressing \\RETURN\\ | |
29908 | causes a call to Exim to be made using the \-Mar-\ option to request that an | |
29909 | additional recipient be added to the message, unless the entry box is empty, in | |
29910 | which case no action is taken. | |
29911 | .nextp | |
29912 | \*mark delivered*\: A dialog box is displayed into which a recipient address can | |
29913 | be typed. If the address is not qualified and the \\QUALIFY@_DOMAIN\\ parameter | |
29914 | is set in \(Local/eximon.conf)\, the address is qualified with that domain. | |
29915 | Otherwise it must be entered as a fully qualified address. Pressing \\RETURN\\ | |
29916 | causes a call to Exim to be made using the \-Mmd-\ option to mark the given | |
29917 | recipient address as already delivered, unless the entry box is empty, in which | |
29918 | case no action is taken. | |
29919 | .nextp | |
29920 | \*mark all delivered*\: A call to Exim is made using the \-Mmad-\ option to mark | |
29921 | all recipient addresses as already delivered. | |
29922 | .nextp | |
29923 | \*edit sender*\: A dialog box is displayed initialized with the current sender's | |
29924 | address. Pressing \\RETURN\\ causes a call to Exim to be made using the \-Mes-\ | |
29925 | option to replace the sender address, unless the entry box is empty, in which | |
29926 | case no action is taken. If you want to set an empty sender (as in bounce | |
29927 | messages), you must specify it as `<>'. Otherwise, if the address is not | |
29928 | qualified and the \\QUALIFY@_DOMAIN\\ parameter is set in | |
29929 | \(Local/eximon.conf)\, the address is qualified with that domain. | |
29930 | .endp | |
29931 | When a delivery is forced, a window showing the \-v-\ output is displayed. In | |
29932 | other cases when a call to Exim is made, if there is any output from Exim (in | |
29933 | particular, if the command fails) a window containing the command and the | |
29934 | output is displayed. Otherwise, the results of the action are normally apparent | |
29935 | from the log and queue displays. However, if you set \\ACTION@_OUTPUT\\=yes in | |
29936 | \(Local/eximon.conf)\, a window showing the Exim command is always opened, even | |
29937 | if no output is generated. | |
29938 | ||
29939 | The queue display is automatically updated for actions such as freezing and | |
29940 | thawing, unless \\ACTION@_QUEUE@_UPDATE\\=no has been set in | |
29941 | \(Local/eximon.conf)\. In this case the `Update' button has to be used to force | |
29942 | an update of the display after one of these actions. | |
29943 | ||
29944 | In any text window that is displayed as result of a menu action, the normal | |
29945 | cut-and-paste facility is available, and searching can be carried out using ^R | |
29946 | and ^S, as described above for the log tail window. | |
29947 | ||
29948 | ||
29949 | ||
29950 | ||
29951 | ||
29952 | ||
29953 | . | |
29954 | . | |
29955 | . | |
29956 | . | |
29957 | . ============================================================================ | |
29958 | .chapter Security considerations | |
29959 | .set runningfoot "security" | |
29960 | .rset CHAPsecurity ~~chapter | |
29961 | .index security | |
29962 | This chapter discusses a number of issues concerned with security, some of | |
29963 | which are also covered in other parts of this manual. | |
29964 | ||
29965 | For reasons that this author does not understand, some people have promoted | |
29966 | Exim as a `particularly secure' mailer. Perhaps it is because of the existence | |
29967 | of this chapter in the documentation. However, the intent of the chapter is | |
29968 | simply to describe the way Exim works in relation to certain security concerns, | |
29969 | not to make any specific claims about the effectiveness of its security as | |
29970 | compared with other MTAs. | |
29971 | ||
29972 | What follows is a description of the way Exim is supposed to be. Best efforts | |
29973 | have been made to try to ensure that the code agrees with the theory, but an | |
29974 | absence of bugs can never be guaranteed. Any that are reported will get fixed | |
29975 | as soon as possible. | |
29976 | ||
29977 | .section Building a more `hardened' Exim | |
29978 | .index security||build-time features | |
29979 | There are a number of build-time options that can be set in \(Local/Makefile)\ | |
29980 | to create Exim binaries that are `harder' to attack, in particular by a rogue | |
29981 | Exim administrator who does not have the root password, or by someone who has | |
29982 | penetrated the Exim (but not the root) account. These options are as follows: | |
29983 | .numberpars $. | |
29984 | \\ALT@_CONFIG@_PREFIX\\ can be set to a string that is required to match the | |
29985 | start of any file names used with the \-C-\ option. When it is set, these file | |
29986 | names are also not allowed to contain the sequence `/../'. (However, if the | |
29987 | value of the \-C-\ option is identical to the value of \\CONFIGURE@_FILE\\ in | |
29988 | \(Local/Makefile)\, Exim ignores \-C-\ and proceeds as usual.) There is no | |
29989 | default setting for \ALT@_CONFIG@_PREFIX\. | |
29990 | ||
29991 | If the permitted configuration files are confined to a directory to | |
29992 | which only root has access, this guards against someone who has broken | |
29993 | into the Exim account from running a privileged Exim with an arbitrary | |
29994 | configuration file, and using it to break into other accounts. | |
29995 | .nextp | |
29996 | If \\ALT@_CONFIG@_ROOT@_ONLY\\ is defined, root privilege is retained for \-C-\ | |
29997 | and \-D-\ only if the caller of Exim is root. Without it, the Exim user may | |
29998 | also use \-C-\ and \-D-\ and retain privilege. Setting this option locks out | |
29999 | the possibility of testing a configuration using \-C-\ right through message | |
30000 | reception and delivery, even if the caller is root. The reception works, but by | |
30001 | that time, Exim is running as the Exim user, so when it re-execs to regain | |
30002 | privilege for the delivery, the use of \-C-\ causes privilege to be lost. | |
30003 | However, root can test reception and delivery using two separate commands. | |
30004 | \\ALT@_CONFIG@_ROOT@_ONLY\\ is not set by default. | |
30005 | .nextp | |
30006 | If \\DISABLE@_D@_OPTION\\ is defined, the use of the \-D-\ command line option | |
30007 | is disabled. | |
30008 | .nextp | |
30009 | \\FIXED@_NEVER@_USERS\\ can be set to a colon-separated list of users that are | |
30010 | never to be used for any deliveries. This is like the \never@_users\ runtime | |
30011 | option, but it cannot be overridden; the runtime option adds additional users | |
30012 | to the list. The default setting is `root'; this prevents a non-root user who | |
30013 | is permitted to modify the runtime file from using Exim as a way to get root. | |
30014 | .endp | |
30015 | ||
30016 | ||
30017 | .section Root privilege | |
30018 | .index setuid | |
30019 | .index root privilege | |
30020 | The Exim binary is normally setuid to root, which means that it gains root | |
30021 | privilege (runs as root) when it starts execution. In some special cases (for | |
30022 | example, when the daemon is not in use and there are no local deliveries), it | |
30023 | may be possible to run Exim setuid to some user other than root. This is | |
30024 | discussed in the next section. However, in most installations, root privilege | |
30025 | is required for two things: | |
30026 | .numberpars $. | |
30027 | To set up a socket connected to the standard SMTP port (25) when initialising | |
30028 | the listening daemon. If Exim is run from \*inetd*\, this privileged action is | |
30029 | not required. | |
30030 | .nextp | |
30031 | To be able to change uid and gid in order to read users' \(.forward)\ files and | |
30032 | perform local deliveries as the receiving user or as specified in the | |
30033 | configuration. | |
30034 | .endp | |
30035 | It is not necessary to be root to do any of the other things Exim does, such as | |
30036 | receiving messages and delivering them externally over SMTP, and it is | |
30037 | obviously more secure if Exim does not run as root except when necessary. | |
30038 | For this reason, a user and group for Exim to use must be defined in | |
30039 | \(Local/Makefile)\. These are known as `the Exim user' and `the Exim group'. | |
30040 | Their values can be changed by the run time configuration, though this is not | |
30041 | recommended. Often a user called \*exim*\ is used, but some sites use \*mail*\ | |
30042 | or another user name altogether. | |
30043 | ||
30044 | Exim uses \*setuid()*\ whenever it gives up root privilege. This is a permanent | |
30045 | abdication; the process cannot regain root afterwards. Prior to release 4.00, | |
30046 | \*seteuid()*\ was used in some circumstances, but this is no longer the case. | |
30047 | ||
30048 | After a new Exim process has interpreted its command line options, it changes | |
30049 | uid and gid in the following cases: | |
30050 | .numberpars $. | |
30051 | .index \-C-\ option | |
30052 | .index \-D-\ option | |
30053 | If the \-C-\ option is used to specify an alternate configuration file, or if | |
30054 | the \-D-\ option is used to define macro values for the configuration, and the | |
30055 | calling process is not running as root or the Exim user, the uid and gid are | |
30056 | changed to those of the calling process. | |
4964e932 PH |
30057 | However, if \\ALT@_CONFIG@_ROOT@_ONLY\\ is defined in \(Local/Makefile)\, only |
30058 | root callers may use \-C-\ and \-D-\ without losing privilege, and if | |
495ae4b0 PH |
30059 | \\DISABLE@_D@_OPTION\\ is set, the \-D-\ option may not be used at all. |
30060 | .nextp | |
30061 | .index \-be-\ option | |
30062 | .index \-bf-\ option | |
30063 | .index \-bF-\ option | |
30064 | If the expansion test option (\-be-\) or one of the filter testing options | |
30065 | (\-bf-\ or \-bF-\) are used, the uid and gid are changed to those of the | |
30066 | calling process. | |
30067 | .nextp | |
30068 | If the process is not a daemon process or a queue runner process or a delivery | |
30069 | process or a process for testing address routing (started with \-bt-\), the uid | |
30070 | and gid are changed to the Exim user and group. This means that Exim always | |
30071 | runs under its own uid and gid when receiving messages. This also applies when | |
4964e932 | 30072 | testing address verification |
495ae4b0 PH |
30073 | .index \-bv-\ option |
30074 | .index \-bh-\ option | |
30075 | (the \-bv-\ option) and testing incoming message policy controls (the \-bh-\ | |
30076 | option). | |
30077 | .nextp | |
30078 | For a daemon, queue runner, delivery, or address testing process, the uid | |
30079 | remains as root at this stage, but the gid is changed to the Exim group. | |
30080 | .endp | |
30081 | The processes that initially retain root privilege behave as follows: | |
30082 | .numberpars $. | |
30083 | A daemon process changes the gid to the Exim group and the uid to the Exim user | |
30084 | after setting up one or more listening sockets. The \*initgroups()*\ function | |
30085 | is called, so that if the Exim user is in any additional groups, they will be | |
30086 | used during message reception. | |
30087 | .nextp | |
30088 | A queue runner process retains root privilege throughout its execution. Its job | |
30089 | is to fork a controlled sequence of delivery processes. | |
30090 | .nextp | |
30091 | A delivery process retains root privilege throughout most of its execution, | |
30092 | but any actual deliveries (that is, the transports themselves) are run in | |
30093 | subprocesses which always change to a non-root uid and gid. For local | |
30094 | deliveries this is typically the uid and gid of the owner of the mailbox; for | |
30095 | remote deliveries, the Exim uid and gid are used. Once all the delivery | |
30096 | subprocesses have been run, a delivery process changes to the Exim uid and gid | |
30097 | while doing post-delivery tidying up such as updating the retry database and | |
30098 | generating bounce and warning messages. | |
30099 | ||
30100 | While the recipient addresses in a message are being routed, the delivery | |
30101 | process runs as root. However, if a user's filter file has to be processed, | |
30102 | this is done in a subprocess that runs under the individual user's uid and | |
30103 | gid. A system filter is run as root unless \system@_filter@_user\ is set. | |
30104 | .nextp | |
30105 | A process that is testing addresses (the \-bt-\ option) runs as root so that | |
30106 | the routing is done in the same environment as a message delivery. | |
30107 | .endp | |
30108 | ||
30109 | ||
30110 | .section Running Exim without privilege | |
d43194df | 30111 | .rset SECTrunexiwitpri "~~chapter.~~section" |
495ae4b0 PH |
30112 | .index privilege, running without |
30113 | .index unprivileged running | |
30114 | .index root privilege||running without | |
30115 | Some installations like to run Exim in an unprivileged state for more of its | |
30116 | operation, for added security. Support for this mode of operation is provided | |
30117 | by the global option \deliver@_drop@_privilege\. When this is set, the uid and | |
30118 | gid are changed to the Exim user and group at the start of a delivery process | |
30119 | (and also queue runner and address testing processes). This means that address | |
30120 | routing is no longer run as root, and the deliveries themselves cannot change | |
30121 | to any other uid. | |
30122 | ||
30123 | Leaving the binary setuid to root, but setting \deliver@_drop@_privilege\ means | |
30124 | that the daemon can still be started in the usual way, and it can respond | |
30125 | correctly to SIGHUP because the re-invocation regains root privilege. | |
30126 | ||
30127 | An alternative approach is to make Exim setuid to the Exim user and also setgid | |
30128 | to the Exim group. | |
30129 | If you do this, the daemon must be started from a root process. (Calling | |
30130 | Exim from a root process makes it behave in the way it does when it is setuid | |
30131 | root.) However, the daemon cannot restart itself after a SIGHUP signal because | |
30132 | it cannot regain privilege. | |
30133 | ||
30134 | It is still useful to set \deliver@_drop@_privilege\ in this case, because it | |
30135 | stops Exim from trying to re-invoke itself to do a delivery after a message has | |
30136 | been received. Such a re-invocation is a waste of resources because it has no | |
30137 | effect. | |
30138 | ||
d43194df PH |
30139 | If restarting the daemon is not an issue (for example, if |
30140 | .em | |
30141 | \mua@_wrapper\ is set, or | |
30142 | .nem | |
30143 | \*inetd*\ is being used instead of a daemon), having the binary setuid to the | |
30144 | Exim user seems a clean approach, but there is one complication: | |
495ae4b0 PH |
30145 | |
30146 | In this style of operation, Exim is running with the real uid and gid set to | |
30147 | those of the calling process, and the effective uid/gid set to Exim's values. | |
30148 | Ideally, any association with the calling process' uid/gid should be dropped, | |
30149 | that is, the real uid/gid should be reset to the effective values so as to | |
30150 | discard any privileges that the caller may have. While some operating systems | |
30151 | have a function that permits this action for a non-root effective uid, quite a | |
30152 | number of them do not. Because of this lack of standardization, Exim does not | |
30153 | address this problem at this time. | |
30154 | ||
30155 | For this reason, the recommended approach for `mostly unprivileged' running is | |
30156 | to keep the Exim binary setuid to root, and to set \deliver@_drop@_privilege\. | |
30157 | This also has the advantage of allowing a daemon to be used in the most | |
30158 | straightforward way. | |
30159 | ||
30160 | If you configure Exim not to run delivery processes as root, there are a | |
30161 | number of restrictions on what you can do: | |
30162 | .numberpars $. | |
30163 | You can deliver only as the Exim user/group. You should explicitly use the | |
30164 | \user\ and \group\ options to override routers or local transports that | |
30165 | normally deliver as the recipient. This makes sure that configurations that | |
30166 | work in this mode function the same way in normal mode. Any implicit or | |
30167 | explicit specification of another user causes an error. | |
30168 | .nextp | |
30169 | Use of \(.forward)\ files is severely restricted, such that it is usually | |
30170 | not worthwhile to include them in the configuration. | |
30171 | .nextp | |
30172 | Users who wish to use \(.forward)\ would have to make their home directory and | |
30173 | the file itself accessible to the Exim user. Pipe and append-to-file entries, | |
30174 | and their equivalents in Exim filters, cannot be used. While they could be | |
30175 | enabled in the Exim user's name, that would be insecure and not very useful. | |
30176 | .nextp | |
30177 | Unless the local user mailboxes are all owned by the Exim user (possible in | |
30178 | some POP3 or IMAP-only environments): | |
30179 | .numberpars $*$ | |
30180 | They must be owned by the Exim group and be writable by that group. This | |
30181 | implies you must set \mode\ in the appendfile configuration, as well as the | |
30182 | mode of the mailbox files themselves. | |
30183 | .nextp | |
30184 | You must set \no@_check@_owner\, since most or all of the files will not be | |
30185 | owned by the Exim user. | |
30186 | .nextp | |
30187 | You must set \file@_must@_exist\, because Exim cannot set the owner correctly | |
30188 | on a newly created mailbox when unprivileged. This also implies that new | |
30189 | mailboxes need to be created manually. | |
30190 | .endp | |
30191 | .endp | |
30192 | These restrictions severely restrict what can be done in local deliveries. | |
30193 | However, there are no restrictions on remote deliveries. If you are running a | |
30194 | gateway host that does no local deliveries, setting \deliver@_drop@_privilege\ | |
30195 | gives more security at essentially no cost. | |
d43194df PH |
30196 | .em |
30197 | If you are using the \mua@_wrapper\ facility (see chapter ~~CHAPnonqueueing), | |
30198 | \deliver@_drop@_privilege\ is forced to be true. | |
30199 | .nem | |
495ae4b0 PH |
30200 | |
30201 | ||
30202 | .section Delivering to local files | |
30203 | Full details of the checks applied by \%appendfile%\ before it writes to a file | |
30204 | are given in chapter ~~CHAPappendfile. | |
30205 | ||
30206 | ||
30207 | .section IPv4 source routing | |
30208 | .index source routing||in IP packets | |
30209 | .index IP source routing | |
30210 | Many operating systems suppress IP source-routed packets in the kernel, but | |
30211 | some cannot be made to do this, so Exim does its own check. It logs incoming | |
30212 | IPv4 source-routed TCP calls, and then drops them. Things are all different in | |
30213 | IPv6. No special checking is currently done. | |
30214 | ||
30215 | ||
30216 | .section The VRFY, EXPN, and ETRN commands in SMTP | |
30217 | Support for these SMTP commands is disabled by default. If required, they can | |
30218 | be enabled by defining suitable ACLs. | |
30219 | ||
30220 | ||
30221 | ||
30222 | .section Privileged users | |
30223 | .index trusted user | |
30224 | .index admin user | |
30225 | .index privileged user | |
30226 | .index user||trusted | |
30227 | .index user||admin | |
30228 | Exim recognises two sets of users with special privileges. Trusted users are | |
30229 | able to submit new messages to Exim locally, but supply their own sender | |
30230 | addresses and information about a sending host. For other users submitting | |
30231 | local messages, Exim sets up the sender address from the uid, and doesn't | |
30232 | permit a remote host to be specified. | |
30233 | ||
30234 | .index \-f-\ option | |
30235 | However, an untrusted user is permitted to use the \-f-\ command line option in | |
30236 | the special form \-f @<@>-\ to indicate that a delivery failure for the message | |
30237 | should not cause an error report. This affects the message's envelope, but it | |
30238 | does not affect the ::Sender:: header. Untrusted users may also be permitted to | |
30239 | use specific forms of address with the \-f-\ option by setting the | |
30240 | \untrusted@_set@_sender\ option. | |
30241 | ||
30242 | Trusted users are used to run processes that receive mail messages from some | |
30243 | other mail domain and pass them on to Exim for delivery either locally, or over | |
30244 | the Internet. Exim trusts a caller that is running as root, as the Exim user, | |
30245 | as any user listed in the \trusted@_users\ configuration option, or under any | |
30246 | group listed in the \trusted@_groups\ option. | |
30247 | ||
30248 | Admin users are permitted to do things to the messages on Exim's queue. They | |
30249 | can freeze or thaw messages, cause them to be returned to their senders, remove | |
30250 | them entirely, or modify them in various ways. In addition, admin users can run | |
30251 | the Exim monitor and see all the information it is capable of providing, which | |
30252 | includes the contents of files on the spool. | |
30253 | ||
30254 | .index \-M-\ option | |
30255 | .index \-q-\ option | |
30256 | By default, the use of the \-M-\ and \-q-\ options to cause Exim to attempt | |
30257 | delivery of messages on its queue is restricted to admin users. This | |
30258 | restriction can be relaxed by setting the \no@_prod@_requires@_admin\ option. | |
30259 | Similarly, the use of \-bp-\ (and its variants) to list the contents of the | |
30260 | queue is also restricted to admin users. This restriction can be relaxed by | |
30261 | setting \no@_queue@_list@_requires@_admin\. | |
30262 | ||
30263 | Exim recognises an admin user if the calling process is running as root or as | |
30264 | the Exim user or if any of the groups associated with the calling process is | |
30265 | the Exim group. It is not necessary actually to be running under the Exim | |
30266 | group. However, if admin users who are not root or the Exim user are to access | |
30267 | the contents of files on the spool via the Exim monitor (which runs | |
30268 | unprivileged), Exim must be built to allow group read access to its spool | |
30269 | files. | |
30270 | ||
30271 | ||
30272 | .section Spool files | |
30273 | .index spool directory||files | |
30274 | Exim's spool directory and everything it contains is owned by the Exim user and | |
30275 | set to the Exim group. The mode for spool files is defined in the | |
30276 | \(Local/Makefile)\ configuration file, and defaults to 0640. This means that | |
30277 | any user who is a member of the Exim group can access these files. | |
30278 | ||
30279 | ||
30280 | .section Use of argv[0] | |
30281 | Exim examines the last component of \argv[0]\, and if it matches one of a set | |
30282 | of specific strings, Exim assumes certain options. For example, calling Exim | |
30283 | with the last component of \argv[0]\ set to `rsmtp' is exactly equivalent to | |
30284 | calling it with the option \-bS-\. There are no security implications in this. | |
30285 | ||
30286 | ||
30287 | .section Use of %f formatting | |
30288 | The only use made of `%f' by Exim is in formatting load average values. These | |
30289 | are actually stored in integer variables as 1000 times the load average. | |
30290 | Consequently, their range is limited and so therefore is the length of the | |
30291 | converted output. | |
30292 | ||
30293 | ||
30294 | .section Embedded Exim path | |
30295 | Exim uses its own path name, which is embedded in the code, only when it needs | |
30296 | to re-exec in order to regain root privilege. Therefore, it is not root when it | |
30297 | does so. If some bug allowed the path to get overwritten, it would lead to an | |
30298 | arbitrary program's being run as exim, not as root. | |
30299 | ||
30300 | ||
30301 | .section Use of sprintf() | |
30302 | .index \*sprintf()*\ | |
30303 | A large number of occurrences of `sprintf' in the code are actually calls to | |
30304 | \*string@_sprintf()*\, a function that returns the result in malloc'd store. | |
30305 | The intermediate formatting is done into a large fixed buffer by a function | |
30306 | that runs through the format string itself, and checks the length of each | |
30307 | conversion before performing it, thus preventing buffer overruns. | |
30308 | ||
30309 | The remaining uses of \*sprintf()*\ happen in controlled circumstances where | |
30310 | the output buffer is known to be sufficiently long to contain the converted | |
30311 | string. | |
30312 | ||
30313 | ||
30314 | .section Use of debug@_printf() and log@_write() | |
30315 | Arbitrary strings are passed to both these functions, but they do their | |
30316 | formatting by calling the function \*string@_vformat()*\, which runs through | |
30317 | the format string itself, and checks the length of each conversion. | |
30318 | ||
30319 | ||
30320 | .section Use of strcat() and strcpy() | |
30321 | These are used only in cases where the output buffer is known to be large | |
30322 | enough to hold the result. | |
30323 | ||
30324 | ||
30325 | ||
30326 | ||
30327 | . | |
30328 | . | |
30329 | . | |
30330 | . | |
30331 | . ============================================================================ | |
30332 | .chapter Format of spool files | |
30333 | .set runningfoot "spool file format" | |
30334 | .rset CHAPspool ~~chapter | |
30335 | .index format||spool files | |
30336 | .index spool directory||format of files | |
30337 | .index spool||files, format of | |
30338 | .index spool||files, editing | |
30339 | A message on Exim's queue consists of two files, whose names are the message id | |
30340 | followed by -D and -H, respectively. The data portion of the message is kept in | |
30341 | the -D file on its own. The message's envelope, status, and headers are all | |
30342 | kept in the -H file, whose format is described in this chapter. Each of these | |
30343 | two files contains the final component of its own name as its first line. This | |
30344 | is insurance against disk crashes where the directory is lost but the files | |
30345 | themselves are recoverable. | |
30346 | ||
495ae4b0 PH |
30347 | Some people are tempted into editing -D files in order to modify messages. You |
30348 | need to be extremely careful if you do this; it is not recommended and you are | |
30349 | on your own if you do it. Here are some of the pitfalls: | |
30350 | .numberpars $. | |
30351 | You must use the \*exim@_lock*\ utility to ensure that Exim does not try to | |
30352 | deliver the message while you are fiddling with it. The lock is implemented | |
30353 | by opening the -D file and taking out a write lock on it. If you update the | |
30354 | file in place, the lock will be retained. If you write a new file and rename | |
30355 | it, the lock will be lost at the instant of rename. | |
30356 | .nextp | |
30357 | If you change the number of lines in the file, the value of | |
30358 | \$body@_linecount$\, which is stored in the -H file, will be incorrect. | |
30359 | .nextp | |
30360 | If the message is in MIME format, you must take care not to break it. | |
30361 | .nextp | |
4964e932 | 30362 | If the message is cryptographically signed, any change will invalidate the |
495ae4b0 PH |
30363 | signature. |
30364 | .endp | |
495ae4b0 PH |
30365 | |
30366 | Files whose names end with -J may also be seen in the \(input)\ directory (or | |
30367 | its subdirectories when \split@_spool@_directory\ is set). These are journal | |
30368 | files, used to record addresses to which the message has been delivered during | |
30369 | the course of a delivery run. At the end of the run, the -H file is updated, | |
30370 | and the -J file is deleted. | |
30371 | ||
30372 | .section Format of the -H file | |
30373 | .index uid (user id)||in spool file | |
30374 | .index gid (group id)||in spool file | |
30375 | The second line of the -H file contains the login name for the uid of the | |
30376 | process that called Exim to read the message, followed by the numerical uid and | |
30377 | gid. For a locally generated message, this is normally the user who sent the | |
30378 | message. For a message received over TCP/IP, it is normally the Exim user. | |
30379 | ||
30380 | The third line of the file contains the address of the message's sender as | |
30381 | transmitted in the envelope, contained in angle brackets. The sender address is | |
30382 | empty for bounce messages. For incoming SMTP mail, the sender address is given | |
30383 | in the \\MAIL\\ command. For locally generated mail, the sender address is | |
30384 | created by Exim from the login name of the current user and the configured | |
30385 | \qualify@_domain\. However, this can be overridden by the \-f-\ option or a | |
30386 | leading `From' line if the caller is trusted, or if the supplied address is | |
30387 | `@<@>' or an address that matches \untrusted@_set@_senders\. | |
30388 | ||
30389 | The fourth line contains two numbers. The first is the time that the message | |
30390 | was received, in the conventional Unix form -- the number of seconds since the | |
30391 | start of the epoch. The second number is a count of the number of messages | |
30392 | warning of delayed delivery that have been sent to the sender. | |
30393 | ||
30394 | There follow a number of lines starting with a hyphen. These can appear in any | |
30395 | order, and are omitted when not relevant: | |
30396 | .numberpars $. | |
4964e932 PH |
30397 | \-acl <<number>> <<length>>-\: A line of this form is present for every ACL |
30398 | variable that is not empty. The number identifies the variable; the | |
30399 | \acl@_c\*x*\$$\ variables are numbered 0--9 and the \acl@_m\*x*\$$\ variables | |
30400 | are numbered 10--19. The length is the length of the data string for the | |
495ae4b0 PH |
30401 | variable. The string itself starts at the beginning of the next line, and is |
30402 | followed by a newline character. It may contain internal newlines. | |
30403 | .nextp | |
d43194df PH |
30404 | .em |
30405 | \-active@_hostname <<hostname>>-\: This is present if, when the message was | |
30406 | received over SMTP, the value of \$smtp@_active@_hostname$\ was different to | |
30407 | the value of \$primary@_hostname$\. | |
30408 | .nem | |
30409 | .nextp | |
4964e932 PH |
30410 | \-allow@_unqualified@_recipient-\: This is present if unqualified recipient |
30411 | addresses are permitted in header lines (to stop such addresses from being | |
30412 | qualified if rewriting occurs at transport time). Local messages that were | |
30413 | input using \-bnq-\ and remote messages from hosts that match | |
495ae4b0 PH |
30414 | \recipient@_unqualified@_hosts\ set this flag. |
30415 | .nextp | |
4964e932 PH |
30416 | \-allow@_unqualified@_sender-\: This is present if unqualified sender |
30417 | addresses are permitted in header lines (to stop such addresses from being | |
30418 | qualified if rewriting occurs at transport time). Local messages that were | |
30419 | input using \-bnq-\ and remote messages from hosts that match | |
495ae4b0 | 30420 | \sender@_unqualified@_hosts\ set this flag. |
495ae4b0 PH |
30421 | .nextp |
30422 | \-auth@_id <<text>>-\: The id information for a message received on an | |
30423 | authenticated SMTP connection -- the value of the \$authenticated@_id$\ | |
30424 | variable. | |
30425 | .nextp | |
30426 | \-auth@_sender <<address>>-\: The address of an authenticated sender -- the | |
30427 | value of the \$authenticated@_sender$\ variable. | |
30428 | .nextp | |
30429 | \-body@_linecount <<number>>-\: This records the number of lines in the body of | |
30430 | the message, and is always present. | |
30431 | .nextp | |
d43194df PH |
30432 | .em |
30433 | \-body@_zerocount <<number>>-\: This records the number of binary zero bytes in | |
30434 | the body of the message, and is present if the number is greater than zero. | |
30435 | .nem | |
30436 | .nextp | |
495ae4b0 PH |
30437 | \-deliver@_firsttime-\: This is written when a new message is first added to |
30438 | the spool. When the spool file is updated after a deferral, it is omitted. | |
30439 | .nextp | |
30440 | .index frozen messages||spool data | |
30441 | \-frozen <<time>>-\: The message is frozen, and the freezing happened at | |
30442 | <<time>>. | |
30443 | .nextp | |
30444 | \-helo@_name <<text>>-\: This records the host name as specified by a remote | |
30445 | host in a \\HELO\\ or \\EHLO\\ command. | |
30446 | .nextp | |
30447 | \-host@_address <<address>>.<<port>>-\: This records the IP address of the host | |
30448 | from which the message was received and the remote port number that was used. | |
30449 | It is omitted for locally generated messages. | |
30450 | .nextp | |
30451 | \-host@_auth <<text>>-\: If the message was received on an authenticated SMTP | |
30452 | connection, this records the name of the authenticator -- the value of the | |
30453 | \$sender@_host@_authenticated$\ variable. | |
30454 | .nextp | |
30455 | \-host@_lookup@_failed-\: This is present if an attempt to look up the sending | |
30456 | host's name from its IP address failed. It corresponds to the | |
30457 | \$host@_lookup@_failed$\ variable. | |
30458 | .nextp | |
30459 | .index DNS||reverse lookup | |
30460 | .index reverse DNS lookup | |
30461 | \-host@_name <<text>>-\: This records the name of the remote host from which | |
30462 | the message was received, if the host name was looked up from the IP address | |
30463 | when the message was being received. It is not present if no reverse lookup was | |
30464 | done. | |
30465 | .nextp | |
30466 | \-ident <<text>>-\: For locally submitted messages, this records the login of | |
30467 | the originating user, unless it was a trusted user and the \-oMt-\ option was | |
30468 | used to specify an ident value. For messages received over TCP/IP, this records | |
30469 | the ident string supplied by the remote host, if any. | |
30470 | .nextp | |
30471 | \-interface@_address <<address>>.<<port>>-\: This records the IP address of the | |
30472 | local interface and the port number through which a message was received from a | |
30473 | remote host. It is omitted for locally generated messages. | |
30474 | .nextp | |
30475 | \-local-\: The message is from a local sender. | |
30476 | .nextp | |
30477 | \-localerror-\: The message is a locally-generated bounce message. | |
30478 | .nextp | |
30479 | \-local@_scan <<string>>-\: This records the data string that was | |
30480 | returned by the \*local@_scan()*\ function when the message was received -- the | |
30481 | value of the \$local@_scan@_data$\ variable. It is omitted if no data was | |
30482 | returned. | |
30483 | .nextp | |
30484 | \-manual@_thaw-\: The message was frozen but has been thawed manually, that is, | |
30485 | by an explicit Exim command rather than via the auto-thaw process. | |
30486 | .nextp | |
30487 | \-N-\: A testing delivery process was started using the \-N-\ option to | |
30488 | suppress any actual deliveries, but delivery was deferred. At any further | |
30489 | delivery attempts, \-N-\ is assumed. | |
30490 | .nextp | |
30491 | \-received@_protocol-\: This records the value of the \$received@_protocol$\ | |
30492 | variable, which contains the name of the protocol by which the message was | |
30493 | received. | |
30494 | .nextp | |
30495 | \-sender@_set@_untrusted-\: The envelope sender of this message was set by an | |
30496 | untrusted local caller (used to ensure that the caller is displayed in queue | |
30497 | listings). | |
30498 | .nextp | |
d43194df PH |
30499 | .em |
30500 | \-spam@_score@_int-\: If a message was scanned by SpamAssassin, this is | |
30501 | present. It records the value of \$spam@_score@_int$\. | |
30502 | .nem | |
30503 | .nextp | |
4964e932 | 30504 | \-tls@_certificate@_verified-\: A TLS certificate was received from the client |
495ae4b0 PH |
30505 | that sent this message, and the certificate was verified by the server. |
30506 | .nextp | |
30507 | \-tls@_cipher <<cipher name>>-\: When the message was received over an | |
30508 | encrypted connection, this records the name of the cipher suite that was used. | |
30509 | .nextp | |
30510 | \-tls@_peerdn <<peer DN>>-\: When the message was received over an encrypted | |
30511 | connection, and a certificate was received from the client, this records the | |
30512 | Distinguished Name from that certificate. | |
30513 | .endp | |
30514 | ||
30515 | Following the options there is a list of those addresses to which the message | |
30516 | is not to be delivered. This set of addresses is initialized from the command | |
30517 | line when the \-t-\ option is used and \extract__addresses__remove__arguments\ | |
30518 | is set; otherwise it starts out empty. Whenever a successful delivery is made, | |
30519 | the address is added to this set. The addresses are kept internally as a | |
30520 | balanced binary tree, and it is a representation of that tree which is written | |
30521 | to the spool file. If an address is expanded via an alias or forward file, the | |
30522 | original address is added to the tree when deliveries to all its child | |
30523 | addresses are complete. | |
30524 | ||
30525 | If the tree is empty, there is a single line in the spool file containing just | |
30526 | the text `XX'. Otherwise, each line consists of two letters, which are either Y | |
30527 | or N, followed by an address. The address is the value for the node of the | |
30528 | tree, and the letters indicate whether the node has a left branch and/or a | |
30529 | right branch attached to it, respectively. If branches exist, they immediately | |
30530 | follow. Here is an example of a three-node tree: | |
30531 | .display asis | |
30532 | YY darcy@austen.fict.example | |
30533 | NN alice@wonderland.fict.example | |
30534 | NN editor@thesaurus.ref.example | |
30535 | .endd | |
30536 | After the non-recipients tree, there is a list of the message's recipients. | |
30537 | This is a simple list, preceded by a count. It includes all the original | |
30538 | recipients of the message, including those to whom the message has already been | |
30539 | delivered. In the simplest case, the list contains one address per line. For | |
30540 | example: | |
30541 | .display asis | |
30542 | 4 | |
30543 | editor@thesaurus.ref.example | |
30544 | darcy@austen.fict.example | |
30545 | rdo@foundation | |
30546 | alice@wonderland.fict.example | |
30547 | .endd | |
30548 | However, when a child address has been added to the top-level addresses as a | |
30549 | result of the use of the \one@_time\ option on a \%redirect%\ router, each line | |
30550 | is of the following form: | |
30551 | .display | |
30552 | <<top-level address>> <<errors@_to address>> <<length>>,<<parent number>>@#<<flag bits>> | |
30553 | .endd | |
30554 | The 01 flag bit indicates the presence of the three other fields that follow | |
30555 | the top-level address. Other bits may be used in future to support additional | |
30556 | fields. The <<parent number>> is the offset in the recipients list of the | |
30557 | original parent of the `one time' address. The first two fields are the | |
30558 | envelope sender that is associated with this address and its length. If the | |
30559 | length is zero, there is no special envelope sender (there are then two space | |
30560 | characters in the line). A non-empty field can arise from a \%redirect%\ router | |
30561 | that has an \errors@_to\ setting. | |
30562 | ||
30563 | ||
30564 | A blank line separates the envelope and status information from the headers | |
30565 | which follow. A header may occupy several lines of the file, and to save effort | |
30566 | when reading it in, each header is preceded by a number and an identifying | |
30567 | character. The number is the number of characters in the header, including any | |
30568 | embedded newlines and the terminating newline. The character is one of the | |
30569 | following: | |
30570 | .display | |
30571 | .tabs 9 | |
30572 | <<blank>> $t $rm{header in which Exim has no special interest} | |
30573 | #B $t $rm{::Bcc:: header} | |
30574 | #C $t $rm{::Cc:: header} | |
30575 | #F $t $rm{::From:: header} | |
30576 | #I $t $rm{::Message-id:: header} | |
30577 | #P $t $rm{::Received:: header -- P for `postmark'} | |
30578 | #R $t $rm{::Reply-To:: header} | |
30579 | #S $t $rm{::Sender:: header} | |
30580 | #T $t $rm{::To:: header} | |
30581 | #* $t $rm{replaced or deleted header} | |
30582 | .endd | |
30583 | Deleted or replaced (rewritten) headers remain in the spool file for debugging | |
30584 | purposes. They are not transmitted when the message is delivered. Here is a | |
30585 | typical set of headers: | |
30586 | .display asis | |
30587 | 111P Received: by hobbit.fict.example with local (Exim 4.00) | |
30588 | id 14y9EI-00026G-00; Fri, 11 May 2001 10:28:59 +0100 | |
30589 | 049 Message-Id: <E14y9EI-00026G-00@hobbit.fict.example> | |
30590 | 038* X-rewrote-sender: bb@hobbit.fict.example | |
30591 | 042* From: Bilbo Baggins <bb@hobbit.fict.example> | |
30592 | 049F From: Bilbo Baggins <B.Baggins@hobbit.fict.example> | |
30593 | 099* To: alice@wonderland.fict.example, rdo@foundation, | |
30594 | darcy@austen.fict.example, editor@thesaurus.ref.example | |
30595 | 109T To: alice@wonderland.fict.example, rdo@foundation.fict.example, | |
30596 | darcy@austen.fict.example, editor@thesaurus.ref.example | |
30597 | 038 Date: Fri, 11 May 2001 10:28:59 +0100 | |
30598 | .endd | |
30599 | The asterisked headers indicate that the envelope sender, ::From:: header, and | |
30600 | ::To:: header have been rewritten, the last one because routing expanded the | |
30601 | unqualified domain \*foundation*\. | |
30602 | ||
30603 | . | |
30604 | . | |
30605 | . | |
30606 | . | |
30607 | . ============================================================================ | |
30608 | .chapter Adding new drivers or lookup types | |
30609 | .set runningfoot "adding drivers" | |
30610 | .index adding drivers | |
30611 | .index new drivers, adding | |
30612 | .index drivers||adding new | |
30613 | The following actions have to be taken in order to add a new router, transport, | |
30614 | authenticator, or lookup type to Exim: | |
30615 | .numberpars | |
30616 | Choose a name for the driver or lookup type that does not conflict with any | |
30617 | existing name; I will use `newdriver' in what follows. | |
30618 | .nextp | |
30619 | Add to \(src/EDITME)\ the line | |
30620 | .display | |
30621 | <<type>>@_NEWDRIVER=yes | |
30622 | .endd | |
30623 | where <<type>> is \\ROUTER\\, \\TRANSPORT\\, \\AUTH\\, or \\LOOKUP\\. If the | |
30624 | code is not to be included in the binary by default, comment this line out. You | |
30625 | should also add any relevant comments about the driver or lookup type. | |
30626 | .nextp | |
30627 | Add to \(src/config.h.defaults)\ the line | |
30628 | .display | |
30629 | @#define <<type>>@_NEWDRIVER | |
30630 | .endd | |
30631 | .nextp | |
30632 | Edit \(src/drtables.c)\, adding conditional code to pull in the private header | |
30633 | and create a table entry as is done for all the other drivers and lookup types. | |
30634 | .nextp | |
30635 | Edit \(Makefile)\ in the appropriate sub-directory (\(src/routers)\, | |
30636 | \(src/transports)\, \(src/auths)\, or \(src/lookups)\); add a line for the new | |
30637 | driver or lookup type and add it to the definition of OBJ. | |
30638 | .nextp | |
30639 | Create \(newdriver.h)\ and \(newdriver.c)\ in the appropriate sub-directory of | |
30640 | \(src)\. | |
30641 | .nextp | |
30642 | Edit \(scripts/MakeLinks)\ and add commands to link the \(.h)\ and \(.c)\ files | |
30643 | as for other drivers and lookups. | |
30644 | .endp | |
30645 | Then all you need to do is write the code! A good way to start is to make a | |
30646 | proforma by copying an existing module of the same type, globally changing all | |
30647 | occurrences of the name, and cutting out most of the code. Note that any | |
30648 | options you create must be listed in alphabetical order, because the tables are | |
30649 | searched using a binary chop procedure. | |
30650 | ||
30651 | There is a \(README)\ file in each of the sub-directories of \(src)\ describing | |
30652 | the interface that is expected. | |
30653 | ||
30654 | . | |
30655 | . | |
30656 | . | |
30657 | . | |
30658 | . ============================================================================ | |
30659 | . Fudge for the index page number. We want it to be on a right-hand page. | |
30660 | . | |
30661 | .set indexpage ~~sys.pagenumber + 1 | |
30662 | .if even ~~indexpage | |
30663 | .set indexpage ~~indexpage + 1 | |
30664 | .fi | |
30665 | .if ~~sgcal | |
30666 | .%index Index$e~~indexpage-- | |
30667 | .fi | |
30668 | . | |
30669 | . | |
30670 | . End of Exim specification |