Commit | Line | Data |
---|---|---|
9b371988 PH |
1 | . $Cambridge: exim/doc/doc-docbook/spec.xfpt,v 1.1 2006/02/01 11:01:02 ph10 Exp $ |
2 | . | |
3 | . ///////////////////////////////////////////////////////////////////////////// | |
4 | . This is the primary source of the Exim Manual. It is an xfpt document that is | |
5 | . converted into DocBook XML for subsequent conversion into printing and online | |
6 | . formats. The markup used herein is "standard" xfpt markup, with some extras. | |
7 | . The markup is summarized in a file called Markup.txt. | |
8 | . ///////////////////////////////////////////////////////////////////////////// | |
9 | ||
10 | .include stdflags | |
11 | .include stdmacs | |
12 | .docbook | |
13 | .book | |
14 | ||
15 | . ///////////////////////////////////////////////////////////////////////////// | |
16 | . These definitions set some parameters and save some typing. Remember that | |
17 | . the <bookinfo> element must also be updated for each new edition. | |
18 | . ///////////////////////////////////////////////////////////////////////////// | |
19 | ||
20 | .set ACL "access control lists (ACLs)" | |
21 | .set previousversion "4.50" | |
22 | .set version "4.60" | |
23 | ||
24 | ||
25 | . ///////////////////////////////////////////////////////////////////////////// | |
26 | . Additional xfpt markup used by this document, over and above the default | |
27 | . provided in the xfpt library. | |
28 | . ///////////////////////////////////////////////////////////////////////////// | |
29 | ||
30 | . --- Override the &$ flag to automatically insert a $ with the variable name | |
31 | ||
32 | .flag &$ $& "<varname>$" "</varname>" | |
33 | ||
34 | . --- Short flags for daggers in option headings. They will always be inside | |
35 | . --- an italic string, but we want the daggers to be roman. | |
36 | ||
37 | .flag &!! "</emphasis>†<emphasis>" | |
38 | .flag &!? "</emphasis>‡<emphasis>" | |
39 | ||
40 | . --- A macro for an Exim option definition heading, generating a one-line | |
41 | . --- table with four columns. | |
42 | ||
43 | .macro option | |
44 | .oindex "$1" | |
45 | .itable all 0 0 4 8* left 5* center 5* center 6* right | |
46 | .row "&%$1%&" "Use: &'$2'&" "Type: &'$3'&" "Default: &'$4'&" | |
47 | .endtable | |
48 | .endmacro | |
49 | ||
50 | . --- A macro for the common 2-column tables. The width of the first column | |
51 | . --- is suitable for the many tables at the start of the main options chapter; | |
52 | . --- the small number of other 2-column tables override it. | |
53 | ||
54 | .macro table2 190pt 300pt | |
55 | .itable none 0 0 2 $1 left $2 left | |
56 | .endmacro | |
57 | ||
58 | . --- Macros for the concept and option index entries | |
59 | ||
60 | .macro cindex | |
61 | &<indexterm role="concept">& | |
62 | &<primary>&$1&</primary>& | |
63 | .arg 2 | |
64 | &<secondary>&$2&</secondary>& | |
65 | .endarg | |
66 | &</indexterm>& | |
67 | .endmacro | |
68 | ||
69 | .macro oindex | |
70 | &<indexterm role="option">& | |
71 | &<primary>&$1&</primary>& | |
72 | .arg 2 | |
73 | &<secondary>&$2&</secondary>& | |
74 | .endarg | |
75 | &</indexterm>& | |
76 | .endmacro | |
77 | ||
78 | .macro index | |
79 | .echo "** Don't use .index; use .cindex or .oindex" | |
80 | .endmacro | |
81 | . //////////////////////////////////////////////////////////////////////////// | |
82 | ||
83 | ||
84 | . //////////////////////////////////////////////////////////////////////////// | |
85 | . The <bookinfo> element is removed from the XML before processing for Ascii | |
86 | . output formats. | |
87 | . //////////////////////////////////////////////////////////////////////////// | |
88 | ||
89 | .literal xml | |
90 | <bookinfo> | |
91 | <title>Specification of the Exim Mail Transfer Agent</title> | |
92 | <titleabbrev>The Exim MTA</titleabbrev> | |
93 | <date>05 January 2006</date> | |
94 | <author><firstname>Philip</firstname><surname>Hazel</surname></author> | |
95 | <authorinitials>PH</authorinitials> | |
96 | <affiliation><orgname>University of Cambridge Computing Service</orgname></affiliation> | |
97 | <address>New Museums Site, Pembroke Street, Cambridge CB2 3QH, England</address> | |
98 | <revhistory><revision> | |
99 | <revnumber>4.60-1</revnumber> | |
100 | <date>30 January 2006</date> | |
101 | <authorinitials>PH</authorinitials> | |
102 | </revision></revhistory> | |
103 | <copyright><year>2006</year><holder>University of Cambridge</holder></copyright> | |
104 | </bookinfo> | |
105 | .literal off | |
106 | ||
107 | ||
108 | . ///////////////////////////////////////////////////////////////////////////// | |
109 | . This chunk of literal XML implements index entries of the form "x, see y" and | |
110 | . "x, see also y". However, the DocBook DTD doesn't allow <indexterm> entries | |
111 | . at the top level, so we have to put the .chapter directive first. | |
112 | . ///////////////////////////////////////////////////////////////////////////// | |
113 | ||
114 | .chapter "Introduction" | |
115 | .literal xml | |
116 | ||
168e428f PH |
117 | <indexterm role="concept"> |
118 | <primary>$1, $2, etc.</primary> | |
119 | <see><emphasis>numerical variables</emphasis></see> | |
120 | </indexterm> | |
121 | <indexterm role="concept"> | |
122 | <primary>address</primary> | |
123 | <secondary>rewriting</secondary> | |
124 | <see><emphasis>rewriting</emphasis></see> | |
125 | </indexterm> | |
068aaea8 PH |
126 | <indexterm role="concept"> |
127 | <primary>Bounce Address Tag Validation</primary> | |
128 | <see><emphasis>BATV</emphasis></see> | |
129 | </indexterm> | |
130 | <indexterm role="concept"> | |
131 | <primary>Client SMTP Authorization</primary> | |
132 | <see><emphasis>CSA</emphasis></see> | |
133 | </indexterm> | |
168e428f PH |
134 | <indexterm role="concept"> |
135 | <primary>CR character</primary> | |
136 | <see><emphasis>carriage return</emphasis></see> | |
137 | </indexterm> | |
138 | <indexterm role="concept"> | |
139 | <primary>CRL</primary> | |
140 | <see><emphasis>certificate revocation list</emphasis></see> | |
141 | </indexterm> | |
142 | <indexterm role="concept"> | |
143 | <primary>delivery</primary> | |
144 | <secondary>failure report</secondary> | |
145 | <see><emphasis>bounce message</emphasis></see> | |
146 | </indexterm> | |
147 | <indexterm role="concept"> | |
148 | <primary>dialup</primary> | |
149 | <see><emphasis>intermittently connected hosts</emphasis></see> | |
150 | </indexterm> | |
151 | <indexterm role="concept"> | |
152 | <primary>exiscan</primary> | |
153 | <see><emphasis>content scanning</emphasis></see> | |
154 | </indexterm> | |
155 | <indexterm role="concept"> | |
156 | <primary>failover</primary> | |
157 | <see><emphasis>fallback</emphasis></see> | |
158 | </indexterm> | |
159 | <indexterm role="concept"> | |
160 | <primary>fallover</primary> | |
161 | <see><emphasis>fallback</emphasis></see> | |
162 | </indexterm> | |
163 | <indexterm role="concept"> | |
164 | <primary>filter</primary> | |
165 | <secondary>Sieve</secondary> | |
166 | <see><emphasis>Sieve filter</emphasis></see> | |
167 | </indexterm> | |
168 | <indexterm role="concept"> | |
169 | <primary>ident</primary> | |
170 | <see><emphasis>RFC 1413</emphasis></see> | |
171 | </indexterm> | |
172 | <indexterm role="concept"> | |
173 | <primary>LF character</primary> | |
174 | <see><emphasis>linefeed</emphasis></see> | |
175 | </indexterm> | |
176 | <indexterm role="concept"> | |
177 | <primary>maximum</primary> | |
178 | <see><emphasis>limit</emphasis></see> | |
179 | </indexterm> | |
068aaea8 PH |
180 | <indexterm role="concept"> |
181 | <primary>monitor</primary> | |
182 | <see><emphasis>Exim monitor</emphasis></see> | |
183 | </indexterm> | |
168e428f PH |
184 | <indexterm role="concept"> |
185 | <primary>no_<emphasis>xxx</emphasis></primary> | |
186 | <see>entry for xxx</see> | |
187 | </indexterm> | |
188 | <indexterm role="concept"> | |
189 | <primary>NUL</primary> | |
190 | <see><emphasis>binary zero</emphasis></see> | |
191 | </indexterm> | |
192 | <indexterm role="concept"> | |
193 | <primary>passwd file</primary> | |
194 | <see><emphasis>/etc/passwd</emphasis></see> | |
195 | </indexterm> | |
196 | <indexterm role="concept"> | |
197 | <primary>process id</primary> | |
198 | <see><emphasis>pid</emphasis></see> | |
199 | </indexterm> | |
200 | <indexterm role="concept"> | |
201 | <primary>RBL</primary> | |
202 | <see><emphasis>DNS list</emphasis></see> | |
203 | </indexterm> | |
204 | <indexterm role="concept"> | |
205 | <primary>redirection</primary> | |
206 | <see><emphasis>address redirection</emphasis></see> | |
207 | </indexterm> | |
208 | <indexterm role="concept"> | |
209 | <primary>return path</primary> | |
210 | <seealso><emphasis>envelope sender</emphasis></seealso> | |
211 | </indexterm> | |
212 | <indexterm role="concept"> | |
213 | <primary>scanning</primary> | |
214 | <see><emphasis>content scanning</emphasis></see> | |
215 | </indexterm> | |
216 | <indexterm role="concept"> | |
217 | <primary>SSL</primary> | |
218 | <see><emphasis>TLS</emphasis></see> | |
219 | </indexterm> | |
220 | <indexterm role="concept"> | |
221 | <primary>string</primary> | |
222 | <secondary>expansion</secondary> | |
223 | <see><emphasis>expansion</emphasis></see> | |
224 | </indexterm> | |
225 | <indexterm role="concept"> | |
226 | <primary>top bit</primary> | |
227 | <see><emphasis>8-bit characters</emphasis></see> | |
228 | </indexterm> | |
229 | <indexterm role="concept"> | |
230 | <primary>variables</primary> | |
231 | <see><emphasis>expansion, variables</emphasis></see> | |
232 | </indexterm> | |
233 | <indexterm role="concept"> | |
234 | <primary>zero, binary</primary> | |
235 | <see><emphasis>binary zero</emphasis></see> | |
236 | </indexterm> | |
9b371988 PH |
237 | |
238 | .literal off | |
168e428f PH |
239 | |
240 | ||
9b371988 PH |
241 | . ///////////////////////////////////////////////////////////////////////////// |
242 | . This is the real start of the first chapter. See the comment above as to why | |
243 | . we can't have the .chapter line here. | |
244 | . chapter "Introduction" | |
245 | . ///////////////////////////////////////////////////////////////////////////// | |
168e428f PH |
246 | |
247 | Exim is a mail transfer agent (MTA) for hosts that are running Unix or | |
248 | Unix-like operating systems. It was designed on the assumption that it would be | |
249 | run on hosts that are permanently connected to the Internet. However, it can be | |
250 | used on intermittently connected hosts with suitable configuration adjustments. | |
251 | ||
252 | Configuration files currently exist for the following operating systems: AIX, | |
068aaea8 PH |
253 | BSD/OS (aka BSDI), Darwin (Mac OS X), DGUX, Dragonfly, FreeBSD, GNU/Hurd, |
254 | GNU/Linux, HI-OSF (Hitachi), HI-UX, HP-UX, IRIX, MIPS RISCOS, NetBSD, OpenBSD, | |
255 | OpenUNIX, QNX, SCO, SCO SVR4.2 (aka UNIX-SV), Solaris (aka SunOS5), SunOS4, | |
256 | Tru64-Unix (formerly Digital UNIX, formerly DEC-OSF1), Ultrix, and Unixware. | |
257 | Some of these operating systems are no longer current and cannot easily be | |
258 | tested, so the configuration files may no longer work in practice. | |
168e428f PH |
259 | |
260 | There are also configuration files for compiling Exim in the Cygwin environment | |
261 | that can be installed on systems running Windows. However, this document does | |
262 | not contain any information about running Exim in the Cygwin environment. | |
263 | ||
264 | The terms and conditions for the use and distribution of Exim are contained in | |
9b371988 PH |
265 | the file &_NOTICE_&. Exim is distributed under the terms of the GNU General |
266 | Public Licence, a copy of which may be found in the file &_LICENCE_&. | |
168e428f PH |
267 | |
268 | The use, supply or promotion of Exim for the purpose of sending bulk, | |
269 | unsolicited electronic mail is incompatible with the basic aims of the program, | |
270 | which revolve around the free provision of a service that enhances the quality | |
271 | of personal communications. The author of Exim regards indiscriminate | |
272 | mass-mailing as an antisocial, irresponsible abuse of the Internet. | |
273 | ||
274 | Exim owes a great deal to Smail 3 and its author, Ron Karr. Without the | |
275 | experience of running and working on the Smail 3 code, I could never have | |
276 | contemplated starting to write a new MTA. Many of the ideas and user interfaces | |
277 | were originally taken from Smail 3, though the actual code of Exim is entirely | |
278 | new, and has developed far beyond the initial concept. | |
279 | ||
280 | Many people, both in Cambridge and around the world, have contributed to the | |
281 | development and the testing of Exim, and to porting it to various operating | |
282 | systems. I am grateful to them all. The distribution now contains a file called | |
9b371988 | 283 | &_ACKNOWLEDGMENTS_&, in which I have started recording the names of |
168e428f PH |
284 | contributors. |
285 | ||
286 | ||
9b371988 PH |
287 | .section "Exim documentation" |
288 | .new | |
289 | .cindex "documentation" | |
290 | This edition of the Exim specification applies to version &version; of Exim. | |
291 | Substantive changes from the &previousversion; edition are marked in some | |
168e428f PH |
292 | renditions of the document; this paragraph is so marked if the rendition is |
293 | capable of showing a change indicator. | |
9b371988 | 294 | .wen |
168e428f PH |
295 | |
296 | This document is very much a reference manual; it is not a tutorial. The reader | |
297 | is expected to have some familiarity with the SMTP mail transfer protocol and | |
298 | with general Unix system administration. Although there are some discussions | |
299 | and examples in places, the information is mostly organized in a way that makes | |
300 | it easy to look up, rather than in a natural order for sequential reading. | |
301 | Furthermore, the manual aims to cover every aspect of Exim in detail, including | |
302 | a number of rarely-used, special-purpose features that are unlikely to be of | |
303 | very wide interest. | |
304 | ||
9b371988 PH |
305 | .cindex "books about Exim" |
306 | An &"easier"& discussion of Exim which provides more in-depth explanatory, | |
307 | introductory, and tutorial material can be found in a book entitled &'The Exim | |
308 | SMTP Mail Server'&, published by UIT Cambridge | |
309 | (&url(http://www.uit.co.uk/exim-book/)). | |
168e428f PH |
310 | |
311 | This book also contains a chapter that gives a general introduction to SMTP and | |
312 | Internet mail. Inevitably, however, the book is unlikely to be fully up-to-date | |
313 | with the latest release of Exim. (Note that the earlier book about Exim, | |
314 | published by O'Reilly, covers Exim 3, and many things have changed in Exim 4.) | |
315 | ||
9b371988 PH |
316 | .new |
317 | .cindex "Debian" "information sources" | |
068aaea8 PH |
318 | If you are using a Debian distribution of Exim, you will find information about |
319 | Debian-specific features in the file | |
9b371988 PH |
320 | .display |
321 | &_/usr/share/doc/exim4-base/README.Debian_& | |
322 | .endd | |
323 | The command &(man update-exim.conf)& is another source of Debian-specific | |
068aaea8 | 324 | information. |
9b371988 | 325 | .wen |
068aaea8 | 326 | |
9b371988 PH |
327 | .cindex "&_doc/NewStuff_&" |
328 | .cindex "&_doc/ChangeLog_&" | |
329 | .cindex "change log" | |
168e428f PH |
330 | As the program develops, there may be features in newer versions that have not |
331 | yet made it into this document, which is updated only when the most significant | |
332 | digit of the fractional part of the version number changes. Specifications of | |
333 | new features that are not yet in this manual are placed in the file | |
9b371988 | 334 | &_doc/NewStuff_& in the Exim distribution. |
168e428f | 335 | |
9b371988 | 336 | Some features may be classified as &"experimental"&. These may change |
168e428f PH |
337 | incompatibly while they are developing, or even be withdrawn. For this reason, |
338 | they are not documented in this manual. Information about experimental features | |
9b371988 | 339 | can be found in the file &_doc/experimental.txt_&. |
168e428f PH |
340 | |
341 | All changes to the program (whether new features, bug fixes, or other kinds of | |
9b371988 | 342 | change) are noted briefly in the file called &_doc/ChangeLog_&. |
168e428f | 343 | |
9b371988 PH |
344 | .cindex "&_doc/spec.txt_&" |
345 | This specification itself is available as an ASCII file in &_doc/spec.txt_& so | |
346 | that it can easily be searched with a text editor. Other files in the &_doc_& | |
168e428f PH |
347 | directory are: |
348 | ||
9b371988 PH |
349 | .table2 100pt |
350 | .row &_OptionLists.txt_& "list of all options in alphabetical order" | |
351 | .row &_dbm.discuss.txt_& "discussion about DBM libraries" | |
352 | .row &_exim.8_& "a man page of Exim's command line options" | |
353 | .row &_experimental.txt_& "documentation of experimental features" | |
354 | .row &_filter.txt_& "specification of the filter language" | |
355 | .row &_pcrepattern.txt_& "specification of PCRE regular expressions" | |
356 | .row &_pcretest.txt_& "specification of the PCRE testing program" | |
357 | .row &_Exim3.upgrade_& "upgrade notes from release 2 to release 3" | |
358 | .row &_Exim4.upgrade_& "upgrade notes from release 3 to release 4" | |
359 | .endtable | |
168e428f PH |
360 | |
361 | The main specification and the specification of the filtering language are also | |
362 | available in other formats (HTML, PostScript, PDF, and Texinfo). Section | |
9b371988 | 363 | &<<SECTavail>>& below tells you how to get hold of these. |
168e428f PH |
364 | |
365 | ||
366 | ||
9b371988 PH |
367 | .section "FTP and web sites" |
368 | .cindex "web site" | |
369 | .cindex "FTP site" | |
068aaea8 | 370 | The primary site for Exim source distributions is currently the University of |
9b371988 PH |
371 | Cambridge's FTP site, whose contents are described in &'Where to find the Exim |
372 | distribution'& below. In addition, there is a web site and an FTP site at | |
373 | &%exim.org%&. These are now also hosted at the University of Cambridge. The | |
374 | &%exim.org%& site was previously hosted for a number of years by Energis | |
375 | Squared, formerly Planet Online Ltd, whose support I gratefully acknowledge. | |
376 | ||
377 | .cindex "wiki" | |
378 | .cindex "FAQ" | |
168e428f | 379 | As well as Exim distribution tar files, the Exim web site contains a number of |
9b371988 PH |
380 | differently formatted versions of the documentation, including the FAQ in both |
381 | text and HTML formats. The HTML version comes with a keyword-in-context index. | |
382 | A recent addition to the online information is the Exim wiki | |
383 | (&url(http://www.exim.org/eximwiki/)). We hope that this will make it easier | |
384 | for Exim users to contribute examples, tips, and know-how for the benefit of | |
385 | others. | |
168e428f PH |
386 | |
387 | ||
388 | ||
9b371988 PH |
389 | .section "Mailing lists" |
390 | .cindex "mailing lists" "for Exim users" | |
168e428f PH |
391 | The following are the three main Exim mailing lists: |
392 | ||
9b371988 PH |
393 | .table2 140pt |
394 | .row &'exim-users@exim.org'& "general discussion list" | |
395 | .row &'exim-dev@exim.org'& "discussion of bugs, enhancements, etc." | |
396 | .row &'exim-announce@exim.org'& "moderated, low volume announcements list" | |
397 | .endtable | |
168e428f PH |
398 | |
399 | You can subscribe to these lists, change your existing subscriptions, and view | |
9b371988 PH |
400 | or search the archives via the mailing lists link on the Exim home page. |
401 | .cindex "Debian" "mailing list for" | |
402 | &new("If you are using a Debian distribution of Exim, you may wish to subscribe | |
403 | to the Debian-specific mailing list | |
404 | &'pkg-exim4-users@lists.alioth.debian.org'&.") | |
405 | .wen | |
406 | ||
407 | .section "Exim training" | |
408 | .cindex "training courses" | |
068aaea8 | 409 | From time to time (approximately annually at the time of writing), training |
9b371988 PH |
410 | courses are run by the author of Exim in Cambridge, UK. Details of any |
411 | forthcoming courses can be found on the web site | |
412 | &url(http://www-tus.csx.cam.ac.uk/courses/exim/). | |
168e428f PH |
413 | |
414 | ||
9b371988 PH |
415 | .section "Bug reports" |
416 | .cindex "bug reports" | |
417 | .cindex "reporting bugs" | |
418 | Reports of obvious bugs should be emailed to &'bugs@exim.org'&. However, if you | |
419 | are unsure whether some behaviour is a bug or not, the best thing to do is to | |
420 | post a message to the &'exim-dev'& mailing list and have it discussed. | |
168e428f PH |
421 | |
422 | ||
423 | ||
9b371988 PH |
424 | .section "Where to find the Exim distribution" "SECTavail" |
425 | .cindex "FTP site" | |
426 | .cindex "distribution" "ftp site" | |
168e428f | 427 | The master ftp site for the Exim distribution is |
9b371988 PH |
428 | .display |
429 | &*ftp://ftp.csx.cam.ac.uk/pub/software/email/exim*& | |
430 | .endd | |
168e428f | 431 | This is mirrored by |
9b371988 PH |
432 | .display |
433 | &*ftp://ftp.exim.org/pub/exim*& | |
434 | .endd | |
435 | The file references that follow are relative to the &_exim_& directories at | |
436 | these sites. There are now quite a number of independent mirror sites around | |
437 | the world. Those that I know about are listed in the file called &_Mirrors_&. | |
438 | ||
439 | Within the &_exim_& directory there are subdirectories called &_exim3_& (for | |
440 | previous Exim 3 distributions), &_exim4_& (for the latest Exim 4 | |
441 | distributions), and &_Testing_& for testing versions. In the &_exim4_& | |
168e428f | 442 | subdirectory, the current release can always be found in files called |
9b371988 PH |
443 | .display |
444 | &_exim-n.nn.tar.gz_& | |
445 | &_exim-n.nn.tar.bz2_& | |
446 | .endd | |
447 | where &'n.nn'& is the highest such version number in the directory. The two | |
168e428f | 448 | files contain identical data; the only difference is the type of compression. |
9b371988 | 449 | The &_.bz2_& file is usually a lot smaller than the &_.gz_& file. |
168e428f | 450 | |
9b371988 PH |
451 | .cindex "distribution" "signing details" |
452 | .cindex "distribution" "public key" | |
453 | .cindex "public key for signed distribution" | |
168e428f PH |
454 | The distributions are currently signed with Philip Hazel's GPG key. The |
455 | corresponding public key is available from a number of keyservers, and there is | |
9b371988 | 456 | also a copy in the file &_Public-Key_&. The signatures for the tar bundles are |
168e428f | 457 | in: |
9b371988 PH |
458 | .display |
459 | &_exim-n.nn.tar.gz.sig_& | |
460 | &_exim-n.nn.tar.bz2.sig_& | |
461 | .endd | |
168e428f | 462 | For each released version, the log of changes is made separately available in a |
9b371988 | 463 | separate file in the directory &_ChangeLogs_& so that it is possible to |
168e428f PH |
464 | find out what has changed without having to download the entire distribution. |
465 | ||
9b371988 | 466 | .cindex "documentation" "available formats" |
168e428f PH |
467 | The main distribution contains ASCII versions of this specification and other |
468 | documentation; other formats of the documents are available in separate files | |
9b371988 PH |
469 | inside the &_exim4_& directory of the FTP site: |
470 | .display | |
471 | &_exim-html-n.nn.tar.gz_& | |
472 | &_exim-pdf-n.nn.tar.gz_& | |
473 | &_exim-postscript-n.nn.tar.gz_& | |
474 | &_exim-texinfo-n.nn.tar.gz_& | |
475 | .endd | |
476 | These tar files contain only the &_doc_& directory, not the complete | |
477 | distribution, and are also available in &_.bz2_& as well as &_.gz_& forms. | |
478 | .cindex "FAQ" | |
168e428f | 479 | The FAQ is available for downloading in two different formats in these files: |
9b371988 PH |
480 | .display |
481 | &_exim4/FAQ.txt.gz_& | |
482 | &_exim4/FAQ.html.tar.gz_& | |
483 | .endd | |
168e428f PH |
484 | The first of these is a single ASCII file that can be searched with a text |
485 | editor. The second is a directory of HTML files, normally accessed by starting | |
9b371988 | 486 | at &_index.html_&. The HTML version of the FAQ (which is also included in the |
168e428f PH |
487 | HTML documentation tarbundle) includes a keyword-in-context index, which is |
488 | often the most convenient way of finding your way around. | |
489 | ||
490 | ||
9b371988 PH |
491 | .section "Wish list" |
492 | .cindex "wish list" | |
168e428f PH |
493 | A wish list is maintained, containing ideas for new features that have been |
494 | submitted. From time to time the file is exported to the ftp site into the file | |
9b371988 | 495 | &_exim4/WishList_&. Items are removed from the list if they get implemented. |
168e428f PH |
496 | |
497 | ||
498 | ||
9b371988 PH |
499 | .section "Contributed material" |
500 | .cindex "contributed material" | |
501 | At the ftp site, there is a directory called &_Contrib_& that contains | |
168e428f PH |
502 | miscellaneous files contributed to the Exim community by Exim users. There is |
503 | also a collection of contributed configuration examples in | |
9b371988 PH |
504 | &_exim4/config.samples.tar.gz_&. These samples are referenced from the FAQ. |
505 | ||
506 | ||
507 | ||
508 | .section "Limitations" | |
509 | .ilist | |
510 | .cindex "limitations of Exim" | |
511 | .cindex "bang paths" "not handled by Exim" | |
512 | Exim is designed for use as an Internet MTA, and therefore handles addresses in | |
513 | RFC 2822 domain format only. It cannot handle UUCP &"bang paths"&, though | |
514 | simple two-component bang paths can be converted by a straightforward rewriting | |
515 | configuration. This restriction does not prevent Exim from being interfaced to | |
516 | UUCP as a transport mechanism, provided that domain addresses are used. | |
517 | .next | |
518 | .cindex "domainless addresses" | |
519 | .cindex "address" "without domain" | |
168e428f PH |
520 | Exim insists that every address it handles has a domain attached. For incoming |
521 | local messages, domainless addresses are automatically qualified with a | |
522 | configured domain value. Configuration options specify from which remote | |
523 | systems unqualified addresses are acceptable. These are then qualified on | |
524 | arrival. | |
9b371988 PH |
525 | .next |
526 | .cindex "transport" "external" | |
527 | .cindex "external transports" | |
528 | The only external transport mechanisms that are currently implemented are SMTP | |
529 | and LMTP over a TCP/IP network (including support for IPv6). However, a pipe | |
168e428f | 530 | transport is available, and there are facilities for writing messages to files |
9b371988 PH |
531 | and pipes, optionally in &'batched SMTP'& format; these facilities can be used |
532 | to send messages to other transport mechanisms such as UUCP, provided they can | |
533 | handle domain-style addresses. Batched SMTP input is also catered for. | |
534 | .next | |
535 | Exim is not designed for storing mail for dial-in hosts. When the volumes of | |
536 | such mail are large, it is better to get the messages &"delivered"& into files | |
168e428f PH |
537 | (that is, off Exim's queue) and subsequently passed on to the dial-in hosts by |
538 | other means. | |
9b371988 PH |
539 | .next |
540 | Although Exim does have basic facilities for scanning incoming messages, these | |
168e428f PH |
541 | are not comprehensive enough to do full virus or spam scanning. Such operations |
542 | are best carried out using additional specialized software packages. If you | |
543 | compile Exim with the content-scanning extension, straightforward interfaces to | |
544 | a number of common scanners are provided. | |
9b371988 | 545 | .endlist |
168e428f PH |
546 | |
547 | ||
9b371988 | 548 | .section "Run time configuration" |
168e428f PH |
549 | Exim's run time configuration is held in a single text file that is divided |
550 | into a number of sections. The entries in this file consist of keywords and | |
551 | values, in the style of Smail 3 configuration files. A default configuration | |
552 | file which is suitable for simple online installations is provided in the | |
9b371988 | 553 | distribution, and is described in chapter &<<CHAPdefconfil>>& below. |
168e428f PH |
554 | |
555 | ||
9b371988 PH |
556 | .section "Calling interface" |
557 | .cindex "Sendmail compatibility" "command line interface" | |
168e428f | 558 | Like many MTAs, Exim has adopted the Sendmail command line interface so that it |
9b371988 PH |
559 | can be a straight replacement for &_/usr/lib/sendmail_& or |
560 | &_/usr/sbin/sendmail_& when sending mail, but you do not need to know anything | |
168e428f PH |
561 | about Sendmail in order to run Exim. For actions other than sending messages, |
562 | Sendmail-compatible options also exist, but those that produce output (for | |
9b371988 | 563 | example, &%-bp%&, which lists the messages on the queue) do so in Exim's own |
168e428f | 564 | format. There are also some additional options that are compatible with Smail |
9b371988 | 565 | 3, and some further options that are new to Exim. Chapter &<<CHAPcommandline>>& |
168e428f PH |
566 | documents all Exim's command line options. This information is automatically |
567 | made into the man page that forms part of the Exim distribution. | |
568 | ||
569 | Control of messages on the queue can be done via certain privileged command | |
9b371988 PH |
570 | line options. There is also an optional monitor program called &'eximon'&, |
571 | which displays current information in an X window, and which contains a menu | |
168e428f PH |
572 | interface to Exim's command line administration options. |
573 | ||
574 | ||
575 | ||
9b371988 PH |
576 | .section "Terminology" |
577 | .cindex "terminology definitions" | |
578 | .cindex "body of message" "definition of" | |
579 | The &'body'& of a message is the actual data that the sender wants to transmit. | |
580 | It is the last part of a message, and is separated from the &'header'& (see | |
168e428f PH |
581 | below) by a blank line. |
582 | ||
9b371988 | 583 | .cindex "bounce message" "definition of" |
168e428f | 584 | When a message cannot be delivered, it is normally returned to the sender in a |
9b371988 PH |
585 | delivery failure message or a &"non-delivery report"& (NDR). The term |
586 | &'bounce'& is commonly used for this action, and the error reports are often | |
587 | called &'bounce messages'&. This is a convenient shorthand for &"delivery | |
588 | failure error report"&. Such messages have an empty sender address in the | |
589 | message's &'envelope'& (see below) to ensure that they cannot themselves give | |
590 | rise to further bounce messages. | |
591 | ||
592 | The term &'default'& appears frequently in this manual. It is used to qualify a | |
168e428f PH |
593 | value which is used in the absence of any setting in the configuration. It may |
594 | also qualify an action which is taken unless a configuration setting specifies | |
595 | otherwise. | |
596 | ||
9b371988 | 597 | The term &'defer'& is used when the delivery of a message to a specific |
168e428f | 598 | destination cannot immediately take place for some reason (a remote host may be |
9b371988 | 599 | down, or a user's local mailbox may be full). Such deliveries are &'deferred'& |
168e428f PH |
600 | until a later time. |
601 | ||
9b371988 PH |
602 | The word &'domain'& is sometimes used to mean all but the first component of a |
603 | host's name. It is &'not'& used in that sense here, where it normally refers to | |
604 | the part of an email address following the @ sign. | |
168e428f | 605 | |
9b371988 PH |
606 | .cindex "envelope" "definition of" |
607 | .cindex "sender" "definition of" | |
608 | A message in transit has an associated &'envelope'&, as well as a header and a | |
168e428f PH |
609 | body. The envelope contains a sender address (to which bounce messages should |
610 | be delivered), and any number of recipient addresses. References to the | |
611 | sender or the recipients of a message usually mean the addresses in the | |
612 | envelope. An MTA uses these addresses for delivery, and for returning bounce | |
613 | messages, not the addresses that appear in the header lines. | |
614 | ||
9b371988 PH |
615 | .cindex "message header" "definition of" |
616 | .cindex "header section" "definition of" | |
617 | The &'header'& of a message is the first part of a message's text, consisting | |
618 | of a number of lines, each of which has a name such as &'From:'&, &'To:'&, | |
619 | &'Subject:'&, etc. Long header lines can be split over several text lines by | |
168e428f PH |
620 | indenting the continuations. The header is separated from the body by a blank |
621 | line. | |
622 | ||
9b371988 PH |
623 | .cindex "local part" "definition of" |
624 | .cindex "domain" "definition of" | |
625 | The term &'local part'&, which is taken from RFC 2822, is used to refer to that | |
168e428f | 626 | part of an email address that precedes the @ sign. The part that follows the |
9b371988 | 627 | @ sign is called the &'domain'& or &'mail domain'&. |
168e428f | 628 | |
9b371988 PH |
629 | .cindex "local delivery" "definition of" |
630 | .cindex "remote delivery" "definition of" | |
631 | The terms &'local delivery'& and &'remote delivery'& are used to distinguish | |
168e428f | 632 | delivery to a file or a pipe on the local host from delivery by SMTP over |
068aaea8 | 633 | TCP/IP to another host. As far as Exim is concerned, all hosts other than the |
9b371988 | 634 | host it is running on are &'remote'&. |
168e428f | 635 | |
9b371988 PH |
636 | .cindex "return path" "definition of" |
637 | &'Return path'& is another name that is used for the sender address in a | |
168e428f PH |
638 | message's envelope. |
639 | ||
9b371988 PH |
640 | .cindex "queue" "definition of" |
641 | The term &'queue'& is used to refer to the set of messages awaiting delivery, | |
168e428f PH |
642 | because this term is in widespread use in the context of MTAs. However, in |
643 | Exim's case the reality is more like a pool than a queue, because there is | |
644 | normally no ordering of waiting messages. | |
645 | ||
9b371988 PH |
646 | .cindex "queue runner" "definition of" |
647 | The term &'queue runner'& is used to describe a process that scans the queue | |
168e428f | 648 | and attempts to deliver those messages whose retry times have come. This term |
9b371988 | 649 | is used by other MTAs, and also relates to the command &%runq%&, but in Exim |
168e428f PH |
650 | the waiting messages are normally processed in an unpredictable order. |
651 | ||
9b371988 PH |
652 | .cindex "spool directory" "definition of" |
653 | The term &'spool directory'& is used for a directory in which Exim keeps the | |
654 | messages on its queue &-- that is, those that it is in the process of | |
168e428f | 655 | delivering. This should not be confused with the directory in which local |
9b371988 PH |
656 | mailboxes are stored, which is called a &"spool directory"& by some people. In |
657 | the Exim documentation, &"spool"& is always used in the first sense. | |
168e428f PH |
658 | |
659 | ||
660 | ||
661 | ||
662 | ||
663 | ||
9b371988 PH |
664 | . //////////////////////////////////////////////////////////////////////////// |
665 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 666 | |
9b371988 PH |
667 | .chapter "Incorporated code" |
668 | .cindex "incorporated code" | |
669 | .cindex "regular expressions" "library" | |
670 | .cindex "PCRE" | |
168e428f PH |
671 | A number of pieces of external code are included in the Exim distribution. |
672 | ||
9b371988 PH |
673 | .ilist |
674 | Regular expressions are supported in the main Exim program and in the Exim | |
675 | monitor using the freely-distributable PCRE library, copyright © | |
676 | University of Cambridge. The source is distributed in the directory | |
677 | &_src/pcre_&. However, this is a cut-down version of PCRE. If you want to use | |
678 | the PCRE library in other programs, you should obtain and install the full | |
679 | version from &*ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre*&. | |
680 | .next | |
681 | .cindex "cdb" "acknowledgement" | |
168e428f PH |
682 | Support for the cdb (Constant DataBase) lookup method is provided by code |
683 | contributed by Nigel Metheringham of (at the time he contributed it) Planet | |
9b371988 PH |
684 | Online Ltd. The implementation is completely contained within the code of Exim. |
685 | It does not link against an external cdb library. The code contains the | |
686 | following statements: | |
687 | ||
688 | .blockquote | |
689 | Copyright © 1998 Nigel Metheringham, Planet Online Ltd | |
690 | ||
168e428f PH |
691 | This program is free software; you can redistribute it and/or modify it under |
692 | the terms of the GNU General Public License as published by the Free Software | |
693 | Foundation; either version 2 of the License, or (at your option) any later | |
694 | version. | |
9b371988 | 695 | |
168e428f PH |
696 | This code implements Dan Bernstein's Constant DataBase (cdb) spec. Information, |
697 | the spec and sample code for cdb can be obtained from | |
9b371988 PH |
698 | &url(http://www.pobox.com/~djb/cdb.html). This implementation borrows some |
699 | code from Dan Bernstein's implementation (which has no license restrictions | |
700 | applied to it). | |
701 | .endblockquote | |
702 | .next | |
703 | .cindex "SPA authentication" | |
704 | .cindex "Samba project" | |
705 | .cindex "Microsoft Secure Password Authentication" | |
706 | Client support for Microsoft's &'Secure Password Authentication'& is provided | |
168e428f PH |
707 | by code contributed by Marc Prud'hommeaux. Server support was contributed by |
708 | Tom Kistner. This includes code taken from the Samba project, which is released | |
709 | under the Gnu GPL. | |
9b371988 PH |
710 | .next |
711 | .cindex "Cyrus" | |
712 | .cindex "&'pwcheck'& daemon" | |
713 | .cindex "&'pwauthd'& daemon" | |
714 | Support for calling the Cyrus &'pwcheck'& and &'saslauthd'& daemons is provided | |
168e428f PH |
715 | by code taken from the Cyrus-SASL library and adapted by Alexander S. |
716 | Sabourenkov. The permission notice appears below, in accordance with the | |
717 | conditions expressed therein. | |
9b371988 PH |
718 | |
719 | .blockquote | |
720 | Copyright © 2001 Carnegie Mellon University. All rights reserved. | |
721 | ||
168e428f PH |
722 | Redistribution and use in source and binary forms, with or without |
723 | modification, are permitted provided that the following conditions | |
724 | are met: | |
168e428f | 725 | |
9b371988 PH |
726 | .olist |
727 | Redistributions of source code must retain the above copyright | |
728 | notice, this list of conditions and the following disclaimer. | |
729 | .next | |
730 | Redistributions in binary form must reproduce the above copyright | |
168e428f PH |
731 | notice, this list of conditions and the following disclaimer in |
732 | the documentation and/or other materials provided with the | |
733 | distribution. | |
9b371988 PH |
734 | .next |
735 | The name &"Carnegie Mellon University"& must not be used to | |
168e428f PH |
736 | endorse or promote products derived from this software without |
737 | prior written permission. For permission or any other legal | |
738 | details, please contact | |
9b371988 | 739 | .display |
068aaea8 PH |
740 | Office of Technology Transfer |
741 | Carnegie Mellon University | |
742 | 5000 Forbes Avenue | |
743 | Pittsburgh, PA 15213-3890 | |
744 | (412) 268-4387, fax: (412) 268-7395 | |
745 | tech-transfer@andrew.cmu.edu | |
9b371988 PH |
746 | .endd |
747 | .next | |
748 | Redistributions of any form whatsoever must retain the following | |
168e428f | 749 | acknowledgment: |
9b371988 PH |
750 | |
751 | &"This product includes software developed by Computing Services | |
752 | at Carnegie Mellon University (&url(http://www.cmu.edu/computing/)."& | |
753 | ||
168e428f PH |
754 | CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO |
755 | THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY | |
756 | AND FITNESS, IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY BE LIABLE | |
757 | FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | |
758 | WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN | |
759 | AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING | |
760 | OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | |
9b371988 PH |
761 | .endlist |
762 | .endblockquote | |
168e428f | 763 | |
9b371988 PH |
764 | .next |
765 | .cindex "Exim monitor" "acknowledgement" | |
766 | .cindex "X-windows" | |
767 | .cindex "Athena" | |
168e428f PH |
768 | The Exim Monitor program, which is an X-Window application, includes |
769 | modified versions of the Athena StripChart and TextPop widgets. | |
770 | This code is copyright by DEC and MIT, and their permission notice appears | |
771 | below, in accordance with the conditions expressed therein. | |
9b371988 PH |
772 | |
773 | .blockquote | |
168e428f PH |
774 | Copyright 1987, 1988 by Digital Equipment Corporation, Maynard, Massachusetts, |
775 | and the Massachusetts Institute of Technology, Cambridge, Massachusetts. | |
9b371988 | 776 | |
168e428f | 777 | All Rights Reserved |
9b371988 | 778 | |
168e428f PH |
779 | Permission to use, copy, modify, and distribute this software and its |
780 | documentation for any purpose and without fee is hereby granted, | |
781 | provided that the above copyright notice appear in all copies and that | |
782 | both that copyright notice and this permission notice appear in | |
783 | supporting documentation, and that the names of Digital or MIT not be | |
784 | used in advertising or publicity pertaining to distribution of the | |
785 | software without specific, written prior permission. | |
9b371988 | 786 | |
168e428f PH |
787 | DIGITAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING |
788 | ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL | |
789 | DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR | |
790 | ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, | |
791 | WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, | |
792 | ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS | |
793 | SOFTWARE. | |
9b371988 | 794 | .endblockquote |
168e428f | 795 | |
9b371988 PH |
796 | .next |
797 | Many people have contributed code fragments, some large, some small, that were | |
168e428f PH |
798 | not covered by any specific licence requirements. It is assumed that the |
799 | contributors are happy to see their code incoporated into Exim under the GPL. | |
9b371988 | 800 | .endlist |
168e428f PH |
801 | |
802 | ||
803 | ||
804 | ||
805 | ||
9b371988 PH |
806 | . //////////////////////////////////////////////////////////////////////////// |
807 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 808 | |
9b371988 PH |
809 | .chapter "How Exim receives and delivers mail" "" &&& |
810 | "Receiving and delivering mail" | |
168e428f PH |
811 | |
812 | ||
9b371988 PH |
813 | .section "Overall philosophy" |
814 | .cindex "design philosophy" | |
168e428f PH |
815 | Exim is designed to work efficiently on systems that are permanently connected |
816 | to the Internet and are handling a general mix of mail. In such circumstances, | |
817 | most messages can be delivered immediately. Consequently, Exim does not | |
818 | maintain independent queues of messages for specific domains or hosts, though | |
819 | it does try to send several messages in a single SMTP connection after a host | |
820 | has been down, and it also maintains per-host retry information. | |
821 | ||
822 | ||
9b371988 PH |
823 | .section "Policy control" |
824 | .cindex "policy control" "overview" | |
168e428f PH |
825 | Policy controls are now an important feature of MTAs that are connected to the |
826 | Internet. Perhaps their most important job is to stop MTAs being abused as | |
9b371988 PH |
827 | &"open relays"& by misguided individuals who send out vast amounts of |
828 | unsolicited junk, and want to disguise its source. Exim provides flexible | |
829 | facilities for specifying policy controls on incoming mail: | |
168e428f | 830 | |
9b371988 PH |
831 | .ilist |
832 | .cindex "&ACL;" "introduction" | |
168e428f | 833 | Exim 4 (unlike previous versions of Exim) implements policy controls on |
9b371988 | 834 | incoming mail by means of &'Access Control Lists'& (ACLs). Each list is a |
168e428f PH |
835 | series of statements that may either grant or deny access. ACLs can be used at |
836 | several places in the SMTP dialogue while receiving a message from a remote | |
9b371988 PH |
837 | host. However, the most common places are after each RCPT command, and at the |
838 | very end of the message. The sysadmin can specify conditions for accepting or | |
839 | rejecting individual recipients or the entire message, respectively, at these | |
840 | two points (see chapter &<<CHAPACL>>&). Denial of access results in an SMTP | |
168e428f | 841 | error code. |
9b371988 PH |
842 | .next |
843 | An ACL is also available for locally generated, non-SMTP messages. In this | |
168e428f | 844 | case, the only available actions are to accept or deny the entire message. |
9b371988 PH |
845 | .next |
846 | When Exim is compiled with the content-scanning extension, facilities are | |
168e428f PH |
847 | provided in the ACL mechanism for passing the message to external virus and/or |
848 | spam scanning software. The result of such a scan is passed back to the ACL, | |
849 | which can then use it to decide what to do with the message. | |
9b371988 PH |
850 | .next |
851 | When a message has been received, either from a remote host or from the local | |
168e428f | 852 | host, but before the final acknowledgement has been sent, a locally supplied C |
9b371988 PH |
853 | function called &[local_scan()]& can be run to inspect the message and decide |
854 | whether to accept it or not (see chapter &<<CHAPlocalscan>>&). If the message | |
855 | is accepted, the list of recipients can be modified by the function. | |
856 | .next | |
857 | Using the &[local_scan()]& mechanism is another way of calling external scanner | |
858 | software. The &%SA-Exim%& add-on package works this way. It does not require | |
859 | Exim to be compiled with the content-scanning extension. | |
860 | .next | |
861 | After a message has been accepted, a further checking mechanism is available in | |
862 | the form of the &'system filter'& (see chapter &<<CHAPsystemfilter>>&). This | |
863 | runs at the start of every delivery process. | |
864 | .endlist | |
865 | ||
866 | ||
867 | ||
868 | .section "User filters" | |
869 | .cindex "filter" "introduction" | |
870 | .cindex "Sieve filter" | |
168e428f | 871 | In a conventional Exim configuration, users are able to run private filters by |
9b371988 PH |
872 | setting up appropriate &_.forward_& files in their home directories. See |
873 | chapter &<<CHAPredirect>>& (about the &(redirect)& router) for the | |
874 | configuration needed to support this, and the separate document entitled | |
875 | &'Exim's interfaces to mail filtering'& for user details. Two different kinds | |
876 | of filtering are available: | |
877 | ||
878 | .ilist | |
879 | Sieve filters are written in the standard filtering language that is defined | |
168e428f | 880 | by RFC 3028. |
9b371988 PH |
881 | .next |
882 | Exim filters are written in a syntax that is unique to Exim, but which is more | |
168e428f | 883 | powerful than Sieve, which it pre-dates. |
9b371988 | 884 | .endlist |
168e428f PH |
885 | |
886 | User filters are run as part of the routing process, described below. | |
887 | ||
888 | ||
889 | ||
9b371988 PH |
890 | .section "Message identification" "SECTmessiden" |
891 | .cindex "message ids" "details of format" | |
892 | .cindex "format" "of message id" | |
893 | .cindex "id of message" | |
894 | .cindex "base62" | |
895 | .cindex "base36" | |
896 | .cindex "Darwin" | |
897 | .cindex "Cygwin" | |
898 | Every message handled by Exim is given a &'message id'& which is sixteen | |
168e428f | 899 | characters long. It is divided into three parts, separated by hyphens, for |
9b371988 | 900 | example &`16VDhn-0001bo-D3`&. Each part is a sequence of letters and digits, |
168e428f PH |
901 | normally encoding numbers in base 62. However, in the Darwin operating |
902 | system (Mac OS X) and when Exim is compiled to run under Cygwin, base 36 | |
903 | (avoiding the use of lower case letters) is used instead, because the message | |
904 | id is used to construct file names, and the names of files in those systems are | |
068aaea8 | 905 | not always case-sensitive. |
168e428f | 906 | |
9b371988 | 907 | .cindex "pid (process id)" "re-use of" |
168e428f PH |
908 | The detail of the contents of the message id have changed as Exim has evolved. |
909 | Earlier versions relied on the operating system not re-using a process id (pid) | |
910 | within one second. On modern operating systems, this assumption can no longer | |
911 | be made, so the algorithm had to be changed. To retain backward compatibility, | |
912 | the format of the message id was retained, which is why the following rules are | |
913 | somewhat eccentric: | |
914 | ||
9b371988 PH |
915 | .ilist |
916 | The first six characters of the message id are the time at which the message | |
168e428f PH |
917 | started to be received, to a granularity of one second. That is, this field |
918 | contains the number of seconds since the start of the epoch (the normal Unix | |
919 | way of representing the date and time of day). | |
9b371988 PH |
920 | .next |
921 | After the first hyphen, the next six characters are the id of the process that | |
168e428f | 922 | received the message. |
9b371988 PH |
923 | .next |
924 | There are two different possibilities for the final two characters: | |
925 | .olist | |
926 | .cindex "&%localhost_number%&" | |
927 | If &%localhost_number%& is not set, this value is the fractional part of the | |
168e428f PH |
928 | time of reception, normally in units of 1/2000 of a second, but for systems |
929 | that must use base 36 instead of base 62 (because of case-insensitive file | |
930 | systems), the units are 1/1000 of a second. | |
9b371988 PH |
931 | .next |
932 | If &%localhost_number%& is set, it is multiplied by 200 (100) and added to | |
168e428f PH |
933 | the fractional part of the time, which in this case is in units of 1/200 |
934 | (1/100) of a second. | |
9b371988 PH |
935 | .endlist |
936 | .endlist | |
168e428f PH |
937 | |
938 | After a message has been received, Exim waits for the clock to tick at the | |
939 | appropriate resolution before proceeding, so that if another message is | |
940 | received by the same process, or by another process with the same (re-used) | |
941 | pid, it is guaranteed that the time will be different. In most cases, the clock | |
942 | will already have ticked while the message was being received. | |
943 | ||
944 | ||
9b371988 PH |
945 | .section "Receiving mail" |
946 | .cindex "receiving mail" | |
947 | .cindex "message" "reception" | |
068aaea8 PH |
948 | The only way Exim can receive mail from another host is using SMTP over |
949 | TCP/IP, in which case the sender and recipient addresses are transferred using | |
168e428f PH |
950 | SMTP commands. However, from a locally running process (such as a user's MUA), |
951 | there are several possibilities: | |
952 | ||
9b371988 PH |
953 | .ilist |
954 | If the process runs Exim with the &%-bm%& option, the message is read | |
168e428f | 955 | non-interactively (usually via a pipe), with the recipients taken from the |
9b371988 PH |
956 | command line, or from the body of the message if &%-t%& is also used. |
957 | .next | |
958 | If the process runs Exim with the &%-bS%& option, the message is also read | |
168e428f PH |
959 | non-interactively, but in this case the recipients are listed at the start of |
960 | the message in a series of SMTP RCPT commands, terminated by a DATA | |
9b371988 | 961 | command. This is so-called &"batch SMTP"& format, |
168e428f PH |
962 | but it isn't really SMTP. The SMTP commands are just another way of passing |
963 | envelope addresses in a non-interactive submission. | |
9b371988 PH |
964 | .next |
965 | If the process runs Exim with the &%-bs%& option, the message is read | |
168e428f PH |
966 | interactively, using the SMTP protocol. A two-way pipe is normally used for |
967 | passing data between the local process and the Exim process. | |
9b371988 | 968 | This is &"real"& SMTP and is handled in the same way as SMTP over TCP/IP. For |
168e428f | 969 | example, the ACLs for SMTP commands are used for this form of submission. |
9b371988 PH |
970 | .next |
971 | A local process may also make a TCP/IP call to the host's loopback address | |
168e428f PH |
972 | (127.0.0.1) or any other of its IP addresses. When receiving messages, Exim |
973 | does not treat the loopback address specially. It treats all such connections | |
974 | in the same way as connections from other hosts. | |
9b371988 | 975 | .endlist |
168e428f PH |
976 | |
977 | ||
9b371988 PH |
978 | .cindex "message sender" "constructed by Exim" |
979 | .cindex "sender" "constructed by Exim" | |
168e428f PH |
980 | In the three cases that do not involve TCP/IP, the sender address is |
981 | constructed from the login name of the user that called Exim and a default | |
9b371988 | 982 | qualification domain (which can be set by the &%qualify_domain%& configuration |
168e428f PH |
983 | option). For local or batch SMTP, a sender address that is passed using the |
984 | SMTP MAIL command is ignored. However, the system administrator may allow | |
9b371988 | 985 | certain users (&"trusted users"&) to specify a different sender address |
168e428f | 986 | unconditionally, or all users to specify certain forms of different sender |
9b371988 PH |
987 | address. The &%-f%& option or the SMTP MAIL command is used to specify these |
988 | different addresses. See section &<<SECTtrustedadmin>>& for details of trusted | |
989 | users, and the &%untrusted_set_sender%& option for a way of allowing untrusted | |
168e428f PH |
990 | users to change sender addresses. |
991 | ||
992 | Messages received by either of the non-interactive mechanisms are subject to | |
993 | checking by the non-SMTP ACL, if one is defined. Messages received using SMTP | |
994 | (either over TCP/IP, or interacting with a local process) can be checked by a | |
995 | number of ACLs that operate at different times during the SMTP session. Either | |
996 | individual recipients, or the entire message, can be rejected if local policy | |
9b371988 PH |
997 | requirements are not met. The &[local_scan()]& function (see chapter |
998 | &<<CHAPlocalscan>>&) is run for all incoming messages. | |
168e428f PH |
999 | |
1000 | Exim can be configured not to start a delivery process when a message is | |
1001 | received; this can be unconditional, or depend on the number of incoming SMTP | |
1002 | connections or the system load. In these situations, new messages wait on the | |
1003 | queue until a queue runner process picks them up. However, in standard | |
1004 | configurations under normal conditions, delivery is started as soon as a | |
1005 | message is received. | |
1006 | ||
1007 | ||
1008 | ||
1009 | ||
1010 | ||
9b371988 PH |
1011 | .section "Handling an incoming message" |
1012 | .cindex "spool directory" "files that hold a message" | |
1013 | .cindex "file" "how a message is held" | |
168e428f PH |
1014 | When Exim accepts a message, it writes two files in its spool directory. The |
1015 | first contains the envelope information, the current status of the message, and | |
1016 | the header lines, and the second contains the body of the message. The names of | |
9b371988 PH |
1017 | the two spool files consist of the message id, followed by &`-H`& for the |
1018 | file containing the envelope and header, and &`-D`& for the data file. | |
168e428f | 1019 | |
9b371988 | 1020 | .cindex "spool directory" "&_input_& sub-directory" |
168e428f | 1021 | By default all these message files are held in a single directory called |
9b371988 | 1022 | &_input_& inside the general Exim spool directory. Some operating systems do |
168e428f | 1023 | not perform very well if the number of files in a directory gets very large; to |
9b371988 | 1024 | improve performance in such cases, the &%split_spool_directory%& option can be |
168e428f PH |
1025 | used. This causes Exim to split up the input files into 62 sub-directories |
1026 | whose names are single letters or digits. | |
1027 | ||
1028 | The envelope information consists of the address of the message's sender and | |
1029 | the addresses of the recipients. This information is entirely separate from | |
1030 | any addresses contained in the header lines. The status of the message includes | |
1031 | a list of recipients who have already received the message. The format of the | |
9b371988 | 1032 | first spool file is described in chapter &<<CHAPspool>>&. |
168e428f | 1033 | |
9b371988 | 1034 | .cindex "rewriting" "addresses" |
168e428f | 1035 | Address rewriting that is specified in the rewrite section of the configuration |
9b371988 | 1036 | (see chapter &<<CHAPrewrite>>&) is done once and for all on incoming addresses, |
168e428f PH |
1037 | both in the header lines and the envelope, at the time the message is accepted. |
1038 | If during the course of delivery additional addresses are generated (for | |
1039 | example, via aliasing), these new addresses are rewritten as soon as they are | |
1040 | generated. At the time a message is actually delivered (transported) further | |
1041 | rewriting can take place; because this is a transport option, it can be | |
1042 | different for different forms of delivery. It is also possible to specify the | |
1043 | addition or removal of certain header lines at the time the message is | |
9b371988 PH |
1044 | delivered (see chapters &<<CHAProutergeneric>>& and |
1045 | &<<CHAPtransportgeneric>>&). | |
168e428f PH |
1046 | |
1047 | ||
1048 | ||
9b371988 PH |
1049 | .section "Life of a message" |
1050 | .cindex "message" "life of" | |
1051 | .cindex "message" "frozen" | |
168e428f PH |
1052 | A message remains in the spool directory until it is completely delivered to |
1053 | its recipients or to an error address, or until it is deleted by an | |
1054 | administrator or by the user who originally created it. In cases when delivery | |
9b371988 PH |
1055 | cannot proceed &-- for example, when a message can neither be delivered to its |
1056 | recipients nor returned to its sender, the message is marked &"frozen"& on the | |
168e428f PH |
1057 | spool, and no more deliveries are attempted. |
1058 | ||
9b371988 PH |
1059 | .cindex "frozen messages" "thawing" |
1060 | .cindex "message" "thawing frozen" | |
1061 | An administrator can &"thaw"& such messages when the problem has been | |
1062 | corrected, and can also freeze individual messages by hand if necessary. In | |
1063 | addition, an administrator can force a delivery error, causing a bounce message | |
1064 | to be sent. | |
1065 | ||
1066 | .new | |
1067 | .cindex "&%timeout_frozen_after%&" | |
1068 | .cindex "&%ignore_bounce_errors_after%&" | |
1069 | There are options called &%ignore_bounce_errors_after%& and | |
1070 | &%timeout_frozen_after%&, which discard frozen messages after a certain time. | |
068aaea8 | 1071 | The first applies only to frozen bounces, the second to any frozen messages. |
9b371988 | 1072 | .wen |
168e428f | 1073 | |
9b371988 PH |
1074 | .cindex "message" "log file for" |
1075 | .cindex "log" "file for each message" | |
168e428f | 1076 | While Exim is working on a message, it writes information about each delivery |
068aaea8 | 1077 | attempt to its main log file. This includes successful, unsuccessful, and |
9b371988 PH |
1078 | delayed deliveries for each recipient (see chapter &<<CHAPlog>>&). The log |
1079 | lines are also written to a separate &'message log'& file for each message. | |
1080 | These logs are solely for the benefit of the administrator, and are normally | |
1081 | deleted along with the spool files when processing of a message is complete. | |
168e428f | 1082 | The use of individual message logs can be disabled by setting |
9b371988 PH |
1083 | &%no_message_logs%&; this might give an improvement in performance on very busy |
1084 | systems. | |
168e428f | 1085 | |
9b371988 PH |
1086 | .cindex "journal file" |
1087 | .cindex "file" "journal" | |
168e428f PH |
1088 | All the information Exim itself needs to set up a delivery is kept in the first |
1089 | spool file, along with the header lines. When a successful delivery occurs, the | |
1090 | address is immediately written at the end of a journal file, whose name is the | |
9b371988 PH |
1091 | message id followed by &`-J`&. At the end of a delivery run, if there are some |
1092 | addresses left to be tried again later, the first spool file (the &`-H`& file) | |
168e428f PH |
1093 | is updated to indicate which these are, and the journal file is then deleted. |
1094 | Updating the spool file is done by writing a new file and renaming it, to | |
1095 | minimize the possibility of data loss. | |
1096 | ||
1097 | Should the system or the program crash after a successful delivery but before | |
1098 | the spool file has been updated, the journal is left lying around. The next | |
1099 | time Exim attempts to deliver the message, it reads the journal file and | |
1100 | updates the spool file before proceeding. This minimizes the chances of double | |
1101 | deliveries caused by crashes. | |
1102 | ||
1103 | ||
1104 | ||
9b371988 PH |
1105 | .section "Processing an address for delivery" "SECTprocaddress" |
1106 | .cindex "drivers" "definition of" | |
1107 | .cindex "router" "definition of" | |
1108 | .cindex "transport" "definition of" | |
1109 | The main delivery processing elements of Exim are called &'routers'& and | |
1110 | &'transports'&, and collectively these are known as &'drivers'&. Code for a | |
168e428f PH |
1111 | number of them is provided in the source distribution, and compile-time options |
1112 | specify which ones are included in the binary. Run time options specify which | |
1113 | ones are actually used for delivering messages. | |
1114 | ||
9b371988 PH |
1115 | .cindex "drivers" "instance definition" |
1116 | Each driver that is specified in the run time configuration is an &'instance'& | |
168e428f | 1117 | of that particular driver type. Multiple instances are allowed; for example, |
9b371988 | 1118 | you can set up several different &(smtp)& transports, each with different |
168e428f PH |
1119 | option values that might specify different ports or different timeouts. Each |
1120 | instance has its own identifying name. In what follows we will normally use the | |
1121 | instance name when discussing one particular instance (that is, one specific | |
1122 | configuration of the driver), and the generic driver name when discussing | |
1123 | the driver's features in general. | |
1124 | ||
9b371988 | 1125 | A &'router'& is a driver that operates on an address, either determining how |
068aaea8 | 1126 | its delivery should happen, by assigning it to a specific transport, or |
168e428f PH |
1127 | converting the address into one or more new addresses (for example, via an |
1128 | alias file). A router may also explicitly choose to fail an address, causing it | |
1129 | to be bounced. | |
1130 | ||
9b371988 PH |
1131 | A &'transport'& is a driver that transmits a copy of the message from Exim's |
1132 | spool to some destination. There are two kinds of transport: for a &'local'& | |
168e428f | 1133 | transport, the destination is a file or a pipe on the local host, whereas for a |
9b371988 | 1134 | &'remote'& transport the destination is some other host. A message is passed |
168e428f PH |
1135 | to a specific transport as a result of successful routing. If a message has |
1136 | several recipients, it may be passed to a number of different transports. | |
1137 | ||
9b371988 | 1138 | .cindex "preconditions" "definition of" |
168e428f PH |
1139 | An address is processed by passing it to each configured router instance in |
1140 | turn, subject to certain preconditions, until a router accepts the address or | |
1141 | specifies that it should be bounced. We will describe this process in more | |
068aaea8 PH |
1142 | detail shortly. First, as a simple example, we consider how each recipient |
1143 | address in a message is processed in a small configuration of three routers. | |
168e428f | 1144 | |
068aaea8 | 1145 | To make this a more concrete example, it is described in terms of some actual |
168e428f PH |
1146 | routers, but remember, this is only an example. You can configure Exim's |
1147 | routers in many different ways, and there may be any number of routers in a | |
1148 | configuration. | |
1149 | ||
1150 | The first router that is specified in a configuration is often one that handles | |
1151 | addresses in domains that are not recognized specially by the local host. These | |
1152 | are typically addresses for arbitrary domains on the Internet. A precondition | |
1153 | is set up which looks for the special domains known to the host (for example, | |
9b371988 | 1154 | its own domain name), and the router is run for addresses that do &'not'& |
168e428f PH |
1155 | match. Typically, this is a router that looks up domains in the DNS in order to |
1156 | find the hosts to which this address routes. If it succeeds, the address is | |
068aaea8 | 1157 | assigned to a suitable SMTP transport; if it does not succeed, the router is |
168e428f PH |
1158 | configured to fail the address. |
1159 | ||
068aaea8 | 1160 | The second router is reached only when the domain is recognized as one that |
9b371988 | 1161 | &"belongs"& to the local host. This router does redirection &-- also known as |
068aaea8 PH |
1162 | aliasing and forwarding. When it generates one or more new addresses from the |
1163 | original, each of them is routed independently from the start. Otherwise, the | |
1164 | router may cause an address to fail, or it may simply decline to handle the | |
1165 | address, in which case the address is passed to the next router. | |
168e428f PH |
1166 | |
1167 | The final router in many configurations is one that checks to see if the | |
1168 | address belongs to a local mailbox. The precondition may involve a check to | |
1169 | see if the local part is the name of a login account, or it may look up the | |
1170 | local part in a file or a database. If its preconditions are not met, or if | |
1171 | the router declines, we have reached the end of the routers. When this happens, | |
1172 | the address is bounced. | |
1173 | ||
1174 | ||
1175 | ||
9b371988 PH |
1176 | .section "Processing an address for verification" |
1177 | .cindex "router" "for verification" | |
1178 | .cindex "verifying address" "overview" | |
168e428f | 1179 | As well as being used to decide how to deliver to an address, Exim's routers |
9b371988 | 1180 | are also used for &'address verification'&. Verification can be requested as |
168e428f | 1181 | one of the checks to be performed in an ACL for incoming messages, on both |
9b371988 PH |
1182 | sender and recipient addresses, and it can be tested using the &%-bv%& and |
1183 | &%-bvs%& command line options. | |
168e428f | 1184 | |
9b371988 | 1185 | When an address is being verified, the routers are run in &"verify mode"&. This |
168e428f PH |
1186 | does not affect the way the routers work, but it is a state that can be |
1187 | detected. By this means, a router can be skipped or made to behave differently | |
1188 | when verifying. A common example is a configuration in which the first router | |
1189 | sends all messages to a message-scanning program, unless they have been | |
1190 | previously scanned. Thus, the first router accepts all addresses without any | |
9b371988 | 1191 | checking, making it useless for verifying. Normally, the &%no_verify%& option |
168e428f PH |
1192 | would be set for such a router, causing it to be skipped in verify mode. |
1193 | ||
1194 | ||
1195 | ||
1196 | ||
9b371988 PH |
1197 | .section "Running an individual router" "SECTrunindrou" |
1198 | .cindex "router" "running details" | |
1199 | .cindex "preconditions" "checking" | |
1200 | .cindex "router" "result of running" | |
168e428f PH |
1201 | As explained in the example above, a number of preconditions are checked before |
1202 | running a router. If any are not met, the router is skipped, and the address is | |
9b371988 | 1203 | passed to the next router. When all the preconditions on a router &'are'& met, |
168e428f PH |
1204 | the router is run. What happens next depends on the outcome, which is one of |
1205 | the following: | |
1206 | ||
9b371988 PH |
1207 | .ilist |
1208 | &'accept'&: The router accepts the address, and either assigns it to a | |
1209 | transport, or generates one or more &"child"& addresses. Processing the | |
1210 | original address ceases, | |
1211 | .cindex "&%unseen%& option" | |
1212 | unless the &%unseen%& option is set on the router. This option | |
168e428f | 1213 | can be used to set up multiple deliveries with different routing (for example, |
9b371988 PH |
1214 | for keeping archive copies of messages). When &%unseen%& is set, the address is |
1215 | passed to the next router. Normally, however, an &'accept'& return marks the | |
168e428f | 1216 | end of routing. |
9b371988 | 1217 | |
068aaea8 PH |
1218 | Any child addresses generated by the router are processed independently, |
1219 | starting with the first router by default. It is possible to change this by | |
9b371988 PH |
1220 | setting the &%redirect_router%& option to specify which router to start at for |
1221 | child addresses. Unlike &%pass_router%& (see below) the router specified by | |
1222 | &%redirect_router%& may be anywhere in the router configuration. | |
1223 | .next | |
1224 | &'pass'&: The router recognizes the address, but cannot handle it itself. It | |
168e428f PH |
1225 | requests that the address be passed to another router. By default the address |
1226 | is passed to the next router, but this can be changed by setting the | |
9b371988 | 1227 | &%pass_router%& option. However, (unlike &%redirect_router%&) the named router |
168e428f | 1228 | must be below the current router (to avoid loops). |
9b371988 PH |
1229 | .next |
1230 | &'decline'&: The router declines to accept the address because it does not | |
168e428f | 1231 | recognize it at all. By default, the address is passed to the next router, but |
9b371988 PH |
1232 | this can be prevented by setting the &%no_more%& option. When &%no_more%& is |
1233 | set, all the remaining routers are skipped. In effect, &%no_more%& converts | |
1234 | &'decline'& into &'fail'&. | |
1235 | .next | |
1236 | &'fail'&: The router determines that the address should fail, and queues it for | |
168e428f | 1237 | the generation of a bounce message. There is no further processing of the |
9b371988 PH |
1238 | original address unless &%unseen%& is set on the router. |
1239 | .next | |
1240 | &'defer'&: The router cannot handle the address at the present time. (A | |
068aaea8 PH |
1241 | database may be offline, or a DNS lookup may have timed out.) No further |
1242 | processing of the address happens in this delivery attempt. It is tried again | |
1243 | next time the message is considered for delivery. | |
9b371988 PH |
1244 | .next |
1245 | &'error'&: There is some error in the router (for example, a syntax error in | |
168e428f | 1246 | its configuration). The action is as for defer. |
9b371988 | 1247 | .endlist |
168e428f PH |
1248 | |
1249 | If an address reaches the end of the routers without having been accepted by | |
068aaea8 | 1250 | any of them, it is bounced as unrouteable. The default error message in this |
9b371988 PH |
1251 | situation is &"unrouteable address"&, but you can set your own message by |
1252 | making use of the &%cannot_route_message%& option. This can be set for any | |
1253 | router; the value from the last router that &"saw"& the address is used. | |
168e428f PH |
1254 | |
1255 | Sometimes while routing you want to fail a delivery when some conditions are | |
1256 | met but others are not, instead of passing the address on for further routing. | |
1257 | You can do this by having a second router that explicitly fails the delivery | |
9b371988 | 1258 | when the relevant conditions are met. The &(redirect)& router has a &"fail"& |
168e428f PH |
1259 | facility for this purpose. |
1260 | ||
1261 | ||
9b371988 PH |
1262 | .section "Duplicate addresses" |
1263 | .new | |
1264 | .cindex "case of local parts" | |
1265 | .cindex "address duplicate" "discarding" | |
068aaea8 PH |
1266 | Once routing is complete, Exim scans the addresses that are assigned to local |
1267 | and remote transports, and discards any duplicates that it finds. During this | |
1268 | check, local parts are treated as case-sensitive. | |
9b371988 | 1269 | .wen |
068aaea8 | 1270 | |
168e428f | 1271 | |
9b371988 PH |
1272 | .section "Router preconditions" "SECTrouprecon" |
1273 | .cindex "router preconditions" "order of processing" | |
1274 | .cindex "preconditions" "order of processing" | |
168e428f PH |
1275 | The preconditions that are tested for each router are listed below, in the |
1276 | order in which they are tested. The individual configuration options are | |
9b371988 | 1277 | described in more detail in chapter &<<CHAProutergeneric>>&. |
168e428f | 1278 | |
9b371988 PH |
1279 | .ilist |
1280 | The &%local_part_prefix%& and &%local_part_suffix%& options can specify that | |
168e428f PH |
1281 | the local parts handled by the router may or must have certain prefixes and/or |
1282 | suffixes. If a mandatory affix (prefix or suffix) is not present, the router is | |
1283 | skipped. These conditions are tested first. When an affix is present, it is | |
1284 | removed from the local part before further processing, including the evaluation | |
1285 | of any other conditions. | |
9b371988 PH |
1286 | .next |
1287 | Routers can be designated for use only when not verifying an address, that is, | |
168e428f | 1288 | only when routing it for delivery (or testing its delivery routing). If the |
9b371988 | 1289 | &%verify%& option is set false, the router is skipped when Exim is verifying an |
168e428f | 1290 | address. |
9b371988 PH |
1291 | Setting the &%verify%& option actually sets two options, &%verify_sender%& and |
1292 | &%verify_recipient%&, which independently control the use of the router for | |
168e428f PH |
1293 | sender and recipient verification. You can set these options directly if |
1294 | you want a router to be used for only one type of verification. | |
9b371988 PH |
1295 | .next |
1296 | If the &%address_test%& option is set false, the router is skipped when Exim is | |
1297 | run with the &%-bt%& option to test an address routing. This can be helpful | |
1298 | when the first router sends all new messages to a scanner of some sort; it | |
1299 | makes it possible to use &%-bt%& to test subsequent delivery routing without | |
1300 | having to simulate the effect of the scanner. | |
1301 | .next | |
1302 | Routers can be designated for use only when verifying an address, as | |
1303 | opposed to routing it for delivery. The &%verify_only%& option controls this. | |
1304 | .next | |
1305 | Individual routers can be explicitly skipped when running the routers to | |
1306 | check an address given in the SMTP EXPN command (see the &%expn%& option). | |
1307 | .next | |
1308 | If the &%domains%& option is set, the domain of the address must be in the set | |
068aaea8 | 1309 | of domains that it defines. |
9b371988 PH |
1310 | .next |
1311 | .cindex "&$local_part_prefix$&" | |
1312 | .cindex "&$local_part$&" | |
1313 | .cindex "&$local_part_suffix$&" | |
1314 | If the &%local_parts%& option is set, the local part of the address must be in | |
1315 | the set of local parts that it defines. If &%local_part_prefix%& or | |
1316 | &%local_part_suffix%& is in use, the prefix or suffix is removed from the local | |
168e428f | 1317 | part before this check. If you want to do precondition tests on local parts |
9b371988 PH |
1318 | that include affixes, you can do so by using a &%condition%& option (see below) |
1319 | that uses the variables &$local_part$&, &$local_part_prefix$&, and | |
1320 | &$local_part_suffix$& as necessary. | |
1321 | .next | |
1322 | .cindex "&$local_user_uid$&" | |
1323 | .cindex "&$local_user_gid$&" | |
1324 | .cindex "&$home$&" | |
1325 | If the &%check_local_user%& option is set, the local part must be the name of | |
068aaea8 | 1326 | an account on the local host. If this check succeeds, the uid and gid of the |
9b371988 PH |
1327 | local user are placed in &$local_user_uid$& and &$local_user_gid$& and the |
1328 | user's home directory is placed in &$home$&; these values can be used in the | |
1329 | remaining preconditions. | |
1330 | .next | |
1331 | If the &%router_home_directory%& option is set, it is expanded at this point, | |
1332 | because it overrides the value of &$home$&. If this expansion were left till | |
1333 | later, the value of &$home$& as set by &%check_local_user%& would be used in | |
1334 | subsequent tests. Having two different values of &$home$& in the same router | |
168e428f | 1335 | could lead to confusion. |
9b371988 PH |
1336 | .next |
1337 | If the &%senders%& option is set, the envelope sender address must be in the | |
1338 | set of addresses that it defines. | |
1339 | .next | |
1340 | If the &%require_files%& option is set, the existence or non-existence of | |
168e428f | 1341 | specified files is tested. |
9b371988 PH |
1342 | .next |
1343 | .cindex "customizing" "precondition" | |
1344 | If the &%condition%& option is set, it is evaluated and tested. This option | |
1345 | uses an expanded string to allow you to set up your own custom preconditions. | |
1346 | Expanded strings are described in chapter &<<CHAPexpand>>&. | |
1347 | .endlist | |
168e428f | 1348 | |
168e428f | 1349 | |
9b371988 PH |
1350 | Note that &%require_files%& comes near the end of the list, so you cannot use |
1351 | it to check for the existence of a file in which to lookup up a domain, local | |
168e428f | 1352 | part, or sender. However, as these options are all expanded, you can use the |
9b371988 PH |
1353 | &%exists%& expansion condition to make such tests within each condition. The |
1354 | &%require_files%& option is intended for checking files that the router may be | |
168e428f | 1355 | going to use internally, or which are needed by a specific transport (for |
9b371988 | 1356 | example, &_.procmailrc_&). |
168e428f PH |
1357 | |
1358 | ||
1359 | ||
9b371988 PH |
1360 | .section "Delivery in detail" |
1361 | .cindex "delivery" "in detail" | |
168e428f PH |
1362 | When a message is to be delivered, the sequence of events is as follows: |
1363 | ||
9b371988 PH |
1364 | .ilist |
1365 | If a system-wide filter file is specified, the message is passed to it. The | |
168e428f PH |
1366 | filter may add recipients to the message, replace the recipients, discard the |
1367 | message, cause a new message to be generated, or cause the message delivery to | |
1368 | fail. The format of the system filter file is the same as for Exim user filter | |
9b371988 PH |
1369 | files, described in the separate document entitled &'Exim's interfaces to mail |
1370 | filtering'&. | |
1371 | .cindex "Sieve filter" "not available for system filter" | |
1372 | (&*Note*&: Sieve cannot be used for system filter files.) | |
1373 | ||
1374 | Some additional features are available in system filters &-- see chapter | |
1375 | &<<CHAPsystemfilter>>& for details. Note that a message is passed to the system | |
168e428f PH |
1376 | filter only once per delivery attempt, however many recipients it has. However, |
1377 | if there are several delivery attempts because one or more addresses could not | |
1378 | be immediately delivered, the system filter is run each time. The filter | |
9b371988 | 1379 | condition &%first_delivery%& can be used to detect the first run of the system |
168e428f | 1380 | filter. |
9b371988 PH |
1381 | .next |
1382 | Each recipient address is offered to each configured router in turn, subject to | |
1383 | its preconditions, until one is able to handle it. If no router can handle the | |
1384 | address, that is, if they all decline, the address is failed. Because routers | |
1385 | can be targeted at particular domains, several locally handled domains can be | |
1386 | processed entirely independently of each other. | |
1387 | .next | |
1388 | .cindex "routing" "loops in" | |
1389 | .cindex "loop" "while routing" | |
1390 | A router that accepts an address may assign it to a local or a remote | |
1391 | transport. However, the transport is not run at this time. Instead, the address | |
1392 | is placed on a list for the particular transport, which will be run later. | |
068aaea8 PH |
1393 | Alternatively, the router may generate one or more new addresses (typically |
1394 | from alias, forward, or filter files). New addresses are fed back into this | |
1395 | process from the top, but in order to avoid loops, a router ignores any address | |
1396 | which has an identically-named ancestor that was processed by itself. | |
9b371988 PH |
1397 | .next |
1398 | When all the routing has been done, addresses that have been successfully | |
168e428f PH |
1399 | handled are passed to their assigned transports. When local transports are |
1400 | doing real local deliveries, they handle only one address at a time, but if a | |
1401 | local transport is being used as a pseudo-remote transport (for example, to | |
1402 | collect batched SMTP messages for transmission by some other means) multiple | |
1403 | addresses can be handled. Remote transports can always handle more than one | |
1404 | address at a time, but can be configured not to do so, or to restrict multiple | |
1405 | addresses to the same domain. | |
9b371988 PH |
1406 | .next |
1407 | Each local delivery to a file or a pipe runs in a separate process under a | |
168e428f PH |
1408 | non-privileged uid, and these deliveries are run one at a time. Remote |
1409 | deliveries also run in separate processes, normally under a uid that is private | |
9b371988 | 1410 | to Exim (&"the Exim user"&), but in this case, several remote deliveries can be |
168e428f | 1411 | run in parallel. The maximum number of simultaneous remote deliveries for any |
9b371988 | 1412 | one message is set by the &%remote_max_parallel%& option. |
168e428f PH |
1413 | The order in which deliveries are done is not defined, except that all local |
1414 | deliveries happen before any remote deliveries. | |
9b371988 PH |
1415 | .next |
1416 | .cindex "queue runner" | |
168e428f PH |
1417 | When it encounters a local delivery during a queue run, Exim checks its retry |
1418 | database to see if there has been a previous temporary delivery failure for the | |
1419 | address before running the local transport. If there was a previous failure, | |
1420 | Exim does not attempt a new delivery until the retry time for the address is | |
1421 | reached. However, this happens only for delivery attempts that are part of a | |
1422 | queue run. Local deliveries are always attempted when delivery immediately | |
1423 | follows message reception, even if retry times are set for them. This makes for | |
1424 | better behaviour if one particular message is causing problems (for example, | |
1425 | causing quota overflow, or provoking an error in a filter file). | |
9b371988 PH |
1426 | .next |
1427 | .cindex "delivery" "retry in remote transports" | |
168e428f PH |
1428 | Remote transports do their own retry handling, since an address may be |
1429 | deliverable to one of a number of hosts, each of which may have a different | |
1430 | retry time. If there have been previous temporary failures and no host has | |
1431 | reached its retry time, no delivery is attempted, whether in a queue run or | |
9b371988 PH |
1432 | not. See chapter &<<CHAPretry>>& for details of retry strategies. |
1433 | .next | |
1434 | If there were any permanent errors, a bounce message is returned to an | |
168e428f PH |
1435 | appropriate address (the sender in the common case), with details of the error |
1436 | for each failing address. Exim can be configured to send copies of bounce | |
1437 | messages to other addresses. | |
9b371988 PH |
1438 | .next |
1439 | .cindex "delivery" "deferral" | |
168e428f PH |
1440 | If one or more addresses suffered a temporary failure, the message is left on |
1441 | the queue, to be tried again later. Delivery of these addresses is said to be | |
9b371988 PH |
1442 | &'deferred'&. |
1443 | .next | |
1444 | When all the recipient addresses have either been delivered or bounced, | |
168e428f PH |
1445 | handling of the message is complete. The spool files and message log are |
1446 | deleted, though the message log can optionally be preserved if required. | |
9b371988 | 1447 | .endlist |
168e428f PH |
1448 | |
1449 | ||
1450 | ||
1451 | ||
9b371988 PH |
1452 | .section "Retry mechanism" |
1453 | .cindex "delivery" "retry mechanism" | |
1454 | .cindex "retry" "description of mechanism" | |
1455 | .cindex "queue runner" | |
168e428f PH |
1456 | Exim's mechanism for retrying messages that fail to get delivered at the first |
1457 | attempt is the queue runner process. You must either run an Exim daemon that | |
9b371988 PH |
1458 | uses the &%-q%& option with a time interval to start queue runners at regular |
1459 | intervals, or use some other means (such as &'cron'&) to start them. If you do | |
168e428f PH |
1460 | not arrange for queue runners to be run, messages that fail temporarily at the |
1461 | first attempt will remain on your queue for ever. A queue runner process works | |
068aaea8 | 1462 | its way through the queue, one message at a time, trying each delivery that has |
168e428f PH |
1463 | passed its retry time. |
1464 | You can run several queue runners at once. | |
1465 | ||
1466 | Exim uses a set of configured rules to determine when next to retry the failing | |
9b371988 PH |
1467 | address (see chapter &<<CHAPretry>>&). These rules also specify when Exim |
1468 | should give up trying to deliver to the address, at which point it generates a | |
1469 | bounce message. If no retry rules are set for a particular host, address, and | |
1470 | error combination, no retries are attempted, and temporary errors are treated | |
1471 | as permanent. | |
168e428f PH |
1472 | |
1473 | ||
1474 | ||
9b371988 PH |
1475 | .section "Temporary delivery failure" |
1476 | .cindex "delivery" "temporary failure" | |
168e428f PH |
1477 | There are many reasons why a message may not be immediately deliverable to a |
1478 | particular address. Failure to connect to a remote machine (because it, or the | |
1479 | connection to it, is down) is one of the most common. Temporary failures may be | |
1480 | detected during routing as well as during the transport stage of delivery. | |
1481 | Local deliveries may be delayed if NFS files are unavailable, or if a mailbox | |
1482 | is on a file system where the user is over quota. Exim can be configured to | |
1483 | impose its own quotas on local mailboxes; where system quotas are set they will | |
1484 | also apply. | |
1485 | ||
1486 | If a host is unreachable for a period of time, a number of messages may be | |
1487 | waiting for it by the time it recovers, and sending them in a single SMTP | |
1488 | connection is clearly beneficial. Whenever a delivery to a remote host is | |
1489 | deferred, | |
1490 | ||
9b371988 | 1491 | .cindex "hints database" |
168e428f PH |
1492 | Exim makes a note in its hints database, and whenever a successful |
1493 | SMTP delivery has happened, it looks to see if any other messages are waiting | |
1494 | for the same host. If any are found, they are sent over the same SMTP | |
1495 | connection, subject to a configuration limit as to the maximum number in any | |
1496 | one connection. | |
1497 | ||
1498 | ||
1499 | ||
1500 | ||
9b371988 PH |
1501 | .section "Permanent delivery failure" |
1502 | .cindex "delivery" "permanent failure" | |
1503 | .cindex "bounce message" "when generated" | |
168e428f PH |
1504 | When a message cannot be delivered to some or all of its intended recipients, a |
1505 | bounce message is generated. Temporary delivery failures turn into permanent | |
1506 | errors when their timeout expires. All the addresses that fail in a given | |
1507 | delivery attempt are listed in a single message. If the original message has | |
1508 | many recipients, it is possible for some addresses to fail in one delivery | |
1509 | attempt and others to fail subsequently, giving rise to more than one bounce | |
1510 | message. The wording of bounce messages can be customized by the administrator. | |
9b371988 | 1511 | See chapter &<<CHAPemsgcust>>& for details. |
168e428f | 1512 | |
9b371988 PH |
1513 | .cindex "&'X-Failed-Recipients:'& header line" |
1514 | Bounce messages contain an &'X-Failed-Recipients:'& header line that lists the | |
168e428f PH |
1515 | failed addresses, for the benefit of programs that try to analyse such messages |
1516 | automatically. | |
1517 | ||
9b371988 | 1518 | .cindex "bounce message" "recipient of" |
168e428f PH |
1519 | A bounce message is normally sent to the sender of the original message, as |
1520 | obtained from the message's envelope. For incoming SMTP messages, this is the | |
9b371988 PH |
1521 | address given in the MAIL command. However, when an address is expanded via a |
1522 | forward or alias file, an alternative address can be specified for delivery | |
1523 | failures of the generated addresses. For a mailing list expansion (see section | |
1524 | &<<SECTmailinglists>>&) it is common to direct bounce messages to the manager | |
1525 | of the list. | |
168e428f PH |
1526 | |
1527 | ||
1528 | ||
9b371988 PH |
1529 | .section "Failures to deliver bounce messages" |
1530 | .cindex "bounce message" "failure to deliver" | |
168e428f PH |
1531 | If a bounce message (either locally generated or received from a remote host) |
1532 | itself suffers a permanent delivery failure, the message is left on the queue, | |
1533 | but it is frozen, awaiting the attention of an administrator. There are options | |
068aaea8 | 1534 | that can be used to make Exim discard such failed messages, or to keep them |
9b371988 PH |
1535 | for only a short time (see &%timeout_frozen_after%& and |
1536 | &%ignore_bounce_errors_after%&). | |
168e428f PH |
1537 | |
1538 | ||
1539 | ||
1540 | ||
1541 | ||
9b371988 PH |
1542 | . //////////////////////////////////////////////////////////////////////////// |
1543 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 1544 | |
9b371988 PH |
1545 | .chapter "Building and installing Exim" |
1546 | .cindex "building Exim" | |
168e428f | 1547 | |
9b371988 | 1548 | .section "Unpacking" |
168e428f PH |
1549 | Exim is distributed as a gzipped or bzipped tar file which, when upacked, |
1550 | creates a directory with the name of the current release (for example, | |
9b371988 PH |
1551 | &_exim-&version;_&) into which the following files are placed: |
1552 | ||
1553 | .table2 140pt | |
1554 | .row &_ACKNOWLEDGMENTS_& "contains some acknowledgments" | |
1555 | .row &_CHANGES_& "contains a reference to where changes are documented" | |
1556 | .row &_LICENCE_& "the GNU General Public Licence" | |
1557 | .row &_Makefile_& "top-level make file" | |
1558 | .row &_NOTICE_& "conditions for the use of Exim" | |
1559 | .row &_README_& "list of files, directories and simple build &&& | |
1560 | instructions" | |
1561 | .endtable | |
1562 | ||
1563 | Other files whose names begin with &_README_& may also be present. The | |
168e428f PH |
1564 | following subdirectories are created: |
1565 | ||
9b371988 PH |
1566 | .table2 140pt |
1567 | .row &_Local_& "an empty directory for local configuration files" | |
1568 | .row &_OS_& "OS-specific files" | |
1569 | .row &_doc_& "documentation files" | |
1570 | .row &_exim_monitor_& "source files for the Exim monitor" | |
1571 | .row &_scripts_& "scripts used in the build process" | |
1572 | .row &_src_& "remaining source files" | |
1573 | .row &_util_& "independent utilities" | |
1574 | .endtable | |
1575 | ||
1576 | The main utility programs are contained in the &_src_& directory, and are built | |
1577 | with the Exim binary. The &_util_& directory contains a few optional scripts | |
168e428f PH |
1578 | that may be useful to some sites. |
1579 | ||
1580 | ||
9b371988 PH |
1581 | .section "Multiple machine architectures and operating systems" |
1582 | .cindex "building Exim" "multiple OS/architectures" | |
168e428f PH |
1583 | The building process for Exim is arranged to make it easy to build binaries for |
1584 | a number of different architectures and operating systems from the same set of | |
9b371988 PH |
1585 | source files. Compilation does not take place in the &_src_& directory. |
1586 | Instead, a &'build directory'& is created for each architecture and operating | |
1587 | system. | |
1588 | .cindex "symbolic link" "to build directory" | |
168e428f | 1589 | Symbolic links to the sources are installed in this directory, which is where |
9b371988 PH |
1590 | the actual building takes place. In most cases, Exim can discover the machine |
1591 | architecture and operating system for itself, but the defaults can be | |
1592 | overridden if necessary. | |
168e428f | 1593 | |
168e428f | 1594 | |
9b371988 PH |
1595 | .section "DBM libraries" "SECTdb" |
1596 | .cindex "DBM libraries" "discussion of" | |
1597 | .cindex "hints database" "DBM files used for" | |
168e428f PH |
1598 | Even if you do not use any DBM files in your configuration, Exim still needs a |
1599 | DBM library in order to operate, because it uses indexed files for its hints | |
1600 | databases. Unfortunately, there are a number of DBM libraries in existence, and | |
1601 | different operating systems often have different ones installed. | |
1602 | ||
9b371988 PH |
1603 | .cindex "Solaris" "DBM library for" |
1604 | .cindex "IRIX" "DBM library for" | |
1605 | .cindex "BSD" "DBM library for" | |
1606 | .cindex "Linux" "DBM library for" | |
168e428f PH |
1607 | If you are using Solaris, IRIX, one of the modern BSD systems, or a modern |
1608 | Linux distribution, the DBM configuration should happen automatically, and you | |
1609 | may be able to ignore this section. Otherwise, you may have to learn more than | |
1610 | you would like about DBM libraries from what follows. | |
1611 | ||
9b371988 | 1612 | .cindex "&'ndbm'& DBM library" |
168e428f | 1613 | Licensed versions of Unix normally contain a library of DBM functions operating |
9b371988 | 1614 | via the &'ndbm'& interface, and this is what Exim expects by default. Free |
168e428f PH |
1615 | versions of Unix seem to vary in what they contain as standard. In particular, |
1616 | some early versions of Linux have no default DBM library, and different | |
1617 | distributors have chosen to bundle different libraries with their packaged | |
1618 | versions. However, the more recent releases seem to have standardised on the | |
1619 | Berkeley DB library. | |
1620 | ||
1621 | Different DBM libraries have different conventions for naming the files they | |
9b371988 | 1622 | use. When a program opens a file called &_dbmfile_&, there are several |
168e428f PH |
1623 | possibilities: |
1624 | ||
9b371988 PH |
1625 | .olist |
1626 | A traditional &'ndbm'& implementation, such as that supplied as part of | |
1627 | Solaris, operates on two files called &_dbmfile.dir_& and &_dbmfile.pag_&. | |
1628 | .next | |
1629 | .cindex "&'gdbm'& DBM library" | |
1630 | The GNU library, &'gdbm'&, operates on a single file. If used via its &'ndbm'& | |
168e428f | 1631 | compatibility interface it makes two different hard links to it with names |
9b371988 | 1632 | &_dbmfile.dir_& and &_dbmfile.pag_&, but if used via its native interface, the |
168e428f | 1633 | file name is used unmodified. |
9b371988 PH |
1634 | .next |
1635 | .cindex "Berkeley DB library" | |
1636 | The Berkeley DB package, if called via its &'ndbm'& compatibility interface, | |
1637 | operates on a single file called &_dbmfile.db_&, but otherwise looks to the | |
1638 | programmer exactly the same as the traditional &'ndbm'& implementation. | |
1639 | .next | |
1640 | If the Berkeley package is used in its native mode, it operates on a single | |
1641 | file called &_dbmfile_&; the programmer's interface is somewhat different to | |
1642 | the traditional &'ndbm'& interface. | |
1643 | .next | |
1644 | To complicate things further, there are several very different versions of the | |
168e428f | 1645 | Berkeley DB package. Version 1.85 was stable for a very long time, releases |
9b371988 PH |
1646 | 2.&'x'& and 3.&'x'& were current for a while, but the latest versions are now |
1647 | numbered 4.&'x'&. Maintenance of some of the earlier releases has ceased. All | |
168e428f | 1648 | versions of Berkeley DB can be obtained from |
9b371988 PH |
1649 | &url(http://www.sleepycat.com/). |
1650 | .next | |
1651 | .cindex "&'tdb'& DBM library" | |
1652 | Yet another DBM library, called &'tdb'&, is available from | |
1653 | &url(http://download.sourceforge.net/tdb). It has its own interface, and also | |
1654 | operates on a single file. | |
1655 | .endlist | |
1656 | ||
1657 | .cindex "USE_DB" | |
1658 | .cindex "DBM libraries" "configuration for building" | |
168e428f PH |
1659 | Exim and its utilities can be compiled to use any of these interfaces. In order |
1660 | to use any version of the Berkeley DB package in native mode, you must set | |
1661 | USE_DB in an appropriate configuration file (typically | |
9b371988 PH |
1662 | &_Local/Makefile_&). For example: |
1663 | .code | |
1664 | USE_DB=yes | |
1665 | .endd | |
168e428f PH |
1666 | Similarly, for gdbm you set USE_GDBM, and for tdb you set USE_TDB. An |
1667 | error is diagnosed if you set more than one of these. | |
1668 | ||
1669 | At the lowest level, the build-time configuration sets none of these options, | |
1670 | thereby assuming an interface of type (1). However, some operating system | |
1671 | configuration files (for example, those for the BSD operating systems and | |
1672 | Linux) assume type (4) by setting USE_DB as their default, and the | |
1673 | configuration files for Cygwin set USE_GDBM. Anything you set in | |
9b371988 | 1674 | &_Local/Makefile_&, however, overrides these system defaults. |
168e428f PH |
1675 | |
1676 | As well as setting USE_DB, USE_GDBM, or USE_TDB, it may also be | |
1677 | necessary to set DBMLIB, to cause inclusion of the appropriate library, as | |
1678 | in one of these lines: | |
9b371988 PH |
1679 | .code |
1680 | DBMLIB = -ldb | |
1681 | DBMLIB = -ltdb | |
1682 | .endd | |
168e428f PH |
1683 | Settings like that will work if the DBM library is installed in the standard |
1684 | place. Sometimes it is not, and the library's header file may also not be in | |
1685 | the default path. You may need to set INCLUDE to specify where the header | |
1686 | file is, and to specify the path to the library more fully in DBMLIB, as in | |
1687 | this example: | |
9b371988 PH |
1688 | .code |
1689 | INCLUDE=-I/usr/local/include/db-4.1 | |
1690 | DBMLIB=/usr/local/lib/db-4.1/libdb.a | |
1691 | .endd | |
168e428f | 1692 | There is further detailed discussion about the various DBM libraries in the |
9b371988 | 1693 | file &_doc/dbm.discuss.txt_& in the Exim distribution. |
168e428f PH |
1694 | |
1695 | ||
1696 | ||
9b371988 PH |
1697 | .section "Pre-building configuration" |
1698 | .cindex "building Exim" "pre-building configuration" | |
1699 | .cindex "configuration for building Exim" | |
1700 | .cindex "&_Local/Makefile_&" | |
1701 | .cindex "&_src/EDITME_&" | |
168e428f PH |
1702 | Before building Exim, a local configuration file that specifies options |
1703 | independent of any operating system has to be created with the name | |
9b371988 PH |
1704 | &_Local/Makefile_&. A template for this file is supplied as the file |
1705 | &_src/EDITME_&, and it contains full descriptions of all the option settings | |
168e428f PH |
1706 | therein. These descriptions are therefore not repeated here. If you are |
1707 | building Exim for the first time, the simplest thing to do is to copy | |
9b371988 | 1708 | &_src/EDITME_& to &_Local/Makefile_&, then read it and edit it appropriately. |
168e428f PH |
1709 | |
1710 | There are three settings that you must supply, because Exim will not build | |
1711 | without them. They are the location of the run time configuration file | |
1712 | (CONFIGURE_FILE), the directory in which Exim binaries will be installed | |
1713 | (BIN_DIRECTORY), and the identity of the Exim user (EXIM_USER and | |
1714 | maybe EXIM_GROUP as well). The value of CONFIGURE_FILE can in fact be | |
1715 | a colon-separated list of file names; Exim uses the first of them that exists. | |
1716 | ||
1717 | There are a few other parameters that can be specified either at build time or | |
1718 | at run time, to enable the same binary to be used on a number of different | |
1719 | machines. However, if the locations of Exim's spool directory and log file | |
1720 | directory (if not within the spool directory) are fixed, it is recommended that | |
9b371988 | 1721 | you specify them in &_Local/Makefile_& instead of at run time, so that errors |
168e428f PH |
1722 | detected early in Exim's execution (such as a malformed configuration file) can |
1723 | be logged. | |
1724 | ||
9b371988 | 1725 | .cindex "content scanning" "specifying at build time" |
068aaea8 | 1726 | Exim's interfaces for calling virus and spam scanning software directly from |
168e428f PH |
1727 | access control lists are not compiled by default. If you want to include these |
1728 | facilities, you need to set | |
9b371988 PH |
1729 | .code |
1730 | WITH_CONTENT_SCAN=yes | |
1731 | .endd | |
1732 | in your &_Local/Makefile_&. For details of the facilities themselves, see | |
1733 | chapter &<<CHAPexiscan>>&. | |
168e428f PH |
1734 | |
1735 | ||
9b371988 PH |
1736 | .cindex "&_Local/eximon.conf_&" |
1737 | .cindex "_exim_monitor/EDITME_" | |
168e428f | 1738 | If you are going to build the Exim monitor, a similar configuration process is |
9b371988 PH |
1739 | required. The file &_exim_monitor/EDITME_& must be edited appropriately for |
1740 | your installation and saved under the name &_Local/eximon.conf_&. If you are | |
1741 | happy with the default settings described in &_exim_monitor/EDITME_&, | |
1742 | &_Local/eximon.conf_& can be empty, but it must exist. | |
168e428f PH |
1743 | |
1744 | This is all the configuration that is needed in straightforward cases for known | |
1745 | operating systems. However, the building process is set up so that it is easy | |
1746 | to override options that are set by default or by operating-system-specific | |
1747 | configuration files, for example to change the name of the C compiler, which | |
9b371988 PH |
1748 | defaults to &%gcc%&. See section &<<SECToverride>>& below for details of how to |
1749 | do this. | |
168e428f PH |
1750 | |
1751 | ||
1752 | ||
9b371988 PH |
1753 | .section "Support for iconv()" |
1754 | .cindex "&[iconv()]& support" | |
1755 | .cindex "RFC 2047" | |
168e428f PH |
1756 | The contents of header lines in messages may be encoded according to the rules |
1757 | described RFC 2047. This makes it possible to transmit characters that are not | |
1758 | in the ASCII character set, and to label them as being in a particular | |
9b371988 | 1759 | character set. When Exim is inspecting header lines by means of the &%$h_%& |
168e428f PH |
1760 | mechanism, it decodes them, and translates them into a specified character set |
1761 | (default ISO-8859-1). The translation is possible only if the operating system | |
9b371988 PH |
1762 | supports the &[iconv()]& function. |
1763 | ||
1764 | However, some of the operating systems that supply &[iconv()]& do not support | |
1765 | very many conversions. The GNU &%libiconv%& library (available from | |
1766 | &url(http://www.gnu.org/software/libiconv/)) can be installed on such | |
1767 | systems to remedy this deficiency, as well as on systems that do not supply | |
1768 | &[iconv()]& at all. After installing &%libiconv%&, you should add | |
1769 | .code | |
1770 | HAVE_ICONV=yes | |
1771 | .endd | |
1772 | to your &_Local/Makefile_& and rebuild Exim. | |
1773 | ||
1774 | ||
1775 | ||
1776 | .section "Including TLS/SSL encryption support" "SECTinctlsssl" | |
1777 | .cindex "TLS" "including support for TLS" | |
1778 | .cindex "encryption" "including support for" | |
1779 | .cindex "SUPPORT_TLS" | |
1780 | .cindex "OpenSSL" "building Exim with" | |
1781 | .cindex "GnuTLS" "building Exim with" | |
168e428f PH |
1782 | Exim can be built to support encrypted SMTP connections, using the STARTTLS |
1783 | command as per RFC 2487. It can also support legacy clients that expect to | |
1784 | start a TLS session immediately on connection to a non-standard port (see the | |
9b371988 | 1785 | &%tls_on_connect_ports%& runtime option and the &%-tls-on-connect%& command |
168e428f PH |
1786 | line option). |
1787 | ||
1788 | If you want to build Exim with TLS support, you must first install either the | |
1789 | OpenSSL or GnuTLS library. There is no cryptographic code in Exim itself for | |
1790 | implementing SSL. | |
1791 | ||
1792 | If OpenSSL is installed, you should set | |
9b371988 PH |
1793 | .code |
1794 | SUPPORT_TLS=yes | |
1795 | TLS_LIBS=-lssl -lcrypto | |
1796 | .endd | |
1797 | in &_Local/Makefile_&. You may also need to specify the locations of the | |
168e428f | 1798 | OpenSSL library and include files. For example: |
9b371988 PH |
1799 | .code |
1800 | SUPPORT_TLS=yes | |
1801 | TLS_LIBS=-L/usr/local/openssl/lib -lssl -lcrypto | |
1802 | TLS_INCLUDE=-I/usr/local/openssl/include/ | |
1803 | .endd | |
1804 | .cindex "USE_GNUTLS" | |
168e428f | 1805 | If GnuTLS is installed, you should set |
9b371988 PH |
1806 | .code |
1807 | SUPPORT_TLS=yes | |
1808 | USE_GNUTLS=yes | |
1809 | TLS_LIBS=-lgnutls -ltasn1 -lgcrypt | |
1810 | .endd | |
1811 | in &_Local/Makefile_&, and again you may need to specify the locations of the | |
168e428f | 1812 | library and include files. For example: |
9b371988 PH |
1813 | .code |
1814 | SUPPORT_TLS=yes | |
1815 | USE_GNUTLS=yes | |
1816 | TLS_LIBS=-L/usr/gnu/lib -lgnutls -ltasn1 -lgcrypt | |
1817 | TLS_INCLUDE=-I/usr/gnu/include | |
1818 | .endd | |
168e428f | 1819 | You do not need to set TLS_INCLUDE if the relevant directory is already |
9b371988 PH |
1820 | specified in INCLUDE. Details of how to configure Exim to make use of TLS are |
1821 | given in chapter &<<CHAPTLS>>&. | |
168e428f PH |
1822 | |
1823 | ||
1824 | ||
1825 | ||
9b371988 PH |
1826 | .section "Use of tcpwrappers" |
1827 | .cindex "tcpwrappers" "building Exim to support" | |
1828 | .cindex "USE_TCP_WRAPPERS" | |
1829 | Exim can be linked with the &'tcpwrappers'& library in order to check incoming | |
1830 | SMTP calls using the &'tcpwrappers'& control files. This may be a convenient | |
168e428f | 1831 | alternative to Exim's own checking facilities for installations that are |
9b371988 PH |
1832 | already making use of &'tcpwrappers'& for other purposes. To do this, you |
1833 | should set USE_TCP_WRAPPERS in &_Local/Makefile_&, arrange for the file | |
1834 | &_tcpd.h_& to be available at compile time, and also ensure that the library | |
1835 | &_libwrap.a_& is available at link time, typically by including &%-lwrap%& in | |
1836 | EXTRALIBS_EXIM. For example, if &'tcpwrappers'& is installed in &_/usr/local_&, | |
1837 | you might have | |
1838 | .code | |
1839 | USE_TCP_WRAPPERS=yes | |
1840 | CFLAGS=-O -I/usr/local/include | |
1841 | EXTRALIBS_EXIM=-L/usr/local/lib -lwrap | |
1842 | .endd | |
1843 | in &_Local/Makefile_&. The name to use in the &'tcpwrappers'& control files is | |
1844 | &"exim"&. For example, the line | |
1845 | .code | |
1846 | exim : LOCAL 192.168.1. .friendly.domain.example | |
1847 | .endd | |
1848 | in your &_/etc/hosts.allow_& file allows connections from the local host, from | |
1849 | the subnet 192.168.1.0/24, and from all hosts in &'friendly.domain.example'&. | |
1850 | All other connections are denied. Consult the &'tcpwrappers'& documentation for | |
168e428f PH |
1851 | further details. |
1852 | ||
1853 | ||
1854 | ||
9b371988 PH |
1855 | .section "Including support for IPv6" |
1856 | .cindex "IPv6" "including support for" | |
168e428f | 1857 | Exim contains code for use on systems that have IPv6 support. Setting |
9b371988 | 1858 | &`HAVE_IPV6=YES`& in &_Local/Makefile_& causes the IPv6 code to be included; |
168e428f PH |
1859 | it may also be necessary to set IPV6_INCLUDE and IPV6_LIBS on systems |
1860 | where the IPv6 support is not fully integrated into the normal include and | |
1861 | library files. | |
1862 | ||
1863 | Two different types of DNS record for handling IPv6 addresses have been | |
1864 | defined. AAAA records (analagous to A records for IPv4) are in use, and are | |
1865 | currently seen as the mainstream. Another record type called A6 was proposed | |
1866 | as better than AAAA because it had more flexibility. However, it was felt to be | |
9b371988 | 1867 | over-complex, and its status was reduced to &"experimental"&. It is not known |
168e428f | 1868 | if anyone is actually using A6 records. Exim has support for A6 records, but |
9b371988 | 1869 | this is included only if you set &`SUPPORT_A6=YES`& in &_Local/Makefile_&. The |
168e428f PH |
1870 | support has not been tested for some time. |
1871 | ||
1872 | ||
1873 | ||
9b371988 PH |
1874 | .section "The building process" |
1875 | .cindex "build directory" | |
1876 | Once &_Local/Makefile_& (and &_Local/eximon.conf_&, if required) have been | |
1877 | created, run &'make'& at the top level. It determines the architecture and | |
168e428f PH |
1878 | operating system types, and creates a build directory if one does not exist. |
1879 | For example, on a Sun system running Solaris 8, the directory | |
9b371988 PH |
1880 | &_build-SunOS5-5.8-sparc_& is created. |
1881 | .cindex "symbolic link" "to source files" | |
168e428f PH |
1882 | Symbolic links to relevant source files are installed in the build directory. |
1883 | ||
9b371988 | 1884 | &*Warning*&: The &%-j%& (parallel) flag must not be used with &'make'&; the |
168e428f PH |
1885 | building process fails if it is set. |
1886 | ||
9b371988 | 1887 | If this is the first time &'make'& has been run, it calls a script that builds |
168e428f | 1888 | a make file inside the build directory, using the configuration files from the |
9b371988 PH |
1889 | &_Local_& directory. The new make file is then passed to another instance of |
1890 | &'make'&. This does the real work, building a number of utility scripts, and | |
168e428f | 1891 | then compiling and linking the binaries for the Exim monitor (if configured), a |
9b371988 PH |
1892 | number of utility programs, and finally Exim itself. The command &`make |
1893 | makefile`& can be used to force a rebuild of the make file in the build | |
168e428f PH |
1894 | directory, should this ever be necessary. |
1895 | ||
1896 | If you have problems building Exim, check for any comments there may be in the | |
9b371988 | 1897 | &_README_& file concerning your operating system, and also take a look at the |
168e428f PH |
1898 | FAQ, where some common problems are covered. |
1899 | ||
1900 | ||
1901 | ||
9b371988 PH |
1902 | .section 'Output from &"make"&' |
1903 | .new | |
1904 | The output produced by the &'make'& process for compile lines is often very | |
068aaea8 PH |
1905 | unreadable, because these lines can be very long. For this reason, the normal |
1906 | output is suppressed by default, and instead output similar to that which | |
1907 | appears when compiling the 2.6 Linux kernel is generated: just a short line for | |
1908 | each module that is being compiled or linked. However, it is still possible to | |
9b371988 PH |
1909 | get the full output, by calling &'make'& like this: |
1910 | .code | |
1911 | FULLECHO='' make -e | |
1912 | .endd | |
1913 | The value of FULLECHO defaults to &"@"&, the flag character that suppresses | |
1914 | command reflection in &'make'&. When you ask for the full output, it is | |
068aaea8 | 1915 | given in addition to the the short output. |
9b371988 | 1916 | .wen |
068aaea8 PH |
1917 | |
1918 | ||
1919 | ||
9b371988 PH |
1920 | .section "Overriding build-time options for Exim" "SECToverride" |
1921 | .cindex "build-time options" "overriding" | |
168e428f PH |
1922 | The main make file that is created at the beginning of the building process |
1923 | consists of the concatenation of a number of files which set configuration | |
9b371988 | 1924 | values, followed by a fixed set of &'make'& instructions. If a value is set |
168e428f PH |
1925 | more than once, the last setting overrides any previous ones. This provides a |
1926 | convenient way of overriding defaults. The files that are concatenated are, in | |
1927 | order: | |
9b371988 PH |
1928 | .display |
1929 | &_OS/Makefile-Default_& | |
1930 | &_OS/Makefile-_&<&'ostype'&> | |
1931 | &_Local/Makefile_& | |
1932 | &_Local/Makefile-_&<&'ostype'&> | |
1933 | &_Local/Makefile-_&<&'archtype'&> | |
1934 | &_Local/Makefile-_&<&'ostype'&>-<&'archtype'&> | |
1935 | &_OS/Makefile-Base_& | |
1936 | .endd | |
1937 | .cindex "&_Local/Makefile_&" | |
1938 | .cindex "building Exim" "operating system type" | |
1939 | .cindex "building Exim" "architecture type" | |
1940 | where <&'ostype'&> is the operating system type and <&'archtype'&> is the | |
1941 | architecture type. &_Local/Makefile_& is required to exist, and the building | |
1942 | process fails if it is absent. The other three &_Local_& files are optional, | |
168e428f PH |
1943 | and are often not needed. |
1944 | ||
9b371988 PH |
1945 | The values used for <&'ostype'&> and <&'archtype'&> are obtained from scripts |
1946 | called &_scripts/os-type_& and &_scripts/arch-type_& respectively. If either of | |
168e428f PH |
1947 | the environment variables EXIM_OSTYPE or EXIM_ARCHTYPE is set, their |
1948 | values are used, thereby providing a means of forcing particular settings. | |
9b371988 | 1949 | Otherwise, the scripts try to get values from the &%uname%& command. If this |
168e428f | 1950 | fails, the shell variables OSTYPE and ARCHTYPE are inspected. A number |
9b371988 | 1951 | of &'ad hoc'& transformations are then applied, to produce the standard names |
168e428f PH |
1952 | that Exim expects. You can run these scripts directly from the shell in order |
1953 | to find out what values are being used on your system. | |
1954 | ||
1955 | ||
9b371988 | 1956 | &_OS/Makefile-Default_& contains comments about the variables that are set |
168e428f PH |
1957 | therein. Some (but not all) are mentioned below. If there is something that |
1958 | needs changing, review the contents of this file and the contents of the make | |
9b371988 | 1959 | file for your operating system (&_OS/Makefile-<ostype>_&) to see what the |
168e428f PH |
1960 | default values are. |
1961 | ||
1962 | ||
9b371988 PH |
1963 | .cindex "building Exim" "overriding default settings" |
1964 | If you need to change any of the values that are set in &_OS/Makefile-Default_& | |
1965 | or in &_OS/Makefile-<ostype>_&, or to add any new definitions, you do not | |
168e428f | 1966 | need to change the original files. Instead, you should make the changes by |
9b371988 PH |
1967 | putting the new values in an appropriate &_Local_& file. For example, |
1968 | .cindex "Tru64-Unix build-time settings" | |
168e428f PH |
1969 | when building Exim in many releases of the Tru64-Unix (formerly Digital UNIX, |
1970 | formerly DEC-OSF1) operating system, it is necessary to specify that the C | |
9b371988 PH |
1971 | compiler is called &'cc'& rather than &'gcc'&. Also, the compiler must be |
1972 | called with the option &%-std1%&, to make it recognize some of the features of | |
168e428f | 1973 | Standard C that Exim uses. (Most other compilers recognize Standard C by |
9b371988 | 1974 | default.) To do this, you should create a file called &_Local/Makefile-OSF1_& |
168e428f | 1975 | containing the lines |
9b371988 PH |
1976 | .code |
1977 | CC=cc | |
1978 | CFLAGS=-std1 | |
1979 | .endd | |
168e428f | 1980 | If you are compiling for just one operating system, it may be easier to put |
9b371988 | 1981 | these lines directly into &_Local/Makefile_&. |
168e428f PH |
1982 | |
1983 | Keeping all your local configuration settings separate from the distributed | |
1984 | files makes it easy to transfer them to new versions of Exim simply by copying | |
9b371988 | 1985 | the contents of the &_Local_& directory. |
168e428f PH |
1986 | |
1987 | ||
9b371988 PH |
1988 | .cindex "NIS lookup type" "including support for" |
1989 | .cindex "NIS+ lookup type" "including support for" | |
1990 | .cindex "LDAP" "including support for" | |
1991 | .cindex "lookup" "inclusion in binary" | |
168e428f PH |
1992 | Exim contains support for doing LDAP, NIS, NIS+, and other kinds of file |
1993 | lookup, but not all systems have these components installed, so the default is | |
1994 | not to include the relevant code in the binary. All the different kinds of file | |
1995 | and database lookup that Exim supports are implemented as separate code modules | |
1996 | which are included only if the relevant compile-time options are set. In the | |
9b371988 PH |
1997 | case of LDAP, NIS, and NIS+, the settings for &_Local/Makefile_& are: |
1998 | .code | |
1999 | LOOKUP_LDAP=yes | |
2000 | LOOKUP_NIS=yes | |
2001 | LOOKUP_NISPLUS=yes | |
2002 | .endd | |
168e428f | 2003 | and similar settings apply to the other lookup types. They are all listed in |
9b371988 | 2004 | &_src/EDITME_&. In many cases the relevant include files and interface |
168e428f | 2005 | libraries need to be installed before compiling Exim. |
9b371988 | 2006 | .cindex "cdb" "including support for" |
068aaea8 PH |
2007 | However, there are some optional lookup types (such as cdb) for which |
2008 | the code is entirely contained within Exim, and no external include | |
168e428f PH |
2009 | files or libraries are required. When a lookup type is not included in the |
2010 | binary, attempts to configure Exim to use it cause run time configuration | |
2011 | errors. | |
2012 | ||
9b371988 | 2013 | .cindex "Perl" "including support for" |
168e428f PH |
2014 | Exim can be linked with an embedded Perl interpreter, allowing Perl |
2015 | subroutines to be called during string expansion. To enable this facility, | |
9b371988 PH |
2016 | .code |
2017 | EXIM_PERL=perl.o | |
2018 | .endd | |
2019 | must be defined in &_Local/Makefile_&. Details of this facility are given in | |
2020 | chapter &<<CHAPperl>>&. | |
168e428f | 2021 | |
9b371988 | 2022 | .cindex "X11 libraries" "location of" |
168e428f | 2023 | The location of the X11 libraries is something that varies a lot between |
068aaea8 | 2024 | operating systems, and there may be different versions of X11 to cope |
168e428f PH |
2025 | with. Exim itself makes no use of X11, but if you are compiling the Exim |
2026 | monitor, the X11 libraries must be available. | |
9b371988 PH |
2027 | The following three variables are set in &_OS/Makefile-Default_&: |
2028 | .code | |
2029 | X11=/usr/X11R6 | |
2030 | XINCLUDE=-I$(X11)/include | |
2031 | XLFLAGS=-L$(X11)/lib | |
2032 | .endd | |
168e428f | 2033 | These are overridden in some of the operating-system configuration files. For |
9b371988 PH |
2034 | example, in &_OS/Makefile-SunOS5_& there is |
2035 | .code | |
2036 | X11=/usr/openwin | |
2037 | XINCLUDE=-I$(X11)/include | |
2038 | XLFLAGS=-L$(X11)/lib -R$(X11)/lib | |
2039 | .endd | |
168e428f PH |
2040 | If you need to override the default setting for your operating system, place a |
2041 | definition of all three of these variables into your | |
9b371988 | 2042 | &_Local/Makefile-<ostype>_& file. |
168e428f | 2043 | |
9b371988 | 2044 | .cindex "EXTRALIBS" |
168e428f PH |
2045 | If you need to add any extra libraries to the link steps, these can be put in a |
2046 | variable called EXTRALIBS, which appears in all the link commands, but by | |
2047 | default is not defined. In contrast, EXTRALIBS_EXIM is used only on the | |
2048 | command for linking the main Exim binary, and not for any associated utilities. | |
2049 | ||
9b371988 | 2050 | .cindex "DBM libraries" "configuration for building" |
168e428f | 2051 | There is also DBMLIB, which appears in the link commands for binaries that |
9b371988 | 2052 | use DBM functions (see also section &<<SECTdb>>&). Finally, there is |
168e428f PH |
2053 | EXTRALIBS_EXIMON, which appears only in the link step for the Exim monitor |
2054 | binary, and which can be used, for example, to include additional X11 | |
2055 | libraries. | |
2056 | ||
9b371988 | 2057 | .cindex "configuration file" "editing" |
168e428f PH |
2058 | The make file copes with rebuilding Exim correctly if any of the configuration |
2059 | files are edited. However, if an optional configuration file is deleted, it is | |
9b371988 PH |
2060 | necessary to touch the associated non-optional file (that is, |
2061 | &_Local/Makefile_& or &_Local/eximon.conf_&) before rebuilding. | |
168e428f PH |
2062 | |
2063 | ||
9b371988 PH |
2064 | .section "OS-specific header files" |
2065 | .cindex "&_os.h_&" | |
2066 | .cindex "building Exim" "OS-specific C header files" | |
2067 | The &_OS_& directory contains a number of files with names of the form | |
2068 | &_os.h-<ostype>_&. These are system-specific C header files that should not | |
168e428f | 2069 | normally need to be changed. There is a list of macro settings that are |
9b371988 | 2070 | recognized in the file &_OS/os.configuring_&, which should be consulted if you |
168e428f PH |
2071 | are porting Exim to a new operating system. |
2072 | ||
2073 | ||
2074 | ||
9b371988 PH |
2075 | .section "Overriding build-time options for the monitor" |
2076 | .cindex "building Eximon" "overriding default options" | |
168e428f PH |
2077 | A similar process is used for overriding things when building the Exim monitor, |
2078 | where the files that are involved are | |
9b371988 PH |
2079 | .display |
2080 | &_OS/eximon.conf-Default_& | |
2081 | &_OS/eximon.conf-_&<&'ostype'&> | |
2082 | &_Local/eximon.conf_& | |
2083 | &_Local/eximon.conf-_&<&'ostype'&> | |
2084 | &_Local/eximon.conf-_&<&'archtype'&> | |
2085 | &_Local/eximon.conf-_&<&'ostype'&>-<&'archtype'&> | |
2086 | .endd | |
2087 | .cindex "&_Local/eximon.conf_&" | |
168e428f | 2088 | As with Exim itself, the final three files need not exist, and in this case the |
9b371988 PH |
2089 | &_OS/eximon.conf-<ostype>_& file is also optional. The default values in |
2090 | &_OS/eximon.conf-Default_& can be overridden dynamically by setting environment | |
168e428f PH |
2091 | variables of the same name, preceded by EXIMON_. For example, setting |
2092 | EXIMON_LOG_DEPTH in the environment overrides the value of | |
2093 | LOG_DEPTH at run time. | |
2094 | ||
2095 | ||
2096 | ||
2097 | ||
9b371988 PH |
2098 | .section "Installing Exim binaries and scripts" |
2099 | .cindex "installing Exim" | |
2100 | .cindex "BIN_DIRECTORY" | |
2101 | The command &`make install`& runs the &(exim_install)& script with no | |
2102 | arguments. The script copies binaries and utility scripts into the directory | |
2103 | whose name is specified by the BIN_DIRECTORY setting in &_Local/Makefile_&. | |
2104 | .cindex "setuid" "installing Exim with" | |
068aaea8 PH |
2105 | The install script copies files only if they are newer than the files they are |
2106 | going to replace. The Exim binary is required to be owned by root and have the | |
9b371988 PH |
2107 | &'setuid'& bit set, for normal configurations. Therefore, you must run &`make |
2108 | install`& as root so that it can set up the Exim binary in this way. However, in | |
068aaea8 PH |
2109 | some special situations (for example, if a host is doing no local deliveries) |
2110 | it may be possible to run Exim without making the binary setuid root (see | |
9b371988 | 2111 | chapter &<<CHAPsecurity>>& for details). |
168e428f | 2112 | |
9b371988 | 2113 | .cindex "CONFIGURE_FILE" |
168e428f | 2114 | Exim's run time configuration file is named by the CONFIGURE_FILE setting |
9b371988 PH |
2115 | in &_Local/Makefile_&. If this names a single file, and the file does not |
2116 | exist, the default configuration file &_src/configure.default_& is copied there | |
168e428f PH |
2117 | by the installation script. If a run time configuration file already exists, it |
2118 | is left alone. If CONFIGURE_FILE is a colon-separated list, naming several | |
2119 | alternative files, no default is installed. | |
2120 | ||
9b371988 PH |
2121 | .cindex "system aliases file" |
2122 | .cindex "&_/etc/aliases_&" | |
168e428f PH |
2123 | One change is made to the default configuration file when it is installed: the |
2124 | default configuration contains a router that references a system aliases file. | |
2125 | The path to this file is set to the value specified by | |
9b371988 | 2126 | SYSTEM_ALIASES_FILE in &_Local/Makefile_& (&_/etc/aliases_& by default). |
168e428f PH |
2127 | If the system aliases file does not exist, the installation script creates it, |
2128 | and outputs a comment to the user. | |
2129 | ||
2130 | The created file contains no aliases, but it does contain comments about the | |
2131 | aliases a site should normally have. Mail aliases have traditionally been | |
9b371988 PH |
2132 | kept in &_/etc/aliases_&. However, some operating systems are now using |
2133 | &_/etc/mail/aliases_&. You should check if yours is one of these, and change | |
168e428f PH |
2134 | Exim's configuration if necessary. |
2135 | ||
2136 | The default configuration uses the local host's name as the only local domain, | |
9b371988 PH |
2137 | and is set up to do local deliveries into the shared directory &_/var/mail_&, |
2138 | running as the local user. System aliases and &_.forward_& files in users' home | |
168e428f PH |
2139 | directories are supported, but no NIS or NIS+ support is configured. Domains |
2140 | other than the name of the local host are routed using the DNS, with delivery | |
2141 | over SMTP. | |
2142 | ||
168e428f PH |
2143 | It is possible to install Exim for special purposes (such as building a binary |
2144 | distribution) in a private part of the file system. You can do this by a | |
2145 | command such as | |
9b371988 PH |
2146 | .code |
2147 | make DESTDIR=/some/directory/ install | |
2148 | .endd | |
168e428f PH |
2149 | This has the effect of pre-pending the specified directory to all the file |
2150 | paths, except the name of the system aliases file that appears in the default | |
9b371988 | 2151 | configuration. (If a default alias file is created, its name &'is'& modified.) |
168e428f PH |
2152 | For backwards compatibility, ROOT is used if DESTDIR is not set, |
2153 | but this usage is deprecated. | |
2154 | ||
9b371988 PH |
2155 | .cindex "installing Exim" "what is not installed" |
2156 | Running &'make install'& does not copy the Exim 4 conversion script | |
2157 | &'convert4r4'&, or the &'pcretest'& test program. You will probably run the | |
168e428f | 2158 | first of these only once (if you are upgrading from Exim 3), and the second |
9b371988 | 2159 | isn't really part of Exim. None of the documentation files in the &_doc_& |
168e428f | 2160 | directory are copied, except for the info files when you have set |
9b371988 | 2161 | INFO_DIRECTORY, as described in section &<<SECTinsinfdoc>>& below. |
168e428f | 2162 | |
9b371988 | 2163 | For the utility programs, old versions are renamed by adding the suffix &_.O_& |
168e428f PH |
2164 | to their names. The Exim binary itself, however, is handled differently. It is |
2165 | installed under a name that includes the version number and the compile number, | |
9b371988 PH |
2166 | for example &_exim-&version;-1_&. The script then arranges for a symbolic link |
2167 | called &_exim_& to point to the binary. If you are updating a previous version | |
2168 | of Exim, the script takes care to ensure that the name &_exim_& is never absent | |
168e428f PH |
2169 | from the directory (as seen by other processes). |
2170 | ||
9b371988 PH |
2171 | .cindex "installing Exim" "testing the script" |
2172 | If you want to see what the &'make install'& will do before running it for | |
2173 | real, you can pass the &%-n%& option to the installation script by this | |
2174 | command: | |
2175 | .code | |
2176 | make INSTALL_ARG=-n install | |
2177 | .endd | |
168e428f PH |
2178 | The contents of the variable INSTALL_ARG are passed to the installation |
2179 | script. You do not need to be root to run this test. Alternatively, you can run | |
2180 | the installation script directly, but this must be from within the build | |
2181 | directory. For example, from the top-level Exim directory you could use this | |
2182 | command: | |
9b371988 PH |
2183 | .code |
2184 | (cd build-SunOS5-5.5.1-sparc; ../scripts/exim_install -n) | |
2185 | .endd | |
2186 | .cindex "installing Exim" "install script options" | |
168e428f PH |
2187 | There are two other options that can be supplied to the installation script. |
2188 | ||
9b371988 PH |
2189 | .ilist |
2190 | &%-no_chown%& bypasses the call to change the owner of the installed binary | |
168e428f | 2191 | to root, and the call to make it a setuid binary. |
9b371988 PH |
2192 | .next |
2193 | &%-no_symlink%& bypasses the setting up of the symbolic link &_exim_& to the | |
168e428f | 2194 | installed binary. |
9b371988 | 2195 | .endlist |
168e428f PH |
2196 | |
2197 | INSTALL_ARG can be used to pass these options to the script. For example: | |
9b371988 PH |
2198 | .code |
2199 | make INSTALL_ARG=-no_symlink install | |
2200 | .endd | |
168e428f PH |
2201 | The installation script can also be given arguments specifying which files are |
2202 | to be copied. For example, to install just the Exim binary, and nothing else, | |
2203 | without creating the symbolic link, you could use: | |
9b371988 PH |
2204 | .code |
2205 | make INSTALL_ARG='-no_symlink exim' install | |
2206 | .endd | |
168e428f PH |
2207 | |
2208 | ||
2209 | ||
9b371988 PH |
2210 | .section "Installing info documentation" "SECTinsinfdoc" |
2211 | .cindex "installing Exim" "&'info'& documentation" | |
2212 | Not all systems use the GNU &'info'& system for documentation, and for this | |
168e428f PH |
2213 | reason, the Texinfo source of Exim's documentation is not included in the main |
2214 | distribution. Instead it is available separately from the ftp site (see section | |
9b371988 | 2215 | &<<SECTavail>>&). |
168e428f | 2216 | |
9b371988 PH |
2217 | If you have defined INFO_DIRECTORY in &_Local/Makefile_& and the Texinfo |
2218 | source of the documentation is found in the source tree, running &`make | |
2219 | install`& automatically builds the info files and installs them. | |
168e428f PH |
2220 | |
2221 | ||
2222 | ||
9b371988 PH |
2223 | .section "Setting up the spool directory" |
2224 | .cindex "spool directory" "creating" | |
168e428f PH |
2225 | When it starts up, Exim tries to create its spool directory if it does not |
2226 | exist. The Exim uid and gid are used for the owner and group of the spool | |
2227 | directory. Sub-directories are automatically created in the spool directory as | |
2228 | necessary. | |
2229 | ||
2230 | ||
2231 | ||
2232 | ||
9b371988 PH |
2233 | .section "Testing" |
2234 | .cindex "testing" "installation" | |
168e428f PH |
2235 | Having installed Exim, you can check that the run time configuration file is |
2236 | syntactically valid by running the following command, which assumes that the | |
2237 | Exim binary directory is within your PATH environment variable: | |
9b371988 PH |
2238 | .code |
2239 | exim -bV | |
2240 | .endd | |
168e428f PH |
2241 | If there are any errors in the configuration file, Exim outputs error messages. |
2242 | Otherwise it outputs the version number and build date, | |
2243 | the DBM library that is being used, and information about which drivers and | |
2244 | other optional code modules are included in the binary. | |
2245 | Some simple routing tests can be done by using the address testing option. For | |
2246 | example, | |
9b371988 PH |
2247 | .display |
2248 | &`exim -bt`& <&'local username'&> | |
2249 | .endd | |
168e428f | 2250 | should verify that it recognizes a local mailbox, and |
9b371988 PH |
2251 | .display |
2252 | &`exim -bt`& <&'remote address'&> | |
2253 | .endd | |
168e428f PH |
2254 | a remote one. Then try getting it to deliver mail, both locally and remotely. |
2255 | This can be done by passing messages directly to Exim, without going through a | |
2256 | user agent. For example: | |
9b371988 | 2257 | .code |
068aaea8 PH |
2258 | exim -v postmaster@your.domain.example |
2259 | From: user@your.domain.example | |
2260 | To: postmaster@your.domain.example | |
2261 | Subject: Testing Exim | |
168e428f | 2262 | |
068aaea8 PH |
2263 | This is a test message. |
2264 | ^D | |
9b371988 PH |
2265 | .endd |
2266 | The &%-v%& option causes Exim to output some verification of what it is doing. | |
168e428f | 2267 | In this case you should see copies of three log lines, one for the message's |
9b371988 | 2268 | arrival, one for its delivery, and one containing &"Completed"&. |
168e428f | 2269 | |
9b371988 PH |
2270 | .cindex "delivery" "problems with" |
2271 | If you encounter problems, look at Exim's log files (&'mainlog'& and | |
2272 | &'paniclog'&) to see if there is any relevant information there. Another source | |
168e428f | 2273 | of information is running Exim with debugging turned on, by specifying the |
9b371988 | 2274 | &%-d%& option. If a message is stuck on Exim's spool, you can force a delivery |
168e428f | 2275 | with debugging turned on by a command of the form |
9b371988 PH |
2276 | .display |
2277 | &`exim -d -M`& <&'exim-message-id'&> | |
2278 | .endd | |
2279 | You must be root or an &"admin user"& in order to do this. The &%-d%& option | |
168e428f | 2280 | produces rather a lot of output, but you can cut this down to specific areas. |
9b371988 PH |
2281 | For example, if you use &%-d-all+route%& only the debugging information |
2282 | relevant to routing is included. (See the &%-d%& option in chapter | |
2283 | &<<CHAPcommandline>>& for more details.) | |
168e428f | 2284 | |
9b371988 PH |
2285 | .cindex '&"sticky"& bit' |
2286 | .cindex "lock files" | |
168e428f PH |
2287 | One specific problem that has shown up on some sites is the inability to do |
2288 | local deliveries into a shared mailbox directory, because it does not have the | |
9b371988 | 2289 | &"sticky bit"& set on it. By default, Exim tries to create a lock file before |
168e428f | 2290 | writing to a mailbox file, and if it cannot create the lock file, the delivery |
9b371988 | 2291 | is deferred. You can get round this either by setting the &"sticky bit"& on the |
168e428f PH |
2292 | directory, or by setting a specific group for local deliveries and allowing |
2293 | that group to create files in the directory (see the comments above the | |
9b371988 | 2294 | &(local_delivery)& transport in the default configuration file). Another |
168e428f | 2295 | approach is to configure Exim not to use lock files, but just to rely on |
9b371988 PH |
2296 | &[fcntl()]& locking instead. However, you should do this only if all user |
2297 | agents also use &[fcntl()]& locking. For further discussion of locking issues, | |
2298 | see chapter &<<CHAPappendfile>>&. | |
168e428f PH |
2299 | |
2300 | One thing that cannot be tested on a system that is already running an MTA is | |
2301 | the receipt of incoming SMTP mail on the standard SMTP port. However, the | |
9b371988 PH |
2302 | &%-oX%& option can be used to run an Exim daemon that listens on some other |
2303 | port, or &'inetd'& can be used to do this. The &%-bh%& option and the | |
2304 | &'exim_checkaccess'& utility can be used to check out policy controls on | |
168e428f PH |
2305 | incoming SMTP mail. |
2306 | ||
2307 | Testing a new version on a system that is already running Exim can most easily | |
2308 | be done by building a binary with a different CONFIGURE_FILE setting. From | |
2309 | within the run time configuration, all other file and directory names | |
2310 | that Exim uses can be altered, in order to keep it entirely clear of the | |
2311 | production version. | |
2312 | ||
2313 | ||
9b371988 PH |
2314 | .section "Replacing another MTA with Exim" |
2315 | .cindex "replacing another MTA" | |
168e428f PH |
2316 | Building and installing Exim for the first time does not of itself put it in |
2317 | general use. The name by which the system's MTA is called by mail user agents | |
9b371988 PH |
2318 | is either &_/usr/sbin/sendmail_&, or &_/usr/lib/sendmail_& (depending on the |
2319 | operating system), and it is necessary to make this name point to the &'exim'& | |
168e428f | 2320 | binary in order to get the user agents to pass messages to Exim. This is |
9b371988 PH |
2321 | normally done by renaming any existing file and making &_/usr/sbin/sendmail_& |
2322 | or &_/usr/lib/sendmail_& | |
2323 | .cindex "symbolic link" "to &'exim'& binary" | |
2324 | a symbolic link to the &'exim'& binary. It is a good idea to remove any setuid | |
168e428f PH |
2325 | privilege and executable status from the old MTA. It is then necessary to stop |
2326 | and restart the mailer daemon, if one is running. | |
2327 | ||
9b371988 PH |
2328 | .cindex "FreeBSD" "MTA indirection" |
2329 | .cindex "&_/etc/mail/mailer.conf_&" | |
168e428f PH |
2330 | Some operating systems have introduced alternative ways of switching MTAs. For |
2331 | example, if you are running FreeBSD, you need to edit the file | |
9b371988 | 2332 | &_/etc/mail/mailer.conf_& instead of setting up a symbolic link as just |
168e428f PH |
2333 | described. A typical example of the contents of this file for running Exim is |
2334 | as follows: | |
9b371988 PH |
2335 | .code |
2336 | sendmail /usr/exim/bin/exim | |
2337 | send-mail /usr/exim/bin/exim | |
2338 | mailq /usr/exim/bin/exim -bp | |
2339 | newaliases /usr/bin/true | |
2340 | .endd | |
2341 | Once you have set up the symbolic link, or edited &_/etc/mail/mailer.conf_&, | |
2342 | your Exim installation is &"live"&. Check it by sending a message from your | |
168e428f PH |
2343 | favourite user agent. |
2344 | ||
2345 | You should consider what to tell your users about the change of MTA. Exim may | |
2346 | have different capabilities to what was previously running, and there are | |
2347 | various operational differences such as the text of messages produced by | |
2348 | command line options and in bounce messages. If you allow your users to make | |
2349 | use of Exim's filtering capabilities, you should make the document entitled | |
9b371988 | 2350 | &'Exim's interface to mail filtering'& available to them. |
168e428f PH |
2351 | |
2352 | ||
2353 | ||
9b371988 PH |
2354 | .section "Upgrading Exim" |
2355 | .cindex "upgrading Exim" | |
168e428f PH |
2356 | If you are already running Exim on your host, building and installing a new |
2357 | version automatically makes it available to MUAs, or any other programs that | |
2358 | call the MTA directly. However, if you are running an Exim daemon, you do need | |
9b371988 PH |
2359 | to send it a HUP signal, to make it re-execute itself, and thereby pick up the |
2360 | new binary. You do not need to stop processing mail in order to install a new | |
068aaea8 PH |
2361 | version of Exim. The install script does not modify an existing runtime |
2362 | configuration file. | |
2363 | ||
168e428f PH |
2364 | |
2365 | ||
2366 | ||
9b371988 PH |
2367 | .section "Stopping the Exim daemon on Solaris" |
2368 | .cindex "Solaris" "stopping Exim on" | |
168e428f | 2369 | The standard command for stopping the mailer daemon on Solaris is |
9b371988 PH |
2370 | .code |
2371 | /etc/init.d/sendmail stop | |
2372 | .endd | |
2373 | If &_/usr/lib/sendmail_& has been turned into a symbolic link, this script | |
2374 | fails to stop Exim because it uses the command &'ps -e'& and greps the output | |
2375 | for the text &"sendmail"&; this is not present because the actual program name | |
2376 | (that is, &"exim"&) is given by the &'ps'& command with these options. A | |
2377 | solution is to replace the line that finds the process id with something like | |
2378 | .code | |
2379 | pid=`cat /var/spool/exim/exim-daemon.pid` | |
2380 | .endd | |
168e428f PH |
2381 | to obtain the daemon's pid directly from the file that Exim saves it in. |
2382 | ||
9b371988 | 2383 | Note, however, that stopping the daemon does not &"stop Exim"&. Messages can |
168e428f PH |
2384 | still be received from local processes, and if automatic delivery is configured |
2385 | (the normal case), deliveries will still occur. | |
2386 | ||
2387 | ||
2388 | ||
2389 | ||
9b371988 PH |
2390 | . //////////////////////////////////////////////////////////////////////////// |
2391 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 2392 | |
9b371988 PH |
2393 | .chapter "The Exim command line" "CHAPcommandline" |
2394 | .cindex "command line" "options" | |
2395 | .cindex "options" "command line" | |
168e428f PH |
2396 | Exim's command line takes the standard Unix form of a sequence of options, |
2397 | each starting with a hyphen character, followed by a number of arguments. The | |
2398 | options are compatible with the main options of Sendmail, and there are also | |
2399 | some additional options, some of which are compatible with Smail 3. Certain | |
2400 | combinations of options do not make sense, and provoke an error if used. | |
2401 | The form of the arguments depends on which options are set. | |
2402 | ||
2403 | ||
9b371988 PH |
2404 | .section "Setting options by program name" |
2405 | .cindex "&'mailq'&" | |
2406 | If Exim is called under the name &'mailq'&, it behaves as if the option &%-bp%& | |
168e428f | 2407 | were present before any other options. |
9b371988 | 2408 | The &%-bp%& option requests a listing of the contents of the mail queue on the |
168e428f PH |
2409 | standard output. |
2410 | This feature is for compatibility with some systems that contain a command of | |
2411 | that name in one of the standard libraries, symbolically linked to | |
9b371988 PH |
2412 | &_/usr/sbin/sendmail_& or &_/usr/lib/sendmail_&. |
2413 | ||
2414 | .cindex "&'rsmtp'&" | |
2415 | If Exim is called under the name &'rsmtp'& it behaves as if the option &%-bS%& | |
2416 | were present before any other options, for compatibility with Smail. The | |
2417 | &%-bS%& option is used for reading in a number of messages in batched SMTP | |
2418 | format. | |
2419 | ||
2420 | .cindex "&'rmail'&" | |
2421 | If Exim is called under the name &'rmail'& it behaves as if the &%-i%& and | |
2422 | &%-oee%& options were present before any other options, for compatibility with | |
2423 | Smail. The name &'rmail'& is used as an interface by some UUCP systems. | |
2424 | ||
2425 | .cindex "&'runq'&" | |
2426 | .cindex "queue runner" | |
2427 | If Exim is called under the name &'runq'& it behaves as if the option &%-q%& | |
2428 | were present before any other options, for compatibility with Smail. The &%-q%& | |
168e428f PH |
2429 | option causes a single queue runner process to be started. |
2430 | ||
9b371988 PH |
2431 | .cindex "&'newaliases'&" |
2432 | .cindex "alias file" "building" | |
2433 | .cindex "Sendmail compatibility" "calling Exim as &'newaliases'&" | |
2434 | If Exim is called under the name &'newaliases'& it behaves as if the option | |
2435 | &%-bi%& were present before any other options, for compatibility with Sendmail. | |
168e428f PH |
2436 | This option is used for rebuilding Sendmail's alias file. Exim does not have |
2437 | the concept of a single alias file, but can be configured to run a given | |
9b371988 | 2438 | command if called with the &%-bi%& option. |
168e428f PH |
2439 | |
2440 | ||
9b371988 PH |
2441 | .section "Trusted and admin users" "SECTtrustedadmin" |
2442 | Some Exim options are available only to &'trusted users'& and others are | |
2443 | available only to &'admin users'&. In the description below, the phrases &"Exim | |
2444 | user"& and &"Exim group"& mean the user and group defined by EXIM_USER and | |
2445 | EXIM_GROUP in &_Local/Makefile_& or set by the &%exim_user%& and | |
2446 | &%exim_group%& options. These do not necessarily have to use the name &"exim"&. | |
168e428f | 2447 | |
9b371988 PH |
2448 | .ilist |
2449 | .cindex "trusted user" "definition of" | |
2450 | .cindex "user" "trusted definition of" | |
168e428f | 2451 | The trusted users are root, the Exim user, any user listed in the |
9b371988 PH |
2452 | &%trusted_users%& configuration option, and any user whose current group or any |
2453 | supplementary group is one of those listed in the &%trusted_groups%& | |
168e428f | 2454 | configuration option. Note that the Exim group is not automatically trusted. |
9b371988 PH |
2455 | |
2456 | .cindex '&"From"& line' | |
2457 | .cindex "envelope sender" | |
2458 | Trusted users are always permitted to use the &%-f%& option or a leading | |
2459 | &"From&~"& line to specify the envelope sender of a message that is passed to | |
2460 | Exim through the local interface (see the &%-bm%& and &%-f%& options below). | |
2461 | See the &%untrusted_set_sender%& option for a way of permitting non-trusted | |
2462 | users to set envelope senders. | |
2463 | ||
2464 | .cindex "&'From:'& header line" | |
2465 | .cindex "&'Sender:'& header line" | |
2466 | For a trusted user, there is never any check on the contents of the &'From:'& | |
2467 | header line, and a &'Sender:'& line is never added. Furthermore, any existing | |
2468 | &'Sender:'& line in incoming local (non-TCP/IP) messages is not removed. | |
2469 | ||
168e428f PH |
2470 | Trusted users may also specify a host name, host address, interface address, |
2471 | protocol name, ident value, and authentication data when submitting a message | |
2472 | locally. Thus, they are able to insert messages into Exim's queue locally that | |
2473 | have the characteristics of messages received from a remote host. Untrusted | |
9b371988 | 2474 | users may in some circumstances use &%-f%&, but can never set the other values |
168e428f | 2475 | that are available to trusted users. |
9b371988 PH |
2476 | .next |
2477 | .cindex "user" "admin definition of" | |
2478 | .cindex "admin user" "definition of" | |
168e428f | 2479 | The admin users are root, the Exim user, and any user that is a member of the |
9b371988 | 2480 | Exim group or of any group listed in the &%admin_groups%& configuration option. |
168e428f | 2481 | The current group does not have to be one of these groups. |
9b371988 | 2482 | |
168e428f PH |
2483 | Admin users are permitted to list the queue, and to carry out certain |
2484 | operations on messages, for example, to force delivery failures. It is also | |
2485 | necessary to be an admin user in order to see the full information provided by | |
2486 | the Exim monitor, and full debugging output. | |
9b371988 PH |
2487 | |
2488 | By default, the use of the &%-M%&, &%-q%&, &%-R%&, and &%-S%& options to cause | |
2489 | Exim to attempt delivery of messages on its queue is restricted to admin users. | |
2490 | However, this restriction can be relaxed by setting the &%prod_requires_admin%& | |
2491 | option false (that is, specifying &%no_prod_requires_admin%&). | |
2492 | ||
2493 | Similarly, the use of the &%-bp%& option to list all the messages in the queue | |
2494 | is restricted to admin users unless &%queue_list_requires_admin%& is set | |
168e428f | 2495 | false. |
9b371988 | 2496 | .endlist |
168e428f PH |
2497 | |
2498 | ||
9b371988 | 2499 | &*Warning*&: If you configure your system so that admin users are able to |
168e428f PH |
2500 | edit Exim's configuration file, you are giving those users an easy way of |
2501 | getting root. There is further discussion of this issue at the start of chapter | |
9b371988 | 2502 | &<<CHAPconf>>&. |
168e428f PH |
2503 | |
2504 | ||
2505 | ||
2506 | ||
9b371988 | 2507 | .section "Command line options" |
168e428f PH |
2508 | The command options are described in alphabetical order below. |
2509 | ||
9b371988 PH |
2510 | . //////////////////////////////////////////////////////////////////////////// |
2511 | . Insert a stylized XML comment here, to identify the start of the command line | |
2512 | . options. This is for the benefit of the Perl script that automatically | |
2513 | . creates a man page for the options. | |
2514 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 2515 | |
9b371988 | 2516 | .literal xml |
168e428f | 2517 | <!-- === Start of command line options === --> |
9b371988 | 2518 | .literal off |
168e428f PH |
2519 | |
2520 | ||
9b371988 PH |
2521 | .vlist |
2522 | .vitem &%--%& | |
2523 | .oindex "--" | |
2524 | .cindex "options" "command line; terminating" | |
168e428f PH |
2525 | This is a pseudo-option whose only purpose is to terminate the options and |
2526 | therefore to cause subsequent command line items to be treated as arguments | |
2527 | rather than options, even if they begin with hyphens. | |
2528 | ||
9b371988 PH |
2529 | .vitem &%--help%& |
2530 | .oindex "&%--help%&" | |
168e428f PH |
2531 | This option causes Exim to output a few sentences stating what it is. |
2532 | The same output is generated if the Exim binary is called with no options and | |
2533 | no arguments. | |
2534 | ||
9b371988 PH |
2535 | .vitem &%-B%&<&'type'&> |
2536 | .oindex "&%-B%&" | |
2537 | .cindex "8-bit characters" | |
2538 | .cindex "Sendmail compatibility" "8-bit characters" | |
168e428f PH |
2539 | This is a Sendmail option for selecting 7 or 8 bit processing. Exim is 8-bit |
2540 | clean; it ignores this option. | |
2541 | ||
9b371988 PH |
2542 | .vitem &%-bd%& |
2543 | .oindex "&%-bd%&" | |
2544 | .cindex "daemon" | |
2545 | .cindex "SMTP listener" | |
2546 | .cindex "queue runner" | |
168e428f | 2547 | This option runs Exim as a daemon, awaiting incoming SMTP connections. Usually |
9b371988 PH |
2548 | the &%-bd%& option is combined with the &%-q%&<&'time'&> option, to specify |
2549 | that the daemon should also initiate periodic queue runs. | |
2550 | ||
2551 | The &%-bd%& option can be used only by an admin user. If either of the &%-d%& | |
2552 | (debugging) or &%-v%& (verifying) options are set, the daemon does not | |
168e428f PH |
2553 | disconnect from the controlling terminal. When running this way, it can be |
2554 | stopped by pressing ctrl-C. | |
9b371988 | 2555 | |
168e428f PH |
2556 | By default, Exim listens for incoming connections to the standard SMTP port on |
2557 | all the host's running interfaces. However, it is possible to listen on other | |
2558 | ports, on multiple ports, and only on specific interfaces. Chapter | |
9b371988 PH |
2559 | &<<CHAPinterfaces>>& contains a description of the options that control this. |
2560 | ||
168e428f | 2561 | When a listening daemon |
9b371988 PH |
2562 | .cindex "daemon" "process id (pid)" |
2563 | .cindex "pid (process id)" "of daemon" | |
2564 | is started without the use of &%-oX%& (that is, without overriding the normal | |
2565 | configuration), it writes its process id to a file called &_exim-daemon.pid_& | |
2566 | in Exim's spool directory. This location can be overridden by setting | |
2567 | PID_FILE_PATH in &_Local/Makefile_&. The file is written while Exim is still | |
168e428f | 2568 | running as root. |
9b371988 PH |
2569 | |
2570 | When &%-oX%& is used on the command line to start a listening daemon, the | |
2571 | process id is not written to the normal pid file path. However, &%-oP%& can be | |
168e428f | 2572 | used to specify a path on the command line if a pid file is required. |
9b371988 | 2573 | |
168e428f | 2574 | The SIGHUP signal |
9b371988 | 2575 | .cindex "SIGHUP" |
168e428f PH |
2576 | can be used to cause the daemon to re-exec itself. This should be done whenever |
2577 | Exim's configuration file, or any file that is incorporated into it by means of | |
9b371988 PH |
2578 | the &%.include%& facility, is changed, and also whenever a new version of Exim |
2579 | is installed. It is not necessary to do this when other files that are | |
2580 | referenced from the configuration (for example, alias files) are changed, | |
2581 | because these are reread each time they are used. | |
2582 | ||
2583 | .vitem &%-bdf%& | |
2584 | .oindex "&%-bdf%&" | |
2585 | This option has the same effect as &%-bd%& except that it never disconnects | |
2586 | from the controlling terminal, even when no debugging is specified. | |
2587 | ||
2588 | .vitem &%-be%& | |
2589 | .oindex "&%-be%&" | |
2590 | .cindex "testing" "string expansion" | |
2591 | .cindex "expansion" "testing" | |
168e428f PH |
2592 | Run Exim in expansion testing mode. Exim discards its root privilege, to |
2593 | prevent ordinary users from using this mode to read otherwise inaccessible | |
2594 | files. If no arguments are given, Exim runs interactively, prompting for lines | |
9b371988 PH |
2595 | of data. &new("Otherwise, it processes each argument in turn.") |
2596 | ||
2597 | If Exim was built with USE_READLINE=yes in &_Local/Makefile_&, it tries | |
2598 | to load the &%libreadline%& library dynamically whenever the &%-be%& option is | |
2599 | used without command line arguments. If successful, it uses the &[readline()]& | |
168e428f PH |
2600 | function, which provides extensive line-editing facilities, for reading the |
2601 | test data. A line history is supported. | |
9b371988 | 2602 | |
168e428f | 2603 | Long expansion expressions can be split over several lines by using backslash |
068aaea8 | 2604 | continuations. As in Exim's run time configuration, white space at the start of |
168e428f PH |
2605 | continuation lines is ignored. Each argument or data line is passed through the |
2606 | string expansion mechanism, and the result is output. Variable values from the | |
9b371988 PH |
2607 | configuration file (for example, &$qualify_domain$&) are available, but no |
2608 | message-specific values (such as &$domain$&) are set, because no message is | |
168e428f PH |
2609 | being processed. |
2610 | ||
9b371988 PH |
2611 | .new |
2612 | &*Note*&: If you use this mechanism to test lookups, and you change the data | |
2613 | files or databases you are using, you must exit and restart Exim before trying | |
2614 | the same lookup again. Otherwise, because each Exim process caches the results | |
2615 | of lookups, you will just get the same result as before. | |
2616 | .wen | |
2617 | ||
2618 | .vitem &%-bF%&&~<&'filename'&> | |
2619 | .oindex "&%-bF%&" | |
2620 | .cindex "system filter" "testing" | |
2621 | .cindex "testing" "system filter" | |
2622 | This option is the same as &%-bf%& except that it assumes that the filter being | |
168e428f PH |
2623 | tested is a system filter. The additional commands that are available only in |
2624 | system filters are recognized. | |
2625 | ||
9b371988 PH |
2626 | .vitem &%-bf%&&~<&'filename'&> |
2627 | .oindex "&%-bf%&" | |
2628 | .cindex "filter" "testing" | |
2629 | .cindex "testing" "filter file" | |
2630 | .cindex "forward file" "testing" | |
2631 | .cindex "testing" "forward file" | |
2632 | .cindex "Sieve filter" "testing" | |
168e428f PH |
2633 | This option runs Exim in user filter testing mode; the file is the filter file |
2634 | to be tested, and a test message must be supplied on the standard input. If | |
2635 | there are no message-dependent tests in the filter, an empty file can be | |
2636 | supplied. | |
168e428f | 2637 | |
9b371988 PH |
2638 | If you want to test a system filter file, use &%-bF%& instead of &%-bf%&. You |
2639 | can use both &%-bF%& and &%-bf%& on the same command, in order to test a system | |
2640 | filter and a user filter in the same run. For example: | |
2641 | .code | |
2642 | exim -bF /system/filter -bf /user/filter </test/message | |
2643 | .endd | |
168e428f PH |
2644 | This is helpful when the system filter adds header lines or sets filter |
2645 | variables that are used by the user filter. | |
168e428f | 2646 | |
9b371988 PH |
2647 | If the test filter file does not begin with one of the special lines |
2648 | .code | |
2649 | # Exim filter | |
2650 | # Sieve filter | |
2651 | .endd | |
2652 | it is taken to be a normal &_.forward_& file, and is tested for validity under | |
2653 | that interpretation. See sections &<<SECTitenonfilred>>& to | |
2654 | &<<SECTspecitredli>>& for a description of the possible contents of non-filter | |
2655 | redirection lists. | |
2656 | ||
2657 | The result of an Exim command that uses &%-bf%&, provided no errors are | |
168e428f PH |
2658 | detected, is a list of the actions that Exim would try to take if presented |
2659 | with the message for real. More details of filter testing are given in the | |
9b371988 PH |
2660 | separate document entitled &'Exim's interfaces to mail filtering'&. |
2661 | ||
168e428f | 2662 | When testing a filter file, |
9b371988 PH |
2663 | .cindex "&""From""& line" |
2664 | .cindex "envelope sender" | |
2665 | .cindex "&%-f%& option" "for filter testing" | |
2666 | the envelope sender can be set by the &%-f%& option, | |
2667 | or by a &"From&~"& line at the start of the test message. Various parameters | |
2668 | that would normally be taken from the envelope recipient address of the message | |
2669 | can be set by means of additional command line options (see the next four | |
2670 | options). | |
2671 | ||
2672 | .vitem &%-bfd%&&~<&'domain'&> | |
2673 | .oindex "&%-bfd%&" | |
2674 | .cindex "&$qualify_domain$&" | |
168e428f | 2675 | This sets the domain of the recipient address when a filter file is being |
9b371988 PH |
2676 | tested by means of the &%-bf%& option. The default is the value of |
2677 | &$qualify_domain$&. | |
168e428f | 2678 | |
9b371988 PH |
2679 | .vitem &%-bfl%&&~<&'local&~part'&> |
2680 | .oindex "&%-bfl%&" | |
168e428f | 2681 | This sets the local part of the recipient address when a filter file is being |
9b371988 | 2682 | tested by means of the &%-bf%& option. The default is the username of the |
168e428f PH |
2683 | process that calls Exim. A local part should be specified with any prefix or |
2684 | suffix stripped, because that is how it appears to the filter when a message is | |
2685 | actually being delivered. | |
2686 | ||
9b371988 PH |
2687 | .vitem &%-bfp%&&~<&'prefix'&> |
2688 | .oindex "&%-bfp%&" | |
168e428f | 2689 | This sets the prefix of the local part of the recipient address when a filter |
9b371988 | 2690 | file is being tested by means of the &%-bf%& option. The default is an empty |
168e428f PH |
2691 | prefix. |
2692 | ||
9b371988 PH |
2693 | .vitem &%-bfs%&&~<&'suffix'&> |
2694 | .oindex "&%-bfs%&" | |
168e428f | 2695 | This sets the suffix of the local part of the recipient address when a filter |
9b371988 | 2696 | file is being tested by means of the &%-bf%& option. The default is an empty |
168e428f PH |
2697 | suffix. |
2698 | ||
9b371988 PH |
2699 | .vitem &%-bh%&&~<&'IP&~address'&> |
2700 | .oindex "&%-bh%&" | |
2701 | .cindex "testing" "incoming SMTP" | |
2702 | .cindex "SMTP" "testing incoming" | |
2703 | .cindex "testing" "relay control" | |
2704 | .cindex "relaying" "testing configuration" | |
2705 | .cindex "policy control" "testing" | |
2706 | .cindex "debugging" "&%-bh%& option" | |
168e428f PH |
2707 | This option runs a fake SMTP session as if from the given IP address, using the |
2708 | standard input and output. The IP address may include a port number at the end, | |
2709 | after a full stop. For example: | |
9b371988 PH |
2710 | .code |
2711 | exim -bh 10.9.8.7.1234 | |
2712 | exim -bh fe80::a00:20ff:fe86:a061.5678 | |
2713 | .endd | |
168e428f | 2714 | When an IPv6 address is given, it is converted into canonical form. In the case |
9b371988 PH |
2715 | of the second example above, the value of &$sender_host_address$& after |
2716 | conversion to the canonical form is | |
2717 | &`fe80:0000:0000:0a00:20ff:fe86:a061.5678`&. | |
2718 | ||
168e428f | 2719 | Comments as to what is going on are written to the standard error file. These |
9b371988 | 2720 | include lines beginning with &"LOG"& for anything that would have been logged. |
168e428f PH |
2721 | This facility is provided for testing configuration options for incoming |
2722 | messages, to make sure they implement the required policy. For example, you can | |
9b371988 PH |
2723 | test your relay controls using &%-bh%&. |
2724 | ||
2725 | &*Warning 1*&: | |
2726 | .cindex "RFC 1413" | |
168e428f PH |
2727 | You cannot test features of the configuration that rely on |
2728 | ident (RFC 1413) callouts. These cannot be done when testing using | |
9b371988 PH |
2729 | &%-bh%& because there is no incoming SMTP connection. |
2730 | ||
2731 | &*Warning 2*&: Address verification callouts (see section &<<SECTcallver>>&) | |
2732 | are also skipped when testing using &%-bh%&. If you want these callouts to | |
2733 | occur, use &%-bhc%& instead. | |
2734 | ||
168e428f PH |
2735 | Messages supplied during the testing session are discarded, and nothing is |
2736 | written to any of the real log files. There may be pauses when DNS (and other) | |
9b371988 | 2737 | lookups are taking place, and of course these may time out. The &%-oMi%& option |
168e428f | 2738 | can be used to specify a specific IP interface and port if this is important. |
9b371988 PH |
2739 | |
2740 | The &'exim_checkaccess'& utility is a &"packaged"& version of &%-bh%& whose | |
168e428f | 2741 | output just states whether a given recipient address from a given host is |
9b371988 | 2742 | acceptable or not. See section &<<SECTcheckaccess>>&. |
168e428f | 2743 | |
9b371988 PH |
2744 | .vitem &%-bhc%&&~<&'IP&~address'&> |
2745 | .oindex "&%-bhc%&" | |
2746 | This option operates in the same way as &%-bh%&, except that address | |
168e428f PH |
2747 | verification callouts are performed if required. This includes consulting and |
2748 | updating the callout cache database. | |
2749 | ||
9b371988 PH |
2750 | .vitem &%-bi%& |
2751 | .oindex "&%-bi%&" | |
2752 | .cindex "alias file" "building" | |
2753 | .cindex "building alias file" | |
2754 | .cindex "Sendmail compatibility" "&%-bi%& option" | |
2755 | Sendmail interprets the &%-bi%& option as a request to rebuild its alias file. | |
168e428f | 2756 | Exim does not have the concept of a single alias file, and so it cannot mimic |
9b371988 | 2757 | this behaviour. However, calls to &_/usr/lib/sendmail_& with the &%-bi%& option |
168e428f PH |
2758 | tend to appear in various scripts such as NIS make files, so the option must be |
2759 | recognized. | |
9b371988 PH |
2760 | |
2761 | If &%-bi%& is encountered, the command specified by the &%bi_command%& | |
168e428f | 2762 | configuration option is run, under the uid and gid of the caller of Exim. If |
9b371988 PH |
2763 | the &%-oA%& option is used, its value is passed to the command as an argument. |
2764 | The command set by &%bi_command%& may not contain arguments. The command can | |
2765 | use the &'exim_dbmbuild'& utility, or some other means, to rebuild alias files | |
2766 | if this is required. If the &%bi_command%& option is not set, calling Exim with | |
2767 | &%-bi%& is a no-op. | |
2768 | ||
2769 | .vitem &%-bm%& | |
2770 | .oindex "&%-bm%&" | |
2771 | .cindex "local message reception" | |
168e428f PH |
2772 | This option runs an Exim receiving process that accepts an incoming, |
2773 | locally-generated message on the current input. The recipients are given as the | |
9b371988 | 2774 | command arguments (except when &%-t%& is also present &-- see below). Each |
168e428f PH |
2775 | argument can be a comma-separated list of RFC 2822 addresses. This is the |
2776 | default option for selecting the overall action of an Exim call; it is assumed | |
2777 | if no other conflicting option is present. | |
9b371988 | 2778 | |
168e428f | 2779 | If any addresses in the message are unqualified (have no domain), they are |
9b371988 PH |
2780 | qualified by the values of the &%qualify_domain%& or &%qualify_recipient%& |
2781 | options, as appropriate. The &%-bnq%& option (see below) provides a way of | |
168e428f | 2782 | suppressing this for special cases. |
9b371988 | 2783 | |
168e428f | 2784 | Policy checks on the contents of local messages can be enforced by means of |
9b371988 PH |
2785 | the non-SMTP ACL. See chapter &<<CHAPACL>>& for details. |
2786 | ||
2787 | .cindex "return code" "for &%-bm%&" | |
2788 | The return code is zero if the message is successfully accepted. Otherwise, the | |
2789 | action is controlled by the &%-oe%&&'x'& option setting &-- see below. | |
2790 | ||
168e428f | 2791 | The format |
9b371988 PH |
2792 | .cindex "message" "format" |
2793 | .cindex "format" "message" | |
2794 | .cindex "&""From""& line" | |
2795 | .cindex "UUCP" "&""From""& line" | |
2796 | .cindex "Sendmail compatibility" "&""From""& line" | |
168e428f PH |
2797 | of the message must be as defined in RFC 2822, except that, for |
2798 | compatibility with Sendmail and Smail, a line in one of the forms | |
9b371988 PH |
2799 | .code |
2800 | From sender Fri Jan 5 12:55 GMT 1997 | |
2801 | From sender Fri, 5 Jan 97 12:55:01 | |
2802 | .endd | |
168e428f PH |
2803 | (with the weekday optional, and possibly with additional text after the date) |
2804 | is permitted to appear at the start of the message. There appears to be no | |
2805 | authoritative specification of the format of this line. Exim recognizes it by | |
9b371988 | 2806 | matching against the regular expression defined by the &%uucp_from_pattern%& |
168e428f | 2807 | option, which can be changed if necessary. |
9b371988 | 2808 | |
168e428f | 2809 | The |
9b371988 | 2810 | .cindex "&%-f%& option" "overriding &""From""& line" |
168e428f | 2811 | specified sender is treated as if it were given as the argument to the |
9b371988 | 2812 | &%-f%& option, but if a &%-f%& option is also present, its argument is used in |
168e428f PH |
2813 | preference to the address taken from the message. The caller of Exim must be a |
2814 | trusted user for the sender of a message to be set in this way. | |
2815 | ||
9b371988 PH |
2816 | .vitem &%-bnq%& |
2817 | .oindex "&%-bnq%&" | |
2818 | .cindex "address qualification" "suppressing" | |
168e428f PH |
2819 | By default, Exim automatically qualifies unqualified addresses (those |
2820 | without domains) that appear in messages that are submitted locally (that | |
2821 | is, not over TCP/IP). This qualification applies both to addresses in | |
2822 | envelopes, and addresses in header lines. Sender addresses are qualified using | |
9b371988 PH |
2823 | &%qualify_domain%&, and recipient addresses using &%qualify_recipient%& (which |
2824 | defaults to the value of &%qualify_domain%&). | |
2825 | ||
2826 | Sometimes, qualification is not wanted. For example, if &%-bS%& (batch SMTP) is | |
168e428f PH |
2827 | being used to re-submit messages that originally came from remote hosts after |
2828 | content scanning, you probably do not want to qualify unqualified addresses in | |
2829 | header lines. (Such lines will be present only if you have not enabled a header | |
2830 | syntax check in the appropriate ACL.) | |
9b371988 PH |
2831 | |
2832 | The &%-bnq%& option suppresses all qualification of unqualified addresses in | |
168e428f PH |
2833 | messages that originate on the local host. When this is used, unqualified |
2834 | addresses in the envelope provoke errors (causing message rejection) and | |
2835 | unqualified addresses in header lines are left alone. | |
2836 | ||
2837 | ||
9b371988 PH |
2838 | .vitem &%-bP%& |
2839 | .oindex "&%-bP%&" | |
2840 | .cindex "configuration options" "extracting" | |
2841 | .cindex "options" "configuration &-- extracting" | |
168e428f PH |
2842 | If this option is given with no arguments, it causes the values of all Exim's |
2843 | main configuration options to be written to the standard output. The values | |
2844 | of one or more specific options can be requested by giving their names as | |
2845 | arguments, for example: | |
9b371988 PH |
2846 | .code |
2847 | exim -bP qualify_domain hold_domains | |
2848 | .endd | |
2849 | However, any option setting that is preceded by the word &"hide"& in the | |
168e428f PH |
2850 | configuration file is not shown in full, except to an admin user. For other |
2851 | users, the output is as in this example: | |
9b371988 PH |
2852 | .code |
2853 | mysql_servers = <value not displayable> | |
2854 | .endd | |
2855 | If &%configure_file%& is given as an argument, the name of the run time | |
168e428f PH |
2856 | configuration file is output. |
2857 | If a list of configuration files was supplied, the value that is output here | |
2858 | is the name of the file that was actually used. | |
168e428f | 2859 | |
9b371988 PH |
2860 | .cindex "daemon" "process id (pid)" |
2861 | .cindex "pid (process id)" "of daemon" | |
2862 | If &%log_file_path%& or &%pid_file_path%& are given, the names of the | |
2863 | directories where log files and daemon pid files are written are output, | |
2864 | respectively. If these values are unset, log files are written in a | |
2865 | sub-directory of the spool directory called &%log%&, and the pid file is | |
2866 | written directly into the spool directory. | |
2867 | ||
2868 | If &%-bP%& is followed by a name preceded by &`+`&, for example, | |
2869 | .code | |
2870 | exim -bP +local_domains | |
2871 | .endd | |
168e428f PH |
2872 | it searches for a matching named list of any type (domain, host, address, or |
2873 | local part) and outputs what it finds. | |
9b371988 PH |
2874 | |
2875 | .cindex "options" "router &-- extracting" | |
2876 | .cindex "options" "transport &-- extracting" | |
2877 | If one of the words &%router%&, &%transport%&, or &%authenticator%& is given, | |
168e428f PH |
2878 | followed by the name of an appropriate driver instance, the option settings for |
2879 | that driver are output. For example: | |
9b371988 PH |
2880 | .code |
2881 | exim -bP transport local_delivery | |
2882 | .endd | |
168e428f PH |
2883 | The generic driver options are output first, followed by the driver's private |
2884 | options. A list of the names of drivers of a particular type can be obtained by | |
9b371988 PH |
2885 | using one of the words &%router_list%&, &%transport_list%&, or |
2886 | &%authenticator_list%&, and a complete list of all drivers with their option | |
2887 | settings can be obtained by using &%routers%&, &%transports%&, or | |
2888 | &%authenticators%&. | |
168e428f PH |
2889 | |
2890 | ||
9b371988 PH |
2891 | .vitem &%-bp%& |
2892 | .oindex "&%-bp%&" | |
2893 | .cindex "queue" "listing messages on" | |
2894 | .cindex "listing" "messages on the queue" | |
168e428f | 2895 | This option requests a listing of the contents of the mail queue on the |
9b371988 | 2896 | standard output. If the &%-bp%& option is followed by a list of message ids, |
168e428f | 2897 | just those messages are listed. By default, this option can be used only by an |
9b371988 | 2898 | admin user. However, the &%queue_list_requires_admin%& option can be set false |
168e428f | 2899 | to allow any user to see the queue. |
168e428f | 2900 | |
9b371988 PH |
2901 | Each message on the queue is displayed as in the following example: |
2902 | .code | |
2903 | 25m 2.9K 0t5C6f-0000c8-00 <alice@wonderland.fict.example> | |
2904 | red.king@looking-glass.fict.example | |
2905 | <other addresses> | |
2906 | .endd | |
2907 | .cindex "message" "size in queue listing" | |
2908 | .cindex "size" "of message" | |
2909 | The first line contains the length of time the message has been on the queue | |
168e428f PH |
2910 | (in this case 25 minutes), the size of the message (2.9K), the unique local |
2911 | identifier for the message, and the message sender, as contained in the | |
2912 | envelope. For bounce messages, the sender address is empty, and appears as | |
9b371988 | 2913 | &"<>"&. If the message was submitted locally by an untrusted user who overrode |
168e428f PH |
2914 | the default sender address, the user's login name is shown in parentheses |
2915 | before the sender address. | |
9b371988 PH |
2916 | |
2917 | .cindex "frozen messages" "in queue listing" | |
2918 | If the message is frozen (attempts to deliver it are suspended) then the text | |
2919 | &"*** frozen ***"& is displayed at the end of this line. | |
2920 | ||
168e428f PH |
2921 | The recipients of the message (taken from the envelope, not the headers) are |
2922 | displayed on subsequent lines. Those addresses to which the message has already | |
2923 | been delivered are marked with the letter D. If an original address gets | |
2924 | expanded into several addresses via an alias or forward file, the original is | |
2925 | displayed with a D only when deliveries for all of its child addresses are | |
2926 | complete. | |
2927 | ||
2928 | ||
9b371988 PH |
2929 | .vitem &%-bpa%& |
2930 | .oindex "&%-bpa%&" | |
2931 | This option operates like &%-bp%&, but in addition it shows delivered addresses | |
168e428f | 2932 | that were generated from the original top level address(es) in each message by |
9b371988 PH |
2933 | alias or forwarding operations. These addresses are flagged with &"+D"& instead |
2934 | of just &"D"&. | |
168e428f PH |
2935 | |
2936 | ||
9b371988 PH |
2937 | .vitem &%-bpc%& |
2938 | .oindex "&%-bpc%&" | |
2939 | .cindex "queue" "count of messages on" | |
168e428f PH |
2940 | This option counts the number of messages on the queue, and writes the total |
2941 | to the standard output. It is restricted to admin users, unless | |
9b371988 | 2942 | &%queue_list_requires_admin%& is set false. |
168e428f PH |
2943 | |
2944 | ||
9b371988 PH |
2945 | .vitem &%-bpr%& |
2946 | .oindex "&%-bpr%&" | |
2947 | This option operates like &%-bp%&, but the output is not sorted into | |
168e428f PH |
2948 | chronological order of message arrival. This can speed it up when there are |
2949 | lots of messages on the queue, and is particularly useful if the output is | |
2950 | going to be post-processed in a way that doesn't need the sorting. | |
2951 | ||
9b371988 PH |
2952 | .vitem &%-bpra%& |
2953 | .oindex "&%-bpra%&" | |
2954 | This option is a combination of &%-bpr%& and &%-bpa%&. | |
168e428f | 2955 | |
9b371988 PH |
2956 | .vitem &%-bpru%& |
2957 | .oindex "&%-bpru%&" | |
2958 | This option is a combination of &%-bpr%& and &%-bpu%&. | |
168e428f PH |
2959 | |
2960 | ||
9b371988 PH |
2961 | .vitem &%-bpu%& |
2962 | .oindex "&%-bpu%&" | |
2963 | This option operates like &%-bp%& but shows only undelivered top-level | |
2964 | addresses for each message displayed. Addresses generated by aliasing or | |
2965 | forwarding are not shown, unless the message was deferred after processing by a | |
2966 | router with the &%one_time%& option set. | |
168e428f PH |
2967 | |
2968 | ||
9b371988 PH |
2969 | .vitem &%-brt%& |
2970 | .oindex "&%-brt%&" | |
2971 | .cindex "testing" "retry configuration" | |
2972 | .cindex "retry" "configuration testing" | |
168e428f PH |
2973 | This option is for testing retry rules, and it must be followed by up to three |
2974 | arguments. It causes Exim to look for a retry rule that matches the values | |
2975 | and to write it to the standard output. For example: | |
9b371988 PH |
2976 | .code |
2977 | exim -brt bach.comp.mus.example | |
2978 | Retry rule: *.comp.mus.example F,2h,15m; F,4d,30m; | |
2979 | .endd | |
2980 | See chapter &<<CHAPretry>>& for a description of Exim's retry rules. The first | |
168e428f | 2981 | argument, which is required, can be a complete address in the form |
9b371988 | 2982 | &'local_part@domain'&, or it can be just a domain name. The second argument is |
168e428f PH |
2983 | an optional second domain name; if no retry rule is found for the first |
2984 | argument, the second is tried. This ties in with Exim's behaviour when looking | |
9b371988 | 2985 | for retry rules for remote hosts &-- if no rule is found that matches the host, |
168e428f PH |
2986 | one that matches the mail domain is sought. The final argument is the name of a |
2987 | specific delivery error, as used in setting up retry rules, for example | |
9b371988 | 2988 | &"quota_3d"&. |
168e428f | 2989 | |
9b371988 PH |
2990 | .vitem &%-brw%& |
2991 | .oindex "&%-brw%&" | |
2992 | .cindex "testing" "rewriting" | |
2993 | .cindex "rewriting" "testing" | |
168e428f PH |
2994 | This option is for testing address rewriting rules, and it must be followed by |
2995 | a single argument, consisting of either a local part without a domain, or a | |
2996 | complete address with a fully qualified domain. Exim outputs how this address | |
2997 | would be rewritten for each possible place it might appear. See chapter | |
9b371988 | 2998 | &<<CHAPrewrite>>& for further details. |
168e428f | 2999 | |
9b371988 PH |
3000 | .vitem &%-bS%& |
3001 | .oindex "&%-bS%&" | |
3002 | .cindex "SMTP" "batched incoming" | |
3003 | .cindex "batched SMTP input" | |
168e428f PH |
3004 | This option is used for batched SMTP input, which is an alternative interface |
3005 | for non-interactive local message submission. A number of messages can be | |
3006 | submitted in a single run. However, despite its name, this is not really SMTP | |
3007 | input. Exim reads each message's envelope from SMTP commands on the standard | |
3008 | input, but generates no responses. If the caller is trusted, or | |
9b371988 | 3009 | &%untrusted_set_sender%& is set, the senders in the SMTP MAIL commands are |
168e428f | 3010 | believed; otherwise the sender is always the caller of Exim. |
9b371988 | 3011 | |
168e428f PH |
3012 | The message itself is read from the standard input, in SMTP format (leading |
3013 | dots doubled), terminated by a line containing just a single dot. An error is | |
3014 | provoked if the terminating dot is missing. A further message may then follow. | |
9b371988 | 3015 | |
168e428f | 3016 | As for other local message submissions, the contents of incoming batch SMTP |
9b371988 PH |
3017 | messages can be checked using the non-SMTP ACL (see chapter &<<CHAPACL>>&). |
3018 | Unqualified addresses are automatically qualified using &%qualify_domain%& and | |
3019 | &%qualify_recipient%&, as appropriate, unless the &%-bnq%& option is used. | |
3020 | ||
168e428f PH |
3021 | Some other SMTP commands are recognized in the input. HELO and EHLO act |
3022 | as RSET; VRFY, EXPN, ETRN, and HELP act as NOOP; | |
3023 | QUIT quits, ignoring the rest of the standard input. | |
9b371988 PH |
3024 | |
3025 | .cindex "return code" "for &%-bS%&" | |
168e428f PH |
3026 | If any error is encountered, reports are written to the standard output and |
3027 | error streams, and Exim gives up immediately. The return code is 0 if no error | |
3028 | was detected; it is 1 if one or more messages were accepted before the error | |
3029 | was detected; otherwise it is 2. | |
9b371988 | 3030 | |
168e428f | 3031 | More details of input using batched SMTP are given in section |
9b371988 | 3032 | &<<SECTincomingbatchedSMTP>>&. |
168e428f | 3033 | |
9b371988 PH |
3034 | .vitem &%-bs%& |
3035 | .oindex "&%-bs%&" | |
3036 | .cindex "SMTP" "local input" | |
3037 | .cindex "local SMTP input" | |
168e428f PH |
3038 | This option causes Exim to accept one or more messages by reading SMTP commands |
3039 | on the standard input, and producing SMTP replies on the standard output. SMTP | |
9b371988 | 3040 | policy controls, as defined in ACLs (see chapter &<<CHAPACL>>&) are applied. |
168e428f PH |
3041 | Some user agents use this interface as a way of passing locally-generated |
3042 | messages to the MTA. | |
9b371988 | 3043 | |
168e428f | 3044 | In |
9b371988 PH |
3045 | .cindex "sender" "source of" |
3046 | this usage, if the caller of Exim is trusted, or &%untrusted_set_sender%& is | |
168e428f PH |
3047 | set, the senders of messages are taken from the SMTP MAIL commands. |
3048 | Otherwise the content of these commands is ignored and the sender is set up as | |
3049 | the calling user. Unqualified addresses are automatically qualified using | |
9b371988 PH |
3050 | &%qualify_domain%& and &%qualify_recipient%&, as appropriate, unless the |
3051 | &%-bnq%& option is used. | |
3052 | ||
3053 | .cindex "inetd" | |
168e428f | 3054 | The |
9b371988 PH |
3055 | &%-bs%& option is also used to run Exim from &'inetd'&, as an alternative to |
3056 | using a listening daemon. Exim can distinguish the two cases by checking | |
3057 | whether the standard input is a TCP/IP socket. When Exim is called from | |
3058 | &'inetd'&, the source of the mail is assumed to be remote, and the comments | |
3059 | above concerning senders and qualification do not apply. In this situation, | |
3060 | Exim behaves in exactly the same way as it does when receiving a message via | |
3061 | the listening daemon. | |
3062 | ||
3063 | .vitem &%-bt%& | |
3064 | .oindex "&%-bt%&" | |
3065 | .cindex "testing" "addresses" | |
3066 | .cindex "address" "testing" | |
168e428f PH |
3067 | This option runs Exim in address testing mode, in which each argument is taken |
3068 | as an address to be tested for deliverability. The results are written to the | |
3069 | standard output. If a test fails, and the caller is not an admin user, no | |
3070 | details of the failure are output, because these might contain sensitive | |
3071 | information such as usernames and passwords for database lookups. | |
9b371988 | 3072 | |
168e428f PH |
3073 | If no arguments are given, Exim runs in an interactive manner, prompting with a |
3074 | right angle bracket for addresses to be tested. | |
9b371988 PH |
3075 | |
3076 | Unlike the &%-be%& test option, you cannot arrange for Exim to use the | |
3077 | &[readline()]& function, because it is running as &'root'& and there are | |
168e428f | 3078 | security issues. |
9b371988 | 3079 | |
168e428f | 3080 | Each address is handled as if it were the recipient address of a message |
9b371988 | 3081 | (compare the &%-bv%& option). It is passed to the routers and the result is |
168e428f | 3082 | written to the standard output. However, any router that has |
9b371988 | 3083 | &%no_address_test%& set is bypassed. This can make &%-bt%& easier to use for |
168e428f PH |
3084 | genuine routing tests if your first router passes everything to a scanner |
3085 | program. | |
9b371988 | 3086 | |
168e428f | 3087 | The |
9b371988 | 3088 | .cindex "return code" "for &%-bt%&" |
168e428f PH |
3089 | return code is 2 if any address failed outright; it is 1 if no address |
3090 | failed outright but at least one could not be resolved for some reason. Return | |
3091 | code 0 is given only when all addresses succeed. | |
9b371988 PH |
3092 | |
3093 | &*Warning*&: &%-bt%& can only do relatively simple testing. If any of the | |
168e428f PH |
3094 | routers in the configuration makes any tests on the sender address of a |
3095 | message, | |
9b371988 PH |
3096 | .cindex "&%-f%& option" "for address testing" |
3097 | you can use the &%-f%& option to set an appropriate sender when running | |
3098 | &%-bt%& tests. Without it, the sender is assumed to be the calling user at the | |
168e428f PH |
3099 | default qualifying domain. However, if you have set up (for example) routers |
3100 | whose behaviour depends on the contents of an incoming message, you cannot test | |
9b371988 | 3101 | those conditions using &%-bt%&. The &%-N%& option provides a possible way of |
168e428f PH |
3102 | doing such tests. |
3103 | ||
9b371988 PH |
3104 | .vitem &%-bV%& |
3105 | .oindex "&%-bV%&" | |
3106 | .cindex "version number of Exim" "verifying" | |
168e428f | 3107 | This option causes Exim to write the current version number, compilation |
9b371988 | 3108 | number, and compilation date of the &'exim'& binary to the standard output. |
168e428f PH |
3109 | It also lists the DBM library this is being used, the optional modules (such as |
3110 | specific lookup types), the drivers that are included in the binary, and the | |
3111 | name of the run time configuration file that is in use. | |
9b371988 PH |
3112 | |
3113 | As part of its operation, &%-bV%& causes Exim to read and syntax check its | |
168e428f PH |
3114 | configuration file. However, this is a static check only. It cannot check |
3115 | values that are to be expanded. For example, although a misspelt ACL verb is | |
9b371988 | 3116 | detected, an error in the verb's arguments is not. You cannot rely on &%-bV%& |
168e428f | 3117 | alone to discover (for example) all the typos in the configuration; some |
9b371988 PH |
3118 | realistic testing is needed. The &%-bh%& and &%-N%& options provide more |
3119 | dynamic testing facilities. | |
168e428f | 3120 | |
9b371988 PH |
3121 | .vitem &%-bv%& |
3122 | .oindex "&%-bv%&" | |
3123 | .cindex "verifying address" "using &%-bv%&" | |
3124 | .cindex "address" "verification" | |
168e428f PH |
3125 | This option runs Exim in address verification mode, in which each argument is |
3126 | taken as an address to be verified. During normal operation, verification | |
9b371988 PH |
3127 | happens mostly as a consequence processing a &%verify%& condition in an ACL |
3128 | (see chapter &<<CHAPACL>>&). If you want to test an entire ACL, see the &%-bh%& | |
3129 | option. | |
3130 | ||
168e428f PH |
3131 | If verification fails, and the caller is not an admin user, no details of the |
3132 | failure are output, because these might contain sensitive information such as | |
3133 | usernames and passwords for database lookups. | |
9b371988 | 3134 | |
168e428f PH |
3135 | If no arguments are given, Exim runs in an interactive manner, prompting with a |
3136 | right angle bracket for addresses to be verified. | |
9b371988 PH |
3137 | |
3138 | Unlike the &%-be%& test option, you cannot arrange for Exim to use the | |
3139 | &[readline()]& function, because it is running as &'exim'& and there are | |
168e428f | 3140 | security issues. |
9b371988 PH |
3141 | |
3142 | Verification differs from address testing (the &%-bt%& option) in that routers | |
3143 | that have &%no_verify%& set are skipped, and if the address is accepted by a | |
3144 | router that has &%fail_verify%& set, verification fails. The address is | |
3145 | verified as a recipient if &%-bv%& is used; to test verification for a sender | |
3146 | address, &%-bvs%& should be used. | |
3147 | ||
3148 | If the &%-v%& option is not set, the output consists of a single line for each | |
168e428f PH |
3149 | address, stating whether it was verified or not, and giving a reason in the |
3150 | latter case. Otherwise, more details are given of how the address has been | |
3151 | handled, and in the case of address redirection, all the generated addresses | |
9b371988 PH |
3152 | are also considered. Without &%-v%&, generating more than one address by |
3153 | redirection causes verification to end successfully. | |
3154 | ||
168e428f | 3155 | The |
9b371988 | 3156 | .cindex "return code" "for &%-bv%&" |
168e428f PH |
3157 | return code is 2 if any address failed outright; it is 1 if no address |
3158 | failed outright but at least one could not be resolved for some reason. Return | |
3159 | code 0 is given only when all addresses succeed. | |
9b371988 | 3160 | |
168e428f | 3161 | If any of the routers in the configuration makes any tests on the sender |
9b371988 PH |
3162 | address of a message, you should use the &%-f%& option to set an appropriate |
3163 | sender when running &%-bv%& tests. Without it, the sender is assumed to be the | |
168e428f PH |
3164 | calling user at the default qualifying domain. |
3165 | ||
9b371988 PH |
3166 | .vitem &%-bvs%& |
3167 | .oindex "&%-bvs%&" | |
3168 | This option acts like &%-bv%&, but verifies the address as a sender rather | |
168e428f PH |
3169 | than a recipient address. This affects any rewriting and qualification that |
3170 | might happen. | |
3171 | ||
9b371988 PH |
3172 | .vitem &%-C%&&~<&'filelist'&> |
3173 | .oindex "&%-C%&" | |
3174 | .cindex "configuration file" "alternate" | |
3175 | .cindex "CONFIGURE_FILE" | |
3176 | .cindex "alternate configuration file" | |
168e428f PH |
3177 | This option causes Exim to find the run time configuration file from the given |
3178 | list instead of from the list specified by the CONFIGURE_FILE | |
3179 | compile-time setting. Usually, the list will consist of just a single file | |
3180 | name, but it can be a colon-separated list of names. In this case, the first | |
3181 | file that exists is used. Failure to open an existing file stops Exim from | |
3182 | proceeding any further along the list, and an error is generated. | |
9b371988 | 3183 | |
168e428f PH |
3184 | When this option is used by a caller other than root or the Exim user, and the |
3185 | list is different from the compiled-in list, Exim gives up its root privilege | |
3186 | immediately, and runs with the real and effective uid and gid set to those of | |
3187 | the caller. However, if ALT_CONFIG_ROOT_ONLY is defined in | |
9b371988 | 3188 | &_Local/Makefile_&, root privilege is retained for &%-C%& only if the caller of |
168e428f | 3189 | Exim is root. |
9b371988 | 3190 | |
168e428f PH |
3191 | That is, the Exim user is no longer privileged in this regard. This build-time |
3192 | option is not set by default in the Exim source distribution tarbundle. | |
9b371988 PH |
3193 | However, if you are using a &"packaged"& version of Exim (source or binary), |
3194 | the packagers might have enabled it. | |
3195 | ||
168e428f | 3196 | Setting ALT_CONFIG_ROOT_ONLY locks out the possibility of testing a |
9b371988 PH |
3197 | configuration using &%-C%& right through message reception and delivery, even |
3198 | if the caller is root. The reception works, but by that time, Exim is running | |
3199 | as the Exim user, so when it re-executes to regain privilege for the delivery, | |
3200 | the use of &%-C%& causes privilege to be lost. However, root can test reception | |
3201 | and delivery using two separate commands (one to put a message on the queue, | |
3202 | using &%-odq%&, and another to do the delivery, using &%-M%&). | |
3203 | ||
3204 | If ALT_CONFIG_PREFIX is defined &_in Local/Makefile_&, it specifies a | |
3205 | prefix string with which any file named in a &%-C%& command line option | |
3206 | must start. In addition, the file name must not contain the sequence &`/../`&. | |
3207 | However, if the value of the &%-C%& option is identical to the value of | |
3208 | CONFIGURE_FILE in &_Local/Makefile_&, Exim ignores &%-C%& and proceeds as | |
168e428f | 3209 | usual. There is no default setting for ALT_CONFIG_PREFIX; when it is |
9b371988 PH |
3210 | unset, any file name can be used with &%-C%&. |
3211 | ||
168e428f PH |
3212 | ALT_CONFIG_PREFIX can be used to confine alternative configuration files |
3213 | to a directory to which only root has access. This prevents someone who has | |
3214 | broken into the Exim account from running a privileged Exim with an arbitrary | |
3215 | configuration file. | |
9b371988 PH |
3216 | |
3217 | The &%-C%& facility is useful for ensuring that configuration files are | |
168e428f PH |
3218 | syntactically correct, but cannot be used for test deliveries, unless the |
3219 | caller is privileged, or unless it is an exotic configuration that does not | |
3220 | require privilege. No check is made on the owner or group of the files | |
3221 | specified by this option. | |
3222 | ||
9b371988 PH |
3223 | .vitem &%-D%&<&'macro'&>=<&'value'&> |
3224 | .oindex "&%-D%&" | |
3225 | .cindex "macro" "setting on command line" | |
168e428f | 3226 | This option can be used to override macro definitions in the configuration file |
9b371988 | 3227 | (see section &<<SECTmacrodefs>>&). However, like &%-C%&, if it is used by an |
168e428f | 3228 | unprivileged caller, it causes Exim to give up its root privilege. |
9b371988 | 3229 | If DISABLE_D_OPTION is defined in &_Local/Makefile_&, the use of &%-D%& is |
168e428f | 3230 | completely disabled, and its use causes an immediate error exit. |
9b371988 | 3231 | |
168e428f | 3232 | The entire option (including equals sign if present) must all be within one |
9b371988 | 3233 | command line item. &%-D%& can be used to set the value of a macro to the empty |
168e428f PH |
3234 | string, in which case the equals sign is optional. These two commands are |
3235 | synonymous: | |
9b371988 PH |
3236 | .code |
3237 | exim -DABC ... | |
3238 | exim -DABC= ... | |
3239 | .endd | |
168e428f PH |
3240 | To include spaces in a macro definition item, quotes must be used. If you use |
3241 | quotes, spaces are permitted around the macro name and the equals sign. For | |
3242 | example: | |
9b371988 PH |
3243 | .code |
3244 | exim '-D ABC = something' ... | |
3245 | .endd | |
3246 | &%-D%& may be repeated up to 10 times on a command line. | |
3247 | ||
3248 | .vitem &%-d%&<&'debug&~options'&> | |
3249 | .oindex "&%-d%&" | |
3250 | .cindex "debugging" "list of selectors" | |
3251 | .cindex "debugging" "&%-d%& option" | |
168e428f PH |
3252 | This option causes debugging information to be written to the standard |
3253 | error stream. It is restricted to admin users because debugging output may show | |
3254 | database queries that contain password information. Also, the details of users' | |
9b371988 PH |
3255 | filter files should be protected. When &%-d%& is used, &%-v%& is assumed. If |
3256 | &%-d%& is given on its own, a lot of standard debugging data is output. This | |
3257 | can be reduced, or increased to include some more rarely needed information, by | |
3258 | directly following &%-d%& with a string made up of names preceded by plus or | |
068aaea8 | 3259 | minus characters. These add or remove sets of debugging data, respectively. For |
9b371988 | 3260 | example, &%-d+filter%& adds filter debugging, whereas &%-d-all+filter%& selects |
068aaea8 PH |
3261 | only filter debugging. Note that no spaces are allowed in the debug setting. |
3262 | The available debugging categories are: | |
9b371988 PH |
3263 | .display |
3264 | &`acl `& ACL interpretation | |
3265 | &`auth `& authenticators | |
3266 | &`deliver `& general delivery logic | |
3267 | &`dns `& DNS lookups (see also resolver) | |
3268 | &`dnsbl `& DNS black list (aka RBL) code | |
3269 | &`exec `& arguments for &[execv()]& calls | |
3270 | &`expand `& detailed debugging for string expansions | |
3271 | &`filter `& filter handling | |
3272 | &`hints_lookup `& hints data lookups | |
3273 | &`host_lookup `& all types of name-to-IP address handling | |
3274 | &`ident `& ident lookup | |
3275 | &`interface `& lists of local interfaces | |
3276 | &`lists `& matching things in lists | |
3277 | &`load `& system load checks | |
3278 | &`local_scan `& can be used by &[local_scan()]& (see chapter &&& | |
3279 | &<<CHAPlocalscan>>&) | |
3280 | &`lookup `& general lookup code and all lookups | |
3281 | &`memory `& memory handling | |
3282 | &`pid `& add pid to debug output lines | |
3283 | &`process_info `& setting info for the process log | |
3284 | &`queue_run `& queue runs | |
3285 | &`receive `& general message reception logic | |
3286 | &`resolver `& turn on the DNS resolver's debugging output | |
3287 | &`retry `& retry handling | |
3288 | &`rewrite `& address rewriting | |
3289 | &`route `& address routing | |
3290 | &`timestamp `& add timestamp to debug output lines | |
3291 | &`tls `& TLS logic | |
3292 | &`transport `& transports | |
3293 | &`uid `& changes of uid/gid and looking up uid/gid | |
3294 | &`verify `& address verification logic | |
3295 | &`all `& almost all of the above (see below), and also &%-v%& | |
3296 | .endd | |
3297 | .new | |
3298 | The &`all`& option excludes &`memory`& when used as &`+all`&, but includes it | |
3299 | for &`-all`&. The reason for this is that &`+all`& is something that people | |
3300 | tend to use when generating debug output for Exim maintainers. If &`+memory`& | |
3301 | is included, an awful lot of output that is very rarely of interest is | |
3302 | generated, so it now has to be explicitly requested. However, &`-all`& does | |
3303 | turn everything off. | |
3304 | .wen | |
3305 | ||
3306 | .cindex "resolver" "debugging output" | |
3307 | .cindex "DNS resolver" "debugging output" | |
3308 | The &`resolver`& option produces output only if the DNS resolver was compiled | |
168e428f PH |
3309 | with DEBUG enabled. This is not the case in some operating systems. Also, |
3310 | unfortunately, debugging output from the DNS resolver is written to stdout | |
3311 | rather than stderr. | |
9b371988 PH |
3312 | |
3313 | The default (&%-d%& with no argument) omits &`expand`&, &`filter`&, | |
3314 | &`interface`&, &`load`&, &`memory`&, &`pid`&, &`resolver`&, and &`timestamp`&. | |
3315 | However, the &`pid`& selector is forced when debugging is turned on for a | |
168e428f PH |
3316 | daemon, which then passes it on to any re-executed Exims. Exim also |
3317 | automatically adds the pid to debug lines when several remote deliveries are | |
3318 | run in parallel. | |
9b371988 PH |
3319 | |
3320 | The &`timestamp`& selector causes the current time to be inserted at the start | |
168e428f PH |
3321 | of all debug output lines. This can be useful when trying to track down delays |
3322 | in processing. | |
168e428f | 3323 | |
9b371988 PH |
3324 | If the &%debug_print%& option is set in any driver, it produces output whenever |
3325 | any debugging is selected, or if &%-v%& is used. | |
3326 | ||
3327 | .vitem &%-dd%&<&'debug&~options'&> | |
3328 | .oindex "&%-dd%&" | |
3329 | This option behaves exactly like &%-d%& except when used on a command that | |
168e428f PH |
3330 | starts a daemon process. In that case, debugging is turned off for the |
3331 | subprocesses that the daemon creates. Thus, it is useful for monitoring the | |
3332 | behaviour of the daemon without creating as much output as full debugging does. | |
3333 | ||
9b371988 PH |
3334 | .vitem &%-dropcr%& |
3335 | .oindex "&%-dropcr%&" | |
168e428f PH |
3336 | This is an obsolete option that is now a no-op. It used to affect the way Exim |
3337 | handled CR and LF characters in incoming messages. What happens now is | |
9b371988 | 3338 | described in section &<<SECTlineendings>>&. |
168e428f | 3339 | |
9b371988 PH |
3340 | .vitem &%-E%& |
3341 | .oindex "&%-E%&" | |
3342 | .cindex "bounce message" "generating" | |
168e428f PH |
3343 | This option specifies that an incoming message is a locally-generated delivery |
3344 | failure report. It is used internally by Exim when handling delivery failures | |
3345 | and is not intended for external use. Its only effect is to stop Exim | |
3346 | generating certain messages to the postmaster, as otherwise message cascades | |
3347 | could occur in some situations. As part of the same option, a message id may | |
9b371988 PH |
3348 | follow the characters &%-E%&. If it does, the log entry for the receipt of the |
3349 | new message contains the id, following &"R="&, as a cross-reference. | |
3350 | ||
3351 | .vitem &%-e%&&'x'& | |
3352 | .oindex "&%-e%&&'x'&" | |
3353 | There are a number of Sendmail options starting with &%-oe%& which seem to be | |
3354 | called by various programs without the leading &%o%& in the option. For | |
3355 | example, the &%vacation%& program uses &%-eq%&. Exim treats all options of the | |
3356 | form &%-e%&&'x'& as synonymous with the corresponding &%-oe%&&'x'& options. | |
3357 | ||
3358 | .vitem &%-F%&&~<&'string'&> | |
3359 | .oindex "&%-F%&" | |
3360 | .cindex "sender" "name" | |
3361 | .cindex "name" "of sender" | |
168e428f | 3362 | This option sets the sender's full name for use when a locally-generated |
9b371988 | 3363 | message is being accepted. In the absence of this option, the user's &'gecos'& |
168e428f | 3364 | entry from the password data is used. As users are generally permitted to alter |
9b371988 PH |
3365 | their &'gecos'& entries, no security considerations are involved. White space |
3366 | between &%-F%& and the <&'string'&> is optional. | |
3367 | ||
3368 | .vitem &%-f%&&~<&'address'&> | |
3369 | .oindex "&%-f%&" | |
3370 | .cindex "sender" "address" | |
3371 | .cindex "address" "sender" | |
3372 | .cindex "trusted user" | |
3373 | .cindex "envelope sender" | |
3374 | .cindex "user" "trusted" | |
168e428f PH |
3375 | This option sets the address of the envelope sender of a locally-generated |
3376 | message (also known as the return path). The option can normally be used only | |
9b371988 | 3377 | by a trusted user, but &%untrusted_set_sender%& can be set to allow untrusted |
168e428f | 3378 | users to use it. |
9b371988 | 3379 | |
168e428f | 3380 | Processes running as root or the Exim user are always trusted. Other |
9b371988 PH |
3381 | trusted users are defined by the &%trusted_users%& or &%trusted_groups%& |
3382 | options. In the absence of &%-f%&, or if the caller is not trusted, the sender | |
3383 | of a local message is set to the caller's login name at the default qualify | |
3384 | domain. | |
3385 | ||
3386 | There is one exception to the restriction on the use of &%-f%&: an empty sender | |
168e428f PH |
3387 | can be specified by any user, trusted or not, to create a message that can |
3388 | never provoke a bounce. An empty sender can be specified either as an empty | |
3389 | string, or as a pair of angle brackets with nothing between them, as in these | |
3390 | examples of shell commands: | |
9b371988 PH |
3391 | .code |
3392 | exim -f '<>' user@domain | |
3393 | exim -f "" user@domain | |
3394 | .endd | |
3395 | In addition, the use of &%-f%& is not restricted when testing a filter file | |
3396 | with &%-bf%& or when testing or verifying addresses using the &%-bt%& or | |
3397 | &%-bv%& options. | |
168e428f | 3398 | |
168e428f | 3399 | Allowing untrusted users to change the sender address does not of itself make |
9b371988 PH |
3400 | it possible to send anonymous mail. Exim still checks that the &'From:'& header |
3401 | refers to the local user, and if it does not, it adds a &'Sender:'& header, | |
3402 | though this can be overridden by setting &%no_local_from_check%&. | |
3403 | ||
168e428f | 3404 | White |
9b371988 PH |
3405 | .cindex "&""From""& line" |
3406 | space between &%-f%& and the <&'address'&> is optional (that is, they can be | |
3407 | given as two arguments or one combined argument). The sender of a | |
3408 | locally-generated message can also be set (when permitted) by an initial | |
3409 | &"From&~"& line in the message &-- see the description of &%-bm%& above &-- but | |
3410 | if &%-f%& is also present, it overrides &"From&~"&. | |
3411 | ||
3412 | .vitem &%-G%& | |
3413 | .oindex "&%-G%&" | |
3414 | .cindex "Sendmail compatibility" "&%-G%& option ignored" | |
168e428f PH |
3415 | This is a Sendmail option which is ignored by Exim. |
3416 | ||
9b371988 PH |
3417 | .vitem &%-h%&&~<&'number'&> |
3418 | .oindex "&%-h%&" | |
3419 | .cindex "Sendmail compatibility" "&%-h%& option ignored" | |
168e428f | 3420 | This option is accepted for compatibility with Sendmail, but has no effect. (In |
9b371988 | 3421 | Sendmail it overrides the &"hop count"& obtained by counting &'Received:'& |
168e428f PH |
3422 | headers.) |
3423 | ||
9b371988 PH |
3424 | .vitem &%-i%& |
3425 | .oindex "&%-i%&" | |
3426 | .cindex "Solaris" "&'mail'& command" | |
3427 | .cindex "dot in incoming" "non-SMTP message" | |
3428 | This option, which has the same effect as &%-oi%&, specifies that a dot on a | |
3429 | line by itself should not terminate an incoming, non-SMTP message. I can find | |
3430 | no documentation for this option in Solaris 2.4 Sendmail, but the &'mailx'& | |
3431 | command in Solaris 2.4 uses it. See also &%-ti%&. | |
3432 | ||
3433 | .vitem &%-M%&&~<&'message&~id'&>&~<&'message&~id'&>&~... | |
3434 | .oindex "&%-M%&" | |
3435 | .cindex "forcing delivery" | |
3436 | .cindex "delivery" "forcing attempt" | |
3437 | .cindex "frozen messages" "forcing delivery" | |
168e428f PH |
3438 | This option requests Exim to run a delivery attempt on each message in turn. If |
3439 | any of the messages are frozen, they are automatically thawed before the | |
9b371988 PH |
3440 | delivery attempt. The settings of &%queue_domains%&, &%queue_smtp_domains%&, |
3441 | and &%hold_domains%& are ignored. | |
3442 | ||
168e428f | 3443 | Retry |
9b371988 PH |
3444 | .cindex "hints database" "overriding retry hints" |
3445 | hints for any of the addresses are overridden &-- Exim tries to deliver even if | |
168e428f | 3446 | the normal retry time has not yet been reached. This option requires the caller |
9b371988 | 3447 | to be an admin user. However, there is an option called &%prod_requires_admin%& |
168e428f | 3448 | which can be set false to relax this restriction (and also the same requirement |
9b371988 PH |
3449 | for the &%-q%&, &%-R%&, and &%-S%& options). |
3450 | ||
3451 | .new | |
068aaea8 PH |
3452 | The deliveries happen synchronously, that is, the original Exim process does |
3453 | not terminate until all the delivery attempts have finished. No output is | |
3454 | produced unless there is a serious error. If you want to see what is happening, | |
9b371988 PH |
3455 | use the &%-v%& option as well, or inspect Exim's main log. |
3456 | .wen | |
168e428f | 3457 | |
9b371988 PH |
3458 | .vitem &%-Mar%&&~<&'message&~id'&>&~<&'address'&>&~<&'address'&>&~... |
3459 | .oindex "&%-Mar%&" | |
3460 | .cindex "message" "adding recipients" | |
3461 | .cindex "recipient" "adding" | |
168e428f | 3462 | This option requests Exim to add the addresses to the list of recipients of the |
9b371988 PH |
3463 | message (&"ar"& for &"add recipients"&). The first argument must be a message |
3464 | id, and the remaining ones must be email addresses. However, if the message is | |
168e428f PH |
3465 | active (in the middle of a delivery attempt), it is not altered. This option |
3466 | can be used only by an admin user. | |
3467 | ||
9b371988 PH |
3468 | .vitem "&*-MC*&&~<&'transport'&>&~<&'hostname'&>&~<&'sequence&~number'&>&&& |
3469 | &~<&'message&~id'&>" | |
3470 | .oindex "&%-MC%&" | |
3471 | .cindex "SMTP" "passed connection" | |
3472 | .cindex "SMTP" "multiple deliveries" | |
3473 | .cindex "multiple SMTP deliveries" | |
168e428f PH |
3474 | This option is not intended for use by external callers. It is used internally |
3475 | by Exim to invoke another instance of itself to deliver a waiting message using | |
3476 | an existing SMTP connection, which is passed as the standard input. Details are | |
9b371988 PH |
3477 | given in chapter &<<CHAPSMTP>>&. This must be the final option, and the caller |
3478 | must be root or the Exim user in order to use it. | |
168e428f | 3479 | |
9b371988 PH |
3480 | .vitem &%-MCA%& |
3481 | .oindex "&%-MCA%&" | |
168e428f | 3482 | This option is not intended for use by external callers. It is used internally |
9b371988 PH |
3483 | by Exim in conjunction with the &%-MC%& option. It signifies that the |
3484 | connection to the remote host has been authenticated. | |
168e428f | 3485 | |
9b371988 PH |
3486 | .vitem &%-MCP%& |
3487 | .oindex "&%-MCP%&" | |
168e428f | 3488 | This option is not intended for use by external callers. It is used internally |
9b371988 | 3489 | by Exim in conjunction with the &%-MC%& option. It signifies that the server to |
168e428f PH |
3490 | which Exim is connected supports pipelining. |
3491 | ||
9b371988 PH |
3492 | .vitem &%-MCQ%&&~<&'process&~id'&>&~<&'pipe&~fd'&> |
3493 | .oindex "&%-MCQ%&" | |
168e428f | 3494 | This option is not intended for use by external callers. It is used internally |
9b371988 | 3495 | by Exim in conjunction with the &%-MC%& option when the original delivery was |
168e428f PH |
3496 | started by a queue runner. It passes on the process id of the queue runner, |
3497 | together with the file descriptor number of an open pipe. Closure of the pipe | |
3498 | signals the final completion of the sequence of processes that are passing | |
3499 | messages through the same SMTP connection. | |
3500 | ||
9b371988 PH |
3501 | .vitem &%-MCS%& |
3502 | .oindex "&%-MCS%&" | |
168e428f | 3503 | This option is not intended for use by external callers. It is used internally |
9b371988 | 3504 | by Exim in conjunction with the &%-MC%& option, and passes on the fact that the |
168e428f PH |
3505 | SMTP SIZE option should be used on messages delivered down the existing |
3506 | connection. | |
3507 | ||
9b371988 PH |
3508 | .vitem &%-MCT%& |
3509 | .oindex "&%-MCT%&" | |
168e428f | 3510 | This option is not intended for use by external callers. It is used internally |
9b371988 | 3511 | by Exim in conjunction with the &%-MC%& option, and passes on the fact that the |
168e428f PH |
3512 | host to which Exim is connected supports TLS encryption. |
3513 | ||
9b371988 PH |
3514 | .vitem &%-Mc%&&~<&'message&~id'&>&~<&'message&~id'&>&~... |
3515 | .oindex "&%-Mc%&" | |
3516 | .cindex "hints database" "not overridden by &%-Mc%&" | |
3517 | .cindex "delivery" "manually started &-- not forced" | |
168e428f | 3518 | This option requests Exim to run a delivery attempt on each message in turn, |
9b371988 | 3519 | but unlike the &%-M%& option, it does check for retry hints, and respects any |
168e428f PH |
3520 | that are found. This option is not very useful to external callers. It is |
3521 | provided mainly for internal use by Exim when it needs to re-invoke itself in | |
9b371988 PH |
3522 | order to regain root privilege for a delivery (see chapter &<<CHAPsecurity>>&). |
3523 | However, &%-Mc%& can be useful when testing, in order to run a delivery that | |
3524 | respects retry times and other options such as &%hold_domains%& that are | |
3525 | overridden when &%-M%& is used. Such a delivery does not count as a queue run. | |
168e428f | 3526 | If you want to run a specific delivery as if in a queue run, you should use |
9b371988 | 3527 | &%-q%& with a message id argument. A distinction between queue run deliveries |
168e428f PH |
3528 | and other deliveries is made in one or two places. |
3529 | ||
9b371988 PH |
3530 | .vitem &%-Mes%&&~<&'message&~id'&>&~<&'address'&> |
3531 | .oindex "&%-Mes%&" | |
3532 | .cindex "message" "changing sender" | |
3533 | .cindex "sender" "changing" | |
168e428f | 3534 | This option requests Exim to change the sender address in the message to the |
9b371988 PH |
3535 | given address, which must be a fully qualified address or &"<>"& (&"es"& for |
3536 | &"edit sender"&). There must be exactly two arguments. The first argument must | |
3537 | be a message id, and the second one an email address. However, if the message | |
3538 | is active (in the middle of a delivery attempt), its status is not altered. | |
3539 | This option can be used only by an admin user. | |
3540 | ||
3541 | .vitem &%-Mf%&&~<&'message&~id'&>&~<&'message&~id'&>&~... | |
3542 | .oindex "&%-Mf%&" | |
3543 | .cindex "freezing messages" | |
3544 | .cindex "message" "manually freezing" | |
3545 | This option requests Exim to mark each listed message as &"frozen"&. This | |
3546 | prevents any delivery attempts taking place until the message is &"thawed"&, | |
3547 | either manually or as a result of the &%auto_thaw%& configuration option. | |
168e428f PH |
3548 | However, if any of the messages are active (in the middle of a delivery |
3549 | attempt), their status is not altered. This option can be used only by an admin | |
3550 | user. | |
3551 | ||
9b371988 PH |
3552 | .vitem &%-Mg%&&~<&'message&~id'&>&~<&'message&~id'&>&~... |
3553 | .oindex "&%-Mg%&" | |
3554 | .cindex "giving up on messages" | |
3555 | .cindex "message" "abandoning delivery attempts" | |
3556 | .cindex "delivery" "abandoning further attempts" | |
168e428f PH |
3557 | This option requests Exim to give up trying to deliver the listed messages, |
3558 | including any that are frozen. However, if any of the messages are active, | |
3559 | their status is not altered. For non-bounce messages, a delivery error message | |
9b371988 | 3560 | is sent to the sender, containing the text &"cancelled by administrator"&. |
168e428f PH |
3561 | Bounce messages are just discarded. This option can be used only by an admin |
3562 | user. | |
3563 | ||
9b371988 PH |
3564 | .vitem &%-Mmad%&&~<&'message&~id'&>&~<&'message&~id'&>&~... |
3565 | .oindex "&%-Mmad%&" | |
3566 | .cindex "delivery" "cancelling all" | |
168e428f | 3567 | This option requests Exim to mark all the recipient addresses in the messages |
9b371988 | 3568 | as already delivered (&"mad"& for &"mark all delivered"&). However, if any |
168e428f PH |
3569 | message is active (in the middle of a delivery attempt), its status is not |
3570 | altered. This option can be used only by an admin user. | |
3571 | ||
9b371988 PH |
3572 | .vitem &%-Mmd%&&~<&'message&~id'&>&~<&'address'&>&~<&'address'&>&~... |
3573 | .oindex "&%-Mmd%&" | |
3574 | .cindex "delivery" "cancelling by address" | |
3575 | .cindex "recipient" "removing" | |
3576 | .cindex "removing recipients" | |
168e428f | 3577 | This option requests Exim to mark the given addresses as already delivered |
9b371988 | 3578 | (&"md"& for &"mark delivered"&). The first argument must be a message id, and |
168e428f PH |
3579 | the remaining ones must be email addresses. These are matched to recipient |
3580 | addresses in the message in a case-sensitive manner. If the message is active | |
3581 | (in the middle of a delivery attempt), its status is not altered. This option | |
3582 | can be used only by an admin user. | |
3583 | ||
9b371988 PH |
3584 | .vitem &%-Mrm%&&~<&'message&~id'&>&~<&'message&~id'&>&~... |
3585 | .oindex "&%-Mrm%&" | |
3586 | .cindex "removing messages" | |
3587 | .cindex "abandoning mail" | |
3588 | .cindex "message" "manually discarding" | |
168e428f PH |
3589 | This option requests Exim to remove the given messages from the queue. No |
3590 | bounce messages are sent; each message is simply forgotten. However, if any of | |
3591 | the messages are active, their status is not altered. This option can be used | |
3592 | only by an admin user or by the user who originally caused the message to be | |
3593 | placed on the queue. | |
3594 | ||
9b371988 PH |
3595 | .vitem &%-Mt%&&~<&'message&~id'&>&~<&'message&~id'&>&~... |
3596 | .oindex "&%-Mt%&" | |
3597 | .cindex "thawing messages" | |
3598 | .cindex "unfreezing messages" | |
3599 | .cindex "frozen messages" "thawing" | |
3600 | .cindex "message" "thawing frozen" | |
3601 | This option requests Exim to &"thaw"& any of the listed messages that are | |
3602 | &"frozen"&, so that delivery attempts can resume. However, if any of the | |
3603 | messages are active, their status is not altered. This option can be used only | |
3604 | by an admin user. | |
3605 | ||
3606 | .vitem &%-Mvb%&&~<&'message&~id'&> | |
3607 | .oindex "&%-Mvb%&" | |
3608 | .cindex "listing" "message body" | |
3609 | .cindex "message" "listing body of" | |
168e428f PH |
3610 | This option causes the contents of the message body (-D) spool file to be |
3611 | written to the standard output. This option can be used only by an admin user. | |
3612 | ||
9b371988 PH |
3613 | .vitem &%-Mvh%&&~<&'message&~id'&> |
3614 | .oindex "&%-Mvh%&" | |
3615 | .cindex "listing" "message headers" | |
3616 | .cindex "header lines" "listing" | |
3617 | .cindex "message" "listing header lines" | |
168e428f PH |
3618 | This option causes the contents of the message headers (-H) spool file to be |
3619 | written to the standard output. This option can be used only by an admin user. | |
3620 | ||
9b371988 PH |
3621 | .vitem &%-Mvl%&&~<&'message&~id'&> |
3622 | .oindex "&%-Mvl%&" | |
3623 | .cindex "listing" "message log" | |
3624 | .cindex "message" "listing message log" | |
168e428f PH |
3625 | This option causes the contents of the message log spool file to be written to |
3626 | the standard output. This option can be used only by an admin user. | |
3627 | ||
9b371988 PH |
3628 | .vitem &%-m%& |
3629 | .oindex "&%-m%&" | |
3630 | This is apparently a synonym for &%-om%& that is accepted by Sendmail, so Exim | |
168e428f PH |
3631 | treats it that way too. |
3632 | ||
9b371988 PH |
3633 | .vitem &%-N%& |
3634 | .oindex "&%-N%&" | |
3635 | .cindex "debugging" "&%-N%& option" | |
3636 | .cindex "debugging" "suppressing delivery" | |
168e428f | 3637 | This is a debugging option that inhibits delivery of a message at the transport |
9b371988 | 3638 | level. It implies &%-v%&. Exim goes through many of the motions of delivery &-- |
168e428f PH |
3639 | it just doesn't actually transport the message, but instead behaves as if it |
3640 | had successfully done so. However, it does not make any updates to the retry | |
9b371988 PH |
3641 | database, and the log entries for deliveries are flagged with &"*>"& rather |
3642 | than &"=>"&. | |
3643 | ||
3644 | Because &%-N%& discards any message to which it applies, only root or the Exim | |
3645 | user are allowed to use it with &%-bd%&, &%-q%&, &%-R%& or &%-M%&. In other | |
3646 | words, an ordinary user can use it only when supplying an incoming message to | |
3647 | which it will apply. Although transportation never fails when &%-N%& is set, an | |
3648 | address may be deferred because of a configuration problem on a transport, or a | |
3649 | routing problem. Once &%-N%& has been used for a delivery attempt, it sticks to | |
3650 | the message, and applies to any subsequent delivery attempts that may happen | |
3651 | for that message. | |
3652 | ||
3653 | .vitem &%-n%& | |
3654 | .oindex "&%-n%&" | |
3655 | .cindex "Sendmail compatibility" "&%-n%& option ignored" | |
3656 | This option is interpreted by Sendmail to mean &"no aliasing"&. It is ignored | |
3657 | by Exim. | |
3658 | ||
3659 | .vitem &%-O%&&~<&'data'&> | |
3660 | .oindex "&%-O%&" | |
3661 | This option is interpreted by Sendmail to mean &`set option`&. It is ignored by | |
168e428f PH |
3662 | Exim. |
3663 | ||
9b371988 PH |
3664 | .vitem &%-oA%&&~<&'file&~name'&> |
3665 | .oindex "&%-oA%&" | |
3666 | .cindex "Sendmail compatibility" "&%-oA%& option" | |
3667 | This option is used by Sendmail in conjunction with &%-bi%& to specify an | |
3668 | alternative alias file name. Exim handles &%-bi%& differently; see the | |
168e428f PH |
3669 | description above. |
3670 | ||
9b371988 PH |
3671 | .vitem &%-oB%&&~<&'n'&> |
3672 | .oindex "&%-oB%&" | |
3673 | .cindex "SMTP" "passed connection" | |
3674 | .cindex "SMTP" "multiple deliveries" | |
3675 | .cindex "multiple SMTP deliveries" | |
168e428f | 3676 | This is a debugging option which limits the maximum number of messages that can |
9b371988 PH |
3677 | be delivered down one SMTP connection, overriding the value set in any &(smtp)& |
3678 | transport. If <&'n'&> is omitted, the limit is set to 1. | |
168e428f | 3679 | |
9b371988 PH |
3680 | .vitem &%-odb%& |
3681 | .oindex "&%-odb%&" | |
3682 | .cindex "background delivery" | |
3683 | .cindex "delivery" "in the background" | |
168e428f | 3684 | This option applies to all modes in which Exim accepts incoming messages, |
9b371988 | 3685 | including the listening daemon. It requests &"background"& delivery of such |
168e428f PH |
3686 | messages, which means that the accepting process automatically starts a |
3687 | delivery process for each message received, but does not wait for the delivery | |
3688 | processes to finish. | |
9b371988 | 3689 | |
168e428f PH |
3690 | When all the messages have been received, the reception process exits, |
3691 | leaving the delivery processes to finish in their own time. The standard output | |
3692 | and error streams are closed at the start of each delivery process. | |
9b371988 PH |
3693 | This is the default action if none of the &%-od%& options are present. |
3694 | ||
168e428f | 3695 | If one of the queueing options in the configuration file |
9b371988 PH |
3696 | (&%queue_only%& or &%queue_only_file%&, for example) is in effect, &%-odb%& |
3697 | overrides it if &%queue_only_override%& is set true, which is the default | |
3698 | setting. If &%queue_only_override%& is set false, &%-odb%& has no effect. | |
3699 | ||
3700 | .vitem &%-odf%& | |
3701 | .oindex "&%-odf%&" | |
3702 | .cindex "foreground delivery" | |
3703 | .cindex "delivery" "in the foreground" | |
3704 | This option requests &"foreground"& (synchronous) delivery when Exim has | |
3705 | accepted a locally-generated message. (For the daemon it is exactly the same as | |
3706 | &%-odb%&.) A delivery process is automatically started to deliver the message, | |
3707 | and Exim waits for it to complete before proceeding. | |
3708 | ||
168e428f PH |
3709 | The original Exim reception process does not finish until the delivery |
3710 | process for the final message has ended. The standard error stream is left open | |
3711 | during deliveries. | |
9b371988 PH |
3712 | |
3713 | However, like &%-odb%&, this option has no effect if &%queue_only_override%& is | |
168e428f | 3714 | false and one of the queueing options in the configuration file is in effect. |
9b371988 | 3715 | |
168e428f PH |
3716 | If there is a temporary delivery error during foreground delivery, the |
3717 | message is left on the queue for later delivery, and the original reception | |
9b371988 | 3718 | process exits. See chapter &<<CHAPnonqueueing>>& for a way of setting up a |
168e428f PH |
3719 | restricted configuration that never queues messages. |
3720 | ||
3721 | ||
9b371988 PH |
3722 | .vitem &%-odi%& |
3723 | .oindex "&%-odi%&" | |
3724 | This option is synonymous with &%-odf%&. It is provided for compatibility with | |
168e428f PH |
3725 | Sendmail. |
3726 | ||
9b371988 PH |
3727 | .vitem &%-odq%& |
3728 | .oindex "&%-odq%&" | |
3729 | .cindex "non-immediate delivery" | |
3730 | .cindex "delivery" "suppressing immediate" | |
3731 | .cindex "queueing incoming messages" | |
168e428f PH |
3732 | This option applies to all modes in which Exim accepts incoming messages, |
3733 | including the listening daemon. It specifies that the accepting process should | |
3734 | not automatically start a delivery process for each message received. Messages | |
3735 | are placed on the queue, and remain there until a subsequent queue runner | |
3736 | process encounters them. There are several configuration options (such as | |
9b371988 PH |
3737 | &%queue_only%&) that can be used to queue incoming messages under certain |
3738 | conditions. This option overrides all of them and also &%-odqs%&. It always | |
168e428f PH |
3739 | forces queueing. |
3740 | ||
9b371988 PH |
3741 | .vitem &%-odqs%& |
3742 | .oindex "&%-odqs%&" | |
3743 | .cindex "SMTP" "delaying delivery" | |
3744 | This option is a hybrid between &%-odb%&/&%-odi%& and &%-odq%&. | |
3745 | However, like &%-odb%& and &%-odi%&, this option has no effect if | |
3746 | &%queue_only_override%& is false and one of the queueing options in the | |
168e428f | 3747 | configuration file is in effect. |
9b371988 PH |
3748 | |
3749 | When &%-odqs%& does operate, a delivery process is started for each incoming | |
3750 | message, in the background by default, but in the foreground if &%-odi%& is | |
3751 | also present. The recipient addresses are routed, and local deliveries are done | |
3752 | in the normal way. However, if any SMTP deliveries are required, they are not | |
3753 | done at this time, so the message remains on the queue until a subsequent queue | |
168e428f PH |
3754 | runner process encounters it. Because routing was done, Exim knows which |
3755 | messages are waiting for which hosts, and so a number of messages for the same | |
9b371988 | 3756 | host can be sent in a single SMTP connection. The &%queue_smtp_domains%& |
168e428f | 3757 | configuration option has the same effect for specific domains. See also the |
9b371988 | 3758 | &%-qq%& option. |
168e428f | 3759 | |
9b371988 PH |
3760 | .vitem &%-oee%& |
3761 | .oindex "&%-oee%&" | |
3762 | .cindex "error" "reporting" | |
168e428f PH |
3763 | If an error is detected while a non-SMTP message is being received (for |
3764 | example, a malformed address), the error is reported to the sender in a mail | |
3765 | message. | |
9b371988 PH |
3766 | |
3767 | .cindex "return code" "for &%-oee%&" | |
168e428f | 3768 | Provided |
168e428f PH |
3769 | this error message is successfully sent, the Exim receiving process |
3770 | exits with a return code of zero. If not, the return code is 2 if the problem | |
3771 | is that the original message has no recipients, or 1 any other error. This is | |
9b371988 | 3772 | the default &%-oe%&&'x'& option if Exim is called as &'rmail'&. |
168e428f | 3773 | |
9b371988 PH |
3774 | .vitem &%-oem%& |
3775 | .oindex "&%-oem%&" | |
3776 | .cindex "error" "reporting" | |
3777 | .cindex "return code" "for &%-oem%&" | |
3778 | This is the same as &%-oee%&, except that Exim always exits with a non-zero | |
168e428f | 3779 | return code, whether or not the error message was successfully sent. |
9b371988 | 3780 | This is the default &%-oe%&&'x'& option, unless Exim is called as &'rmail'&. |
168e428f | 3781 | |
9b371988 PH |
3782 | .vitem &%-oep%& |
3783 | .oindex "&%-oep%&" | |
3784 | .cindex "error" "reporting" | |
168e428f PH |
3785 | If an error is detected while a non-SMTP message is being received, the |
3786 | error is reported by writing a message to the standard error file (stderr). | |
9b371988 | 3787 | .cindex "return code" "for &%-oep%&" |
168e428f PH |
3788 | The return code is 1 for all errors. |
3789 | ||
9b371988 PH |
3790 | .vitem &%-oeq%& |
3791 | .oindex "&%-oeq%&" | |
3792 | .cindex "error" "reporting" | |
168e428f | 3793 | This option is supported for compatibility with Sendmail, but has the same |
9b371988 | 3794 | effect as &%-oep%&. |
168e428f | 3795 | |
9b371988 PH |
3796 | .vitem &%-oew%& |
3797 | .oindex "&%-oew%&" | |
3798 | .cindex "error" "reporting" | |
168e428f | 3799 | This option is supported for compatibility with Sendmail, but has the same |
9b371988 PH |
3800 | effect as &%-oem%&. |
3801 | ||
3802 | .vitem &%-oi%& | |
3803 | .oindex "&%-oi%&" | |
3804 | .cindex "dot in incoming" "non-SMTP message" | |
3805 | This option, which has the same effect as &%-i%&, specifies that a dot on a | |
3806 | line by itself should not terminate an incoming, non-SMTP message. Otherwise, a | |
3807 | single dot does terminate, though Exim does no special processing for other | |
3808 | lines that start with a dot. This option is set by default if Exim is called as | |
3809 | &'rmail'&. See also &%-ti%&. | |
3810 | ||
3811 | .vitem &%-oitrue%& | |
3812 | .oindex "&%-oitrue%&" | |
3813 | This option is treated as synonymous with &%-oi%&. | |
3814 | ||
3815 | .vitem &%-oMa%&&~<&'host&~address'&> | |
3816 | .oindex "&%-oMa%&" | |
3817 | .cindex "sender host address" "specifying for local message" | |
3818 | A number of options starting with &%-oM%& can be used to set values associated | |
168e428f PH |
3819 | with remote hosts on locally-submitted messages (that is, messages not received |
3820 | over TCP/IP). These options can be used by any caller in conjunction with the | |
9b371988 PH |
3821 | &%-bh%&, &%-be%&, &%-bf%&, &%-bF%&, &%-bt%&, or &%-bv%& testing options. In |
3822 | other circumstances, they are ignored unless the caller is trusted. | |
3823 | ||
3824 | The &%-oMa%& option sets the sender host address. This may include a port | |
3825 | number at the end, after a full stop (period). For example: | |
3826 | .code | |
3827 | exim -bs -oMa 10.9.8.7.1234 | |
3828 | .endd | |
168e428f PH |
3829 | An alternative syntax is to enclose the IP address in square brackets, |
3830 | followed by a colon and the port number: | |
9b371988 PH |
3831 | .code |
3832 | exim -bs -oMa [10.9.8.7]:1234 | |
3833 | .endd | |
3834 | The IP address is placed in the &$sender_host_address$& variable, and the | |
3835 | port, if present, in &$sender_host_port$&. | |
3836 | ||
3837 | .vitem &%-oMaa%&&~<&'name'&> | |
3838 | .oindex "&%-oMaa%&" | |
3839 | .cindex "authentication name" "specifying for local message" | |
3840 | See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMaa%& | |
3841 | option sets the value of &$sender_host_authenticated$& (the authenticator | |
3842 | name). See chapter &<<CHAPSMTPAUTH>>& for a discussion of SMTP authentication. | |
3843 | ||
3844 | .vitem &%-oMai%&&~<&'string'&> | |
3845 | .oindex "&%-oMai%&" | |
3846 | .cindex "authentication id" "specifying for local message" | |
3847 | See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMai%& | |
3848 | option sets the value of &$authenticated_id$& (the id that was authenticated). | |
168e428f | 3849 | This overrides the default value (the caller's login id) for messages from |
9b371988 | 3850 | local sources. See chapter &<<CHAPSMTPAUTH>>& for a discussion of authenticated |
168e428f PH |
3851 | ids. |
3852 | ||
9b371988 PH |
3853 | .vitem &%-oMas%&&~<&'address'&> |
3854 | .oindex "&%-oMas%&" | |
3855 | .cindex "authentication sender" "specifying for local message" | |
3856 | See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMas%& | |
3857 | option sets the authenticated sender value in &$authenticated_sender$&. It | |
168e428f | 3858 | overrides the sender address that is created from the caller's login id for |
9b371988 | 3859 | messages from local sources. See chapter &<<CHAPSMTPAUTH>>& for a discussion of |
168e428f PH |
3860 | authenticated senders. |
3861 | ||
9b371988 PH |
3862 | .vitem &%-oMi%&&~<&'interface&~address'&> |
3863 | .oindex "&%-oMi%&" | |
3864 | .cindex "interface address" "specifying for local message" | |
3865 | See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMi%& | |
3866 | option sets the IP interface address value. A port number may be included, | |
3867 | using the same syntax as for &%-oMa%&. The interface address is placed in | |
3868 | &$interface_address$& and the port number, if present, in &$interface_port$&. | |
3869 | ||
3870 | .vitem &%-oMr%&&~<&'protocol&~name'&> | |
3871 | .oindex "&%-oMr%&" | |
3872 | .cindex "protocol" "incoming &-- specifying for local message" | |
3873 | .cindex "&$received_protocol$&" | |
3874 | See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMr%& | |
3875 | option sets the received protocol value that is stored in | |
3876 | &$received_protocol$&. However, this applies only when &%-bs%& is not used. For | |
3877 | interactive SMTP input (&%-bs%&), the protocol is always &"local-"& followed by | |
3878 | one of the standard SMTP protocol names (see the description of | |
3879 | &$received_protocol$& in section &<<SECTexpvar>>&). For &%-bS%& (batch SMTP) | |
3880 | however, the protocol can be set by &%-oMr%&. | |
3881 | ||
3882 | .vitem &%-oMs%&&~<&'host&~name'&> | |
3883 | .oindex "&%-oMs%&" | |
3884 | .cindex "sender host name" "specifying for local message" | |
3885 | See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMs%& | |
3886 | option sets the sender host name in &$sender_host_name$&. When this option is | |
3887 | present, Exim does not attempt to look up a host name from an IP address; it | |
3888 | uses the name it is given. | |
3889 | ||
3890 | .vitem &%-oMt%&&~<&'ident&~string'&> | |
3891 | .oindex "&%-oMt%&" | |
3892 | .cindex "sender ident string" "specifying for local message" | |
3893 | See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMt%& | |
3894 | option sets the sender ident value in &$sender_ident$&. The default setting for | |
3895 | local callers is the login id of the calling process. | |
3896 | ||
3897 | .vitem &%-om%& | |
3898 | .oindex "&%-om%&" | |
3899 | .cindex "Sendmail compatibility" "&%-om%& option ignored" | |
3900 | In Sendmail, this option means &"me too"&, indicating that the sender of a | |
168e428f PH |
3901 | message should receive a copy of the message if the sender appears in an alias |
3902 | expansion. Exim always does this, so the option does nothing. | |
3903 | ||
9b371988 PH |
3904 | .vitem &%-oo%& |
3905 | .oindex "&%-oo%&" | |
3906 | .cindex "Sendmail compatibility" "&%-oo%& option ignored" | |
3907 | This option is ignored. In Sendmail it specifies &"old style headers"&, | |
3908 | whatever that means. | |
3909 | ||
3910 | .vitem &%-oP%&&~<&'path'&> | |
3911 | .oindex "&%-oP%&" | |
3912 | .cindex "pid (process id)" "of daemon" | |
3913 | .cindex "daemon" "process id (pid)" | |
3914 | This option is useful only in conjunction with &%-bd%& or &%-q%& with a time | |
168e428f | 3915 | value. The option specifies the file to which the process id of the daemon is |
9b371988 PH |
3916 | written. When &%-oX%& is used with &%-bd%&, or when &%-q%& with a time is used |
3917 | without &%-bd%&, this is the only way of causing Exim to write a pid file, | |
168e428f PH |
3918 | because in those cases, the normal pid file is not used. |
3919 | ||
9b371988 PH |
3920 | .vitem &%-or%&&~<&'time'&> |
3921 | .oindex "&%-or%&" | |
3922 | .cindex "timeout" "for non-SMTP input" | |
168e428f PH |
3923 | This option sets a timeout value for incoming non-SMTP messages. If it is not |
3924 | set, Exim will wait forever for the standard input. The value can also be set | |
9b371988 PH |
3925 | by the &%receive_timeout%& option. The format used for specifying times is |
3926 | described in section &<<SECTtimeformat>>&. | |
168e428f | 3927 | |
9b371988 PH |
3928 | .vitem &%-os%&&~<&'time'&> |
3929 | .oindex "&%-os%&" | |
3930 | .cindex "timeout" "for SMTP input" | |
3931 | .cindex "SMTP timeout" "input" | |
168e428f PH |
3932 | This option sets a timeout value for incoming SMTP messages. The timeout |
3933 | applies to each SMTP command and block of data. The value can also be set by | |
9b371988 PH |
3934 | the &%smtp_receive_timeout%& option; it defaults to 5 minutes. The format used |
3935 | for specifying times is described in section &<<SECTtimeformat>>&. | |
3936 | ||
3937 | .vitem &%-ov%& | |
3938 | .oindex "&%-ov%&" | |
3939 | This option has exactly the same effect as &%-v%&. | |
3940 | ||
3941 | .vitem &%-oX%&&~<&'number&~or&~string'&> | |
3942 | .oindex "&%-oX%&" | |
3943 | .cindex "TCP/IP" "setting listening ports" | |
3944 | .cindex "TCP/IP" "setting listening interfaces" | |
3945 | .cindex "port" "receiving TCP/IP" | |
3946 | This option is relevant only when the &%-bd%& (start listening daemon) option | |
3947 | is also given. It controls which ports and interfaces the daemon uses. Details | |
3948 | of the syntax, and how it interacts with configuration file options, are given | |
3949 | in chapter &<<CHAPinterfaces>>&. When &%-oX%& is used to start a daemon, no pid | |
3950 | file is written unless &%-oP%& is also present to specify a pid file name. | |
3951 | ||
3952 | .vitem &%-pd%& | |
3953 | .oindex "&%-pd%&" | |
3954 | .cindex "Perl" "starting the interpreter" | |
168e428f | 3955 | This option applies when an embedded Perl interpreter is linked with Exim (see |
9b371988 PH |
3956 | chapter &<<CHAPperl>>&). It overrides the setting of the &%perl_at_start%& |
3957 | option, forcing the starting of the interpreter to be delayed until it is | |
3958 | needed. | |
168e428f | 3959 | |
9b371988 PH |
3960 | .vitem &%-ps%& |
3961 | .oindex "&%-ps%&" | |
3962 | .cindex "Perl" "starting the interpreter" | |
168e428f | 3963 | This option applies when an embedded Perl interpreter is linked with Exim (see |
9b371988 PH |
3964 | chapter &<<CHAPperl>>&). It overrides the setting of the &%perl_at_start%& |
3965 | option, forcing the starting of the interpreter to occur as soon as Exim is | |
3966 | started. | |
168e428f | 3967 | |
9b371988 PH |
3968 | .vitem &%-p%&<&'rval'&>:<&'sval'&> |
3969 | .oindex "&%-p%&" | |
168e428f | 3970 | For compatibility with Sendmail, this option is equivalent to |
9b371988 PH |
3971 | .display |
3972 | &`-oMr`& <&'rval'&> &`-oMs`& <&'sval'&> | |
3973 | .endd | |
168e428f PH |
3974 | It sets the incoming protocol and host name (for trusted callers). The |
3975 | host name and its colon can be omitted when only the protocol is to be set. | |
9b371988 PH |
3976 | Note the Exim already has two private options, &%-pd%& and &%-ps%&, that refer |
3977 | to embedded Perl. It is therefore impossible to set a protocol value of &`p`& | |
3978 | or &`s`& using this option (but that does not seem a real limitation). | |
168e428f | 3979 | |
9b371988 PH |
3980 | .vitem &%-q%& |
3981 | .oindex "&%-q%&" | |
3982 | .cindex "queue runner" "starting manually" | |
168e428f | 3983 | This option is normally restricted to admin users. However, there is a |
9b371988 PH |
3984 | configuration option called &%prod_requires_admin%& which can be set false to |
3985 | relax this restriction (and also the same requirement for the &%-M%&, &%-R%&, | |
3986 | and &%-S%& options). | |
3987 | ||
3988 | .cindex "queue runner" "description of operation" | |
3989 | The &%-q%& option starts one queue runner process. This scans the queue of | |
168e428f PH |
3990 | waiting messages, and runs a delivery process for each one in turn. It waits |
3991 | for each delivery process to finish before starting the next one. A delivery | |
3992 | process may not actually do any deliveries if the retry times for the addresses | |
9b371988 PH |
3993 | have not been reached. Use &%-qf%& (see below) if you want to override this. |
3994 | ||
168e428f | 3995 | If |
9b371988 PH |
3996 | .cindex "SMTP" "passed connection" |
3997 | .cindex "SMTP" "multiple deliveries" | |
3998 | .cindex "multiple SMTP deliveries" | |
168e428f PH |
3999 | the delivery process spawns other processes to deliver other messages down |
4000 | passed SMTP connections, the queue runner waits for these to finish before | |
4001 | proceeding. | |
9b371988 | 4002 | |
168e428f PH |
4003 | When all the queued messages have been considered, the original queue runner |
4004 | process terminates. In other words, a single pass is made over the waiting | |
9b371988 PH |
4005 | mail, one message at a time. Use &%-q%& with a time (see below) if you want |
4006 | this to be repeated periodically. | |
4007 | ||
168e428f PH |
4008 | Exim processes the waiting messages in an unpredictable order. It isn't very |
4009 | random, but it is likely to be different each time, which is all that matters. | |
4010 | If one particular message screws up a remote MTA, other messages to the same | |
4011 | MTA have a chance of getting through if they get tried first. | |
9b371988 | 4012 | |
168e428f PH |
4013 | It is possible to cause the messages to be processed in lexical message id |
4014 | order, which is essentially the order in which they arrived, by setting the | |
9b371988 | 4015 | &%queue_run_in_order%& option, but this is not recommended for normal use. |
168e428f | 4016 | |
9b371988 PH |
4017 | .vitem &%-q%&<&'qflags'&> |
4018 | The &%-q%& option may be followed by one or more flag letters that change its | |
168e428f PH |
4019 | behaviour. They are all optional, but if more than one is present, they must |
4020 | appear in the correct order. Each flag is described in a separate item below. | |
4021 | ||
9b371988 PH |
4022 | .vitem &%-qq...%& |
4023 | .oindex "&%-qq%&" | |
4024 | .cindex "queue" "double scanning" | |
4025 | .cindex "queue" "routing" | |
4026 | .cindex "routing" "whole queue before delivery" | |
4027 | An option starting with &%-qq%& requests a two-stage queue run. In the first | |
4028 | stage, the queue is scanned as if the &%queue_smtp_domains%& option matched | |
168e428f PH |
4029 | every domain. Addresses are routed, local deliveries happen, but no remote |
4030 | transports are run. | |
9b371988 PH |
4031 | |
4032 | .cindex "hints database" "remembering routing" | |
4033 | The hints database that remembers which messages are waiting for specific hosts | |
4034 | is updated, as if delivery to those hosts had been deferred. After this is | |
168e428f PH |
4035 | complete, a second, normal queue scan happens, with routing and delivery taking |
4036 | place as normal. Messages that are routed to the same host should mostly be | |
4037 | delivered down a single SMTP | |
9b371988 PH |
4038 | .cindex "SMTP" "passed connection" |
4039 | .cindex "SMTP" "multiple deliveries" | |
4040 | .cindex "multiple SMTP deliveries" | |
168e428f PH |
4041 | connection because of the hints that were set up during the first queue scan. |
4042 | This option may be useful for hosts that are connected to the Internet | |
4043 | intermittently. | |
4044 | ||
9b371988 PH |
4045 | .vitem &%-q[q]i...%& |
4046 | .oindex "&%-qi%&" | |
4047 | .cindex "queue" "initial delivery" | |
4048 | If the &'i'& flag is present, the queue runner runs delivery processes only for | |
4049 | those messages that haven't previously been tried. (&'i'& stands for &"initial | |
4050 | delivery"&.) This can be helpful if you are putting messages on the queue using | |
4051 | &%-odq%& and want a queue runner just to process the new messages. | |
4052 | ||
4053 | .vitem &%-q[q][i]f...%& | |
4054 | .oindex "&%-qf%&" | |
4055 | .cindex "queue" "forcing delivery" | |
4056 | .cindex "delivery" "forcing in queue run" | |
4057 | If one &'f'& flag is present, a delivery attempt is forced for each non-frozen | |
4058 | message, whereas without &'f'& only those non-frozen addresses that have passed | |
168e428f PH |
4059 | their retry times are tried. |
4060 | ||
9b371988 PH |
4061 | .vitem &%-q[q][i]ff...%& |
4062 | .oindex "&%-qff%&" | |
4063 | .cindex "frozen messages" "forcing delivery" | |
4064 | If &'ff'& is present, a delivery attempt is forced for every message, whether | |
168e428f PH |
4065 | frozen or not. |
4066 | ||
9b371988 PH |
4067 | .vitem &%-q[q][i][f[f]]l%& |
4068 | .oindex "&%-ql%&" | |
4069 | .cindex "queue" "local deliveries only" | |
4070 | The &'l'& (the letter &"ell"&) flag specifies that only local deliveries are to | |
4071 | be done. If a message requires any remote deliveries, it remains on the queue | |
4072 | for later delivery. | |
168e428f | 4073 | |
9b371988 PH |
4074 | .vitem &%-q%&<&'qflags'&>&~<&'start&~id'&>&~<&'end&~id'&> |
4075 | .cindex "queue" "delivering specific messages" | |
168e428f | 4076 | When scanning the queue, Exim can be made to skip over messages whose ids are |
9b371988 PH |
4077 | lexically less than a given value by following the &%-q%& option with a |
4078 | starting message id. For example: | |
4079 | .code | |
4080 | exim -q 0t5C6f-0000c8-00 | |
4081 | .endd | |
4082 | Messages that arrived earlier than &`0t5C6f-0000c8-00`& are not inspected. If a | |
168e428f PH |
4083 | second message id is given, messages whose ids are lexically greater than it |
4084 | are also skipped. If the same id is given twice, for example, | |
9b371988 PH |
4085 | .code |
4086 | exim -q 0t5C6f-0000c8-00 0t5C6f-0000c8-00 | |
4087 | .endd | |
4088 | just one delivery process is started, for that message. This differs from | |
4089 | &%-M%& in that retry data is respected, and it also differs from &%-Mc%& in | |
4090 | that it counts as a delivery from a queue run. Note that the selection | |
4091 | mechanism does not affect the order in which the messages are scanned. There | |
4092 | are also other ways of selecting specific sets of messages for delivery in a | |
4093 | queue run &-- see &%-R%& and &%-S%&. | |
4094 | ||
4095 | .vitem &%-q%&<&'qflags'&><&'time'&> | |
4096 | .cindex "queue runner" "starting periodically" | |
4097 | .cindex "periodic queue running" | |
4098 | When a time value is present, the &%-q%& option causes Exim to run as a daemon, | |
168e428f | 4099 | starting a queue runner process at intervals specified by the given time value |
9b371988 PH |
4100 | (whose format is described in section &<<SECTtimeformat>>&). This form of the |
4101 | &%-q%& option is commonly combined with the &%-bd%& option, in which case a | |
4102 | single daemon process handles both functions. A common way of starting up a | |
4103 | combined daemon at system boot time is to use a command such as | |
4104 | .code | |
4105 | /usr/exim/bin/exim -bd -q30m | |
4106 | .endd | |
168e428f PH |
4107 | Such a daemon listens for incoming SMTP calls, and also starts a queue runner |
4108 | process every 30 minutes. | |
9b371988 PH |
4109 | |
4110 | When a daemon is started by &%-q%& with a time value, but without &%-bd%&, no | |
4111 | pid file is written unless one is explicitly requested by the &%-oP%& option. | |
4112 | ||
4113 | .vitem &%-qR%&<&'rsflags'&>&~<&'string'&> | |
4114 | .oindex "&%-qR%&" | |
4115 | This option is synonymous with &%-R%&. It is provided for Sendmail | |
4116 | compatibility. | |
4117 | ||
4118 | .vitem &%-qS%&<&'rsflags'&>&~<&'string'&> | |
4119 | .oindex "&%-qS%&" | |
4120 | This option is synonymous with &%-S%&. | |
4121 | ||
4122 | .vitem &%-R%&<&'rsflags'&>&~<&'string'&> | |
4123 | .oindex "&%-R%&" | |
4124 | .cindex "queue runner" "for specific recipients" | |
4125 | .cindex "delivery" "to given domain" | |
4126 | .cindex "domain" "delivery to" | |
4127 | The <&'rsflags'&> may be empty, in which case the white space before the string | |
4128 | is optional, unless the string is &'f'&, &'ff'&, &'r'&, &'rf'&, or &'rff'&, | |
4129 | which are the possible values for <&'rsflags'&>. White space is required if | |
4130 | <&'rsflags'&> is not empty. | |
4131 | ||
4132 | This option is similar to &%-q%& with no time value, that is, it causes Exim to | |
168e428f PH |
4133 | perform a single queue run, except that, when scanning the messages on the |
4134 | queue, Exim processes only those that have at least one undelivered recipient | |
4135 | address containing the given string, which is checked in a case-independent | |
9b371988 PH |
4136 | way. If the <&'rsflags'&> start with &'r'&, <&'string'&> is interpreted as a |
4137 | regular expression; otherwise it is a literal string. | |
4138 | ||
168e428f PH |
4139 | Once a message is selected, all its addresses are processed. For the first |
4140 | selected message, Exim overrides any retry information and forces a delivery | |
4141 | attempt for each undelivered address. This means that if delivery of any | |
4142 | address in the first message is successful, any existing retry information is | |
4143 | deleted, and so delivery attempts for that address in subsequently selected | |
4144 | messages (which are processed without forcing) will run. However, if delivery | |
4145 | of any address does not succeed, the retry information is updated, and in | |
4146 | subsequently selected messages, the failing address will be skipped. | |
9b371988 PH |
4147 | |
4148 | .cindex "frozen messages" "forcing delivery" | |
4149 | If the <&'rsflags'&> contain &'f'& or &'ff'&, the delivery forcing applies to | |
4150 | all selected messages, not just the first; frozen messages are included when | |
4151 | &'ff'& is present. | |
4152 | ||
4153 | The &%-R%& option makes it straightforward to initiate delivery of all messages | |
168e428f | 4154 | to a given domain after a host has been down for some time. When the SMTP |
9b371988 PH |
4155 | command ETRN is accepted by its ACL (see chapter &<<CHAPACL>>&), its default |
4156 | effect is to run Exim with the &%-R%& option, but it can be configured to run | |
4157 | an arbitrary command instead. | |
4158 | ||
4159 | .vitem &%-r%& | |
4160 | .oindex "&%-r%&" | |
4161 | This is a documented (for Sendmail) obsolete alternative name for &%-f%&. | |
4162 | ||
4163 | .vitem &%-S%&<&'rsflags'&>&~<&'string'&> | |
4164 | .oindex "&%-S%&" | |
4165 | .cindex "delivery" "from given sender" | |
4166 | .cindex "queue runner" "for specific senders" | |
4167 | This option acts like &%-R%& except that it checks the string against each | |
4168 | message's sender instead of against the recipients. If &%-R%& is also set, both | |
168e428f | 4169 | conditions must be met for a message to be selected. If either of the options |
9b371988 | 4170 | has &'f'& or &'ff'& in its flags, the associated action is taken. |
168e428f | 4171 | |
9b371988 PH |
4172 | .vitem &%-Tqt%&&~<&'times'&> |
4173 | .oindex "&%-Tqt%&" | |
168e428f PH |
4174 | This an option that is exclusively for use by the Exim testing suite. It is not |
4175 | recognized when Exim is run normally. It allows for the setting up of explicit | |
9b371988 PH |
4176 | &"queue times"& so that various warning/retry features can be tested. |
4177 | ||
4178 | .vitem &%-t%& | |
4179 | .new | |
4180 | .oindex "&%-t%&" | |
4181 | .cindex "recipient" "extracting from header lines" | |
4182 | .cindex "&'Bcc:'& header line" | |
4183 | .cindex "&'Cc:'& header line" | |
4184 | .cindex "&'To:'& header line" | |
168e428f | 4185 | When Exim is receiving a locally-generated, non-SMTP message on its standard |
9b371988 PH |
4186 | input, the &%-t%& option causes the recipients of the message to be obtained |
4187 | from the &'To:'&, &'Cc:'&, and &'Bcc:'& header lines in the message instead of | |
4188 | from the command arguments. The addresses are extracted before any rewriting | |
4189 | takes place and the &'Bcc:'& header line, if present, is then removed. | |
4190 | .wen | |
4191 | ||
4192 | .cindex "Sendmail compatibility" "&%-t%& option" | |
4193 | If the command has any arguments, they specify addresses to which the message | |
4194 | is &'not'& to be delivered. That is, the argument addresses are removed from | |
168e428f PH |
4195 | the recipients list obtained from the headers. This is compatible with Smail 3 |
4196 | and in accordance with the documented behaviour of several versions of | |
4197 | Sendmail, as described in man pages on a number of operating systems (e.g. | |
9b371988 | 4198 | Solaris 8, IRIX 6.5, HP-UX 11). However, some versions of Sendmail &'add'& |
168e428f PH |
4199 | argument addresses to those obtained from the headers, and the O'Reilly |
4200 | Sendmail book documents it that way. Exim can be made to add argument addresses | |
4201 | instead of subtracting them by setting the option | |
9b371988 PH |
4202 | &%extract_addresses_remove_arguments%& false. |
4203 | ||
4204 | .cindex "&%Resent-%& header lines" "with &%-t%&" | |
4205 | If there are any &%Resent-%& header lines in the message, Exim extracts | |
4206 | recipients from all &'Resent-To:'&, &'Resent-Cc:'&, and &'Resent-Bcc:'& header | |
4207 | lines instead of from &'To:'&, &'Cc:'&, and &'Bcc:'&. This is for compatibility | |
168e428f | 4208 | with Sendmail and other MTAs. (Prior to release 4.20, Exim gave an error if |
9b371988 PH |
4209 | &%-t%& was used in conjunction with &%Resent-%& header lines.) |
4210 | ||
4211 | RFC 2822 talks about different sets of &%Resent-%& header lines (for when a | |
168e428f | 4212 | message is resent several times). The RFC also specifies that they should be |
9b371988 PH |
4213 | added at the front of the message, and separated by &'Received:'& lines. It is |
4214 | not at all clear how &%-t%& should operate in the present of multiple sets, | |
4215 | nor indeed exactly what constitutes a &"set"&. | |
4216 | In practice, it seems that MUAs do not follow the RFC. The &%Resent-%& lines | |
4217 | are often added at the end of the header, and if a message is resent more than | |
4218 | once, it is common for the original set of &%Resent-%& headers to be renamed as | |
4219 | &%X-Resent-%& when a new set is added. This removes any possible ambiguity. | |
4220 | ||
4221 | .vitem &*-ti*& | |
4222 | .oindex "&%-ti%&" | |
4223 | This option is exactly equivalent to &%-t%& &%-i%&. It is provided for | |
168e428f PH |
4224 | compatibility with Sendmail. |
4225 | ||
9b371988 PH |
4226 | .vitem &*-tls-on-connect*& |
4227 | .oindex "&%-tls-on-connect%&" | |
4228 | .cindex "TLS" "use without STARTTLS" | |
4229 | .cindex "TLS" "automatic start" | |
168e428f PH |
4230 | This option is available when Exim is compiled with TLS support. It forces all |
4231 | incoming SMTP connections to behave as if the incoming port is listed in the | |
9b371988 PH |
4232 | &%tls_on_connect_ports%& option. See section &<<SECTsupobssmt>>& and chapter |
4233 | &<<CHAPTLS>>& for further details. | |
168e428f PH |
4234 | |
4235 | ||
9b371988 PH |
4236 | .vitem &*-U*& |
4237 | .oindex "&%-U%&" | |
4238 | .cindex "Sendmail compatibility" "&%-U%& option ignored" | |
4239 | Sendmail uses this option for &"initial message submission"&, and its | |
168e428f PH |
4240 | documentation states that in future releases, it may complain about |
4241 | syntactically invalid messages rather than fixing them when this flag is not | |
4242 | set. Exim ignores this option. | |
4243 | ||
9b371988 PH |
4244 | .vitem &*-v*& |
4245 | .oindex "&%-v%&" | |
168e428f PH |
4246 | This option causes Exim to write information to the standard error stream, |
4247 | describing what it is doing. In particular, it shows the log lines for | |
4248 | receiving and delivering a message, and if an SMTP connection is made, the SMTP | |
4249 | dialogue is shown. Some of the log lines shown may not actually be written to | |
9b371988 PH |
4250 | the log if the setting of &%log_selector%& discards them. Any relevant |
4251 | selectors are shown with each log line. If none are shown, the logging is | |
4252 | unconditional. | |
4253 | ||
4254 | .vitem &*-x*& | |
4255 | .oindex "&%-x%&" | |
4256 | AIX uses &%-x%& for a private purpose (&"mail from a local mail program has | |
4257 | National Language Support extended characters in the body of the mail item"&). | |
4258 | It sets &%-x%& when calling the MTA from its &%mail%& command. Exim ignores | |
4259 | this option. | |
4260 | .endlist | |
4261 | ||
4262 | . //////////////////////////////////////////////////////////////////////////// | |
4263 | . Insert a stylized DocBook comment here, to identify the end of the command | |
4264 | . line options. This is for the benefit of the Perl script that automatically | |
4265 | . creates a man page for the options. | |
4266 | . //////////////////////////////////////////////////////////////////////////// | |
4267 | ||
4268 | .literal xml | |
168e428f | 4269 | <!-- === End of command line options === --> |
9b371988 | 4270 | .literal off |
168e428f PH |
4271 | |
4272 | ||
4273 | ||
4274 | ||
4275 | ||
9b371988 PH |
4276 | . //////////////////////////////////////////////////////////////////////////// |
4277 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f PH |
4278 | |
4279 | ||
9b371988 PH |
4280 | .chapter "The Exim run time configuration file" "CHAPconf" &&& |
4281 | "The runtime configuration file" | |
168e428f | 4282 | |
9b371988 PH |
4283 | .cindex "run time configuration" |
4284 | .cindex "configuration file" "general description" | |
4285 | .cindex "CONFIGURE_FILE" | |
4286 | .cindex "configuration file" "errors in" | |
4287 | .cindex "error" "in configuration file" | |
4288 | .cindex "return code" "for bad configuration" | |
168e428f PH |
4289 | Exim uses a single run time configuration file that is read whenever an Exim |
4290 | binary is executed. Note that in normal operation, this happens frequently, | |
4291 | because Exim is designed to operate in a distributed manner, without central | |
4292 | control. | |
4293 | ||
4294 | If a syntax error is detected while reading the configuration file, Exim | |
4295 | writes a message on the standard error, and exits with a non-zero return code. | |
9b371988 | 4296 | The message is also written to the panic log. &*Note*&: Only simple syntax |
168e428f PH |
4297 | errors can be detected at this time. The values of any expanded options are |
4298 | not checked until the expansion happens, even when the expansion does not | |
4299 | actually alter the string. | |
4300 | ||
168e428f PH |
4301 | The name of the configuration file is compiled into the binary for security |
4302 | reasons, and is specified by the CONFIGURE_FILE compilation option. In | |
4303 | most configurations, this specifies a single file. However, it is permitted to | |
4304 | give a colon-separated list of file names, in which case Exim uses the first | |
4305 | existing file in the list. | |
4306 | ||
9b371988 PH |
4307 | .cindex "EXIM_USER" |
4308 | .cindex "EXIM_GROUP" | |
4309 | .cindex "CONFIGURE_OWNER" | |
4310 | .cindex "CONFIGURE_GROUP" | |
4311 | .cindex "configuration file" "ownership" | |
4312 | .cindex "ownership" "configuration file" | |
168e428f PH |
4313 | The run time configuration file must be owned by root or by the user that is |
4314 | specified at compile time by the EXIM_USER option, or by the user that is | |
4315 | specified at compile time by the CONFIGURE_OWNER option (if set). The | |
4316 | configuration file must not be world-writeable or group-writeable, unless its | |
9b371988 PH |
4317 | group is the one specified at compile time by the EXIM_GROUP option or by the |
4318 | CONFIGURE_GROUP option. | |
168e428f | 4319 | |
9b371988 | 4320 | &*Warning*&: In a conventional configuration, where the Exim binary is setuid |
168e428f PH |
4321 | to root, anybody who is able to edit the run time configuration file has an |
4322 | easy way to run commands as root. If you make your mail administrators members | |
4323 | of the Exim group, but do not trust them with root, make sure that the run time | |
4324 | configuration is not group writeable. | |
4325 | ||
4326 | A default configuration file, which will work correctly in simple situations, | |
9b371988 | 4327 | is provided in the file &_src/configure.default_&. If CONFIGURE_FILE |
168e428f PH |
4328 | defines just one file name, the installation process copies the default |
4329 | configuration to a new file of that name if it did not previously exist. If | |
4330 | CONFIGURE_FILE is a list, no default is automatically installed. Chapter | |
9b371988 PH |
4331 | &<<CHAPdefconfil>>& is a &"walk-through"& discussion of the default |
4332 | configuration. | |
168e428f PH |
4333 | |
4334 | ||
4335 | ||
9b371988 PH |
4336 | .section "Using a different configuration file" |
4337 | .cindex "configuration file" "alternate" | |
4338 | A one-off alternate configuration can be specified by the &%-C%& command line | |
4339 | option, which may specify a single file or a list of files. However, when | |
4340 | &%-C%& is used, Exim gives up its root privilege, unless called by root or the | |
4341 | Exim user (or unless the argument for &%-C%& is identical to the built-in value | |
4342 | from CONFIGURE_FILE). &%-C%& is useful mainly for checking the syntax of | |
168e428f | 4343 | configuration files before installing them. No owner or group checks are done |
9b371988 | 4344 | on a configuration file specified by &%-C%&. |
168e428f | 4345 | |
9b371988 PH |
4346 | The privileged use of &%-C%& by the Exim user can be locked out by setting |
4347 | ALT_CONFIG_ROOT_ONLY in &_Local/Makefile_& when building Exim. However, | |
168e428f | 4348 | if you do this, you also lock out the possibility of testing a |
9b371988 PH |
4349 | configuration using &%-C%& right through message reception and delivery, even |
4350 | if the caller is root. The reception works, but by that time, Exim is running | |
4351 | as the Exim user, so when it re-execs to regain privilege for the delivery, the | |
4352 | use of &%-C%& causes privilege to be lost. However, root can test reception and | |
168e428f | 4353 | delivery using two separate commands (one to put a message on the queue, using |
9b371988 | 4354 | &%-odq%&, and another to do the delivery, using &%-M%&). |
168e428f | 4355 | |
9b371988 PH |
4356 | If ALT_CONFIG_PREFIX is defined &_in Local/Makefile_&, it specifies a |
4357 | prefix string with which any file named in a &%-C%& command line option must | |
4358 | start. In addition, the file name must not contain the sequence &"&`/../`&"&. | |
068aaea8 | 4359 | There is no default setting for ALT_CONFIG_PREFIX; when it is unset, any file |
9b371988 | 4360 | name can be used with &%-C%&. |
168e428f | 4361 | |
9b371988 | 4362 | One-off changes to a configuration can be specified by the &%-D%& command line |
168e428f | 4363 | option, which defines and overrides values for macros used inside the |
9b371988 | 4364 | configuration file. However, like &%-C%&, the use of this option by a |
168e428f | 4365 | non-privileged user causes Exim to discard its root privilege. |
9b371988 | 4366 | If DISABLE_D_OPTION is defined in &_Local/Makefile_&, the use of &%-D%& is |
168e428f PH |
4367 | completely disabled, and its use causes an immediate error exit. |
4368 | ||
4369 | Some sites may wish to use the same Exim binary on different machines that | |
4370 | share a file system, but to use different configuration files on each machine. | |
9b371988 | 4371 | If CONFIGURE_FILE_USE_NODE is defined in &_Local/Makefile_&, Exim first |
168e428f | 4372 | looks for a file whose name is the configuration file name followed by a dot |
9b371988 | 4373 | and the machine's node name, as obtained from the &[uname()]& function. If this |
168e428f | 4374 | file does not exist, the standard name is tried. This processing occurs for |
9b371988 | 4375 | each file name in the list given by CONFIGURE_FILE or &%-C%&. |
168e428f PH |
4376 | |
4377 | In some esoteric situations different versions of Exim may be run under | |
4378 | different effective uids and the CONFIGURE_FILE_USE_EUID is defined to | |
9b371988 | 4379 | help with this. See the comments in &_src/EDITME_& for details. |
168e428f PH |
4380 | |
4381 | ||
4382 | ||
9b371988 PH |
4383 | .section "Configuration file format" "SECTconffilfor" |
4384 | .cindex "configuration file" "format of" | |
4385 | .cindex "format" "configuration file" | |
168e428f PH |
4386 | Exim's configuration file is divided into a number of different parts. General |
4387 | option settings must always appear at the start of the file. The other parts | |
4388 | are all optional, and may appear in any order. Each part other than the first | |
9b371988 | 4389 | is introduced by the word &"begin"& followed by the name of the part. The |
168e428f PH |
4390 | optional parts are: |
4391 | ||
9b371988 PH |
4392 | .ilist |
4393 | &'ACL'&: Access control lists for controlling incoming SMTP mail. | |
4394 | .next | |
4395 | .cindex "AUTH" "configuration" | |
4396 | &'authenticators'&: Configuration settings for the authenticator drivers. These | |
4397 | are concerned with the SMTP AUTH command (see chapter &<<CHAPSMTPAUTH>>&). | |
4398 | .next | |
4399 | &'routers'&: Configuration settings for the router drivers. Routers process | |
168e428f | 4400 | addresses and determine how the message is to be delivered. |
9b371988 PH |
4401 | .next |
4402 | &'transports'&: Configuration settings for the transport drivers. Transports | |
168e428f | 4403 | define mechanisms for copying messages to destinations. |
9b371988 PH |
4404 | .next |
4405 | &'retry'&: Retry rules, for use when a message cannot be immediately delivered. | |
4406 | .next | |
4407 | &'rewrite'&: Global address rewriting rules, for use when a message arrives and | |
168e428f | 4408 | when new addresses are generated during delivery. |
9b371988 PH |
4409 | .next |
4410 | &'local_scan'&: Private options for the &[local_scan()]& function. If you | |
168e428f | 4411 | want to use this feature, you must set |
9b371988 PH |
4412 | .code |
4413 | LOCAL_SCAN_HAS_OPTIONS=yes | |
4414 | .endd | |
4415 | in &_Local/Makefile_& before building Exim. Full details of the | |
4416 | &[local_scan()]& facility are given in chapter &<<CHAPlocalscan>>&. | |
4417 | .endlist | |
4418 | ||
4419 | .cindex "configuration file" "leading white space in" | |
4420 | .cindex "configuration file" "trailing white space in" | |
4421 | .cindex "white space" "in configuration file" | |
068aaea8 | 4422 | Leading and trailing white space in configuration lines is always ignored. |
168e428f PH |
4423 | |
4424 | Blank lines in the file, and lines starting with a # character (ignoring | |
9b371988 | 4425 | leading white space) are treated as comments and are ignored. &*Note*&: A |
168e428f PH |
4426 | # character other than at the beginning of a line is not treated specially, |
4427 | and does not introduce a comment. | |
4428 | ||
4429 | Any non-comment line can be continued by ending it with a backslash. Note that | |
068aaea8 PH |
4430 | the general rule for white space means that trailing white space after the |
4431 | backslash and leading white space at the start of continuation | |
4432 | lines is ignored. Comment lines beginning with # (but not empty lines) may | |
168e428f PH |
4433 | appear in the middle of a sequence of continuation lines. |
4434 | ||
4435 | A convenient way to create a configuration file is to start from the | |
9b371988 | 4436 | default, which is supplied in &_src/configure.default_&, and add, delete, or |
168e428f PH |
4437 | change settings as required. |
4438 | ||
4439 | The ACLs, retry rules, and rewriting rules have their own syntax which is | |
9b371988 | 4440 | described in chapters &<<CHAPACL>>&, &<<CHAPretry>>&, and &<<CHAPrewrite>>&, |
168e428f | 4441 | respectively. The other parts of the configuration file have some syntactic |
9b371988 | 4442 | items in common, and these are described below, from section &<<SECTcos>>& |
168e428f PH |
4443 | onwards. Before that, the inclusion, macro, and conditional facilities are |
4444 | described. | |
4445 | ||
4446 | ||
4447 | ||
9b371988 PH |
4448 | .section "File inclusions in the configuration file" |
4449 | .cindex "inclusions in configuration file" | |
4450 | .cindex "configuration file" "including other files" | |
4451 | .cindex ".include in configuration file" | |
4452 | .cindex ".include_if_exists in configuration file" | |
168e428f PH |
4453 | You can include other files inside Exim's run time configuration file by |
4454 | using this syntax: | |
9b371988 PH |
4455 | .display |
4456 | &`.include`& <&'file name'&> | |
4457 | &`.include_if_exists`& <&'file name'&> | |
4458 | .endd | |
168e428f PH |
4459 | on a line by itself. Double quotes round the file name are optional. If you use |
4460 | the first form, a configuration error occurs if the file does not exist; the | |
4461 | second form does nothing for non-existent files. | |
4462 | ||
4463 | Includes may be nested to any depth, but remember that Exim reads its | |
4464 | configuration file often, so it is a good idea to keep them to a minimum. | |
4465 | If you change the contents of an included file, you must HUP the daemon, | |
4466 | because an included file is read only when the configuration itself is read. | |
4467 | ||
4468 | The processing of inclusions happens early, at a physical line level, so, like | |
4469 | comment lines, an inclusion can be used in the middle of an option setting, | |
4470 | for example: | |
9b371988 | 4471 | .code |
168e428f PH |
4472 | hosts_lookup = a.b.c \ |
4473 | .include /some/file | |
9b371988 | 4474 | .endd |
168e428f PH |
4475 | Include processing happens after macro processing (see below). Its effect is to |
4476 | process the lines of the file as if they occurred inline where the inclusion | |
4477 | appears. | |
4478 | ||
4479 | ||
4480 | ||
9b371988 PH |
4481 | .section "Macros in the configuration file" "SECTmacrodefs" |
4482 | .cindex "macro" "description of" | |
4483 | .cindex "configuration file" "macros" | |
168e428f | 4484 | If a line in the main part of the configuration (that is, before the first |
9b371988 | 4485 | &"begin"& line) begins with an upper case letter, it is taken as a macro |
168e428f | 4486 | definition, and must be of the form |
9b371988 PH |
4487 | .display |
4488 | <&'name'&> = <&'rest of line'&> | |
4489 | .endd | |
168e428f PH |
4490 | The name must consist of letters, digits, and underscores, and need not all be |
4491 | in upper case, though that is recommended. The rest of the line, including any | |
4492 | continuations, is the replacement text, and has leading and trailing white | |
4493 | space removed. Quotes are not removed. The replacement text can never end with | |
4494 | a backslash character, but this doesn't seem to be a serious limitation. | |
4495 | ||
9b371988 | 4496 | .new |
068aaea8 PH |
4497 | Macros may also be defined between router, transport, authenticator, or ACL |
4498 | definitions. They may not, however, be defined within an individual driver or | |
9b371988 PH |
4499 | ACL, or in the &%local_scan%&, retry, or rewrite sections of the configuration. |
4500 | .wen | |
068aaea8 | 4501 | |
9b371988 | 4502 | .section "Macro substitution" |
168e428f PH |
4503 | Once a macro is defined, all subsequent lines in the file (and any included |
4504 | files) are scanned for the macro name; if there are several macros, the line is | |
068aaea8 | 4505 | scanned for each in turn, in the order in which the macros are defined. The |
168e428f PH |
4506 | replacement text is not re-scanned for the current macro, though it is scanned |
4507 | for subsequently defined macros. For this reason, a macro name may not contain | |
4508 | the name of a previously defined macro as a substring. You could, for example, | |
4509 | define | |
9b371988 PH |
4510 | .display |
4511 | &`ABCD_XYZ = `&<&'something'&> | |
4512 | &`ABCD = `&<&'something else'&> | |
4513 | .endd | |
168e428f | 4514 | but putting the definitions in the opposite order would provoke a configuration |
068aaea8 PH |
4515 | error. Macro expansion is applied to individual physical lines from the file, |
4516 | before checking for line continuation or file inclusion (see above). If a line | |
4517 | consists solely of a macro name, and the expansion of the macro is empty, the | |
4518 | line is ignored. A macro at the start of a line may turn the line into a | |
9b371988 | 4519 | comment line or a &`.include`& line. |
068aaea8 PH |
4520 | |
4521 | ||
9b371988 PH |
4522 | .new |
4523 | .section "Redefining macros" | |
068aaea8 | 4524 | Once defined, the value of a macro can be redefined later in the configuration |
9b371988 PH |
4525 | (or in an included file). Redefinition is specified by using &'=='& instead of |
4526 | &'='&. For example: | |
4527 | .code | |
4528 | MAC = initial value | |
4529 | ... | |
4530 | MAC == updated value | |
4531 | .endd | |
4532 | Redefinition does not alter the order in which the macros are applied to the | |
4533 | subsequent lines of the configuration file. It is still the same order in which | |
4534 | the macros were originally defined. All that changes is the macro's value. | |
4535 | Redefinition makes it possible to accumulate values. For example: | |
4536 | .code | |
4537 | MAC = initial value | |
4538 | ... | |
4539 | MAC == MAC and something added | |
4540 | .endd | |
068aaea8 PH |
4541 | This can be helpful in situations where the configuration file is built |
4542 | from a number of other files. | |
9b371988 | 4543 | .wen |
068aaea8 | 4544 | |
9b371988 | 4545 | .section "Overriding macro values" |
068aaea8 | 4546 | The values set for macros in the configuration file can be overridden by the |
9b371988 | 4547 | &%-D%& command line option, but Exim gives up its root privilege when &%-D%& is |
068aaea8 | 4548 | used, unless called by root or the Exim user. A definition on the command line |
9b371988 PH |
4549 | using the &%-D%& option causes all definitions and redefinitions within the |
4550 | file to be ignored. | |
068aaea8 | 4551 | |
168e428f | 4552 | |
168e428f | 4553 | |
9b371988 | 4554 | .section "Example of macro usage" |
168e428f PH |
4555 | As an example of macro usage, consider a configuration where aliases are looked |
4556 | up in a MySQL database. It helps to keep the file less cluttered if long | |
4557 | strings such as SQL statements are defined separately as macros, for example: | |
9b371988 | 4558 | .code |
168e428f PH |
4559 | ALIAS_QUERY = select mailbox from user where \ |
4560 | login=${quote_mysql:$local_part}; | |
9b371988 PH |
4561 | .endd |
4562 | This can then be used in a &(redirect)& router setting like this: | |
4563 | .code | |
4564 | data = ${lookup mysql{ALIAS_QUERY}} | |
4565 | .endd | |
168e428f | 4566 | In earlier versions of Exim macros were sometimes used for domain, host, or |
9b371988 PH |
4567 | address lists. In Exim 4 these are handled better by named lists &-- see |
4568 | section &<<SECTnamedlists>>&. | |
168e428f | 4569 | |
168e428f | 4570 | |
9b371988 PH |
4571 | .section "Conditional skips in the configuration file" |
4572 | .cindex "configuration file" "conditional skips" | |
4573 | .cindex ".ifdef" | |
4574 | You can use the directives &`.ifdef`&, &`.ifndef`&, &`.elifdef`&, | |
4575 | &`.elifndef`&, &`.else`&, and &`.endif`& to dynamically include or exclude | |
168e428f PH |
4576 | portions of the configuration file. The processing happens whenever the file is |
4577 | read (that is, when an Exim binary starts to run). | |
4578 | ||
4579 | The implementation is very simple. Instances of the first four directives must | |
4580 | be followed by text that includes the names of one or macros. The condition | |
4581 | that is tested is whether or not any macro substitution has taken place in the | |
4582 | line. Thus: | |
9b371988 PH |
4583 | .code |
4584 | .ifdef AAA | |
4585 | message_size_limit = 50M | |
4586 | .else | |
4587 | message_size_limit = 100M | |
4588 | .endif | |
4589 | .endd | |
4590 | sets a message size limit of 50M if the macro &`AAA`& is defined, and 100M | |
168e428f | 4591 | otherwise. If there is more than one macro named on the line, the condition |
9b371988 PH |
4592 | is true if any of them are defined. That is, it is an &"or"& condition. To |
4593 | obtain an &"and"& condition, you need to use nested &`.ifdef`&s. | |
168e428f PH |
4594 | |
4595 | Although you can use a macro expansion to generate one of these directives, | |
9b371988 PH |
4596 | it is not very useful, because the condition &"there was a macro substitution |
4597 | in this line"& will always be true. | |
168e428f | 4598 | |
9b371988 | 4599 | Text following &`.else`& and &`.endif`& is ignored, and can be used as comment |
168e428f PH |
4600 | to clarify complicated nestings. |
4601 | ||
4602 | ||
4603 | ||
9b371988 PH |
4604 | .section "Common option syntax" "SECTcos" |
4605 | .cindex "common option syntax" | |
4606 | .cindex "syntax of common options" | |
4607 | .cindex "configuration file" "common option syntax" | |
4608 | For the main set of options, driver options, and &[local_scan()]& options, | |
168e428f PH |
4609 | each setting is on a line by itself, and starts with a name consisting of |
4610 | lower-case letters and underscores. Many options require a data value, and in | |
4611 | these cases the name must be followed by an equals sign (with optional white | |
4612 | space) and then the value. For example: | |
9b371988 PH |
4613 | .code |
4614 | qualify_domain = mydomain.example.com | |
4615 | .endd | |
168e428f | 4616 | Some option settings may contain sensitive data, for example, passwords for |
9b371988 PH |
4617 | accessing databases. To stop non-admin users from using the &%-bP%& command |
4618 | line option to read these values, you can precede the option settings with the | |
4619 | word &"hide"&. For example: | |
4620 | .code | |
4621 | hide mysql_servers = localhost/users/admin/secret-password | |
4622 | .endd | |
168e428f | 4623 | For non-admin users, such options are displayed like this: |
9b371988 PH |
4624 | .code |
4625 | mysql_servers = <value not displayable> | |
4626 | .endd | |
4627 | If &"hide"& is used on a driver option, it hides the value of that option on | |
4628 | all instances of the same driver. | |
168e428f PH |
4629 | |
4630 | The following sections describe the syntax used for the different data types | |
4631 | that are found in option settings. | |
4632 | ||
4633 | ||
9b371988 PH |
4634 | .section "Boolean options" |
4635 | .cindex "format" "boolean" | |
4636 | .cindex "boolean configuration values" | |
4637 | .oindex "&%no_%&&'xxx'&" | |
4638 | .oindex "&%not_%&&'xxx'&" | |
168e428f PH |
4639 | Options whose type is given as boolean are on/off switches. There are two |
4640 | different ways of specifying such options: with and without a data value. If | |
4641 | the option name is specified on its own without data, the switch is turned on; | |
9b371988 | 4642 | if it is preceded by &"no_"& or &"not_"& the switch is turned off. However, |
068aaea8 | 4643 | boolean options may be followed by an equals sign and one of the words |
9b371988 | 4644 | &"true"&, &"false"&, &"yes"&, or &"no"&, as an alternative syntax. For example, |
168e428f | 4645 | the following two settings have exactly the same effect: |
9b371988 PH |
4646 | .code |
4647 | queue_only | |
4648 | queue_only = true | |
4649 | .endd | |
168e428f | 4650 | The following two lines also have the same (opposite) effect: |
9b371988 PH |
4651 | .code |
4652 | no_queue_only | |
4653 | queue_only = false | |
4654 | .endd | |
168e428f PH |
4655 | You can use whichever syntax you prefer. |
4656 | ||
4657 | ||
4658 | ||
4659 | ||
9b371988 PH |
4660 | .section "Integer values" |
4661 | .cindex "integer configuration values" | |
4662 | .cindex "format" "integer" | |
4663 | If an integer data item starts with the characters &"0x"&, the remainder of it | |
168e428f PH |
4664 | is interpreted as a hexadecimal number. Otherwise, it is treated as octal if it |
4665 | starts with the digit 0, and decimal if not. If an integer value is followed by | |
4666 | the letter K, it is multiplied by 1024; if it is followed by the letter M, it | |
4667 | is multiplied by 1024x1024. | |
4668 | ||
4669 | When the values of integer option settings are output, values which are an | |
4670 | exact multiple of 1024 or 1024x1024 are | |
4671 | sometimes, but not always, | |
4672 | printed using the letters K and M. The printing style is independent of the | |
4673 | actual input format that was used. | |
4674 | ||
4675 | ||
9b371988 PH |
4676 | .section "Octal integer values" |
4677 | .cindex "integer format" | |
4678 | .cindex "format" "octal integer" | |
168e428f PH |
4679 | The value of an option specified as an octal integer is always interpreted in |
4680 | octal, whether or not it starts with the digit zero. Such options are always | |
4681 | output in octal. | |
4682 | ||
4683 | ||
4684 | ||
9b371988 PH |
4685 | .section "Fixed point number values" |
4686 | .cindex "fixed point configuration values" | |
4687 | .cindex "format" "fixed point" | |
168e428f PH |
4688 | A fixed point number consists of a decimal integer, optionally followed by a |
4689 | decimal point and up to three further digits. | |
4690 | ||
4691 | ||
4692 | ||
9b371988 PH |
4693 | .section "Time interval values" "SECTtimeformat" |
4694 | .cindex "time interval" "specifying in configuration" | |
4695 | .cindex "format" "time interval" | |
168e428f PH |
4696 | A time interval is specified as a sequence of numbers, each followed by one of |
4697 | the following letters, with no intervening white space: | |
4698 | ||
9b371988 PH |
4699 | .table2 50pt |
4700 | .row &~&%s%& seconds | |
4701 | .row &~&%m%& minutes | |
4702 | .row &~&%h%& hours | |
4703 | .row &~&%d%& days | |
4704 | .row &~&%w%& weeks | |
4705 | .endtable | |
168e428f | 4706 | |
9b371988 | 4707 | For example, &"3h50m"& specifies 3 hours and 50 minutes. The values of time |
168e428f | 4708 | intervals are output in the same format. Exim does not restrict the values; it |
9b371988 | 4709 | is perfectly acceptable, for example, to specify &"90m"& instead of &"1h30m"&. |
168e428f PH |
4710 | |
4711 | ||
4712 | ||
9b371988 PH |
4713 | .section "String values" "SECTstrings" |
4714 | .cindex "string" "format of configuration values" | |
4715 | .cindex "format" "string" | |
168e428f PH |
4716 | If a string data item does not start with a double-quote character, it is taken |
4717 | as consisting of the remainder of the line plus any continuation lines, | |
4718 | starting at the first character after any leading white space, with trailing | |
9b371988 PH |
4719 | white space removed, and with no interpretation of the characters in the |
4720 | string. Because Exim removes comment lines (those beginning with #) at an early | |
4721 | stage, they can appear in the middle of a multi-line string. The following | |
4722 | settings are therefore equivalent: | |
4723 | .code | |
168e428f PH |
4724 | trusted_users = uucp:mail |
4725 | ||
4726 | trusted_users = uucp:\ | |
4727 | # This comment line is ignored | |
4728 | ||
9b371988 PH |
4729 | .endd |
4730 | .cindex "string" "quoted" | |
4731 | .cindex "escape characters in quoted strings" | |
168e428f PH |
4732 | If a string does start with a double-quote, it must end with a closing |
4733 | double-quote, and any backslash characters other than those used for line | |
4734 | continuation are interpreted as escape characters, as follows: | |
4735 | ||
9b371988 PH |
4736 | .table2 100pt |
4737 | .row &~&`\\`& "single backslash" | |
4738 | .row &~&`\n`& "newline" | |
4739 | .row &~&`\r`& "carriage return" | |
4740 | .row &~&`\t`& "tab" | |
4741 | .row "&~&`\`&<&'octal digits'&>" "up to 3 octal digits specify one character" | |
4742 | .row "&~&`\x`&<&'hex digits'&>" "up to 2 hexadecimal digits specify one &&& | |
4743 | character" | |
4744 | .endtable | |
168e428f PH |
4745 | |
4746 | If a backslash is followed by some other character, including a double-quote | |
4747 | character, that character replaces the pair. | |
4748 | ||
4749 | Quoting is necessary only if you want to make use of the backslash escapes to | |
4750 | insert special characters, or if you need to specify a value with leading or | |
4751 | trailing spaces. These cases are rare, so quoting is almost never needed in | |
4752 | current versions of Exim. In versions of Exim before 3.14, quoting was required | |
4753 | in order to continue lines, so you may come across older configuration files | |
4754 | and examples that apparently quote unnecessarily. | |
4755 | ||
4756 | ||
9b371988 PH |
4757 | .section "Expanded strings" |
4758 | .cindex "string expansion" "definition of" | |
4759 | .cindex "expansion" "definition of" | |
4760 | Some strings in the configuration file are subjected to &'string expansion'&, | |
168e428f | 4761 | by which means various parts of the string may be changed according to the |
9b371988 PH |
4762 | circumstances (see chapter &<<CHAPexpand>>&). The input syntax for such strings |
4763 | is as just described; in particular, the handling of backslashes in quoted | |
4764 | strings is done as part of the input process, before expansion takes place. | |
4765 | However, backslash is also an escape character for the expander, so any | |
4766 | backslashes that are required for that reason must be doubled if they are | |
4767 | within a quoted configuration string. | |
4768 | ||
4769 | ||
4770 | .section "User and group names" | |
4771 | .cindex "user name" "format of" | |
4772 | .cindex "format" "user name" | |
4773 | .cindex "group" "name format" | |
4774 | .cindex "format" "group name" | |
168e428f PH |
4775 | User and group names are specified as strings, using the syntax described |
4776 | above, but the strings are interpreted specially. A user or group name must | |
4777 | either consist entirely of digits, or be a name that can be looked up using the | |
9b371988 | 4778 | &[getpwnam()]& or &[getgrnam()]& function, as appropriate. |
168e428f PH |
4779 | |
4780 | ||
9b371988 PH |
4781 | .section "List construction" "SECTlistconstruct" |
4782 | .cindex "list" "syntax of in configuration" | |
4783 | .cindex "format" "list item in configuration" | |
4784 | .cindex "string list" "definition" | |
168e428f | 4785 | The data for some configuration options is a list of items, with colon as the |
9b371988 PH |
4786 | default separator. Many of these options are shown with type &"string list"& in |
4787 | the descriptions later in this document. Others are listed as &"domain list"&, | |
4788 | &"host list"&, &"address list"&, or &"local part list"&. Syntactically, they | |
4789 | are all the same; however, those other than &"string list"& are subject to | |
068aaea8 | 4790 | particular kinds of interpretation, as described in chapter |
9b371988 | 4791 | &<<CHAPdomhosaddlists>>&. |
168e428f PH |
4792 | |
4793 | In all these cases, the entire list is treated as a single string as far as the | |
9b371988 PH |
4794 | input syntax is concerned. The &%trusted_users%& setting in section |
4795 | &<<SECTstrings>>& above is an example. If a colon is actually needed in an item | |
4796 | in a list, it must be entered as two colons. Leading and trailing white space | |
4797 | on each item in a list is ignored. This makes it possible to include items that | |
168e428f PH |
4798 | start with a colon, and in particular, certain forms of IPv6 address. For |
4799 | example, the list | |
9b371988 PH |
4800 | .code |
4801 | local_interfaces = 127.0.0.1 : ::::1 | |
4802 | .endd | |
068aaea8 PH |
4803 | contains two IP addresses, the IPv4 address 127.0.0.1 and the IPv6 address ::1. |
4804 | ||
9b371988 PH |
4805 | .new |
4806 | &*Note*&: Although leading and trailing white space is ignored in individual | |
4807 | list items, it is not ignored when parsing the list. The space after the first | |
4808 | colon in the example above is necessary. If it were not there, the list would | |
4809 | be interpreted as the two items 127.0.0.1:: and 1. | |
4810 | .wen | |
168e428f | 4811 | |
9b371988 PH |
4812 | .cindex "list separator" "changing" |
4813 | .cindex "IPv6" "addresses in lists" | |
168e428f PH |
4814 | Doubling colons in IPv6 addresses is an unwelcome chore, so a mechanism was |
4815 | introduced to allow the separator character to be changed. If a list begins | |
4816 | with a left angle bracket, followed by any punctuation character, that | |
4817 | character is used instead of colon as the list separator. For example, the list | |
4818 | above can be rewritten to use a semicolon separator like this: | |
9b371988 PH |
4819 | .code |
4820 | local_interfaces = <; 127.0.0.1 ; ::1 | |
4821 | .endd | |
168e428f | 4822 | This facility applies to all lists, with the exception of the list in |
9b371988 | 4823 | &%log_file_path%&. It is recommended that the use of non-colon separators be |
168e428f PH |
4824 | confined to circumstances where they really are needed. |
4825 | ||
4826 | ||
4827 | ||
9b371988 PH |
4828 | .section "Empty items in lists" "SECTempitelis" |
4829 | .cindex "list" "empty item in" | |
168e428f PH |
4830 | An empty item at the end of a list is always ignored. In other words, trailing |
4831 | separator characters are ignored. Thus, the list in | |
9b371988 PH |
4832 | .code |
4833 | senders = user@domain : | |
4834 | .endd | |
168e428f PH |
4835 | contains only a single item. If you want to include an empty string as one item |
4836 | in a list, it must not be the last item. For example, this list contains three | |
4837 | items, the second of which is empty: | |
9b371988 PH |
4838 | .code |
4839 | senders = user1@domain : : user2@domain | |
4840 | .endd | |
4841 | &*Note*&: There must be white space between the two colons, as otherwise they | |
168e428f PH |
4842 | are interpreted as representing a single colon data character (and the list |
4843 | would then contain just one item). If you want to specify a list that contains | |
4844 | just one, empty item, you can do it as in this example: | |
9b371988 PH |
4845 | .code |
4846 | senders = : | |
4847 | .endd | |
168e428f PH |
4848 | In this case, the first item is empty, and the second is discarded because it |
4849 | is at the end of the list. | |
4850 | ||
4851 | ||
4852 | ||
4853 | ||
9b371988 PH |
4854 | .section "Format of driver configurations" "SECTfordricon" |
4855 | .cindex "drivers" "configuration format" | |
168e428f PH |
4856 | There are separate parts in the configuration for defining routers, transports, |
4857 | and authenticators. In each part, you are defining a number of driver | |
4858 | instances, each with its own set of options. Each driver instance is defined by | |
4859 | a sequence of lines like this: | |
9b371988 PH |
4860 | .display |
4861 | <&'instance name'&>: | |
4862 | <&'option'&> | |
168e428f | 4863 | ... |
9b371988 PH |
4864 | <&'option'&> |
4865 | .endd | |
4866 | In the following example, the instance name is &(localuser)&, and it is | |
168e428f | 4867 | followed by three options settings: |
9b371988 PH |
4868 | .code |
4869 | localuser: | |
4870 | driver = accept | |
4871 | check_local_user | |
4872 | transport = local_delivery | |
4873 | .endd | |
4874 | For each driver instance, you specify which Exim code module it uses &-- by the | |
4875 | setting of the &%driver%& option &-- and (optionally) some configuration | |
4876 | settings. For example, in the case of transports, if you want a transport to | |
4877 | deliver with SMTP you would use the &(smtp)& driver; if you want to deliver to | |
4878 | a local file you would use the &(appendfile)& driver. Each of the drivers is | |
4879 | described in detail in its own separate chapter later in this manual. | |
168e428f PH |
4880 | |
4881 | You can have several routers, transports, or authenticators that are based on | |
068aaea8 | 4882 | the same underlying driver (each must have a different instance name). |
168e428f PH |
4883 | |
4884 | The order in which routers are defined is important, because addresses are | |
4885 | passed to individual routers one by one, in order. The order in which | |
4886 | transports are defined does not matter at all. The order in which | |
4887 | authenticators are defined is used only when Exim, as a client, is searching | |
4888 | them to find one that matches an authentication mechanism offered by the | |
4889 | server. | |
4890 | ||
9b371988 PH |
4891 | .cindex "generic options" |
4892 | .cindex "options" "generic &-- definition of" | |
4893 | Within a driver instance definition, there are two kinds of option: &'generic'& | |
4894 | and &'private'&. The generic options are those that apply to all drivers of the | |
4895 | same type (that is, all routers, all transports or all authenticators). The | |
4896 | &%driver%& option is a generic option that must appear in every definition. | |
4897 | .cindex "private options" | |
168e428f PH |
4898 | The private options are special for each driver, and none need appear, because |
4899 | they all have default values. | |
4900 | ||
9b371988 | 4901 | The options may appear in any order, except that the &%driver%& option must |
168e428f | 4902 | precede any private options, since these depend on the particular driver. For |
9b371988 | 4903 | this reason, it is recommended that &%driver%& always be the first option. |
168e428f PH |
4904 | |
4905 | Driver instance names, which are used for reference in log entries and | |
4906 | elsewhere, can be any sequence of letters, digits, and underscores (starting | |
4907 | with a letter) and must be unique among drivers of the same type. A router and | |
4908 | a transport (for example) can each have the same name, but no two router | |
4909 | instances can have the same name. The name of a driver instance should not be | |
4910 | confused with the name of the underlying driver module. For example, the | |
4911 | configuration lines: | |
9b371988 PH |
4912 | .code |
4913 | remote_smtp: | |
4914 | driver = smtp | |
4915 | .endd | |
4916 | create an instance of the &(smtp)& transport driver whose name is | |
4917 | &(remote_smtp)&. The same driver code can be used more than once, with | |
168e428f | 4918 | different instance names and different option settings each time. A second |
9b371988 | 4919 | instance of the &(smtp)& transport, with different options, might be defined |
168e428f | 4920 | thus: |
9b371988 PH |
4921 | .code |
4922 | special_smtp: | |
4923 | driver = smtp | |
4924 | port = 1234 | |
4925 | command_timeout = 10s | |
4926 | .endd | |
4927 | The names &(remote_smtp)& and &(special_smtp)& would be used to reference | |
168e428f PH |
4928 | these transport instances from routers, and these names would appear in log |
4929 | lines. | |
4930 | ||
4931 | Comment lines may be present in the middle of driver specifications. The full | |
4932 | list of option settings for any particular driver instance, including all the | |
9b371988 | 4933 | defaulted values, can be extracted by making use of the &%-bP%& command line |
168e428f PH |
4934 | option. |
4935 | ||
4936 | ||
4937 | ||
4938 | ||
4939 | ||
4940 | ||
9b371988 PH |
4941 | . //////////////////////////////////////////////////////////////////////////// |
4942 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 4943 | |
9b371988 PH |
4944 | .chapter "The default configuration file" "CHAPdefconfil" |
4945 | .cindex "configuration file" "default &""walk through""&" | |
4946 | .cindex "default" "configuration file &""walk through""&" | |
4947 | The default configuration file supplied with Exim as &_src/configure.default_& | |
168e428f | 4948 | is sufficient for a host with simple mail requirements. As an introduction to |
9b371988 | 4949 | the way Exim is configured, this chapter &"walks through"& the default |
168e428f PH |
4950 | configuration, giving brief explanations of the settings. Detailed descriptions |
4951 | of the options are given in subsequent chapters. The default configuration file | |
4952 | itself contains extensive comments about ways you might want to modify the | |
4953 | initial settings. However, note that there are many options that are not | |
4954 | mentioned at all in the default configuration. | |
4955 | ||
4956 | ||
4957 | ||
9b371988 | 4958 | .section "Main configuration settings" |
168e428f PH |
4959 | The main (global) configuration option settings must always come first in the |
4960 | file. The first thing you'll see in the file, after some initial comments, is | |
4961 | the line | |
9b371988 PH |
4962 | .code |
4963 | # primary_hostname = | |
4964 | .endd | |
4965 | This is a commented-out setting of the &%primary_hostname%& option. Exim needs | |
168e428f PH |
4966 | to know the official, fully qualified name of your host, and this is where you |
4967 | can specify it. However, in most cases you do not need to set this option. When | |
9b371988 | 4968 | it is unset, Exim uses the &[uname()]& system function to obtain the host name. |
168e428f PH |
4969 | |
4970 | The first three non-comment configuration lines are as follows: | |
9b371988 PH |
4971 | .code |
4972 | domainlist local_domains = @ | |
4973 | domainlist relay_to_domains = | |
4974 | hostlist relay_from_hosts = 127.0.0.1 | |
4975 | .endd | |
168e428f PH |
4976 | These are not, in fact, option settings. They are definitions of two named |
4977 | domain lists and one named host list. Exim allows you to give names to lists of | |
4978 | domains, hosts, and email addresses, in order to make it easier to manage the | |
9b371988 | 4979 | configuration file (see section &<<SECTnamedlists>>&). |
168e428f | 4980 | |
9b371988 | 4981 | The first line defines a domain list called &'local_domains'&; this is used |
168e428f PH |
4982 | later in the configuration to identify domains that are to be delivered |
4983 | on the local host. | |
4984 | ||
9b371988 PH |
4985 | .cindex "@ in a domain list" |
4986 | There is just one item in this list, the string &"@"&. This is a special form | |
4987 | of entry which means &"the name of the local host"&. Thus, if the local host is | |
4988 | called &'a.host.example'&, mail to &'any.user@a.host.example'& is expected to | |
168e428f PH |
4989 | be delivered locally. Because the local host's name is referenced indirectly, |
4990 | the same configuration file can be used on different hosts. | |
4991 | ||
9b371988 | 4992 | The second line defines a domain list called &'relay_to_domains'&, but the |
168e428f PH |
4993 | list itself is empty. Later in the configuration we will come to the part that |
4994 | controls mail relaying through the local host; it allows relaying to any | |
4995 | domains in this list. By default, therefore, no relaying on the basis of a mail | |
4996 | domain is permitted. | |
4997 | ||
9b371988 | 4998 | The third line defines a host list called &'relay_from_hosts'&. This list is |
168e428f PH |
4999 | used later in the configuration to permit relaying from any host or IP address |
5000 | that matches the list. The default contains just the IP address of the IPv4 | |
5001 | loopback interface, which means that processes on the local host are able to | |
5002 | submit mail for relaying by sending it over TCP/IP to that interface. No other | |
5003 | hosts are permitted to submit messages for relaying. | |
5004 | ||
5005 | Just to be sure there's no misunderstanding: at this point in the configuration | |
5006 | we aren't actually setting up any controls. We are just defining some domains | |
5007 | and hosts that will be used in the controls that are specified later. | |
5008 | ||
068aaea8 | 5009 | The next two configuration lines are genuine option settings: |
9b371988 PH |
5010 | .code |
5011 | acl_smtp_rcpt = acl_check_rcpt | |
5012 | acl_smtp_data = acl_check_data | |
5013 | .endd | |
5014 | .new | |
5015 | These options specify &'Access Control Lists'& (ACLs) that are to be used | |
5016 | during an incoming SMTP session for every recipient of a message (every RCPT | |
5017 | command), and after the contents of the message have been received, | |
5018 | respectively. The names of the lists are &'acl_check_rcpt'& and | |
5019 | &'acl_check_data'&, and we will come to their definitions below, in the ACL | |
5020 | section of the configuration. The RCPT ACL controls which recipients are | |
5021 | accepted for an incoming message &-- if a configuration does not provide an ACL | |
5022 | to check recipients, no SMTP mail can be accepted. The DATA ACL allows the | |
5023 | contents of a message to be checked. | |
168e428f | 5024 | |
068aaea8 | 5025 | Two commented-out option settings are next: |
9b371988 | 5026 | .code |
068aaea8 PH |
5027 | # av_scanner = clamd:/tmp/clamd |
5028 | # spamd_address = 127.0.0.1 783 | |
9b371988 | 5029 | .endd |
068aaea8 PH |
5030 | These are example settings that can be used when Exim is compiled with the |
5031 | content-scanning extension. The first specifies the interface to the virus | |
5032 | scanner, and the second specifies the interface to SpamAssassin. Further | |
9b371988 PH |
5033 | details are given in chapter &<<CHAPexiscan>>&. |
5034 | .wen | |
168e428f | 5035 | |
068aaea8 | 5036 | Two more commented-out options settings follow: |
9b371988 PH |
5037 | .code |
5038 | # qualify_domain = | |
5039 | # qualify_recipient = | |
5040 | .endd | |
168e428f PH |
5041 | The first of these specifies a domain that Exim uses when it constructs a |
5042 | complete email address from a local login name. This is often needed when Exim | |
9b371988 PH |
5043 | receives a message from a local process. If you do not set &%qualify_domain%&, |
5044 | the value of &%primary_hostname%& is used. If you set both of these options, | |
5045 | you can have different qualification domains for sender and recipient | |
5046 | addresses. If you set only the first one, its value is used in both cases. | |
168e428f | 5047 | |
9b371988 | 5048 | .cindex "domain literal" "recognizing format" |
168e428f | 5049 | The following line must be uncommented if you want Exim to recognize |
9b371988 | 5050 | addresses of the form &'user@[10.11.12.13]'& that is, with a &"domain literal"& |
068aaea8 | 5051 | (an IP address within square brackets) instead of a named domain. |
9b371988 PH |
5052 | .code |
5053 | # allow_domain_literals | |
5054 | .endd | |
168e428f PH |
5055 | The RFCs still require this form, but many people think that in the modern |
5056 | Internet it makes little sense to permit mail to be sent to specific hosts by | |
5057 | quoting their IP addresses. This ancient format has been used by people who | |
5058 | try to abuse hosts by using them for unwanted relaying. However, some | |
5059 | people believe there are circumstances (for example, messages addressed to | |
9b371988 | 5060 | &'postmaster'&) where domain literals are still useful. |
168e428f PH |
5061 | |
5062 | The next configuration line is a kind of trigger guard: | |
9b371988 PH |
5063 | .code |
5064 | never_users = root | |
5065 | .endd | |
168e428f | 5066 | It specifies that no delivery must ever be run as the root user. The normal |
9b371988 | 5067 | convention is to set up &'root'& as an alias for the system administrator. This |
168e428f | 5068 | setting is a guard against slips in the configuration. |
9b371988 PH |
5069 | The list of users specified by &%never_users%& is not, however, the complete |
5070 | list; the build-time configuration in &_Local/Makefile_& has an option called | |
168e428f | 5071 | FIXED_NEVER_USERS specifying a list that cannot be overridden. The |
9b371988 | 5072 | contents of &%never_users%& are added to this list. By default |
168e428f PH |
5073 | FIXED_NEVER_USERS also specifies root. |
5074 | ||
5075 | When a remote host connects to Exim in order to send mail, the only information | |
5076 | Exim has about the host's identity is its IP address. The next configuration | |
5077 | line, | |
9b371988 PH |
5078 | .code |
5079 | host_lookup = * | |
5080 | .endd | |
168e428f PH |
5081 | specifies that Exim should do a reverse DNS lookup on all incoming connections, |
5082 | in order to get a host name. This improves the quality of the logging | |
5083 | information, but if you feel it is too expensive, you can remove it entirely, | |
9b371988 | 5084 | or restrict the lookup to hosts on &"nearby"& networks. |
168e428f PH |
5085 | Note that it is not always possible to find a host name from an IP address, |
5086 | because not all DNS reverse zones are maintained, and sometimes DNS servers are | |
5087 | unreachable. | |
5088 | ||
9b371988 | 5089 | The next two lines are concerned with &'ident'& callbacks, as defined by RFC |
168e428f | 5090 | 1413 (hence their names): |
9b371988 PH |
5091 | .code |
5092 | rfc1413_hosts = * | |
5093 | rfc1413_query_timeout = 30s | |
5094 | .endd | |
168e428f PH |
5095 | These settings cause Exim to make ident callbacks for all incoming SMTP calls. |
5096 | You can limit the hosts to which these calls are made, or change the timeout | |
5097 | that is used. If you set the timeout to zero, all ident calls are disabled. | |
5098 | Although they are cheap and can provide useful information for tracing problem | |
5099 | messages, some hosts and firewalls have problems with ident calls. This can | |
5100 | result in a timeout instead of an immediate refused connection, leading to | |
5101 | delays on starting up an incoming SMTP session. | |
5102 | ||
5103 | When Exim receives messages over SMTP connections, it expects all addresses to | |
5104 | be fully qualified with a domain, as required by the SMTP definition. However, | |
5105 | if you are running a server to which simple clients submit messages, you may | |
5106 | find that they send unqualified addresses. The two commented-out options: | |
9b371988 PH |
5107 | .code |
5108 | # sender_unqualified_hosts = | |
5109 | # recipient_unqualified_hosts = | |
5110 | .endd | |
168e428f PH |
5111 | show how you can specify hosts that are permitted to send unqualified sender |
5112 | and recipient addresses, respectively. | |
5113 | ||
9b371988 PH |
5114 | The &%percent_hack_domains%& option is also commented out: |
5115 | .code | |
5116 | # percent_hack_domains = | |
5117 | .endd | |
5118 | It provides a list of domains for which the &"percent hack"& is to operate. | |
5119 | This is an almost obsolete form of explicit email routing. If you do not know | |
168e428f PH |
5120 | anything about it, you can safely ignore this topic. |
5121 | ||
5122 | The last two settings in the main part of the default configuration are | |
9b371988 PH |
5123 | concerned with messages that have been &"frozen"& on Exim's queue. When a |
5124 | message is frozen, Exim no longer continues to try to deliver it. Freezing | |
5125 | occurs when a bounce message encounters a permanent failure because the sender | |
5126 | address of the original message that caused the bounce is invalid, so the | |
5127 | bounce cannot be delivered. This is probably the most common case, but there | |
5128 | are also other conditions that cause freezing, and frozen messages are not | |
5129 | always bounce messages. | |
5130 | .code | |
5131 | ignore_bounce_errors_after = 2d | |
5132 | timeout_frozen_after = 7d | |
5133 | .endd | |
168e428f PH |
5134 | The first of these options specifies that failing bounce messages are to be |
5135 | discarded after 2 days on the queue. The second specifies that any frozen | |
5136 | message (whether a bounce message or not) is to be timed out (and discarded) | |
5137 | after a week. In this configuration, the first setting ensures that no failing | |
5138 | bounce message ever lasts a week. | |
5139 | ||
5140 | ||
5141 | ||
9b371988 PH |
5142 | .section "ACL configuration" |
5143 | .cindex "default" "ACLs" | |
5144 | .cindex "&ACL;" "default configuration" | |
168e428f PH |
5145 | In the default configuration, the ACL section follows the main configuration. |
5146 | It starts with the line | |
9b371988 PH |
5147 | .code |
5148 | begin acl | |
5149 | .endd | |
5150 | and it contains the definitions of two ACLs, called &'acl_check_rcpt'& and | |
5151 | &'acl_check_data'&, that were referenced in the settings of &%acl_smtp_rcpt%& | |
5152 | and &%acl_smtp_data%& above. | |
5153 | ||
5154 | .cindex "RCPT" "ACL for" | |
068aaea8 | 5155 | The first ACL is used for every RCPT command in an incoming SMTP message. Each |
168e428f PH |
5156 | RCPT command specifies one of the message's recipients. The ACL statements |
5157 | are considered in order, until the recipient address is either accepted or | |
5158 | rejected. The RCPT command is then accepted or rejected, according to the | |
5159 | result of the ACL processing. | |
9b371988 PH |
5160 | .code |
5161 | acl_check_rcpt: | |
5162 | .endd | |
168e428f PH |
5163 | This line, consisting of a name terminated by a colon, marks the start of the |
5164 | ACL, and names it. | |
9b371988 PH |
5165 | .code |
5166 | accept hosts = : | |
5167 | .endd | |
168e428f PH |
5168 | This ACL statement accepts the recipient if the sending host matches the list. |
5169 | But what does that strange list mean? It doesn't actually contain any host | |
5170 | names or IP addresses. The presence of the colon puts an empty item in the | |
068aaea8 PH |
5171 | list; Exim matches this only if the incoming message did not come from a remote |
5172 | host, because in that case, the remote hostname is empty. The colon is | |
5173 | important. Without it, the list itself is empty, and can never match anything. | |
168e428f PH |
5174 | |
5175 | What this statement is doing is to accept unconditionally all recipients in | |
5176 | messages that are submitted by SMTP from local processes using the standard | |
5177 | input and output (that is, not using TCP/IP). A number of MUAs operate in this | |
5178 | manner. | |
9b371988 PH |
5179 | .code |
5180 | deny message = Restricted characters in address | |
5181 | domains = +local_domains | |
5182 | local_parts = ^[.] : ^.*[@%!/|] | |
5183 | ||
5184 | deny message = Restricted characters in address | |
5185 | domains = !+local_domains | |
5186 | local_parts = ^[./|] : ^.*[@%!] : ^.*/\\.\\./ | |
5187 | .endd | |
168e428f | 5188 | These statements are concerned with local parts that contain any of the |
9b371988 PH |
5189 | characters &"@"&, &"%"&, &"!"&, &"/"&, &"|"&, or dots in unusual places. |
5190 | Although these characters are entirely legal in local parts (in the case of | |
5191 | &"@"& and leading dots, only if correctly quoted), they do not commonly occur | |
5192 | in Internet mail addresses. | |
168e428f PH |
5193 | |
5194 | The first three have in the past been associated with explicitly routed | |
9b371988 | 5195 | addresses (percent is still sometimes used &-- see the &%percent_hack_domains%& |
168e428f PH |
5196 | option). Addresses containing these characters are regularly tried by spammers |
5197 | in an attempt to bypass relaying restrictions, and also by open relay testing | |
5198 | programs. Unless you really need them it is safest to reject these characters | |
5199 | at this early stage. This configuration is heavy-handed in rejecting these | |
5200 | characters for all messages it accepts from remote hosts. This is a deliberate | |
5201 | policy of being as safe as possible. | |
5202 | ||
5203 | The first rule above is stricter, and is applied to messages that are addressed | |
5204 | to one of the local domains handled by this host. This is implemented by the | |
5205 | first condition, which restricts it to domains that are listed in the | |
9b371988 | 5206 | &'local_domains'& domain list. The &"+"& character is used to indicate a |
168e428f | 5207 | reference to a named list. In this configuration, there is just one domain in |
9b371988 | 5208 | &'local_domains'&, but in general there may be many. |
168e428f PH |
5209 | |
5210 | The second condition on the first statement uses two regular expressions to | |
9b371988 PH |
5211 | block local parts that begin with a dot or contain &"@"&, &"%"&, &"!"&, &"/"&, |
5212 | or &"|"&. If you have local accounts that include these characters, you will | |
5213 | have to modify this rule. | |
168e428f PH |
5214 | |
5215 | Empty components (two dots in a row) are not valid in RFC 2822, but Exim | |
9b371988 PH |
5216 | allows them because they have been encountered in practice. (Consider the |
5217 | common convention of local parts constructed as | |
5218 | &"&'first-initial.second-initial.family-name'&"& when applied to someone like | |
5219 | the author of Exim, who has no second initial.) However, a local part starting | |
5220 | with a dot or containing &"/../"& can cause trouble if it is used as part of a | |
5221 | file name (for example, for a mailing list). This is also true for local parts | |
5222 | that contain slashes. A pipe symbol can also be troublesome if the local part | |
5223 | is incorporated unthinkingly into a shell command line. | |
168e428f PH |
5224 | |
5225 | The second rule above applies to all other domains, and is less strict. This | |
5226 | allows your own users to send outgoing messages to sites that use slashes | |
5227 | and vertical bars in their local parts. It blocks local parts that begin | |
5228 | with a dot, slash, or vertical bar, but allows these characters within the | |
9b371988 PH |
5229 | local part. However, the sequence &"/../"& is barred. The use of &"@"&, &"%"&, |
5230 | and &"!"& is blocked, as before. The motivation here is to prevent your users | |
5231 | (or your users' viruses) from mounting certain kinds of attack on remote sites. | |
5232 | .code | |
5233 | accept local_parts = postmaster | |
5234 | domains = +local_domains | |
5235 | .endd | |
168e428f | 5236 | This statement, which has two conditions, accepts an incoming address if the |
9b371988 PH |
5237 | local part is &'postmaster'& and the domain is one of those listed in the |
5238 | &'local_domains'& domain list. The &"+"& character is used to indicate a | |
168e428f | 5239 | reference to a named list. In this configuration, there is just one domain in |
9b371988 | 5240 | &'local_domains'&, but in general there may be many. |
168e428f PH |
5241 | |
5242 | The presence of this statement means that mail to postmaster is never blocked | |
5243 | by any of the subsequent tests. This can be helpful while sorting out problems | |
5244 | in cases where the subsequent tests are incorrectly denying access. | |
9b371988 PH |
5245 | .code |
5246 | require verify = sender | |
5247 | .endd | |
168e428f PH |
5248 | This statement requires the sender address to be verified before any subsequent |
5249 | ACL statement can be used. If verification fails, the incoming recipient | |
5250 | address is refused. Verification consists of trying to route the address, to | |
068aaea8 | 5251 | see if a bounce message could be delivered to it. In the case of remote |
9b371988 PH |
5252 | addresses, basic verification checks only the domain, but &'callouts'& can be |
5253 | used for more verification if required. Section &<<SECTaddressverification>>& | |
068aaea8 | 5254 | discusses the details of address verification. |
9b371988 PH |
5255 | .code |
5256 | accept hosts = +relay_from_hosts | |
5257 | control = submission | |
5258 | .endd | |
5259 | .new | |
068aaea8 PH |
5260 | This statement accepts the address if the message is coming from one of the |
5261 | hosts that are defined as being allowed to relay through this host. Recipient | |
5262 | verification is omitted here, because in many cases the clients are dumb MUAs | |
5263 | that do not cope well with SMTP error responses. For the same reason, the | |
9b371988 PH |
5264 | second line specifies &"submission mode"& for messages that are accepted. This |
5265 | is described in detail in section &<<SECTsubmodnon>>&; it causes Exim to fix | |
068aaea8 | 5266 | messages that are deficient in some way, for example, because they lack a |
9b371988 | 5267 | &'Date:'& header line. If you are actually relaying out from MTAs, you should |
068aaea8 | 5268 | probably add recipient verification here, and disable submission mode. |
9b371988 PH |
5269 | .code |
5270 | accept authenticated = * | |
5271 | control = submission | |
5272 | .endd | |
068aaea8 PH |
5273 | This statement accepts the address if the client host has authenticated itself. |
5274 | Submission mode is again specified, on the grounds that such messages are most | |
5275 | likely to come from MUAs. The default configuration does not define any | |
5276 | authenticators, which means that no client can in fact authenticate. You will | |
5277 | need to add authenticator definitions if you want to make use of this ACL | |
5278 | statement. | |
9b371988 PH |
5279 | .wen |
5280 | .code | |
5281 | # deny message = rejected because $sender_host_address \ | |
5282 | # is in a black list at $dnslist_domain\n\ | |
5283 | # $dnslist_text | |
5284 | # dnslists = black.list.example | |
168e428f | 5285 | # |
9b371988 PH |
5286 | # warn message = X-Warning: $sender_host_address is \ |
5287 | # in a black list at $dnslist_domain | |
5288 | # log_message = found in $dnslist_domain | |
5289 | # dnslists = black.list.example | |
5290 | .endd | |
168e428f PH |
5291 | These commented-out lines are examples of how you could configure Exim to check |
5292 | sending hosts against a DNS black list. The first statement rejects messages | |
5293 | from blacklisted hosts, whereas the second merely inserts a warning header | |
5294 | line. | |
9b371988 PH |
5295 | .code |
5296 | accept domains = +local_domains | |
5297 | endpass | |
5298 | verify = recipient | |
5299 | .endd | |
168e428f PH |
5300 | This statement accepts the incoming recipient address if its domain is one of |
5301 | the local domains, but only if the address can be verified. Verification of | |
5302 | local addresses normally checks both the local part and the domain. The | |
9b371988 PH |
5303 | &%endpass%& line needs some explanation: if the condition above &%endpass%& |
5304 | fails, that is, if the address is not in a local domain, control is passed to | |
5305 | the next ACL statement. However, if the condition below &%endpass%& fails, that | |
5306 | is, if a recipient in a local domain cannot be verified, access is denied and | |
5307 | the recipient is rejected. | |
5308 | .code | |
5309 | accept domains = +relay_to_domains | |
5310 | endpass | |
5311 | verify = recipient | |
5312 | .endd | |
168e428f PH |
5313 | This statement accepts the incoming recipient address if its domain is one of |
5314 | the domains for which this host is a relay, but again, only if the address can | |
5315 | be verified. | |
9b371988 PH |
5316 | .code |
5317 | deny message = relay not permitted | |
5318 | .endd | |
168e428f PH |
5319 | The final statement denies access, giving a specific error message. Reaching |
5320 | the end of the ACL also causes access to be denied, but with the generic | |
9b371988 PH |
5321 | message &"administrative prohibition"&. |
5322 | .code | |
5323 | acl_check_data: | |
5324 | .endd | |
5325 | .new | |
068aaea8 PH |
5326 | This line marks the start of the second ACL, and names it. Most of the contents |
5327 | of this ACL are commented out: | |
9b371988 | 5328 | .code |
068aaea8 PH |
5329 | # deny malware = * |
5330 | # message = This message contains a virus \ | |
5331 | # ($malware_name). | |
9b371988 | 5332 | .endd |
068aaea8 PH |
5333 | These lines are examples of how to arrange for messages to be scanned for |
5334 | viruses when Exim has been compiled with the content-scanning extension, and a | |
5335 | suitable virus scanner is installed. If the message is found to contain a | |
5336 | virus, it is rejected with the given custom error message. | |
9b371988 | 5337 | .code |
068aaea8 PH |
5338 | # warn spam = nobody |
5339 | # message = X-Spam_score: $spam_score\n\ | |
5340 | # X-Spam_score_int: $spam_score_int\n\ | |
5341 | # X-Spam_bar: $spam_bar\n\ | |
5342 | # X-Spam_report: $spam_report | |
9b371988 | 5343 | .endd |
068aaea8 PH |
5344 | These lines are an example of how to arrange for messages to be scanned by |
5345 | SpamAssassin when Exim has been compiled with the content-scanning extension, | |
5346 | and SpamAssassin has been installed. The SpamAssassin check is run with | |
9b371988 | 5347 | &`nobody`& as its user parameter, and the results are added to the message as a |
068aaea8 PH |
5348 | series of extra header line. In this case, the message is not rejected, |
5349 | whatever the spam score. | |
9b371988 PH |
5350 | .code |
5351 | accept | |
5352 | .endd | |
068aaea8 | 5353 | This final line in the DATA ACL accepts the message unconditionally. |
9b371988 | 5354 | .wen |
068aaea8 | 5355 | |
168e428f | 5356 | |
9b371988 PH |
5357 | .section "Router configuration" |
5358 | .cindex "default" "routers" | |
5359 | .cindex "routers" "default" | |
168e428f PH |
5360 | The router configuration comes next in the default configuration, introduced |
5361 | by the line | |
9b371988 PH |
5362 | .code |
5363 | begin routers | |
5364 | .endd | |
168e428f PH |
5365 | Routers are the modules in Exim that make decisions about where to send |
5366 | messages. An address is passed to each router in turn, until it is either | |
5367 | accepted, or failed. This means that the order in which you define the routers | |
5368 | matters. Each router is fully described in its own chapter later in this | |
5369 | manual. Here we give only brief overviews. | |
9b371988 PH |
5370 | .code |
5371 | # domain_literal: | |
5372 | # driver = ipliteral | |
5373 | # domains = !+local_domains | |
5374 | # transport = remote_smtp | |
5375 | .endd | |
5376 | .cindex "domain literal" "default router" | |
168e428f | 5377 | This router is commented out because the majority of sites do not want to |
9b371988 | 5378 | support domain literal addresses (those of the form &'user@[10.9.8.7]'&). If |
168e428f | 5379 | you uncomment this router, you also need to uncomment the setting of |
9b371988 PH |
5380 | &%allow_domain_literals%& in the main part of the configuration. |
5381 | .code | |
5382 | dnslookup: | |
5383 | driver = dnslookup | |
5384 | domains = ! +local_domains | |
5385 | transport = remote_smtp | |
5386 | ignore_target_hosts = 0.0.0.0 : 127.0.0.0/8 | |
5387 | no_more | |
5388 | .endd | |
168e428f PH |
5389 | The first uncommented router handles addresses that do not involve any local |
5390 | domains. This is specified by the line | |
9b371988 PH |
5391 | .code |
5392 | domains = ! +local_domains | |
5393 | .endd | |
5394 | The &%domains%& option lists the domains to which this router applies, but the | |
168e428f | 5395 | exclamation mark is a negation sign, so the router is used only for domains |
9b371988 PH |
5396 | that are not in the domain list called &'local_domains'& (which was defined at |
5397 | the start of the configuration). The plus sign before &'local_domains'& | |
168e428f PH |
5398 | indicates that it is referring to a named list. Addresses in other domains are |
5399 | passed on to the following routers. | |
5400 | ||
9b371988 PH |
5401 | The name of the router driver is &(dnslookup)&, |
5402 | and is specified by the &%driver%& option. Do not be confused by the fact that | |
168e428f | 5403 | the name of this router instance is the same as the name of the driver. The |
9b371988 PH |
5404 | instance name is arbitrary, but the name set in the &%driver%& option must be |
5405 | one of the driver modules that is in the Exim binary. | |
168e428f | 5406 | |
9b371988 | 5407 | The &(dnslookup)& router routes addresses by looking up their domains in the |
168e428f | 5408 | DNS in order to obtain a list of hosts to which the address is routed. If the |
9b371988 PH |
5409 | router succeeds, the address is queued for the &(remote_smtp)& transport, as |
5410 | specified by the &%transport%& option. If the router does not find the domain | |
5411 | in the DNS, no further routers are tried because of the &%no_more%& setting, so | |
5412 | the address fails and is bounced. | |
168e428f | 5413 | |
9b371988 | 5414 | The &%ignore_target_hosts%& option specifies a list of IP addresses that are to |
168e428f PH |
5415 | be entirely ignored. This option is present because a number of cases have been |
5416 | encountered where MX records in the DNS point to host names | |
5417 | whose IP addresses are 0.0.0.0 or are in the 127 subnet (typically 127.0.0.1). | |
5418 | Completely ignoring these IP addresses causes Exim to fail to route the | |
5419 | email address, so it bounces. Otherwise, Exim would log a routing problem, and | |
5420 | continue to try to deliver the message periodically until the address timed | |
5421 | out. | |
9b371988 PH |
5422 | .code |
5423 | system_aliases: | |
5424 | driver = redirect | |
5425 | allow_fail | |
5426 | allow_defer | |
5427 | data = ${lookup{$local_part}lsearch{/etc/aliases}} | |
5428 | # user = exim | |
5429 | file_transport = address_file | |
5430 | pipe_transport = address_pipe | |
5431 | .endd | |
168e428f PH |
5432 | Control reaches this and subsequent routers only for addresses in the local |
5433 | domains. This router checks to see whether the local part is defined as an | |
9b371988 | 5434 | alias in the &_/etc/aliases_& file, and if so, redirects it according to the |
168e428f | 5435 | data that it looks up from that file. If no data is found for the local part, |
9b371988 | 5436 | the value of the &%data%& option is empty, causing the address to be passed to |
168e428f PH |
5437 | the next router. |
5438 | ||
9b371988 | 5439 | &_/etc/aliases_& is a conventional name for the system aliases file that is |
168e428f PH |
5440 | often used. That is why it is referenced by from the default configuration |
5441 | file. However, you can change this by setting SYSTEM_ALIASES_FILE in | |
9b371988 PH |
5442 | &_Local/Makefile_& before building Exim. |
5443 | .code | |
5444 | userforward: | |
5445 | driver = redirect | |
5446 | check_local_user | |
5447 | # local_part_suffix = +* : -* | |
5448 | # local_part_suffix_optional | |
5449 | file = $home/.forward | |
5450 | # allow_filter | |
5451 | no_verify | |
5452 | no_expn | |
5453 | check_ancestor | |
5454 | file_transport = address_file | |
5455 | pipe_transport = address_pipe | |
5456 | reply_transport = address_reply | |
5457 | .endd | |
5458 | .new | |
168e428f PH |
5459 | This is the most complicated router in the default configuration. It is another |
5460 | redirection router, but this time it is looking for forwarding data set up by | |
9b371988 | 5461 | individual users. The &%check_local_user%& setting specifies a check that the |
068aaea8 | 5462 | local part of the address is the login name of a local user. If it is not, the |
9b371988 | 5463 | router is skipped. The two commented options that follow &%check_local_user%&, |
068aaea8 | 5464 | namely: |
9b371988 | 5465 | .code |
068aaea8 PH |
5466 | # local_part_suffix = +* : -* |
5467 | # local_part_suffix_optional | |
9b371988 PH |
5468 | .endd |
5469 | .cindex "&$local_part_suffix$&" | |
068aaea8 PH |
5470 | show how you can specify the recognition of local part suffixes. If the first |
5471 | is uncommented, a suffix beginning with either a plus or a minus sign, followed | |
5472 | by any sequence of characters, is removed from the local part and placed in the | |
9b371988 | 5473 | variable &$local_part_suffix$&. The second suffix option specifies that the |
068aaea8 PH |
5474 | presence of a suffix in the local part is optional. When a suffix is present, |
5475 | the check for a local login uses the local part with the suffix removed. | |
9b371988 | 5476 | .wen |
068aaea8 | 5477 | |
9b371988 | 5478 | When a local user account is found, the file called &_.forward_& in the user's |
068aaea8 | 5479 | home directory is consulted. If it does not exist, or is empty, the router |
9b371988 PH |
5480 | declines. Otherwise, the contents of &_.forward_& are interpreted as |
5481 | redirection data (see chapter &<<CHAPredirect>>& for more details). | |
5482 | ||
5483 | .cindex "Sieve filter" "enabling in default router" | |
5484 | Traditional &_.forward_& files contain just a list of addresses, pipes, or | |
5485 | files. Exim supports this by default. However, if &%allow_filter%& is set (it | |
5486 | is commented out by default), the contents of the file are interpreted as a set | |
5487 | of Exim or Sieve filtering instructions, provided the file begins with &"#Exim | |
5488 | filter"& or &"#Sieve filter"&, respectively. User filtering is discussed in the | |
5489 | separate document entitled &'Exim's interfaces to mail filtering'&. | |
5490 | ||
5491 | The &%no_verify%& and &%no_expn%& options mean that this router is skipped when | |
068aaea8 | 5492 | verifying addresses, or when running as a consequence of an SMTP EXPN command. |
168e428f PH |
5493 | There are two reasons for doing this: |
5494 | ||
9b371988 PH |
5495 | .olist |
5496 | Whether or not a local user has a &_.forward_& file is not really relevant when | |
168e428f PH |
5497 | checking an address for validity; it makes sense not to waste resources doing |
5498 | unnecessary work. | |
9b371988 PH |
5499 | .next |
5500 | More importantly, when Exim is verifying addresses or handling an EXPN | |
168e428f PH |
5501 | command during an SMTP session, it is running as the Exim user, not as root. |
5502 | The group is the Exim group, and no additional groups are set up. | |
9b371988 | 5503 | It may therefore not be possible for Exim to read users' &_.forward_& files at |
168e428f | 5504 | this time. |
9b371988 | 5505 | .endlist |
168e428f | 5506 | |
9b371988 | 5507 | The setting of &%check_ancestor%& prevents the router from generating a new |
168e428f PH |
5508 | address that is the same as any previous address that was redirected. (This |
5509 | works round a problem concerning a bad interaction between aliasing and | |
9b371988 | 5510 | forwarding &-- see section &<<SECTredlocmai>>&). |
168e428f PH |
5511 | |
5512 | The final three option settings specify the transports that are to be used when | |
5513 | forwarding generates a direct delivery to a file, or to a pipe, or sets up an | |
9b371988 PH |
5514 | auto-reply, respectively. For example, if a &_.forward_& file contains |
5515 | .code | |
5516 | a.nother@elsewhere.example, /home/spqr/archive | |
5517 | .endd | |
5518 | the delivery to &_/home/spqr/archive_& is done by running the &%address_file%& | |
168e428f | 5519 | transport. |
9b371988 PH |
5520 | .code |
5521 | localuser: | |
5522 | driver = accept | |
5523 | check_local_user | |
5524 | # local_part_suffix = +* : -* | |
5525 | # local_part_suffix_optional | |
5526 | transport = local_delivery | |
5527 | .endd | |
5528 | .new | |
168e428f | 5529 | The final router sets up delivery into local mailboxes, provided that the local |
068aaea8 | 5530 | part is the name of a local login, by accepting the address and assigning it to |
9b371988 | 5531 | the &(local_delivery)& transport. Otherwise, we have reached the end of the |
068aaea8 | 5532 | routers, so the address is bounced. The commented suffix settings fulfil the |
9b371988 PH |
5533 | same purpose as they do for the &(userforward)& router. |
5534 | .wen | |
168e428f PH |
5535 | |
5536 | ||
9b371988 PH |
5537 | .section "Transport configuration" |
5538 | .cindex "default" "transports" | |
5539 | .cindex "transports" "default" | |
168e428f PH |
5540 | Transports define mechanisms for actually delivering messages. They operate |
5541 | only when referenced from routers, so the order in which they are defined does | |
5542 | not matter. The transports section of the configuration starts with | |
9b371988 PH |
5543 | .code |
5544 | begin transports | |
5545 | .endd | |
168e428f | 5546 | One remote transport and four local transports are defined. |
9b371988 PH |
5547 | .code |
5548 | remote_smtp: | |
5549 | driver = smtp | |
5550 | .endd | |
168e428f PH |
5551 | This transport is used for delivering messages over SMTP connections. All its |
5552 | options are defaulted. The list of remote hosts comes from the router. | |
9b371988 PH |
5553 | .code |
5554 | local_delivery: | |
5555 | driver = appendfile | |
5556 | file = /var/mail/$local_part | |
5557 | delivery_date_add | |
5558 | envelope_to_add | |
5559 | return_path_add | |
5560 | # group = mail | |
5561 | # mode = 0660 | |
5562 | .endd | |
5563 | This &(appendfile)& transport is used for local delivery to user mailboxes in | |
168e428f | 5564 | traditional BSD mailbox format. By default it runs under the uid and gid of the |
9b371988 | 5565 | local user, which requires the sticky bit to be set on the &_/var/mail_& |
168e428f PH |
5566 | directory. Some systems use the alternative approach of running mail deliveries |
5567 | under a particular group instead of using the sticky bit. The commented options | |
5568 | show how this can be done. | |
5569 | ||
9b371988 PH |
5570 | Exim adds three headers to the message as it delivers it: &'Delivery-date:'&, |
5571 | &'Envelope-to:'& and &'Return-path:'&. This action is requested by the three | |
168e428f | 5572 | similarly-named options above. |
9b371988 PH |
5573 | .code |
5574 | address_pipe: | |
5575 | driver = pipe | |
5576 | return_output | |
5577 | .endd | |
168e428f | 5578 | This transport is used for handling deliveries to pipes that are generated by |
9b371988 | 5579 | redirection (aliasing or users' &_.forward_& files). The &%return_output%& |
168e428f PH |
5580 | option specifies that any output generated by the pipe is to be returned to the |
5581 | sender. | |
9b371988 PH |
5582 | .code |
5583 | address_file: | |
5584 | driver = appendfile | |
5585 | delivery_date_add | |
5586 | envelope_to_add | |
5587 | return_path_add | |
5588 | .endd | |
168e428f PH |
5589 | This transport is used for handling deliveries to files that are generated by |
5590 | redirection. The name of the file is not specified in this instance of | |
9b371988 PH |
5591 | &(appendfile)&, because it comes from the &(redirect)& router. |
5592 | .code | |
5593 | address_reply: | |
5594 | driver = autoreply | |
5595 | .endd | |
168e428f PH |
5596 | This transport is used for handling automatic replies generated by users' |
5597 | filter files. | |
5598 | ||
5599 | ||
5600 | ||
9b371988 PH |
5601 | .section "Default retry rule" |
5602 | .cindex "retry" "default rule" | |
5603 | .cindex "default" "retry rule" | |
168e428f PH |
5604 | The retry section of the configuration file contains rules which affect the way |
5605 | Exim retries deliveries that cannot be completed at the first attempt. It is | |
5606 | introduced by the line | |
9b371988 PH |
5607 | .code |
5608 | begin retry | |
5609 | .endd | |
168e428f PH |
5610 | In the default configuration, there is just one rule, which applies to all |
5611 | errors: | |
9b371988 PH |
5612 | .code |
5613 | * * F,2h,15m; G,16h,1h,1.5; F,4d,6h | |
5614 | .endd | |
168e428f PH |
5615 | This causes any temporarily failing address to be retried every 15 minutes for |
5616 | 2 hours, then at intervals starting at one hour and increasing by a factor of | |
5617 | 1.5 until 16 hours have passed, then every 6 hours up to 4 days. If an address | |
9b371988 | 5618 | is not delivered after 4 days of temporary failure, it is bounced. |
168e428f PH |
5619 | |
5620 | ||
5621 | ||
9b371988 | 5622 | .section "Rewriting configuration" |
168e428f | 5623 | The rewriting section of the configuration, introduced by |
9b371988 PH |
5624 | .code |
5625 | begin rewrite | |
5626 | .endd | |
168e428f PH |
5627 | contains rules for rewriting addresses in messages as they arrive. There are no |
5628 | rewriting rules in the default configuration file. | |
5629 | ||
5630 | ||
5631 | ||
9b371988 PH |
5632 | .section "Authenticators configuration" |
5633 | .cindex "AUTH" "configuration" | |
168e428f | 5634 | The authenticators section of the configuration, introduced by |
9b371988 PH |
5635 | .code |
5636 | begin authenticators | |
5637 | .endd | |
168e428f PH |
5638 | defines mechanisms for the use of the SMTP AUTH command. No authenticators |
5639 | are specified in the default configuration file. | |
5640 | ||
5641 | ||
5642 | ||
9b371988 PH |
5643 | . //////////////////////////////////////////////////////////////////////////// |
5644 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 5645 | |
9b371988 | 5646 | .chapter "Regular expressions" "CHAPregexp" |
168e428f | 5647 | |
9b371988 PH |
5648 | .cindex "regular expressions" "library" |
5649 | .cindex "PCRE" | |
168e428f PH |
5650 | Exim supports the use of regular expressions in many of its options. It |
5651 | uses the PCRE regular expression library; this provides regular expression | |
5652 | matching that is compatible with Perl 5. The syntax and semantics of | |
5653 | regular expressions is discussed in many Perl reference books, and also in | |
9b371988 PH |
5654 | Jeffrey Friedl's &'Mastering Regular Expressions'&, which is published by |
5655 | O'Reilly (see &url(http://www.oreilly.com/catalog/regex2/)). | |
168e428f PH |
5656 | |
5657 | The documentation for the syntax and semantics of the regular expressions that | |
5658 | are supported by PCRE is included in plain text in the file | |
9b371988 PH |
5659 | &_doc/pcrepattern.txt_& in the Exim distribution, and also in the HTML |
5660 | tarbundle of Exim documentation. It describes in detail the features of the | |
5661 | regular expressions that PCRE supports, so no further description is included | |
5662 | here. The PCRE functions are called from Exim using the default option settings | |
5663 | (that is, with no PCRE options set), except that the PCRE_CASELESS option is | |
5664 | set when the matching is required to be case-insensitive. | |
168e428f PH |
5665 | |
5666 | In most cases, when a regular expression is required in an Exim configuration, | |
5667 | it has to start with a circumflex, in order to distinguish it from plain text | |
9b371988 | 5668 | or an &"ends with"& wildcard. In this example of a configuration setting, the |
168e428f | 5669 | second item in the colon-separated list is a regular expression. |
9b371988 PH |
5670 | .code |
5671 | domains = a.b.c : ^\\d{3} : *.y.z : ... | |
5672 | .endd | |
168e428f | 5673 | The doubling of the backslash is required because of string expansion that |
9b371988 PH |
5674 | precedes interpretation &-- see section &<<SECTlittext>>& for more discussion |
5675 | of this issue, and a way of avoiding the need for doubling backslashes. The | |
168e428f PH |
5676 | regular expression that is eventually used in this example contains just one |
5677 | backslash. The circumflex is included in the regular expression, and has the | |
9b371988 | 5678 | normal effect of &"anchoring"& it to the start of the string that is being |
168e428f PH |
5679 | matched. |
5680 | ||
5681 | There are, however, two cases where a circumflex is not required for the | |
9b371988 PH |
5682 | recognition of a regular expression: these are the &%match%& condition in a |
5683 | string expansion, and the &%matches%& condition in an Exim filter file. In | |
5684 | these cases, the relevant string is always treated as a regular expression; if | |
5685 | it does not start with a circumflex, the expression is not anchored, and can | |
5686 | match anywhere in the subject string. | |
168e428f PH |
5687 | |
5688 | In all cases, if you want a regular expression to match at the end of a string, | |
9b371988 PH |
5689 | you must code the $ metacharacter to indicate this. For example: |
5690 | .code | |
5691 | domains = ^\\d{3}\\.example | |
5692 | .endd | |
5693 | matches the domain &'123.example'&, but it also matches &'123.example.com'&. | |
168e428f | 5694 | You need to use: |
9b371988 PH |
5695 | .code |
5696 | domains = ^\\d{3}\\.example\$ | |
5697 | .endd | |
5698 | if you want &'example'& to be the top-level domain. The backslash before the | |
5699 | $ is needed because string expansion also interprets dollar characters. | |
168e428f | 5700 | |
168e428f PH |
5701 | |
5702 | ||
9b371988 PH |
5703 | .section "Testing regular expressions" |
5704 | .cindex "testing" "regular expressions" | |
5705 | .cindex "regular expressions" "testing" | |
5706 | .cindex "&'pcretest'&" | |
5707 | A program called &'pcretest'& forms part of the PCRE distribution and is built | |
168e428f PH |
5708 | with PCRE during the process of building Exim. It is primarily intended for |
5709 | testing PCRE itself, but it can also be used for experimenting with regular | |
5710 | expressions. After building Exim, the binary can be found in the build | |
5711 | directory (it is not installed anywhere automatically). There is documentation | |
9b371988 PH |
5712 | of various options in &_doc/pcretest.txt_&, but for simple testing, none are |
5713 | needed. This is the output of a sample run of &'pcretest'&: | |
5714 | .display | |
5715 | &` re> `&&*&`/^([@]+)@.+\.(ac|edu)\.(?!kr)[a-z]{2}$/`&*& | |
5716 | &`data> `&&*&`x@y.ac.uk`&*& | |
5717 | &` 0: x@y.ac.uk`& | |
5718 | &` 1: x`& | |
5719 | &` 2: ac`& | |
5720 | &`data> `&&*&`x@y.ac.kr`&*& | |
5721 | &`No match`& | |
5722 | &`data> `&&*&`x@y.edu.com`&*& | |
5723 | &`No match`& | |
5724 | &`data> `&&*&`x@y.edu.co`&*& | |
5725 | &` 0: x@y.edu.co`& | |
5726 | &` 1: x`& | |
5727 | &` 2: edu`& | |
5728 | .endd | |
5729 | Input typed by the user is shown in bold face. After the &"re>"& prompt, a | |
168e428f | 5730 | regular expression enclosed in delimiters is expected. If this compiles without |
9b371988 | 5731 | error, &"data>"& prompts are given for strings against which the expression is |
168e428f PH |
5732 | matched. An empty data line causes a new regular expression to be read. If the |
5733 | match is successful, the captured substring values (that is, what would be in | |
9b371988 PH |
5734 | the variables &$0$&, &$1$&, &$2$&, etc.) are shown. The above example tests for |
5735 | an email address whose domain ends with either &"ac"& or &"edu"& followed by a | |
5736 | two-character top-level domain that is not &"kr"&. The local part is captured | |
5737 | in &$1$& and the &"ac"& or &"edu"& in &$2$&. | |
168e428f PH |
5738 | |
5739 | ||
5740 | ||
5741 | ||
5742 | ||
5743 | ||
9b371988 PH |
5744 | . //////////////////////////////////////////////////////////////////////////// |
5745 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 5746 | |
9b371988 PH |
5747 | .chapter "File and database lookups" "CHAPfdlookup" |
5748 | .cindex "file" "lookup" | |
5749 | .cindex "database lookups" | |
5750 | .cindex "lookup" "description of" | |
168e428f PH |
5751 | Exim can be configured to look up data in files or databases as it processes |
5752 | messages. Two different kinds of syntax are used: | |
5753 | ||
9b371988 PH |
5754 | .olist |
5755 | A string that is to be expanded may contain explicit lookup requests. These | |
168e428f | 5756 | cause parts of the string to be replaced by data that is obtained from the |
9b371988 PH |
5757 | lookup. Lookups of this type are conditional expansion items. Different results |
5758 | can be defined for the cases of lookup success and failure. See chapter | |
5759 | &<<CHAPexpand>>&, where string expansions are described in detail. | |
5760 | .next | |
5761 | Lists of domains, hosts, and email addresses can contain lookup requests as a | |
168e428f PH |
5762 | way of avoiding excessively long linear lists. In this case, the data that is |
5763 | returned by the lookup is often (but not always) discarded; whether the lookup | |
5764 | succeeds or fails is what really counts. These kinds of list are described in | |
9b371988 PH |
5765 | chapter &<<CHAPdomhosaddlists>>&. |
5766 | .endlist | |
168e428f | 5767 | |
9b371988 | 5768 | .new |
068aaea8 PH |
5769 | String expansions, lists, and lookups interact with each other in such a way |
5770 | that there is no order in which to describe any one of them that does not | |
5771 | involve references to the others. Each of these three chapters makes more sense | |
5772 | if you have read the other two first. If you are reading this for the first | |
5773 | time, be aware that some of it will make a lot more sense after you have read | |
9b371988 PH |
5774 | chapters &<<CHAPdomhosaddlists>>& and &<<CHAPexpand>>&. |
5775 | .wen | |
068aaea8 | 5776 | |
9b371988 | 5777 | .section "Examples of different lookup syntax" |
168e428f PH |
5778 | It is easy to confuse the two different kinds of lookup, especially as the |
5779 | lists that may contain the second kind are always expanded before being | |
5780 | processed as lists. Therefore, they may also contain lookups of the first kind. | |
5781 | Be careful to distinguish between the following two examples: | |
9b371988 PH |
5782 | .code |
5783 | domains = ${lookup{$sender_host_address}lsearch{/some/file}} | |
5784 | domains = lsearch;/some/file | |
5785 | .endd | |
5786 | .new | |
168e428f | 5787 | The first uses a string expansion, the result of which must be a domain list. |
9b371988 PH |
5788 | No strings have been specified for a successful or a failing lookup; the |
5789 | defaults in this case are the looked-up data and an empty string, respectively. | |
068aaea8 PH |
5790 | The expansion takes place before the string is processed as a list, and the |
5791 | file that is searched could contain lines like this: | |
9b371988 PH |
5792 | .wen |
5793 | .code | |
5794 | 192.168.3.4: domain1:domain2:... | |
5795 | 192.168.1.9: domain3:domain4:... | |
5796 | .endd | |
5797 | When the lookup succeeds, the result of the expansion is a list of domains (and | |
5798 | possibly other types of item that are allowed in domain lists). | |
168e428f | 5799 | |
068aaea8 | 5800 | In the second example, the lookup is a single item in a domain list. It causes |
168e428f PH |
5801 | Exim to use a lookup to see if the domain that is being processed can be found |
5802 | in the file. The file could contains lines like this: | |
9b371988 PH |
5803 | .code |
5804 | domain1: | |
5805 | domain2: | |
5806 | .endd | |
168e428f PH |
5807 | Any data that follows the keys is not relevant when checking that the domain |
5808 | matches the list item. | |
5809 | ||
068aaea8 PH |
5810 | It is possible, though no doubt confusing, to use both kinds of lookup at once. |
5811 | Consider a file containing lines like this: | |
9b371988 PH |
5812 | .code |
5813 | 192.168.5.6: lsearch;/another/file | |
5814 | .endd | |
5815 | If the value of &$sender_host_address$& is 192.168.5.6, expansion of the | |
5816 | first &%domains%& setting above generates the second setting, which therefore | |
168e428f PH |
5817 | causes a second lookup to occur. |
5818 | ||
5819 | The rest of this chapter describes the different lookup types that are | |
068aaea8 PH |
5820 | available. Any of them can be used in any part of the configuration where a |
5821 | lookup is permitted. | |
168e428f PH |
5822 | |
5823 | ||
9b371988 PH |
5824 | .section "Lookup types" |
5825 | .cindex "lookup" "types of" | |
5826 | .cindex "single-key lookup" "definition of" | |
068aaea8 | 5827 | Two different types of data lookup are implemented: |
168e428f | 5828 | |
9b371988 PH |
5829 | .ilist |
5830 | The &'single-key'& type requires the specification of a file in which to look, | |
168e428f PH |
5831 | and a single key to search for. The key must be a non-empty string for the |
5832 | lookup to succeed. The lookup type determines how the file is searched. | |
9b371988 PH |
5833 | .next |
5834 | .cindex "query-style lookup" "definition of" | |
5835 | The &'query-style'& type accepts a generalized database query. No particular | |
5836 | key value is assumed by Exim for query-style lookups. You can use whichever | |
5837 | Exim variables you need to construct the database query. | |
5838 | .endlist | |
168e428f PH |
5839 | |
5840 | The code for each lookup type is in a separate source file that is included in | |
5841 | the binary of Exim only if the corresponding compile-time option is set. The | |
9b371988 PH |
5842 | default settings in &_src/EDITME_& are: |
5843 | .code | |
5844 | LOOKUP_DBM=yes | |
5845 | LOOKUP_LSEARCH=yes | |
5846 | .endd | |
168e428f PH |
5847 | which means that only linear searching and DBM lookups are included by default. |
5848 | For some types of lookup (e.g. SQL databases), you need to install appropriate | |
5849 | libraries and header files before building Exim. | |
5850 | ||
5851 | ||
5852 | ||
5853 | ||
9b371988 PH |
5854 | .section "Single-key lookup types" "SECTsinglekeylookups" |
5855 | .cindex "lookup" "single-key types" | |
5856 | .cindex "single-key lookup" "list of types" | |
168e428f PH |
5857 | The following single-key lookup types are implemented: |
5858 | ||
9b371988 PH |
5859 | .ilist |
5860 | .cindex "cdb" "description of" | |
5861 | .cindex "lookup" "cdb" | |
5862 | .cindex "binary zero" "in lookup key" | |
5863 | &(cdb)&: The given file is searched as a Constant DataBase file, using the key | |
168e428f PH |
5864 | string without a terminating binary zero. The cdb format is designed for |
5865 | indexed files that are read frequently and never updated, except by total | |
5866 | re-creation. As such, it is particulary suitable for large files containing | |
5867 | aliases or other indexed data referenced by an MTA. Information about cdb can | |
5868 | be found in several places: | |
9b371988 PH |
5869 | .display |
5870 | &url(http://www.pobox.com/~djb/cdb.html) | |
5871 | &url(ftp://ftp.corpit.ru/pub/tinycdb/) | |
5872 | &url(http://packages.debian.org/stable/utils/freecdb.html) | |
5873 | .endd | |
168e428f PH |
5874 | A cdb distribution is not needed in order to build Exim with cdb support, |
5875 | because the code for reading cdb files is included directly in Exim itself. | |
5876 | However, no means of building or testing cdb files is provided with Exim, so | |
5877 | you need to obtain a cdb distribution in order to do this. | |
9b371988 PH |
5878 | .next |
5879 | .cindex "DBM" "lookup type" | |
5880 | .cindex "lookup" "dbm" | |
5881 | .cindex "binary zero" "in lookup key" | |
5882 | &(dbm)&: Calls to DBM library functions are used to extract data from the given | |
168e428f PH |
5883 | DBM file by looking up the record with the given key. A terminating binary |
5884 | zero is included in the key that is passed to the DBM library. See section | |
9b371988 PH |
5885 | &<<SECTdb>>& for a discussion of DBM libraries. |
5886 | ||
5887 | .cindex "Berkeley DB library" "file format" | |
168e428f | 5888 | For all versions of Berkeley DB, Exim uses the DB_HASH style of database |
9b371988 PH |
5889 | when building DBM files using the &%exim_dbmbuild%& utility. However, when |
5890 | using Berkeley DB versions 3 or 4, it opens existing databases for reading with | |
5891 | the DB_UNKNOWN option. This enables it to handle any of the types of database | |
168e428f PH |
5892 | that the library supports, and can be useful for accessing DBM files created by |
5893 | other applications. (For earlier DB versions, DB_HASH is always used.) | |
9b371988 PH |
5894 | .next |
5895 | .cindex "lookup" "dbmnz" | |
5896 | .cindex "lookup" "dbm &-- terminating zero" | |
5897 | .cindex "binary zero" "in lookup key" | |
5898 | .cindex "Courier" | |
5899 | .cindex "&_/etc/userdbshadow.dat_&" | |
5900 | .cindex "dmbnz lookup type" | |
5901 | &(dbmnz)&: This is the same as &(dbm)&, except that a terminating binary zero | |
168e428f PH |
5902 | is not included in the key that is passed to the DBM library. You may need this |
5903 | if you want to look up data in files that are created by or shared with some | |
5904 | other application that does not use terminating zeros. For example, you need to | |
9b371988 PH |
5905 | use &(dbmnz)& rather than &(dbm)& if you want to authenticate incoming SMTP |
5906 | calls using the passwords from Courier's &_/etc/userdbshadow.dat_& file. Exim's | |
5907 | utility program for creating DBM files (&'exim_dbmbuild'&) includes the zeros | |
5908 | by default, but has an option to omit them (see section &<<SECTdbmbuild>>&). | |
5909 | .next | |
5910 | .cindex "lookup" "dsearch" | |
5911 | .cindex "dsearch lookup type" | |
5912 | &(dsearch)&: The given file must be a directory; this is searched for a file | |
168e428f PH |
5913 | whose name is the key. The key may not contain any forward slash characters. |
5914 | The result of a successful lookup is the name of the file. An example of how | |
5915 | this lookup can be used to support virtual domains is given in section | |
9b371988 PH |
5916 | &<<SECTvirtualdomains>>&. |
5917 | .next | |
5918 | .cindex "lookup" "iplsearch" | |
5919 | .cindex "iplsearch lookup type" | |
5920 | &(iplsearch)&: The given file is a text file containing keys and data. A key is | |
168e428f PH |
5921 | terminated by a colon or white space or the end of the line. The keys in the |
5922 | file must be IP addresses, or IP addresses with CIDR masks. Keys that involve | |
5923 | IPv6 addresses must be enclosed in quotes to prevent the first internal colon | |
5924 | being interpreted as a key terminator. For example: | |
9b371988 PH |
5925 | .code |
5926 | 1.2.3.4: data for 1.2.3.4 | |
5927 | 192.168.0.0/16 data for 192.168.0.0/16 | |
5928 | "abcd::cdab": data for abcd::cdab | |
5929 | "abcd:abcd::/32" data for abcd:abcd::/32 | |
5930 | .endd | |
5931 | The key for an &(iplsearch)& lookup must be an IP address (without a mask). The | |
168e428f PH |
5932 | file is searched linearly, using the CIDR masks where present, until a matching |
5933 | key is found. The first key that matches is used; there is no attempt to find a | |
9b371988 PH |
5934 | &"best"& match. Apart from the way the keys are matched, the processing for |
5935 | &(iplsearch)& is the same as for &(lsearch)&. | |
5936 | ||
5937 | &*Warning 1*&: Unlike most other single-key lookup types, a file of data for | |
5938 | &(iplsearch)& can &'not'& be turned into a DBM or cdb file, because those | |
168e428f | 5939 | lookup types support only literal keys. |
9b371988 PH |
5940 | |
5941 | &*Warning 2*&: In a host list, you must always use &(net-iplsearch)& so that | |
168e428f | 5942 | the implicit key is the host's IP address rather than its name (see section |
9b371988 | 5943 | &<<SECThoslispatsikey>>&). |
168e428f | 5944 | |
9b371988 PH |
5945 | .next |
5946 | .cindex "linear search" | |
5947 | .cindex "lookup" "lsearch" | |
5948 | .cindex "lsearch lookup type" | |
5949 | &(lsearch)&: The given file is a text file that is searched linearly for a | |
168e428f PH |
5950 | line beginning with the search key, terminated by a colon or white space or the |
5951 | end of the line. The first occurrence that is found in the file is used. White | |
5952 | space between the key and the colon is permitted. The remainder of the line, | |
5953 | with leading and trailing white space removed, is the data. This can be | |
5954 | continued onto subsequent lines by starting them with any amount of white | |
5955 | space, but only a single space character is included in the data at such a | |
5956 | junction. If the data begins with a colon, the key must be terminated by a | |
5957 | colon, for example: | |
9b371988 PH |
5958 | .code |
5959 | baduser: :fail: | |
5960 | .endd | |
168e428f PH |
5961 | Empty lines and lines beginning with # are ignored, even if they occur in the |
5962 | middle of an item. This is the traditional textual format of alias files. Note | |
9b371988 | 5963 | that the keys in an &(lsearch)& file are literal strings. There is no |
168e428f | 5964 | wildcarding of any kind. |
9b371988 PH |
5965 | |
5966 | .cindex "lookup" "lsearch &-- colons in keys" | |
5967 | .cindex "white space" "in lsearch key" | |
5968 | In most &(lsearch)& files, keys are not required to contain colons or # | |
068aaea8 | 5969 | characters, or white space. However, if you need this feature, it is available. |
168e428f PH |
5970 | If a key begins with a doublequote character, it is terminated only by a |
5971 | matching quote (or end of line), and the normal escaping rules apply to its | |
9b371988 | 5972 | contents (see section &<<SECTstrings>>&). An optional colon is permitted after |
168e428f | 5973 | quoted keys (exactly as for unquoted keys). There is no special handling of |
9b371988 | 5974 | quotes for the data part of an &(lsearch)& line. |
168e428f | 5975 | |
9b371988 PH |
5976 | .next |
5977 | .cindex "NIS lookup type" | |
5978 | .cindex "lookup" "NIS" | |
5979 | .cindex "binary zero" "in lookup key" | |
5980 | &(nis)&: The given file is the name of a NIS map, and a NIS lookup is done with | |
168e428f | 5981 | the given key, without a terminating binary zero. There is a variant called |
9b371988 | 5982 | &(nis0)& which does include the terminating binary zero in the key. This is |
168e428f PH |
5983 | reportedly needed for Sun-style alias files. Exim does not recognize NIS |
5984 | aliases; the full map names must be used. | |
5985 | ||
9b371988 PH |
5986 | .next |
5987 | .cindex "wildlsearch lookup type" | |
5988 | .cindex "lookup" "wildlsearch" | |
5989 | .cindex "nwildlsearch lookup type" | |
5990 | .cindex "lookup" "nwildlsearch" | |
5991 | &(wildlsearch)& or &(nwildlsearch)&: These search a file linearly, like | |
5992 | &(lsearch)&, but instead of being interpreted as a literal string, each key in | |
5993 | the file may be wildcarded. The difference between these two lookup types is | |
5994 | that for &(wildlsearch)&, each key in the file is string-expanded before being | |
5995 | used, whereas for &(nwildlsearch)&, no expansion takes place. | |
5996 | ||
5997 | Like &(lsearch)&, the testing is done case-insensitively. The following forms | |
168e428f | 5998 | of wildcard are recognized: |
168e428f | 5999 | |
9b371988 PH |
6000 | . ==== As this is a nested list, any displays it contains must be indented |
6001 | . ==== as otherwise they are too far to the left. | |
6002 | ||
6003 | .olist | |
6004 | The string may begin with an asterisk to mean &"ends with"&. For example: | |
6005 | .code | |
6006 | *.a.b.c data for anything.a.b.c | |
6007 | *fish data for anythingfish | |
6008 | .endd | |
6009 | .next | |
6010 | The string may begin with a circumflex to indicate a regular expression. For | |
6011 | example, for &(wildlsearch)&: | |
6012 | .code | |
6013 | ^\N\d+\.a\.b\N data for <digits>.a.b | |
6014 | .endd | |
6015 | Note the use of &`\N`& to disable expansion of the contents of the regular | |
6016 | expression. If you are using &(nwildlsearch)&, where the keys are not | |
168e428f | 6017 | string-expanded, the equivalent entry is: |
9b371988 PH |
6018 | .code |
6019 | ^\d+\.a\.b data for <digits>.a.b | |
6020 | .endd | |
168e428f | 6021 | If the regular expression contains white space or colon characters, you must |
9b371988 PH |
6022 | either quote it (see &(lsearch)& above), or represent these characters in other |
6023 | ways. For example, &`\s`& can be used for white space and &`\x3A`& for a | |
168e428f PH |
6024 | colon. This may be easier than quoting, because if you quote, you have to |
6025 | escape all the backslashes inside the quotes. | |
6026 | ||
9b371988 PH |
6027 | &*Note*&: It is not possible to capture substrings in a regular expression |
6028 | match for later use, because the results of all lookups are cached. If a lookup | |
6029 | is repeated, the result is taken from the cache, and no actual pattern matching | |
d1e83bff | 6030 | takes place. The values of all the numeric variables are unset after a |
9b371988 | 6031 | &((n)wildlsearch)& match. |
d1e83bff | 6032 | |
9b371988 PH |
6033 | .next |
6034 | Although I cannot see it being of much use, the general matching function that | |
6035 | is used to implement &((n)wildlsearch)& means that the string may begin with a | |
6036 | lookup name terminated by a semicolon, and followed by lookup data. For | |
168e428f | 6037 | example: |
9b371988 PH |
6038 | .code |
6039 | cdb;/some/file data for keys that match the file | |
6040 | .endd | |
168e428f | 6041 | The data that is obtained from the nested lookup is discarded. |
9b371988 PH |
6042 | .endlist olist |
6043 | ||
168e428f | 6044 | Keys that do not match any of these patterns are interpreted literally. The |
9b371988 | 6045 | continuation rules for the data are the same as for &(lsearch)&, and keys may |
168e428f | 6046 | be followed by optional colons. |
168e428f | 6047 | |
9b371988 PH |
6048 | &*Warning*&: Unlike most other single-key lookup types, a file of data for |
6049 | &((n)wildlsearch)& can &'not'& be turned into a DBM or cdb file, because those | |
6050 | lookup types support only literal keys. | |
6051 | .endlist ilist | |
168e428f PH |
6052 | |
6053 | ||
9b371988 PH |
6054 | .section "Query-style lookup types" |
6055 | .cindex "lookup" "query-style types" | |
6056 | .cindex "query-style lookup" "list of types" | |
168e428f PH |
6057 | The supported query-style lookup types are listed below. Further details about |
6058 | many of them are given in later sections. | |
6059 | ||
9b371988 PH |
6060 | .ilist |
6061 | .cindex "DNS" "as a lookup type" | |
6062 | .cindex "lookup" "DNS" | |
6063 | &(dnsdb)&: This does a DNS search for one or more records whose domain names | |
6064 | are given in the supplied query. The resulting data is the contents of the | |
6065 | records. See section &<<SECTdnsdb>>&. | |
6066 | .next | |
6067 | .cindex "Interbase lookup type" | |
6068 | .cindex "lookup" "Interbase" | |
6069 | &(ibase)&: This does a lookup in an Interbase database. | |
6070 | .next | |
6071 | .cindex "LDAP" "lookup type" | |
6072 | .cindex "lookup" "LDAP" | |
6073 | &(ldap)&: This does an LDAP lookup using a query in the form of a URL, and | |
6074 | returns attributes from a single entry. There is a variant called &(ldapm)& | |
168e428f | 6075 | that permits values from multiple entries to be returned. A third variant |
9b371988 PH |
6076 | called &(ldapdn)& returns the Distinguished Name of a single entry instead of |
6077 | any attribute values. See section &<<SECTldap>>&. | |
6078 | .next | |
6079 | .cindex "MySQL" "lookup type" | |
6080 | .cindex "lookup" "MySQL" | |
6081 | &(mysql)&: The format of the query is an SQL statement that is passed to a | |
6082 | MySQL database. See section &<<SECTsql>>&. | |
6083 | .next | |
6084 | .cindex "NIS+ lookup type" | |
6085 | .cindex "lookup" "NIS+" | |
6086 | &(nisplus)&: This does a NIS+ lookup using a query that can specify the name of | |
6087 | the field to be returned. See section &<<SECTnisplus>>&. | |
6088 | .next | |
6089 | .cindex "Oracle" "lookup type" | |
6090 | .cindex "lookup" "Oracle" | |
6091 | &(oracle)&: The format of the query is an SQL statement that is passed to an | |
6092 | Oracle database. See section &<<SECTsql>>&. | |
6093 | .next | |
6094 | .cindex "lookup" "passwd" | |
6095 | .cindex "passwd lookup type" | |
6096 | .cindex "&_/etc/passwd_&" | |
6097 | &(passwd)& is a query-style lookup with queries that are just user names. The | |
6098 | lookup calls &[getpwnam()]& to interrogate the system password data, and on | |
6099 | success, the result string is the same as you would get from an &(lsearch)& | |
6100 | lookup on a traditional &_/etc/passwd file_&, though with &`*`& for the | |
168e428f | 6101 | password value. For example: |
9b371988 PH |
6102 | .code |
6103 | *:42:42:King Rat:/home/kr:/bin/bash | |
6104 | .endd | |
6105 | .next | |
6106 | .cindex "PostgreSQL lookup type" | |
6107 | .cindex "lookup" "PostgreSQL" | |
6108 | &(pgsql)&: The format of the query is an SQL statement that is passed to a | |
6109 | PostgreSQL database. See section &<<SECTsql>>&. | |
6110 | ||
6111 | .next | |
6112 | .new | |
6113 | .cindex "sqlite lookup type" | |
6114 | .cindex "lookup" "sqlite" | |
6115 | &(sqlite)&: The format of the query is a file name followed by an SQL statement | |
6116 | that is passed to an SQLite database. See section &<<SECTsqlite>>&. | |
6117 | .wen | |
6118 | ||
6119 | .next | |
6120 | &(testdb)&: This is a lookup type that is used for testing Exim. It is | |
168e428f | 6121 | not likely to be useful in normal operation. |
9b371988 PH |
6122 | .next |
6123 | .cindex "whoson lookup type" | |
6124 | .cindex "lookup" "whoson" | |
6125 | &(whoson)&: &'Whoson'& (&url(http://whoson.sourceforge.net)) is a proposed | |
168e428f PH |
6126 | Internet protocol that allows Internet server programs to check whether a |
6127 | particular (dynamically allocated) IP address is currently allocated to a known | |
6128 | (trusted) user and, optionally, to obtain the identity of the said user. In | |
9b371988 | 6129 | Exim, this can be used to implement &"POP before SMTP"& checking using ACL |
168e428f | 6130 | statements such as |
9b371988 | 6131 | .code |
168e428f PH |
6132 | require condition = \ |
6133 | ${lookup whoson {$sender_host_address}{yes}{no}} | |
9b371988 PH |
6134 | .endd |
6135 | .new | |
168e428f | 6136 | The query consists of a single IP address. The value returned is the name of |
9b371988 PH |
6137 | the authenticated user, which is stored in the variable &$value$&. However, in |
6138 | this example, the data in &$value$& is not used; the result of the lookup is | |
6139 | one of the fixed strings &"yes"& or &"no"&. | |
6140 | .wen | |
6141 | .endlist | |
168e428f PH |
6142 | |
6143 | ||
6144 | ||
9b371988 PH |
6145 | .section "Temporary errors in lookups" |
6146 | .cindex "lookup" "temporary error in" | |
168e428f | 6147 | Lookup functions can return temporary error codes if the lookup cannot be |
068aaea8 | 6148 | completed. For example, an SQL or LDAP database might be unavailable. For this |
168e428f PH |
6149 | reason, it is not advisable to use a lookup that might do this for critical |
6150 | options such as a list of local domains. | |
6151 | ||
6152 | When a lookup cannot be completed in a router or transport, delivery | |
6153 | of the message (to the relevant address) is deferred, as for any other | |
6154 | temporary error. In other circumstances Exim may assume the lookup has failed, | |
6155 | or may give up altogether. | |
6156 | ||
6157 | ||
6158 | ||
9b371988 PH |
6159 | .section "Default values in single-key lookups" "SECTdefaultvaluelookups" |
6160 | .cindex "wildcard lookups" | |
6161 | .cindex "lookup" "default values" | |
6162 | .cindex "lookup" "wildcard" | |
6163 | .cindex "lookup" "* added to type" | |
6164 | .cindex "default" "in single-key lookups" | |
6165 | In this context, a &"default value"& is a value specified by the administrator | |
168e428f PH |
6166 | that is to be used if a lookup fails. |
6167 | ||
9b371988 PH |
6168 | If &"*"& is added to a single-key lookup type (for example, &%lsearch*%&) |
6169 | and the initial lookup fails, the key &"*"& is looked up in the file to | |
6170 | provide a default value. See also the section on partial matching below. | |
168e428f | 6171 | |
9b371988 PH |
6172 | .cindex "*@ with single-key lookup" |
6173 | .cindex "lookup" "*@ added to type" | |
6174 | .cindex "alias file" "per-domain default" | |
6175 | Alternatively, if &"*@"& is added to a single-key lookup type (for example | |
6176 | &%dbm*@%&) then, if the initial lookup fails and the key contains an @ | |
168e428f | 6177 | character, a second lookup is done with everything before the last @ replaced |
9b371988 | 6178 | by *. This makes it possible to provide per-domain defaults in alias files |
168e428f | 6179 | that include the domains in the keys. If the second lookup fails (or doesn't |
9b371988 PH |
6180 | take place because there is no @ in the key), &"*"& is looked up. |
6181 | For example, a &(redirect)& router might contain: | |
6182 | .code | |
6183 | data = ${lookup{$local_part@$domain}lsearch*@{/etc/mix-aliases}} | |
6184 | .endd | |
6185 | Suppose the address that is being processed is &'jane@eyre.example'&. Exim | |
168e428f | 6186 | looks up these keys, in this order: |
9b371988 PH |
6187 | .code |
6188 | jane@eyre.example | |
6189 | *@eyre.example | |
6190 | * | |
6191 | .endd | |
6192 | The data is taken from whichever key it finds first. &*Note*&: In an | |
6193 | &(lsearch)& file, this does not mean the first of these keys in the file. A | |
168e428f PH |
6194 | complete scan is done for each key, and only if it is not found at all does |
6195 | Exim move on to try the next key. | |
6196 | ||
6197 | ||
6198 | ||
9b371988 PH |
6199 | .section "Partial matching in single-key lookups" "SECTpartiallookup" |
6200 | .cindex "partial matching" | |
6201 | .cindex "wildcard lookups" | |
6202 | .cindex "lookup" "partial matching" | |
6203 | .cindex "lookup" "wildcard" | |
6204 | .cindex "asterisk" "in search type" | |
168e428f PH |
6205 | The normal operation of a single-key lookup is to search the file for an exact |
6206 | match with the given key. However, in a number of situations where domains are | |
6207 | being looked up, it is useful to be able to do partial matching. In this case, | |
9b371988 | 6208 | information in the file that has a key starting with &"*."& is matched by any |
168e428f PH |
6209 | domain that ends with the components that follow the full stop. For example, if |
6210 | a key in a DBM file is | |
9b371988 PH |
6211 | .code |
6212 | *.dates.fict.example | |
6213 | .endd | |
168e428f | 6214 | then when partial matching is enabled this is matched by (amongst others) |
9b371988 PH |
6215 | &'2001.dates.fict.example'& and &'1984.dates.fict.example'&. It is also matched |
6216 | by &'dates.fict.example'&, if that does not appear as a separate key in the | |
168e428f PH |
6217 | file. |
6218 | ||
9b371988 | 6219 | &*Note*&: Partial matching is not available for query-style lookups. It is |
168e428f | 6220 | also not available for any lookup items in address lists (see section |
9b371988 | 6221 | &<<SECTaddresslist>>&). |
168e428f PH |
6222 | |
6223 | Partial matching is implemented by doing a series of separate lookups using | |
6224 | keys constructed by modifying the original subject key. This means that it can | |
6225 | be used with any of the single-key lookup types, provided that | |
6226 | partial matching keys | |
9b371988 | 6227 | beginning with a special prefix (default &"*."&) are included in the data file. |
168e428f PH |
6228 | Keys in the file that do not begin with the prefix are matched only by |
6229 | unmodified subject keys when partial matching is in use. | |
6230 | ||
9b371988 PH |
6231 | Partial matching is requested by adding the string &"partial-"& to the front of |
6232 | the name of a single-key lookup type, for example, &%partial-dbm%&. When this | |
6233 | is done, the subject key is first looked up unmodified; if that fails, &"*."& | |
168e428f | 6234 | is added at the start of the subject key, and it is looked up again. If that |
9b371988 PH |
6235 | fails, further lookups are tried with dot-separated components removed from the |
6236 | start of the subject key, one-by-one, and &"*."& added on the front of what | |
6237 | remains. | |
168e428f | 6238 | |
9b371988 | 6239 | A minimum number of two non-* components are required. This can be adjusted |
168e428f | 6240 | by including a number before the hyphen in the search type. For example, |
9b371988 PH |
6241 | &%partial3-lsearch%& specifies a minimum of three non-* components in the |
6242 | modified keys. Omitting the number is equivalent to &"partial2-"&. If the | |
6243 | subject key is &'2250.dates.fict.example'& then the following keys are looked | |
6244 | up when the minimum number of non-* components is two: | |
6245 | .code | |
6246 | 2250.dates.fict.example | |
6247 | *.2250.dates.fict.example | |
6248 | *.dates.fict.example | |
6249 | *.fict.example | |
6250 | .endd | |
168e428f PH |
6251 | As soon as one key in the sequence is successfully looked up, the lookup |
6252 | finishes. | |
6253 | ||
9b371988 PH |
6254 | .cindex "lookup" "partial matching &-- changing prefix" |
6255 | .cindex "prefix" "for partial matching" | |
6256 | The use of &"*."& as the partial matching prefix is a default that can be | |
168e428f PH |
6257 | changed. The motivation for this feature is to allow Exim to operate with file |
6258 | formats that are used by other MTAs. A different prefix can be supplied in | |
9b371988 PH |
6259 | parentheses instead of the hyphen after &"partial"&. For example: |
6260 | .code | |
6261 | domains = partial(.)lsearch;/some/file | |
6262 | .endd | |
6263 | In this example, if the domain is &'a.b.c'&, the sequence of lookups is | |
6264 | &`a.b.c`&, &`.a.b.c`&, and &`.b.c`& (the default minimum of 2 non-wild | |
168e428f PH |
6265 | components is unchanged). The prefix may consist of any punctuation characters |
6266 | other than a closing parenthesis. It may be empty, for example: | |
9b371988 PH |
6267 | .code |
6268 | domains = partial1()cdb;/some/file | |
6269 | .endd | |
6270 | For this example, if the domain is &'a.b.c'&, the sequence of lookups is | |
6271 | &`a.b.c`&, &`b.c`&, and &`c`&. | |
6272 | ||
6273 | If &"partial0"& is specified, what happens at the end (when the lookup with | |
6274 | just one non-wild component has failed, and the original key is shortened right | |
6275 | down to the null string) depends on the prefix: | |
6276 | ||
6277 | .ilist | |
6278 | If the prefix has zero length, the whole lookup fails. | |
6279 | .next | |
6280 | If the prefix has length 1, a lookup for just the prefix is done. For | |
6281 | example, the final lookup for &"partial0(.)"& is for &`.`& alone. | |
6282 | .next | |
6283 | Otherwise, if the prefix ends in a dot, the dot is removed, and the | |
168e428f | 6284 | remainder is looked up. With the default prefix, therefore, the final lookup is |
9b371988 PH |
6285 | for &"*"& on its own. |
6286 | .next | |
6287 | Otherwise, the whole prefix is looked up. | |
6288 | .endlist | |
168e428f | 6289 | |
168e428f | 6290 | |
9b371988 PH |
6291 | If the search type ends in &"*"& or &"*@"& (see section |
6292 | &<<SECTdefaultvaluelookups>>& above), the search for an ultimate default that | |
6293 | this implies happens after all partial lookups have failed. If &"partial0"& is | |
6294 | specified, adding &"*"& to the search type has no effect with the default | |
6295 | prefix, because the &"*"& key is already included in the sequence of partial | |
168e428f | 6296 | lookups. However, there might be a use for lookup types such as |
9b371988 | 6297 | &"partial0(.)lsearch*"&. |
168e428f | 6298 | |
9b371988 | 6299 | The use of &"*"& in lookup partial matching differs from its use as a wildcard |
168e428f | 6300 | in domain lists and the like. Partial matching works only in terms of |
9b371988 | 6301 | dot-separated components; a key such as &`*fict.example`& |
168e428f PH |
6302 | in a database file is useless, because the asterisk in a partial matching |
6303 | subject key is always followed by a dot. | |
6304 | ||
6305 | ||
6306 | ||
6307 | ||
9b371988 PH |
6308 | .section "Lookup caching" |
6309 | .cindex "lookup" "caching" | |
6310 | .cindex "caching" "lookup data" | |
168e428f PH |
6311 | Exim caches all lookup results in order to avoid needless repetition of |
6312 | lookups. However, because (apart from the daemon) Exim operates as a collection | |
6313 | of independent, short-lived processes, this caching applies only within a | |
9b371988 | 6314 | single Exim process. There is no inter-process lookup caching facility. |
168e428f PH |
6315 | |
6316 | For single-key lookups, Exim keeps the relevant files open in case there is | |
6317 | another lookup that needs them. In some types of configuration this can lead to | |
6318 | many files being kept open for messages with many recipients. To avoid hitting | |
6319 | the operating system limit on the number of simultaneously open files, Exim | |
6320 | closes the least recently used file when it needs to open more files than its | |
9b371988 | 6321 | own internal limit, which can be changed via the &%lookup_open_max%& option. |
168e428f PH |
6322 | |
6323 | The single-key lookup files are closed and the lookup caches are flushed at | |
9b371988 PH |
6324 | strategic points during delivery &-- for example, after all routing is |
6325 | complete. | |
168e428f PH |
6326 | |
6327 | ||
6328 | ||
6329 | ||
9b371988 PH |
6330 | .section "Quoting lookup data" |
6331 | .cindex "lookup" "quoting" | |
6332 | .cindex "quoting" "in lookups" | |
168e428f PH |
6333 | When data from an incoming message is included in a query-style lookup, there |
6334 | is the possibility of special characters in the data messing up the syntax of | |
6335 | the query. For example, a NIS+ query that contains | |
9b371988 PH |
6336 | .code |
6337 | [name=$local_part] | |
6338 | .endd | |
168e428f PH |
6339 | will be broken if the local part happens to contain a closing square bracket. |
6340 | For NIS+, data can be enclosed in double quotes like this: | |
9b371988 PH |
6341 | .code |
6342 | [name="$local_part"] | |
6343 | .endd | |
168e428f PH |
6344 | but this still leaves the problem of a double quote in the data. The rule for |
6345 | NIS+ is that double quotes must be doubled. Other lookup types have different | |
6346 | rules, and to cope with the differing requirements, an expansion operator | |
6347 | of the following form is provided: | |
9b371988 PH |
6348 | .code |
6349 | ${quote_<lookup-type>:<string>} | |
6350 | .endd | |
168e428f | 6351 | For example, the safest way to write the NIS+ query is |
9b371988 PH |
6352 | .code |
6353 | [name="${quote_nisplus:$local_part}"] | |
6354 | .endd | |
6355 | See chapter &<<CHAPexpand>>& for full coverage of string expansions. The quote | |
168e428f PH |
6356 | operator can be used for all lookup types, but has no effect for single-key |
6357 | lookups, since no quoting is ever needed in their key strings. | |
6358 | ||
6359 | ||
6360 | ||
6361 | ||
9b371988 PH |
6362 | .section "More about dnsdb" "SECTdnsdb" |
6363 | .cindex "dnsdb lookup" | |
6364 | .cindex "lookup" "dnsdb" | |
6365 | .cindex "DNS" "as a lookup type" | |
6366 | The &(dnsdb)& lookup type uses the DNS as its database. A simple query consists | |
168e428f PH |
6367 | of a record type and a domain name, separated by an equals sign. For example, |
6368 | an expansion string could contain: | |
9b371988 PH |
6369 | .code |
6370 | ${lookup dnsdb{mx=a.b.example}{$value}fail} | |
6371 | .endd | |
6372 | .new | |
6373 | If the lookup succeeds, the result is placed in &$value$&, which in this case | |
6374 | is used on its own as the result. If the lookup succeeds, the &`fail`& keyword | |
6375 | causes a &'forced expansion failure'& &-- see section &<<SECTforexpfai>>& for | |
6376 | an explanation of what this means. | |
6377 | .wen | |
168e428f PH |
6378 | |
6379 | The supported DNS record types are A, CNAME, MX, NS, PTR, SRV, and TXT, and, | |
6380 | when Exim is compiled with IPv6 support, AAAA (and A6 if that is also | |
6381 | configured). If no type is given, TXT is assumed. When the type is PTR, | |
6382 | the data can be an IP address, written as normal; inversion and the addition of | |
9b371988 PH |
6383 | &%in-addr.arpa%& or &%ip6.arpa%& happens automatically. For example: |
6384 | .code | |
6385 | ${lookup dnsdb{ptr=192.168.4.5}{$value}fail} | |
6386 | .endd | |
168e428f PH |
6387 | If the data for a PTR record is not a syntactically valid IP address, it is not |
6388 | altered and nothing is added. | |
6389 | ||
9b371988 PH |
6390 | .cindex "MX record" "in &(dnsdb)& lookup" |
6391 | .cindex "SRV record" "in &(dnsdb)& lookup" | |
068aaea8 PH |
6392 | For an MX lookup, both the preference value and the host name are returned for |
6393 | each record, separated by a space. For an SRV lookup, the priority, weight, | |
6394 | port, and host name are returned for each record, separated by spaces. | |
6395 | ||
168e428f PH |
6396 | For any record type, if multiple records are found (or, for A6 lookups, if a |
6397 | single record leads to multiple addresses), the data is returned as a | |
6398 | concatenation, with newline as the default separator. The order, of course, | |
6399 | depends on the DNS resolver. You can specify a different separator character | |
6400 | between multiple records by putting a right angle-bracket followed immediately | |
6401 | by the new separator at the start of the query. For example: | |
9b371988 PH |
6402 | .code |
6403 | ${lookup dnsdb{>: a=host1.example}} | |
6404 | .endd | |
168e428f | 6405 | It is permitted to specify a space as the separator character. Further |
068aaea8 | 6406 | white space is ignored. |
168e428f | 6407 | |
9b371988 PH |
6408 | .section "Pseudo dnsdb record types" |
6409 | .cindex "MX record" "in &(dnsdb)& lookup" | |
068aaea8 PH |
6410 | By default, both the preference value and the host name are returned for |
6411 | each MX record, separated by a space. If you want only host names, you can use | |
6412 | the pseudo-type MXH: | |
9b371988 PH |
6413 | .code |
6414 | ${lookup dnsdb{mxh=a.b.example}} | |
6415 | .endd | |
068aaea8 PH |
6416 | In this case, the preference values are omitted, and just the host names are |
6417 | returned. | |
168e428f | 6418 | |
9b371988 PH |
6419 | .cindex "name server" "for enclosing domain" |
6420 | Another pseudo-type is ZNS (for &"zone NS"&). It performs a lookup for NS | |
168e428f PH |
6421 | records on the given domain, but if none are found, it removes the first |
6422 | component of the domain name, and tries again. This process continues until NS | |
6423 | records are found or there are no more components left (or there is a DNS | |
6424 | error). In other words, it may return the name servers for a top-level domain, | |
6425 | but it never returns the root name servers. If there are no NS records for the | |
6426 | top-level domain, the lookup fails. Consider these examples: | |
9b371988 PH |
6427 | .code |
6428 | ${lookup dnsdb{zns=xxx.quercite.com}} | |
6429 | ${lookup dnsdb{zns=xxx.edu}} | |
6430 | .endd | |
168e428f | 6431 | Assuming that in each case there are no NS records for the full domain name, |
9b371988 PH |
6432 | the first returns the name servers for &%quercite.com%&, and the second returns |
6433 | the name servers for &%edu%&. | |
168e428f PH |
6434 | |
6435 | You should be careful about how you use this lookup because, unless the | |
6436 | top-level domain does not exist, the lookup always returns some host names. The | |
6437 | sort of use to which this might be put is for seeing if the name servers for a | |
6438 | given domain are on a blacklist. You can probably assume that the name servers | |
9b371988 PH |
6439 | for the high-level domains such as &%com%& or &%co.uk%& are not going to be on |
6440 | such a list. | |
168e428f | 6441 | |
9b371988 PH |
6442 | .new |
6443 | .cindex "CSA" "in &(dnsdb)& lookup" | |
6444 | A third pseudo-type is CSA (Client SMTP Authorization). This looks up SRV | |
068aaea8 | 6445 | records according to the CSA rules, which are described in section |
9b371988 PH |
6446 | &<<SECTverifyCSA>>&. Although &(dnsdb)& supports SRV lookups directly, this is |
6447 | not sufficient because of the extra parent domain search behaviour of CSA. The | |
068aaea8 | 6448 | result of a successful lookup such as: |
9b371988 | 6449 | .code |
068aaea8 | 6450 | ${lookup dnsdb {csa=$sender_helo_name}} |
9b371988 | 6451 | .endd |
068aaea8 | 6452 | has two space-separated fields: an authorization code and a target host name. |
9b371988 PH |
6453 | The authorization code can be &"Y"& for yes, &"N"& for no, &"X"& for explicit |
6454 | authorization required but absent, or &"?"& for unknown. | |
6455 | .wen | |
168e428f PH |
6456 | |
6457 | ||
9b371988 PH |
6458 | .section "Multiple dnsdb lookups" |
6459 | In the previous sections, &(dnsdb)& lookups for a single domain are described. | |
168e428f | 6460 | However, you can specify a list of domains or IP addresses in a single |
9b371988 | 6461 | &(dnsdb)& lookup. The list is specified in the normal Exim way, with colon as |
168e428f | 6462 | the default separator, but with the ability to change this. For example: |
9b371988 PH |
6463 | .code |
6464 | ${lookup dnsdb{one.domain.com:two.domain.com}} | |
6465 | ${lookup dnsdb{a=one.host.com:two.host.com}} | |
6466 | ${lookup dnsdb{ptr = <; 1.2.3.4 ; 4.5.6.8}} | |
6467 | .endd | |
168e428f PH |
6468 | In order to retain backwards compatibility, there is one special case: if |
6469 | the lookup type is PTR and no change of separator is specified, Exim looks | |
6470 | to see if the rest of the string is precisely one IPv6 address. In this | |
6471 | case, it does not treat it as a list. | |
6472 | ||
6473 | The data from each lookup is concatenated, with newline separators by default, | |
6474 | in the same way that multiple DNS records for a single item are handled. A | |
6475 | different separator can be specified, as described above. | |
6476 | ||
9b371988 | 6477 | The &(dnsdb)& lookup fails only if all the DNS lookups fail. If there is a |
168e428f PH |
6478 | temporary DNS error for any of them, the behaviour is controlled by |
6479 | an optional keyword followed by a comma that may appear before the record | |
9b371988 PH |
6480 | type. The possible keywords are &"defer_strict"&, &"defer_never"&, and |
6481 | &"defer_lax"&. With &"strict"& behaviour, any temporary DNS error causes the | |
6482 | whole lookup to defer. With &"never"& behaviour, a temporary DNS error is | |
168e428f | 6483 | ignored, and the behaviour is as if the DNS lookup failed to find anything. |
9b371988 | 6484 | With &"lax"& behaviour, all the queries are attempted, but a temporary DNS |
168e428f | 6485 | error causes the whole lookup to defer only if none of the other lookups |
9b371988 PH |
6486 | succeed. The default is &"lax"&, so the following lookups are equivalent: |
6487 | .code | |
6488 | ${lookup dnsdb{defer_lax,a=one.host.com:two.host.com}} | |
6489 | ${lookup dnsdb{a=one.host.com:two.host.com}} | |
6490 | .endd | |
168e428f PH |
6491 | Thus, in the default case, as long as at least one of the DNS lookups |
6492 | yields some data, the lookup succeeds. | |
6493 | ||
6494 | ||
6495 | ||
6496 | ||
9b371988 PH |
6497 | .section "More about LDAP" "SECTldap" |
6498 | .cindex "LDAP lookup" | |
6499 | .cindex "lookup" "LDAP" | |
6500 | .cindex "Solaris" "LDAP" | |
168e428f | 6501 | The original LDAP implementation came from the University of Michigan; this has |
9b371988 | 6502 | become &"Open LDAP"&, and there are now two different releases. Another |
168e428f PH |
6503 | implementation comes from Netscape, and Solaris 7 and subsequent releases |
6504 | contain inbuilt LDAP support. Unfortunately, though these are all compatible at | |
6505 | the lookup function level, their error handling is different. For this reason | |
6506 | it is necessary to set a compile-time variable when building Exim with LDAP, to | |
6507 | indicate which LDAP library is in use. One of the following should appear in | |
9b371988 PH |
6508 | your &_Local/Makefile_&: |
6509 | .code | |
6510 | LDAP_LIB_TYPE=UMICHIGAN | |
6511 | LDAP_LIB_TYPE=OPENLDAP1 | |
6512 | LDAP_LIB_TYPE=OPENLDAP2 | |
6513 | LDAP_LIB_TYPE=NETSCAPE | |
6514 | LDAP_LIB_TYPE=SOLARIS | |
6515 | .endd | |
6516 | If LDAP_LIB_TYPE is not set, Exim assumes &`OPENLDAP1`&, which has the | |
168e428f PH |
6517 | same interface as the University of Michigan version. |
6518 | ||
6519 | There are three LDAP lookup types in Exim. These behave slightly differently in | |
6520 | the way they handle the results of a query: | |
6521 | ||
9b371988 PH |
6522 | .ilist |
6523 | &(ldap)& requires the result to contain just one entry; if there are more, it | |
168e428f | 6524 | gives an error. |
9b371988 PH |
6525 | .next |
6526 | &(ldapdn)& also requires the result to contain just one entry, but it is the | |
168e428f | 6527 | Distinguished Name that is returned rather than any attribute values. |
9b371988 PH |
6528 | .next |
6529 | &(ldapm)& permits the result to contain more than one entry; the attributes | |
6530 | from all of them are returned. | |
6531 | .endlist | |
168e428f PH |
6532 | |
6533 | ||
9b371988 | 6534 | For &(ldap)& and &(ldapm)&, if a query finds only entries with no attributes, |
168e428f PH |
6535 | Exim behaves as if the entry did not exist, and the lookup fails. The format of |
6536 | the data returned by a successful lookup is described in the next section. | |
6537 | First we explain how LDAP queries are coded. | |
6538 | ||
6539 | ||
9b371988 PH |
6540 | .section "Format of LDAP queries" "SECTforldaque" |
6541 | .cindex "LDAP" "query format" | |
168e428f | 6542 | An LDAP query takes the form of a URL as defined in RFC 2255. For example, in |
9b371988 PH |
6543 | the configuration of a &(redirect)& router one might have this setting: |
6544 | .code | |
168e428f PH |
6545 | data = ${lookup ldap \ |
6546 | {ldap:///cn=$local_part,o=University%20of%20Cambridge,\ | |
6547 | c=UK?mailbox?base?}} | |
9b371988 PH |
6548 | .endd |
6549 | .cindex "LDAP" "with TLS" | |
6550 | The URL may begin with &`ldap`& or &`ldaps`& if your LDAP library supports | |
168e428f PH |
6551 | secure (encrypted) LDAP connections. The second of these ensures that an |
6552 | encrypted TLS connection is used. | |
6553 | ||
6554 | ||
9b371988 PH |
6555 | .section "LDAP quoting" |
6556 | .cindex "LDAP" "quoting" | |
168e428f PH |
6557 | Two levels of quoting are required in LDAP queries, the first for LDAP itself |
6558 | and the second because the LDAP query is represented as a URL. Furthermore, | |
6559 | within an LDAP query, two different kinds of quoting are required. For this | |
6560 | reason, there are two different LDAP-specific quoting operators. | |
6561 | ||
9b371988 | 6562 | The &%quote_ldap%& operator is designed for use on strings that are part of |
168e428f PH |
6563 | filter specifications. Conceptually, it first does the following conversions on |
6564 | the string: | |
9b371988 | 6565 | .code |
168e428f PH |
6566 | * => \2A |
6567 | ( => \28 | |
6568 | ) => \29 | |
6569 | \ => \5C | |
9b371988 | 6570 | .endd |
168e428f | 6571 | in accordance with RFC 2254. The resulting string is then quoted according |
9b371988 PH |
6572 | to the rules for URLs, that is, all non-alphanumeric characters except |
6573 | .code | |
6574 | ! $ ' - . _ ( ) * + | |
6575 | .endd | |
168e428f | 6576 | are converted to their hex values, preceded by a percent sign. For example: |
9b371988 PH |
6577 | .code |
6578 | ${quote_ldap: a(bc)*, a<yz>; } | |
6579 | .endd | |
168e428f | 6580 | yields |
9b371988 PH |
6581 | .code |
6582 | %20a%5C28bc%5C29%5C2A%2C%20a%3Cyz%3E%3B%20 | |
6583 | .endd | |
168e428f | 6584 | Removing the URL quoting, this is (with a leading and a trailing space): |
9b371988 PH |
6585 | .code |
6586 | a\28bc\29\2A, a<yz>; | |
6587 | .endd | |
6588 | The &%quote_ldap_dn%& operator is designed for use on strings that are part of | |
168e428f PH |
6589 | base DN specifications in queries. Conceptually, it first converts the string |
6590 | by inserting a backslash in front of any of the following characters: | |
9b371988 PH |
6591 | .code |
6592 | , + " \ < > ; | |
6593 | .endd | |
168e428f PH |
6594 | It also inserts a backslash before any leading spaces or # characters, and |
6595 | before any trailing spaces. (These rules are in RFC 2253.) The resulting string | |
6596 | is then quoted according to the rules for URLs. For example: | |
9b371988 PH |
6597 | .code |
6598 | ${quote_ldap_dn: a(bc)*, a<yz>; } | |
6599 | .endd | |
168e428f | 6600 | yields |
9b371988 PH |
6601 | .code |
6602 | %5C%20a(bc)*%5C%2C%20a%5C%3Cyz%5C%3E%5C%3B%5C%20 | |
6603 | .endd | |
168e428f | 6604 | Removing the URL quoting, this is (with a trailing space): |
9b371988 | 6605 | .code |
168e428f | 6606 | \ a(bc)*\, a\<yz\>\;\ |
9b371988 | 6607 | .endd |
168e428f PH |
6608 | There are some further comments about quoting in the section on LDAP |
6609 | authentication below. | |
6610 | ||
6611 | ||
9b371988 PH |
6612 | .section "LDAP connections" |
6613 | .cindex "LDAP" "connections" | |
168e428f PH |
6614 | The connection to an LDAP server may either be over TCP/IP, or, when OpenLDAP |
6615 | is in use, via a Unix domain socket. The example given above does not specify | |
6616 | an LDAP server. A server that is reached by TCP/IP can be specified in a query | |
6617 | by starting it with | |
9b371988 PH |
6618 | .code |
6619 | ldap://<hostname>:<port>/... | |
6620 | .endd | |
168e428f PH |
6621 | If the port (and preceding colon) are omitted, the standard LDAP port (389) is |
6622 | used. When no server is specified in a query, a list of default servers is | |
9b371988 | 6623 | taken from the &%ldap_default_servers%& configuration option. This supplies a |
168e428f PH |
6624 | colon-separated list of servers which are tried in turn until one successfully |
6625 | handles a query, or there is a serious error. Successful handling either | |
6626 | returns the requested data, or indicates that it does not exist. Serious errors | |
6627 | are syntactical, or multiple values when only a single value is expected. | |
6628 | Errors which cause the next server to be tried are connection failures, bind | |
6629 | failures, and timeouts. | |
6630 | ||
6631 | For each server name in the list, a port number can be given. The standard way | |
6632 | of specifing a host and port is to use a colon separator (RFC 1738). Because | |
9b371988 | 6633 | &%ldap_default_servers%& is a colon-separated list, such colons have to be |
168e428f | 6634 | doubled. For example |
9b371988 PH |
6635 | .code |
6636 | ldap_default_servers = ldap1.example.com::145:ldap2.example.com | |
6637 | .endd | |
6638 | If &%ldap_default_servers%& is unset, a URL with no server name is passed | |
168e428f PH |
6639 | to the LDAP library with no server name, and the library's default (normally |
6640 | the local host) is used. | |
6641 | ||
6642 | If you are using the OpenLDAP library, you can connect to an LDAP server using | |
6643 | a Unix domain socket instead of a TCP/IP connection. This is specified by using | |
9b371988 | 6644 | &`ldapi`& instead of &`ldap`& in LDAP queries. What follows here applies only |
168e428f PH |
6645 | to OpenLDAP. If Exim is compiled with a different LDAP library, this feature is |
6646 | not available. | |
6647 | ||
6648 | For this type of connection, instead of a host name for the server, a pathname | |
6649 | for the socket is required, and the port number is not relevant. The pathname | |
9b371988 | 6650 | can be specified either as an item in &%ldap_default_servers%&, or inline in |
168e428f | 6651 | the query. In the former case, you can have settings such as |
9b371988 PH |
6652 | .code |
6653 | ldap_default_servers = /tmp/ldap.sock : backup.ldap.your.domain | |
6654 | .endd | |
168e428f | 6655 | When the pathname is given in the query, you have to escape the slashes as |
9b371988 PH |
6656 | &`%2F`& to fit in with the LDAP URL syntax. For example: |
6657 | .code | |
6658 | ${lookup ldap {ldapi://%2Ftmp%2Fldap.sock/o=... | |
6659 | .endd | |
6660 | When Exim processes an LDAP lookup and finds that the &"hostname"& is really | |
168e428f | 6661 | a pathname, it uses the Unix domain socket code, even if the query actually |
9b371988 | 6662 | specifies &`ldap`& or &`ldaps`&. In particular, no encryption is used for a |
168e428f | 6663 | socket connection. This behaviour means that you can use a setting of |
9b371988 PH |
6664 | &%ldap_default_servers%& such as in the example above with traditional &`ldap`& |
6665 | or &`ldaps`& queries, and it will work. First, Exim tries a connection via | |
168e428f PH |
6666 | the Unix domain socket; if that fails, it tries a TCP/IP connection to the |
6667 | backup host. | |
6668 | ||
9b371988 | 6669 | If an explicit &`ldapi`& type is given in a query when a host name is |
168e428f | 6670 | specified, an error is diagnosed. However, if there are more items in |
9b371988 | 6671 | &%ldap_default_servers%&, they are tried. In other words: |
168e428f | 6672 | |
9b371988 PH |
6673 | .ilist |
6674 | Using a pathname with &`ldap`& or &`ldaps`& forces the use of the Unix domain | |
168e428f | 6675 | interface. |
9b371988 PH |
6676 | .next |
6677 | Using &`ldapi`& with a host name causes an error. | |
6678 | .endlist | |
168e428f PH |
6679 | |
6680 | ||
9b371988 PH |
6681 | Using &`ldapi`& with no host or path in the query, and no setting of |
6682 | &%ldap_default_servers%&, does whatever the library does by default. | |
168e428f PH |
6683 | |
6684 | ||
6685 | ||
9b371988 PH |
6686 | .section "LDAP authentication and control information" |
6687 | .cindex "LDAP" "authentication" | |
168e428f PH |
6688 | The LDAP URL syntax provides no way of passing authentication and other control |
6689 | information to the server. To make this possible, the URL in an LDAP query may | |
9b371988 | 6690 | be preceded by any number of <&'name'&>=<&'value'&> settings, separated by |
168e428f PH |
6691 | spaces. If a value contains spaces it must be enclosed in double quotes, and |
6692 | when double quotes are used, backslash is interpreted in the usual way inside | |
6693 | them. The following names are recognized: | |
9b371988 PH |
6694 | .display |
6695 | &`DEREFERENCE`& set the dereferencing parameter | |
6696 | &`NETTIME `& set a timeout for a network operation | |
6697 | &`USER `& set the DN, for authenticating the LDAP bind | |
6698 | &`PASS `& set the password, likewise | |
6699 | &`SIZE `& set the limit for the number of entries returned | |
6700 | &`TIME `& set the maximum waiting time for a query | |
6701 | .endd | |
6702 | The value of the DEREFERENCE parameter must be one of the words &"never"&, | |
6703 | &"searching"&, &"finding"&, or &"always"&. | |
168e428f PH |
6704 | |
6705 | The name CONNECT is an obsolete name for NETTIME, retained for | |
6706 | backwards compatibility. This timeout (specified as a number of seconds) is | |
6707 | enforced from the client end for operations that can be carried out over a | |
6708 | network. Specifically, it applies to network connections and calls to the | |
9b371988 | 6709 | &'ldap_result()'& function. If the value is greater than zero, it is used if |
168e428f PH |
6710 | LDAP_OPT_NETWORK_TIMEOUT is defined in the LDAP headers (OpenLDAP), or |
6711 | if LDAP_X_OPT_CONNECT_TIMEOUT is defined in the LDAP headers (Netscape | |
9b371988 | 6712 | SDK 4.1). A value of zero forces an explicit setting of &"no timeout"& for |
168e428f PH |
6713 | Netscape SDK; for OpenLDAP no action is taken. |
6714 | ||
6715 | The TIME parameter (also a number of seconds) is passed to the server to | |
6716 | set a server-side limit on the time taken to complete a search. | |
6717 | ||
6718 | ||
6719 | Here is an example of an LDAP query in an Exim lookup that uses some of these | |
9b371988 PH |
6720 | values. This is a single line, folded to fit on the page: |
6721 | .code | |
6722 | ${lookup ldap | |
6723 | {user="cn=manager,o=University of Cambridge,c=UK" pass=secret | |
6724 | ldap:///o=University%20of%20Cambridge,c=UK?sn?sub?(cn=foo)} | |
6725 | {$value}fail} | |
6726 | .endd | |
6727 | The encoding of spaces as &`%20`& is a URL thing which should not be done for | |
6728 | any of the auxiliary data. Exim configuration settings that include lookups | |
6729 | which contain password information should be preceded by &"hide"& to prevent | |
6730 | non-admin users from using the &%-bP%& option to see their values. | |
168e428f PH |
6731 | |
6732 | The auxiliary data items may be given in any order. The default is no | |
6733 | connection timeout (the system timeout is used), no user or password, no limit | |
6734 | on the number of entries returned, and no time limit on queries. | |
6735 | ||
6736 | When a DN is quoted in the USER= setting for LDAP authentication, Exim | |
6737 | removes any URL quoting that it may contain before passing it LDAP. Apparently | |
6738 | some libraries do this for themselves, but some do not. Removing the URL | |
6739 | quoting has two advantages: | |
6740 | ||
9b371988 PH |
6741 | .ilist |
6742 | It makes it possible to use the same &%quote_ldap_dn%& expansion for USER= | |
168e428f | 6743 | DNs as with DNs inside actual queries. |
9b371988 PH |
6744 | .next |
6745 | It permits spaces inside USER= DNs. | |
6746 | .endlist | |
168e428f PH |
6747 | |
6748 | For example, a setting such as | |
9b371988 PH |
6749 | .code |
6750 | USER=cn=${quote_ldap_dn:$1} | |
6751 | .endd | |
6752 | should work even if &$1$& contains spaces. | |
168e428f | 6753 | |
9b371988 | 6754 | Expanded data for the PASS= value should be quoted using the &%quote%& |
168e428f PH |
6755 | expansion operator, rather than the LDAP quote operators. The only reason this |
6756 | field needs quoting is to ensure that it conforms to the Exim syntax, which | |
6757 | does not allow unquoted spaces. For example: | |
9b371988 PH |
6758 | .code |
6759 | PASS=${quote:$3} | |
6760 | .endd | |
168e428f | 6761 | The LDAP authentication mechanism can be used to check passwords as part of |
9b371988 PH |
6762 | SMTP authentication. See the &%ldapauth%& expansion string condition in chapter |
6763 | &<<CHAPexpand>>&. | |
168e428f | 6764 | |
168e428f PH |
6765 | |
6766 | ||
9b371988 PH |
6767 | .section "Format of data returned by LDAP" |
6768 | .cindex "LDAP" "returned data formats" | |
6769 | The &(ldapdn)& lookup type returns the Distinguished Name from a single entry | |
6770 | as a sequence of values, for example | |
6771 | .code | |
6772 | cn=manager, o=University of Cambridge, c=UK | |
6773 | .endd | |
6774 | The &(ldap)& lookup type generates an error if more than one entry matches the | |
6775 | search filter, whereas &(ldapm)& permits this case, and inserts a newline in | |
168e428f | 6776 | the result between the data from different entries. It is possible for multiple |
9b371988 | 6777 | values to be returned for both &(ldap)& and &(ldapm)&, but in the former case |
168e428f PH |
6778 | you know that whatever values are returned all came from a single entry in the |
6779 | directory. | |
6780 | ||
6781 | In the common case where you specify a single attribute in your LDAP query, the | |
6782 | result is not quoted, and does not contain the attribute name. If the attribute | |
6783 | has multiple values, they are separated by commas. | |
6784 | ||
6785 | If you specify multiple attributes, the result contains space-separated, quoted | |
6786 | strings, each preceded by the attribute name and an equals sign. Within the | |
6787 | quotes, the quote character, backslash, and newline are escaped with | |
6788 | backslashes, and commas are used to separate multiple values for the attribute. | |
6789 | Apart from the escaping, the string within quotes takes the same form as the | |
6790 | output when a single attribute is requested. Specifying no attributes is the | |
6791 | same as specifying all of an entry's attributes. | |
6792 | ||
6793 | Here are some examples of the output format. The first line of each pair is an | |
6794 | LDAP query, and the second is the data that is returned. The attribute called | |
9b371988 PH |
6795 | &%attr1%& has two values, whereas &%attr2%& has only one value: |
6796 | .code | |
6797 | ldap:///o=base?attr1?sub?(uid=fred) | |
6798 | value1.1, value1.2 | |
168e428f | 6799 | |
9b371988 PH |
6800 | ldap:///o=base?attr2?sub?(uid=fred) |
6801 | value two | |
168e428f | 6802 | |
9b371988 PH |
6803 | ldap:///o=base?attr1,attr2?sub?(uid=fred) |
6804 | attr1="value1.1, value1.2" attr2="value two" | |
168e428f | 6805 | |
9b371988 PH |
6806 | ldap:///o=base??sub?(uid=fred) |
6807 | objectClass="top" attr1="value1.1, value1.2" attr2="value two" | |
6808 | .endd | |
6809 | The &%extract%& operator in string expansions can be used to pick out | |
6810 | individual fields from data that consists of &'key'&=&'value'& pairs. You can | |
6811 | make use of Exim's &%-be%& option to run expansion tests and thereby check the | |
6812 | results of LDAP lookups. | |
168e428f | 6813 | |
168e428f | 6814 | |
168e428f PH |
6815 | |
6816 | ||
9b371988 PH |
6817 | .section "More about NIS+" "SECTnisplus" |
6818 | .cindex "NIS+ lookup type" | |
6819 | .cindex "lookup" "NIS+" | |
6820 | NIS+ queries consist of a NIS+ &'indexed name'& followed by an optional colon | |
168e428f PH |
6821 | and field name. If this is given, the result of a successful query is the |
6822 | contents of the named field; otherwise the result consists of a concatenation | |
9b371988 | 6823 | of &'field-name=field-value'& pairs, separated by spaces. Empty values and |
168e428f | 6824 | values containing spaces are quoted. For example, the query |
9b371988 PH |
6825 | .code |
6826 | [name=mg1456],passwd.org_dir | |
6827 | .endd | |
168e428f | 6828 | might return the string |
9b371988 PH |
6829 | .code |
6830 | name=mg1456 passwd="" uid=999 gid=999 gcos="Martin Guerre" | |
6831 | home=/home/mg1456 shell=/bin/bash shadow="" | |
6832 | .endd | |
168e428f | 6833 | (split over two lines here to fit on the page), whereas |
9b371988 PH |
6834 | .code |
6835 | [name=mg1456],passwd.org_dir:gcos | |
6836 | .endd | |
168e428f | 6837 | would just return |
9b371988 PH |
6838 | .code |
6839 | Martin Guerre | |
6840 | .endd | |
168e428f | 6841 | with no quotes. A NIS+ lookup fails if NIS+ returns more than one table entry |
9b371988 | 6842 | for the given indexed key. The effect of the &%quote_nisplus%& expansion |
168e428f PH |
6843 | operator is to double any quote characters within the text. |
6844 | ||
6845 | ||
6846 | ||
9b371988 PH |
6847 | .section "SQL lookups" "SECTsql" |
6848 | .new | |
6849 | .cindex "SQL lookup types" | |
068aaea8 PH |
6850 | Exim can support lookups in Interbase, MySQL, Oracle, PostgreSQL, and SQLite |
6851 | databases. Queries for these databases contain SQL statements, so an example | |
6852 | might be | |
9b371988 PH |
6853 | .wen |
6854 | .code | |
068aaea8 PH |
6855 | ${lookup mysql{select mailbox from users where id='userx'}\ |
6856 | {$value}fail} | |
9b371988 | 6857 | .endd |
068aaea8 PH |
6858 | If the result of the query contains more than one field, the data for each |
6859 | field in the row is returned, preceded by its name, so the result of | |
9b371988 | 6860 | .code |
068aaea8 PH |
6861 | ${lookup pgsql{select home,name from users where id='userx'}\ |
6862 | {$value}} | |
9b371988 | 6863 | .endd |
068aaea8 | 6864 | might be |
9b371988 PH |
6865 | .code |
6866 | home=/home/userx name="Mister X" | |
6867 | .endd | |
068aaea8 PH |
6868 | Empty values and values containing spaces are double quoted, with embedded |
6869 | quotes escaped by a backslash. If the result of the query contains just one | |
6870 | field, the value is passed back verbatim, without a field name, for example: | |
9b371988 PH |
6871 | .code |
6872 | Mister X | |
6873 | .endd | |
068aaea8 PH |
6874 | If the result of the query yields more than one row, it is all concatenated, |
6875 | with a newline between the data for each row. | |
6876 | ||
6877 | ||
9b371988 PH |
6878 | .section "More about MySQL, PostgreSQL, Oracle, and Interbase" |
6879 | .cindex "MySQL" "lookup type" | |
6880 | .cindex "PostgreSQL lookup type" | |
6881 | .cindex "lookup" "MySQL" | |
6882 | .cindex "lookup" "PostgreSQL" | |
6883 | .cindex "Oracle" "lookup type" | |
6884 | .cindex "lookup" "Oracle" | |
6885 | .cindex "Interbase lookup type" | |
6886 | .cindex "lookup" "Interbase" | |
168e428f | 6887 | If any MySQL, PostgreSQL, Oracle, or Interbase lookups are used, the |
9b371988 PH |
6888 | &%mysql_servers%&, &%pgsql_servers%&, &%oracle_servers%&, or &%ibase_servers%& |
6889 | option (as appropriate) must be set to a colon-separated list of server | |
6890 | information. Each item in the list is a slash-separated list of four items: | |
6891 | host name, database name, user name, and password. In the case of Oracle, the | |
6892 | host name field is used for the &"service name"&, and the database name field | |
6893 | is not used and should be empty. For example: | |
6894 | .code | |
6895 | hide oracle_servers = oracle.plc.example//userx/abcdwxyz | |
6896 | .endd | |
168e428f | 6897 | Because password data is sensitive, you should always precede the setting with |
9b371988 | 6898 | &"hide"&, to prevent non-admin users from obtaining the setting via the &%-bP%& |
168e428f | 6899 | option. Here is an example where two MySQL servers are listed: |
9b371988 | 6900 | .code |
168e428f PH |
6901 | hide mysql_servers = localhost/users/root/secret:\ |
6902 | otherhost/users/root/othersecret | |
9b371988 PH |
6903 | .endd |
6904 | For MySQL and PostgreSQL, a host may be specified as <&'name'&>:<&'port'&> but | |
068aaea8 PH |
6905 | because this is a colon-separated list, the colon has to be doubled. For each |
6906 | query, these parameter groups are tried in order until a connection and a query | |
6907 | succeeds. | |
168e428f | 6908 | |
9b371988 | 6909 | The &%quote_mysql%&, &%quote_pgsql%&, and &%quote_oracle%& expansion operators |
168e428f PH |
6910 | convert newline, tab, carriage return, and backspace to \n, \t, \r, and \b |
6911 | respectively, and the characters single-quote, double-quote, and backslash | |
9b371988 | 6912 | itself are escaped with backslashes. The &%quote_pgsql%& expansion operator, in |
168e428f PH |
6913 | addition, escapes the percent and underscore characters. This cannot be done |
6914 | for MySQL because these escapes are not recognized in contexts where these | |
6915 | characters are not special. | |
6916 | ||
6917 | ||
9b371988 PH |
6918 | .section "Special MySQL features" |
6919 | For MySQL, an empty host name or the use of &"localhost"& in &%mysql_servers%& | |
168e428f PH |
6920 | causes a connection to the server on the local host by means of a Unix domain |
6921 | socket. An alternate socket can be specified in parentheses. The full syntax of | |
9b371988 PH |
6922 | each item in &%mysql_servers%& is: |
6923 | .display | |
6924 | <&'hostname'&>::<&'port'&>(<&'socket name'&>)/<&'database'&>/&&& | |
6925 | <&'user'&>/<&'password'&> | |
6926 | .endd | |
168e428f | 6927 | Any of the three sub-parts of the first field can be omitted. For normal use on |
9b371988 | 6928 | the local host it can be left blank or set to just &"localhost"&. |
168e428f | 6929 | |
9b371988 | 6930 | No database need be supplied &-- but if it is absent here, it must be given in |
168e428f PH |
6931 | the queries. |
6932 | ||
6933 | If a MySQL query is issued that does not request any data (an insert, update, | |
6934 | or delete command), the result of the lookup is the number of rows affected. | |
6935 | ||
9b371988 | 6936 | &*Warning*&: This can be misleading. If an update does not actually change |
168e428f PH |
6937 | anything (for example, setting a field to the value it already has), the result |
6938 | is zero because no rows are affected. | |
6939 | ||
6940 | ||
9b371988 | 6941 | .section "Special PostgreSQL features" |
168e428f PH |
6942 | PostgreSQL lookups can also use Unix domain socket connections to the database. |
6943 | This is usually faster and costs less CPU time than a TCP/IP connection. | |
6944 | However it can be used only if the mail server runs on the same machine as the | |
6945 | database server. A configuration line for PostgreSQL via Unix domain sockets | |
6946 | looks like this: | |
9b371988 PH |
6947 | .code |
6948 | hide pgsql_servers = (/tmp/.s.PGSQL.5432)/db/user/password : ... | |
6949 | .endd | |
168e428f PH |
6950 | In other words, instead of supplying a host name, a path to the socket is |
6951 | given. The path name is enclosed in parentheses so that its slashes aren't | |
6952 | visually confused with the delimiters for the other server parameters. | |
6953 | ||
6954 | If a PostgreSQL query is issued that does not request any data (an insert, | |
6955 | update, or delete command), the result of the lookup is the number of rows | |
6956 | affected. | |
6957 | ||
9b371988 PH |
6958 | .new |
6959 | .section "More about SQLite" "SECTsqlite" | |
6960 | .cindex "lookup" "SQLite" | |
6961 | .cindex "SQLite lookup type" | |
068aaea8 PH |
6962 | SQLite is different to the other SQL lookups because a file name is required in |
6963 | addition to the SQL query. An SQLite database is a single file, and there is no | |
6964 | daemon as in the other SQL databases. The interface to Exim requires the name | |
6965 | of the file, as an absolute path, to be given at the start of the query. It is | |
6966 | separated from the query by white space. This means that the path name cannot | |
6967 | contain white space. Here is a lookup expansion example: | |
9b371988 | 6968 | .code |
068aaea8 PH |
6969 | ${lookup sqlite {/some/thing/sqlitedb \ |
6970 | select name from aliases where id='userx';}} | |
9b371988 | 6971 | .endd |
068aaea8 | 6972 | In a list, the syntax is similar. For example: |
9b371988 | 6973 | .code |
068aaea8 PH |
6974 | domainlist relay_domains = sqlite;/some/thing/sqlitedb \ |
6975 | select * from relays where ip='$sender_host_address'; | |
9b371988 PH |
6976 | .endd |
6977 | The only character affected by the &%quote_sqlite%& operator is a single | |
068aaea8 PH |
6978 | quote, which it doubles. |
6979 | ||
068aaea8 PH |
6980 | The SQLite library handles multiple simultaneous accesses to the database |
6981 | internally. Multiple readers are permitted, but only one process can | |
6982 | update at once. Attempts to access the database while it is being updated | |
6983 | are rejected after a timeout period, during which the SQLite library | |
6984 | waits for the lock to be released. In Exim, the default timeout is set | |
9b371988 | 6985 | to 5 seconds, but it can be changed by means of the &%sqlite_lock_timeout%& |
068aaea8 | 6986 | option. |
9b371988 | 6987 | .wen |
168e428f PH |
6988 | |
6989 | ||
9b371988 PH |
6990 | . //////////////////////////////////////////////////////////////////////////// |
6991 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 6992 | |
9b371988 PH |
6993 | .chapter "Domain, host, address, and local part lists" &&& |
6994 | "CHAPdomhosaddlists" &&& | |
6995 | "Domain, host, and address lists" | |
6996 | .cindex "list of domains; hosts; etc." | |
168e428f | 6997 | A number of Exim configuration options contain lists of domains, hosts, |
9b371988 | 6998 | email addresses, or local parts. For example, the &%hold_domains%& option |
168e428f | 6999 | contains a list of domains whose delivery is currently suspended. These lists |
9b371988 PH |
7000 | are also used as data in ACL statements (see chapter &<<CHAPACL>>&), and as |
7001 | arguments to expansion conditions such as &%match_domain%&. | |
168e428f PH |
7002 | |
7003 | Each item in one of these lists is a pattern to be matched against a domain, | |
7004 | host, email address, or local part, respectively. In the sections below, the | |
7005 | different types of pattern for each case are described, but first we cover some | |
7006 | general facilities that apply to all four kinds of list. | |
7007 | ||
7008 | ||
7009 | ||
9b371988 PH |
7010 | .section "Expansion of lists" |
7011 | .cindex "expansion" "of lists" | |
168e428f PH |
7012 | Each list is expanded as a single string before it is used. The result of |
7013 | expansion must be a list, possibly containing empty items, which is split up | |
7014 | into separate items for matching. By default, colon is the separator character, | |
9b371988 PH |
7015 | but this can be varied if necessary. See sections &<<SECTlistconstruct>>& and |
7016 | &<<SECTempitelis>>& for details of the list syntax; the second of these | |
7017 | discusses the way to specify empty list items. | |
168e428f PH |
7018 | |
7019 | ||
7020 | If the string expansion is forced to fail, Exim behaves as if the item it is | |
7021 | testing (domain, host, address, or local part) is not in the list. Other | |
7022 | expansion failures cause temporary errors. | |
7023 | ||
7024 | If an item in a list is a regular expression, backslashes, dollars and possibly | |
7025 | other special characters in the expression must be protected against | |
7026 | misinterpretation by the string expander. The easiest way to do this is to use | |
9b371988 | 7027 | the &`\N`& expansion feature to indicate that the contents of the regular |
168e428f | 7028 | expression should not be expanded. For example, in an ACL you might have: |
9b371988 | 7029 | .code |
168e428f PH |
7030 | deny senders = \N^\d{8}\w@.*\.baddomain\.example$\N : \ |
7031 | ${lookup{$domain}lsearch{/badsenders/bydomain}} | |
9b371988 | 7032 | .endd |
168e428f | 7033 | The first item is a regular expression that is protected from expansion by |
9b371988 | 7034 | &`\N`&, whereas the second uses the expansion to obtain a list of unwanted |
168e428f PH |
7035 | senders based on the receiving domain. |
7036 | ||
7037 | ||
7038 | ||
7039 | ||
9b371988 PH |
7040 | .section "Negated items in lists" |
7041 | .cindex "list" "negation" | |
7042 | .cindex "negation in lists" | |
168e428f PH |
7043 | Items in a list may be positive or negative. Negative items are indicated by a |
7044 | leading exclamation mark, which may be followed by optional white space. A list | |
7045 | defines a set of items (domains, etc). When Exim processes one of these lists, | |
7046 | it is trying to find out whether a domain, host, address, or local part | |
7047 | (respectively) is in the set that is defined by the list. It works like this: | |
7048 | ||
7049 | The list is scanned from left to right. If a positive item is matched, the | |
7050 | subject that is being checked is in the set; if a negative item is matched, the | |
7051 | subject is not in the set. If the end of the list is reached without the | |
7052 | subject having matched any of the patterns, it is in the set if the last item | |
7053 | was a negative one, but not if it was a positive one. For example, the list in | |
9b371988 PH |
7054 | .code |
7055 | domainlist relay_domains = !a.b.c : *.b.c | |
7056 | .endd | |
7057 | matches any domain ending in &'.b.c'& except for &'a.b.c'&. Domains that match | |
7058 | neither &'a.b.c'& nor &'*.b.c'& do not match, because the last item in the | |
168e428f | 7059 | list is positive. However, if the setting were |
9b371988 PH |
7060 | .code |
7061 | domainlist relay_domains = !a.b.c | |
7062 | .endd | |
7063 | then all domains other than &'a.b.c'& would match because the last item in the | |
168e428f | 7064 | list is negative. In other words, a list that ends with a negative item behaves |
9b371988 | 7065 | as if it had an extra item &`:*`& on the end. |
168e428f PH |
7066 | |
7067 | Another way of thinking about positive and negative items in lists is to read | |
9b371988 | 7068 | the connector as &"or"& after a positive item and as &"and"& after a negative |
168e428f PH |
7069 | item. |
7070 | ||
7071 | ||
7072 | ||
9b371988 PH |
7073 | .section "File names in lists" "SECTfilnamlis" |
7074 | .cindex "list" "file name in" | |
168e428f PH |
7075 | If an item in a domain, host, address, or local part list is an absolute file |
7076 | name (beginning with a slash character), each line of the file is read and | |
7077 | processed as if it were an independent item in the list, except that further | |
7078 | file names are not allowed, | |
7079 | and no expansion of the data from the file takes place. | |
7080 | Empty lines in the file are ignored, and the file may also contain comment | |
7081 | lines: | |
7082 | ||
9b371988 PH |
7083 | .ilist |
7084 | For domain and host lists, if a # character appears anywhere in a line of the | |
168e428f | 7085 | file, it and all following characters are ignored. |
9b371988 PH |
7086 | .next |
7087 | Because local parts may legitimately contain # characters, a comment in an | |
168e428f PH |
7088 | address list or local part list file is recognized only if # is preceded by |
7089 | white space or the start of the line. For example: | |
9b371988 PH |
7090 | .code |
7091 | not#comment@x.y.z # but this is a comment | |
7092 | .endd | |
7093 | .endlist | |
168e428f PH |
7094 | |
7095 | Putting a file name in a list has the same effect as inserting each line of the | |
7096 | file as an item in the list (blank lines and comments excepted). However, there | |
7097 | is one important difference: the file is read each time the list is processed, | |
7098 | so if its contents vary over time, Exim's behaviour changes. | |
7099 | ||
7100 | If a file name is preceded by an exclamation mark, the sense of any match | |
7101 | within the file is inverted. For example, if | |
9b371988 PH |
7102 | .code |
7103 | hold_domains = !/etc/nohold-domains | |
7104 | .endd | |
168e428f | 7105 | and the file contains the lines |
9b371988 PH |
7106 | .code |
7107 | !a.b.c | |
7108 | *.b.c | |
7109 | .endd | |
7110 | then &'a.b.c'& is in the set of domains defined by &%hold_domains%&, whereas | |
7111 | any domain matching &`*.b.c`& is not. | |
168e428f | 7112 | |
168e428f PH |
7113 | |
7114 | ||
9b371988 | 7115 | .section "An lsearch file is not an out-of-line list" |
168e428f PH |
7116 | As will be described in the sections that follow, lookups can be used in lists |
7117 | to provide indexed methods of checking list membership. There has been some | |
9b371988 PH |
7118 | confusion about the way &(lsearch)& lookups work in lists. Because |
7119 | an &(lsearch)& file contains plain text and is scanned sequentially, it is | |
168e428f | 7120 | sometimes thought that it is allowed to contain wild cards and other kinds of |
9b371988 | 7121 | non-constant pattern. This is not the case. The keys in an &(lsearch)& file are |
168e428f PH |
7122 | always fixed strings, just as for any other single-key lookup type. |
7123 | ||
7124 | If you want to use a file to contain wild-card patterns that form part of a | |
7125 | list, just give the file name on its own, without a search type, as described | |
7126 | in the previous section. | |
7127 | ||
7128 | ||
7129 | ||
7130 | ||
9b371988 PH |
7131 | .section "Named lists" "SECTnamedlists" |
7132 | .cindex "named lists" | |
7133 | .cindex "list" "named" | |
168e428f PH |
7134 | A list of domains, hosts, email addresses, or local parts can be given a name |
7135 | which is then used to refer to the list elsewhere in the configuration. This is | |
7136 | particularly convenient if the same list is required in several different | |
7137 | places. It also allows lists to be given meaningful names, which can improve | |
7138 | the readability of the configuration. For example, it is conventional to define | |
9b371988 | 7139 | a domain list called &'local_domains'& for all the domains that are handled |
168e428f | 7140 | locally on a host, using a configuration line such as |
9b371988 PH |
7141 | .code |
7142 | domainlist local_domains = localhost:my.dom.example | |
7143 | .endd | |
168e428f PH |
7144 | Named lists are referenced by giving their name preceded by a plus sign, so, |
7145 | for example, a router that is intended to handle local domains would be | |
7146 | configured with the line | |
9b371988 PH |
7147 | .code |
7148 | domains = +local_domains | |
7149 | .endd | |
168e428f PH |
7150 | The first router in a configuration is often one that handles all domains |
7151 | except the local ones, using a configuration with a negated item like this: | |
9b371988 PH |
7152 | .code |
7153 | dnslookup: | |
7154 | driver = dnslookup | |
7155 | domains = ! +local_domains | |
7156 | transport = remote_smtp | |
7157 | no_more | |
7158 | .endd | |
168e428f | 7159 | The four kinds of named list are created by configuration lines starting with |
9b371988 | 7160 | the words &%domainlist%&, &%hostlist%&, &%addresslist%&, or &%localpartlist%&, |
168e428f PH |
7161 | respectively. Then there follows the name that you are defining, followed by an |
7162 | equals sign and the list itself. For example: | |
9b371988 PH |
7163 | .code |
7164 | hostlist relay_hosts = 192.168.23.0/24 : my.friend.example | |
7165 | addresslist bad_senders = cdb;/etc/badsenders | |
7166 | .endd | |
168e428f | 7167 | A named list may refer to other named lists: |
9b371988 PH |
7168 | .code |
7169 | domainlist dom1 = first.example : second.example | |
7170 | domainlist dom2 = +dom1 : third.example | |
7171 | domainlist dom3 = fourth.example : +dom2 : fifth.example | |
7172 | .endd | |
7173 | &*Warning*&: If the last item in a referenced list is a negative one, the | |
168e428f PH |
7174 | effect may not be what you intended, because the negation does not propagate |
7175 | out to the higher level. For example, consider: | |
9b371988 PH |
7176 | .code |
7177 | domainlist dom1 = !a.b | |
7178 | domainlist dom2 = +dom1 : *.b | |
7179 | .endd | |
7180 | The second list specifies &"either in the &%dom1%& list or &'*.b'&"&. The first | |
7181 | list specifies just &"not &'a.b'&"&, so the domain &'x.y'& matches it. That | |
7182 | means it matches the second list as well. The effect is not the same as | |
7183 | .code | |
7184 | domainlist dom2 = !a.b : *.b | |
7185 | .endd | |
7186 | where &'x.y'& does not match. It's best to avoid negation altogether in | |
168e428f PH |
7187 | referenced lists if you can. |
7188 | ||
7189 | Named lists may have a performance advantage. When Exim is routing an | |
7190 | address or checking an incoming message, it caches the result of tests on named | |
7191 | lists. So, if you have a setting such as | |
9b371988 PH |
7192 | .code |
7193 | domains = +local_domains | |
7194 | .endd | |
168e428f PH |
7195 | on several of your routers |
7196 | or in several ACL statements, | |
7197 | the actual test is done only for the first one. However, the caching works only | |
7198 | if there are no expansions within the list itself or any sublists that it | |
7199 | references. In other words, caching happens only for lists that are known to be | |
7200 | the same each time they are referenced. | |
7201 | ||
7202 | By default, there may be up to 16 named lists of each type. This limit can be | |
7203 | extended by changing a compile-time variable. The use of domain and host lists | |
7204 | is recommended for concepts such as local domains, relay domains, and relay | |
7205 | hosts. The default configuration is set up like this. | |
7206 | ||
7207 | ||
7208 | ||
9b371988 PH |
7209 | .section "Named lists compared with macros" |
7210 | .cindex "list" "named compared with macro" | |
7211 | .cindex "macro" "compared with named list" | |
168e428f PH |
7212 | At first sight, named lists might seem to be no different from macros in the |
7213 | configuration file. However, macros are just textual substitutions. If you | |
7214 | write | |
9b371988 PH |
7215 | .code |
7216 | ALIST = host1 : host2 | |
7217 | auth_advertise_hosts = !ALIST | |
7218 | .endd | |
168e428f | 7219 | it probably won't do what you want, because that is exactly the same as |
9b371988 PH |
7220 | .code |
7221 | auth_advertise_hosts = !host1 : host2 | |
7222 | .endd | |
168e428f PH |
7223 | Notice that the second host name is not negated. However, if you use a host |
7224 | list, and write | |
9b371988 PH |
7225 | .code |
7226 | hostlist alist = host1 : host2 | |
7227 | auth_advertise_hosts = ! +alist | |
7228 | .endd | |
168e428f | 7229 | the negation applies to the whole list, and so that is equivalent to |
9b371988 PH |
7230 | .code |
7231 | auth_advertise_hosts = !host1 : !host2 | |
7232 | .endd | |
168e428f PH |
7233 | |
7234 | ||
9b371988 PH |
7235 | .section "Named list caching" |
7236 | .cindex "list" "caching of named" | |
7237 | .cindex "caching" "named lists" | |
168e428f PH |
7238 | While processing a message, Exim caches the result of checking a named list if |
7239 | it is sure that the list is the same each time. In practice, this means that | |
9b371988 | 7240 | the cache operates only if the list contains no $ characters, which guarantees |
168e428f PH |
7241 | that it will not change when it is expanded. Sometimes, however, you may have |
7242 | an expanded list that you know will be the same each time within a given | |
7243 | message. For example: | |
9b371988 | 7244 | .code |
168e428f PH |
7245 | domainlist special_domains = \ |
7246 | ${lookup{$sender_host_address}cdb{/some/file}} | |
9b371988 | 7247 | .endd |
168e428f PH |
7248 | This provides a list of domains that depends only on the sending host's IP |
7249 | address. If this domain list is referenced a number of times (for example, | |
7250 | in several ACL lines, or in several routers) the result of the check is not | |
7251 | cached by default, because Exim does not know that it is going to be the | |
7252 | same list each time. | |
7253 | ||
9b371988 | 7254 | By appending &`_cache`& to &`domainlist`& you can tell Exim to go ahead and |
168e428f | 7255 | cache the result anyway. For example: |
9b371988 PH |
7256 | .code |
7257 | domainlist_cache special_domains = ${lookup{... | |
7258 | .endd | |
168e428f PH |
7259 | If you do this, you should be absolutely sure that caching is going to do |
7260 | the right thing in all cases. When in doubt, leave it out. | |
7261 | ||
7262 | ||
7263 | ||
9b371988 PH |
7264 | .section "Domain lists" "SECTdomainlist" |
7265 | .cindex "domain list" "patterns for" | |
7266 | .cindex "list" "domain list" | |
168e428f PH |
7267 | Domain lists contain patterns that are to be matched against a mail domain. |
7268 | The following types of item may appear in domain lists: | |
7269 | ||
9b371988 PH |
7270 | .ilist |
7271 | .cindex "primary host name" | |
7272 | .cindex "host name" "matched in domain list" | |
7273 | .cindex "&%primary_hostname%&" | |
7274 | .cindex "domain list" "matching primary host name" | |
7275 | .cindex "@ in a domain list" | |
168e428f | 7276 | If a pattern consists of a single @ character, it matches the local host name, |
9b371988 PH |
7277 | as set by the &%primary_hostname%& option (or defaulted). This makes it |
7278 | possible to use the same configuration file on several different hosts that | |
7279 | differ only in their names. | |
7280 | .next | |
7281 | .cindex "@[] in a domain list" | |
7282 | .cindex "domain list" "matching local IP interfaces" | |
7283 | .cindex "domain literal" | |
7284 | If a pattern consists of the string &`@[]`& it matches any local IP interface | |
168e428f PH |
7285 | address, enclosed in square brackets, as in an email address that contains a |
7286 | domain literal. | |
7287 | In today's Internet, the use of domain literals is controversial. | |
9b371988 PH |
7288 | .next |
7289 | .cindex "@mx_any" | |
7290 | .cindex "@mx_primary" | |
7291 | .cindex "@mx_secondary" | |
7292 | .cindex "domain list" "matching MX pointers to local host" | |
7293 | If a pattern consists of the string &`@mx_any`& it matches any domain that | |
168e428f | 7294 | has an MX record pointing to the local host or to any host that is listed in |
9b371988 PH |
7295 | .cindex "&%hosts_treat_as_local%&" |
7296 | &%hosts_treat_as_local%&. The items &`@mx_primary`& and &`@mx_secondary`& | |
168e428f PH |
7297 | are similar, except that the first matches only when a primary MX target is the |
7298 | local host, and the second only when no primary MX target is the local host, | |
9b371988 PH |
7299 | but a secondary MX target is. &"Primary"& means an MX record with the lowest |
7300 | preference value &-- there may of course be more than one of them. | |
7301 | ||
168e428f PH |
7302 | The MX lookup that takes place when matching a pattern of this type is |
7303 | performed with the resolver options for widening names turned off. Thus, for | |
9b371988 PH |
7304 | example, a single-component domain will &'not'& be expanded by adding the |
7305 | resolver's default domain. See the &%qualify_single%& and &%search_parents%& | |
7306 | options of the &(dnslookup)& router for a discussion of domain widening. | |
7307 | ||
168e428f | 7308 | Sometimes you may want to ignore certain IP addresses when using one of these |
9b371988 PH |
7309 | patterns. You can specify this by following the pattern with &`/ignore=`&<&'ip |
7310 | list'&>, where <&'ip list'&> is a list of IP addresses. These addresses are | |
7311 | ignored when processing the pattern (compare the &%ignore_target_hosts%& option | |
168e428f | 7312 | on a router). For example: |
9b371988 PH |
7313 | .code |
7314 | domains = @mx_any/ignore=127.0.0.1 | |
7315 | .endd | |
168e428f PH |
7316 | This example matches any domain that has an MX record pointing to one of |
7317 | the local host's IP addresses other than 127.0.0.1. | |
9b371988 | 7318 | |
168e428f PH |
7319 | The list of IP addresses is in fact processed by the same code that processes |
7320 | host lists, so it may contain CIDR-coded network specifications and it may also | |
7321 | contain negative items. | |
9b371988 | 7322 | |
168e428f PH |
7323 | Because the list of IP addresses is a sublist within a domain list, you have to |
7324 | be careful about delimiters if there is more than one address. Like any other | |
7325 | list, the default delimiter can be changed. Thus, you might have: | |
9b371988 | 7326 | .code |
168e428f PH |
7327 | domains = @mx_any/ignore=<;127.0.0.1;0.0.0.0 : \ |
7328 | an.other.domain : ... | |
9b371988 | 7329 | .endd |
168e428f PH |
7330 | so that the sublist uses semicolons for delimiters. When IPv6 addresses are |
7331 | involved, it is easiest to change the delimiter for the main list as well: | |
9b371988 | 7332 | .code |
168e428f PH |
7333 | domains = <? @mx_any/ignore=<;127.0.0.1;::1 ? \ |
7334 | an.other.domain ? ... | |
9b371988 PH |
7335 | .endd |
7336 | .next | |
7337 | .cindex "asterisk" "in domain list" | |
7338 | .cindex "domain list" "asterisk in" | |
7339 | .cindex "domain list" "matching &""ends with""&" | |
168e428f | 7340 | If a pattern starts with an asterisk, the remaining characters of the pattern |
9b371988 | 7341 | are compared with the terminating characters of the domain. The use of &"*"& in |
168e428f PH |
7342 | domain lists differs from its use in partial matching lookups. In a domain |
7343 | list, the character following the asterisk need not be a dot, whereas partial | |
7344 | matching works only in terms of dot-separated components. For example, a domain | |
9b371988 PH |
7345 | list item such as &`*key.ex`& matches &'donkey.ex'& as well as |
7346 | &'cipher.key.ex'&. | |
168e428f | 7347 | |
9b371988 PH |
7348 | .next |
7349 | .cindex "regular expressions" "in domain list" | |
7350 | .cindex "domain list" "matching regular expression" | |
168e428f PH |
7351 | If a pattern starts with a circumflex character, it is treated as a regular |
7352 | expression, and matched against the domain using a regular expression matching | |
7353 | function. The circumflex is treated as part of the regular expression. | |
7354 | References to descriptions of the syntax of regular expressions are given in | |
9b371988 | 7355 | chapter &<<CHAPregexp>>&. |
168e428f | 7356 | |
9b371988 PH |
7357 | &*Warning*&: Because domain lists are expanded before being processed, you |
7358 | must escape any backslash and dollar characters in the regular expression, or | |
7359 | use the special &`\N`& sequence (see chapter &<<CHAPexpand>>&) to specify that | |
7360 | it is not to be expanded (unless you really do want to build a regular | |
7361 | expression by expansion, of course). | |
7362 | .next | |
7363 | .cindex "lookup" "in domain list" | |
7364 | .cindex "domain list" "matching by lookup" | |
168e428f | 7365 | If a pattern starts with the name of a single-key lookup type followed by a |
9b371988 | 7366 | semicolon (for example, &"dbm;"& or &"lsearch;"&), the remainder of the pattern |
168e428f | 7367 | must be a file name in a suitable format for the lookup type. For example, for |
9b371988 PH |
7368 | &"cdb;"& it must be an absolute path: |
7369 | .code | |
7370 | domains = cdb;/etc/mail/local_domains.cdb | |
7371 | .endd | |
168e428f PH |
7372 | The appropriate type of lookup is done on the file using the domain name as the |
7373 | key. In most cases, the data that is looked up is not used; Exim is interested | |
7374 | only in whether or not the key is present in the file. However, when a lookup | |
9b371988 PH |
7375 | is used for the &%domains%& option on a router |
7376 | or a &%domains%& condition in an ACL statement, the data is preserved in the | |
7377 | &$domain_data$& variable and can be referred to in other router options or | |
168e428f PH |
7378 | other statements in the same ACL. |
7379 | ||
9b371988 PH |
7380 | .next |
7381 | Any of the single-key lookup type names may be preceded by | |
7382 | &`partial`&<&'n'&>&`-`&, where the <&'n'&> is optional, for example, | |
7383 | .code | |
7384 | domains = partial-dbm;/partial/domains | |
7385 | .endd | |
168e428f | 7386 | This causes partial matching logic to be invoked; a description of how this |
9b371988 | 7387 | works is given in section &<<SECTpartiallookup>>&. |
168e428f | 7388 | |
9b371988 PH |
7389 | .next |
7390 | .cindex "asterisk" "in lookup type" | |
168e428f PH |
7391 | Any of the single-key lookup types may be followed by an asterisk. This causes |
7392 | a default lookup for a key consisting of a single asterisk to be done if the | |
7393 | original lookup fails. This is not a useful feature when using a domain list to | |
7394 | select particular domains (because any domain would match), but it might have | |
9b371988 | 7395 | value if the result of the lookup is being used via the &$domain_data$& |
168e428f | 7396 | expansion variable. |
9b371988 PH |
7397 | .next |
7398 | If the pattern starts with the name of a query-style lookup type followed by a | |
7399 | semicolon (for example, &"nisplus;"& or &"ldap;"&), the remainder of the | |
7400 | pattern must be an appropriate query for the lookup type, as described in | |
7401 | chapter &<<CHAPfdlookup>>&. For example: | |
7402 | .code | |
168e428f PH |
7403 | hold_domains = mysql;select domain from holdlist \ |
7404 | where domain = '$domain'; | |
9b371988 | 7405 | .endd |
168e428f PH |
7406 | In most cases, the data that is looked up is not used (so for an SQL query, for |
7407 | example, it doesn't matter what field you select). Exim is interested only in | |
7408 | whether or not the query succeeds. However, when a lookup is used for the | |
9b371988 | 7409 | &%domains%& option on a router, the data is preserved in the &$domain_data$& |
168e428f | 7410 | variable and can be referred to in other options. |
9b371988 PH |
7411 | .next |
7412 | .cindex "domain list" "matching literal domain name" | |
168e428f PH |
7413 | If none of the above cases apply, a caseless textual comparison is made |
7414 | between the pattern and the domain. | |
9b371988 | 7415 | .endlist |
168e428f PH |
7416 | |
7417 | Here is an example that uses several different kinds of pattern: | |
9b371988 | 7418 | .code |
168e428f PH |
7419 | domainlist funny_domains = \ |
7420 | @ : \ | |
7421 | lib.unseen.edu : \ | |
7422 | *.foundation.fict.example : \ | |
7423 | \N^[1-2]\d{3}\.fict\.example$\N : \ | |
7424 | partial-dbm;/opt/data/penguin/book : \ | |
7425 | nis;domains.byname : \ | |
7426 | nisplus;[name=$domain,status=local],domains.org_dir | |
9b371988 | 7427 | .endd |
168e428f PH |
7428 | There are obvious processing trade-offs among the various matching modes. Using |
7429 | an asterisk is faster than a regular expression, and listing a few names | |
7430 | explicitly probably is too. The use of a file or database lookup is expensive, | |
7431 | but may be the only option if hundreds of names are required. Because the | |
7432 | patterns are tested in order, it makes sense to put the most commonly matched | |
7433 | patterns earlier. | |
7434 | ||
7435 | ||
7436 | ||
9b371988 PH |
7437 | .section "Host lists" "SECThostlist" |
7438 | .cindex "host list" "patterns in" | |
7439 | .cindex "list" "host list" | |
168e428f PH |
7440 | Host lists are used to control what remote hosts are allowed to do. For |
7441 | example, some hosts may be allowed to use the local host as a relay, and some | |
7442 | may be permitted to use the SMTP ETRN command. Hosts can be identified in | |
7443 | two different ways, by name or by IP address. In a host list, some types of | |
7444 | pattern are matched to a host name, and some are matched to an IP address. | |
7445 | You need to be particularly careful with this when single-key lookups are | |
7446 | involved, to ensure that the right value is being used as the key. | |
7447 | ||
7448 | ||
9b371988 PH |
7449 | .section "Special host list patterns" |
7450 | .cindex "empty item in hosts list" | |
7451 | .cindex "host list" "empty string in" | |
168e428f PH |
7452 | If a host list item is the empty string, it matches only when no remote host is |
7453 | involved. This is the case when a message is being received from a local | |
7454 | process using SMTP on the standard input, that is, when a TCP/IP connection is | |
7455 | not used. | |
7456 | ||
9b371988 PH |
7457 | .cindex "asterisk" "in host list" |
7458 | The special pattern &"*"& in a host list matches any host or no host. Neither | |
168e428f PH |
7459 | the IP address nor the name is actually inspected. |
7460 | ||
7461 | ||
7462 | ||
9b371988 PH |
7463 | .section "Host list patterns that match by IP address" "SECThoslispatip" |
7464 | .cindex "host list" "matching IP addresses" | |
168e428f PH |
7465 | If an IPv4 host calls an IPv6 host and the call is accepted on an IPv6 socket, |
7466 | the incoming address actually appears in the IPv6 host as | |
9b371988 | 7467 | &`::ffff:`&<&'v4address'&>. When such an address is tested against a host |
168e428f PH |
7468 | list, it is converted into a traditional IPv4 address first. (Not all operating |
7469 | systems accept IPv4 calls on IPv6 sockets, as there have been some security | |
7470 | concerns.) | |
7471 | ||
7472 | The following types of pattern in a host list check the remote host by | |
7473 | inspecting its IP address: | |
7474 | ||
9b371988 PH |
7475 | .ilist |
7476 | If the pattern is a plain domain name (not a regular expression, not starting | |
7477 | with *, not a lookup of any kind), Exim calls the operating system function | |
168e428f | 7478 | to find the associated IP address(es). Exim uses the newer |
9b371988 | 7479 | &[getipnodebyname()]& function when available, otherwise &[gethostbyname()]&. |
168e428f PH |
7480 | This typically causes a forward DNS lookup of the name. The result is compared |
7481 | with the IP address of the subject host. | |
9b371988 | 7482 | |
168e428f PH |
7483 | If there is a temporary problem (such as a DNS timeout) with the host name |
7484 | lookup, a temporary error occurs. For example, if the list is being used in an | |
9b371988 PH |
7485 | ACL condition, the ACL gives a &"defer"& response, usually leading to a |
7486 | temporary SMTP error code. If no IP address can be found for the host name, | |
7487 | what happens is described in section &<<SECTbehipnot>>& below. | |
168e428f | 7488 | |
9b371988 PH |
7489 | .next |
7490 | .cindex "@ in a host list" | |
7491 | If the pattern is &"@"&, the primary host name is substituted and used as a | |
168e428f PH |
7492 | domain name, as just described. |
7493 | ||
9b371988 PH |
7494 | .next |
7495 | If the pattern is an IP address, it is matched against the IP address of the | |
7496 | subject host. IPv4 addresses are given in the normal &"dotted-quad"& notation. | |
168e428f PH |
7497 | IPv6 addresses can be given in colon-separated format, but the colons have to |
7498 | be doubled so as not to be taken as item separators when the default list | |
7499 | separator is used. IPv6 addresses are recognized even when Exim is compiled | |
7500 | without IPv6 support. This means that if they appear in a host list on an | |
7501 | IPv4-only host, Exim will not treat them as host names. They are just addresses | |
7502 | that can never match a client host. | |
7503 | ||
9b371988 PH |
7504 | .next |
7505 | .cindex "@[] in a host list" | |
7506 | If the pattern is &"@[]"&, it matches the IP address of any IP interface on | |
168e428f PH |
7507 | the local host. For example, if the local host is an IPv4 host with one |
7508 | interface address 10.45.23.56, these two ACL statements have the same effect: | |
9b371988 PH |
7509 | .code |
7510 | accept hosts = 127.0.0.1 : 10.45.23.56 | |
7511 | accept hosts = @[] | |
7512 | .endd | |
7513 | .next | |
7514 | .cindex "CIDR notation" | |
168e428f PH |
7515 | If the pattern is an IP address followed by a slash and a mask length (for |
7516 | example 10.11.42.0/24), it is matched against the IP address of the subject | |
7517 | host under the given mask. This allows, an entire network of hosts to be | |
7518 | included (or excluded) by a single item. The mask uses CIDR notation; it | |
7519 | specifies the number of address bits that must match, starting from the most | |
7520 | significant end of the address. | |
9b371988 PH |
7521 | |
7522 | &*Note*&: The mask is &'not'& a count of addresses, nor is it the high number | |
168e428f PH |
7523 | of a range of addresses. It is the number of bits in the network portion of the |
7524 | address. The above example specifies a 24-bit netmask, so it matches all 256 | |
7525 | addresses in the 10.11.42.0 network. An item such as | |
9b371988 PH |
7526 | .code |
7527 | 192.168.23.236/31 | |
7528 | .endd | |
168e428f PH |
7529 | matches just two addresses, 192.168.23.236 and 192.168.23.237. A mask value of |
7530 | 32 for an IPv4 address is the same as no mask at all; just a single address | |
7531 | matches. | |
9b371988 | 7532 | |
168e428f | 7533 | Here is another example which shows an IPv4 and an IPv6 network: |
9b371988 | 7534 | .code |
168e428f PH |
7535 | recipient_unqualified_hosts = 192.168.0.0/16: \ |
7536 | 3ffe::ffff::836f::::/48 | |
9b371988 | 7537 | .endd |
168e428f PH |
7538 | The doubling of list separator characters applies only when these items |
7539 | appear inline in a host list. It is not required when indirecting via a file. | |
9b371988 PH |
7540 | For example: |
7541 | .code | |
7542 | recipient_unqualified_hosts = /opt/exim/unqualnets | |
7543 | .endd | |
168e428f | 7544 | could make use of a file containing |
9b371988 PH |
7545 | .code |
7546 | 172.16.0.0/12 | |
7547 | 3ffe:ffff:836f::/48 | |
7548 | .endd | |
168e428f PH |
7549 | to have exactly the same effect as the previous example. When listing IPv6 |
7550 | addresses inline, it is usually more convenient to use the facility for | |
7551 | changing separator characters. This list contains the same two networks: | |
9b371988 | 7552 | .code |
168e428f PH |
7553 | recipient_unqualified_hosts = <; 172.16.0.0/12; \ |
7554 | 3ffe:ffff:836f::/48 | |
9b371988 PH |
7555 | .endd |
7556 | The separator is changed to semicolon by the leading &"<;"& at the start of the | |
168e428f | 7557 | list. |
9b371988 | 7558 | .endlist |
168e428f PH |
7559 | |
7560 | ||
7561 | ||
9b371988 PH |
7562 | .section "Host list patterns for single-key lookups by host address" &&& |
7563 | "SECThoslispatsikey" | |
7564 | .cindex "host list" "lookup of IP address" | |
168e428f PH |
7565 | When a host is to be identified by a single-key lookup of its complete IP |
7566 | address, the pattern takes this form: | |
9b371988 PH |
7567 | .display |
7568 | &`net-<`&&'single-key-search-type'&&`>;<`&&'search-data'&&`>`& | |
7569 | .endd | |
168e428f | 7570 | For example: |
9b371988 PH |
7571 | .code |
7572 | hosts_lookup = net-cdb;/hosts-by-ip.db | |
7573 | .endd | |
168e428f PH |
7574 | The text form of the IP address of the subject host is used as the lookup key. |
7575 | IPv6 addresses are converted to an unabbreviated form, using lower case | |
7576 | letters, with dots as separators because colon is the key terminator in | |
9b371988 | 7577 | &(lsearch)& files. [Colons can in fact be used in keys in &(lsearch)& files by |
168e428f PH |
7578 | quoting the keys, but this is a facility that was added later.] The data |
7579 | returned by the lookup is not used. | |
7580 | ||
9b371988 PH |
7581 | .cindex "IP address" "masking" |
7582 | .cindex "host list" "masked IP address" | |
168e428f PH |
7583 | Single-key lookups can also be performed using masked IP addresses, using |
7584 | patterns of this form: | |
9b371988 PH |
7585 | .display |
7586 | &`net<`&&'number'&&`>-<`&&'single-key-search-type'&&`>;<`&&'search-data'&&`>`& | |
7587 | .endd | |
168e428f | 7588 | For example: |
9b371988 PH |
7589 | .code |
7590 | net24-dbm;/networks.db | |
7591 | .endd | |
7592 | The IP address of the subject host is masked using <&'number'&> as the mask | |
168e428f PH |
7593 | length. A textual string is constructed from the masked value, followed by the |
7594 | mask, and this is used as the lookup key. For example, if the host's IP address | |
7595 | is 192.168.34.6, the key that is looked up for the above example is | |
9b371988 | 7596 | &"192.168.34.0/24"&. IPv6 addresses are converted to a text value using lower |
168e428f | 7597 | case letters and dots as separators instead of the more usual colon, because |
9b371988 | 7598 | colon is the key terminator in &(lsearch)& files. Full, unabbreviated IPv6 |
168e428f PH |
7599 | addresses are always used. |
7600 | ||
9b371988 PH |
7601 | &*Warning*&: Specifing &%net32-%& (for an IPv4 address) or &%net128-%& (for an |
7602 | IPv6 address) is not the same as specifing just &%net-%& without a number. In | |
168e428f PH |
7603 | the former case the key strings include the mask value, whereas in the latter |
7604 | case the IP address is used on its own. | |
7605 | ||
7606 | ||
7607 | ||
9b371988 PH |
7608 | .section "Host list patterns that match by host name" "SECThoslispatnam" |
7609 | .cindex "host" "lookup failures" | |
7610 | .cindex "unknown host name" | |
7611 | .cindex "host list" "matching host name" | |
168e428f PH |
7612 | There are several types of pattern that require Exim to know the name of the |
7613 | remote host. These are either wildcard patterns or lookups by name. (If a | |
7614 | complete hostname is given without any wildcarding, it is used to find an IP | |
9b371988 PH |
7615 | address to match against, as described in the section &<<SECThoslispatip>>& |
7616 | above.) | |
168e428f PH |
7617 | |
7618 | If the remote host name is not already known when Exim encounters one of these | |
7619 | patterns, it has to be found from the IP address. | |
7620 | Although many sites on the Internet are conscientious about maintaining reverse | |
7621 | DNS data for their hosts, there are also many that do not do this. | |
7622 | Consequently, a name cannot always be found, and this may lead to unwanted | |
7623 | effects. Take care when configuring host lists with wildcarded name patterns. | |
7624 | Consider what will happen if a name cannot be found. | |
7625 | ||
7626 | Because of the problems of determining host names from IP addresses, matching | |
7627 | against host names is not as common as matching against IP addresses. | |
7628 | ||
7629 | By default, in order to find a host name, Exim first does a reverse DNS lookup; | |
9b371988 PH |
7630 | if no name is found in the DNS, the system function (&[gethostbyaddr()]& or |
7631 | &[getipnodebyaddr()]& if available) is tried. The order in which these lookups | |
7632 | are done can be changed by setting the &%host_lookup_order%& option. | |
168e428f PH |
7633 | |
7634 | There are some options that control what happens if a host name cannot be | |
9b371988 | 7635 | found. These are described in section &<<SECTbehipnot>>& below. |
168e428f | 7636 | |
9b371988 PH |
7637 | .cindex "host" "alias for" |
7638 | .cindex "alias for host" | |
168e428f PH |
7639 | As a result of aliasing, hosts may have more than one name. When processing any |
7640 | of the following types of pattern, all the host's names are checked: | |
7641 | ||
9b371988 PH |
7642 | .ilist |
7643 | .cindex "asterisk" "in host list" | |
7644 | If a pattern starts with &"*"& the remainder of the item must match the end of | |
7645 | the host name. For example, &`*.b.c`& matches all hosts whose names end in | |
7646 | &'.b.c'&. This special simple form is provided because this is a very common | |
168e428f PH |
7647 | requirement. Other kinds of wildcarding require the use of a regular |
7648 | expression. | |
9b371988 PH |
7649 | .next |
7650 | .cindex "regular expressions" "in host list" | |
7651 | .cindex "host list" "regular expression in" | |
7652 | If the item starts with &"^"& it is taken to be a regular expression which is | |
168e428f | 7653 | matched against the host name. For example, |
9b371988 PH |
7654 | .code |
7655 | ^(a|b)\.c\.d$ | |
7656 | .endd | |
7657 | is a regular expression that matches either of the two hosts &'a.c.d'& or | |
7658 | &'b.c.d'&. When a regular expression is used in a host list, you must take care | |
168e428f | 7659 | that backslash and dollar characters are not misinterpreted as part of the |
9b371988 | 7660 | string expansion. The simplest way to do this is to use &`\N`& to mark that |
168e428f | 7661 | part of the string as non-expandable. For example: |
9b371988 PH |
7662 | .code |
7663 | sender_unqualified_hosts = \N^(a|b)\.c\.d$\N : .... | |
7664 | .endd | |
7665 | &*Warning*&: If you want to match a complete host name, you must include the | |
7666 | &`$`& terminating metacharacter in the regular expression, as in the above | |
168e428f PH |
7667 | example. Without it, a match at the start of the host name is all that is |
7668 | required. | |
9b371988 | 7669 | .endlist |
168e428f PH |
7670 | |
7671 | ||
7672 | ||
7673 | ||
9b371988 PH |
7674 | .section "Behaviour when an IP address or name cannot be found" "SECTbehipnot" |
7675 | .cindex "host" "lookup failures" | |
168e428f | 7676 | While processing a host list, Exim may need to look up an IP address from a |
9b371988 PH |
7677 | name (see section &<<SECThoslispatip>>&), or it may need to look up a host name |
7678 | from an IP address (see section &<<SECThoslispatnam>>&). In either case, the | |
168e428f PH |
7679 | behaviour when it fails to find the information it is seeking is the same. |
7680 | ||
9b371988 PH |
7681 | .cindex "&`+include_unknown`&" |
7682 | .cindex "&`+ignore_unknown`&" | |
168e428f PH |
7683 | By default, Exim behaves as if the host does not match the list. This may not |
7684 | always be what you want to happen. To change Exim's behaviour, the special | |
9b371988 PH |
7685 | items &`+include_unknown`& or &`+ignore_unknown`& may appear in the list (at |
7686 | top level &-- they are not recognized in an indirected file). | |
168e428f | 7687 | |
9b371988 PH |
7688 | .ilist |
7689 | If any item that follows &`+include_unknown`& requires information that | |
168e428f | 7690 | cannot found, Exim behaves as if the host does match the list. For example, |
9b371988 PH |
7691 | .code |
7692 | host_reject_connection = +include_unknown:*.enemy.ex | |
7693 | .endd | |
7694 | rejects connections from any host whose name matches &`*.enemy.ex`&, and also | |
168e428f PH |
7695 | any hosts whose name it cannot find. |
7696 | ||
9b371988 PH |
7697 | .next |
7698 | If any item that follows &`+ignore_unknown`& requires information that cannot | |
168e428f PH |
7699 | be found, Exim ignores that item and proceeds to the rest of the list. For |
7700 | example: | |
9b371988 | 7701 | .code |
168e428f PH |
7702 | accept hosts = +ignore_unknown : friend.example : \ |
7703 | 192.168.4.5 | |
9b371988 PH |
7704 | .endd |
7705 | accepts from any host whose name is &'friend.example'& and from 192.168.4.5, | |
7706 | whether or not its host name can be found. Without &`+ignore_unknown`&, if no | |
168e428f | 7707 | name can be found for 192.168.4.5, it is rejected. |
9b371988 | 7708 | .endlist |
168e428f | 7709 | |
9b371988 | 7710 | Both &`+include_unknown`& and &`+ignore_unknown`& may appear in the same |
168e428f PH |
7711 | list. The effect of each one lasts until the next, or until the end of the |
7712 | list. | |
7713 | ||
9b371988 | 7714 | &*Note*&: This section applies to permanent lookup failures. It does &'not'& |
168e428f PH |
7715 | apply to temporary DNS errors. They always cause a defer action. |
7716 | ||
7717 | ||
7718 | ||
9b371988 PH |
7719 | .section "Host list patterns for single-key lookups by host name" &&& |
7720 | "SECThoslispatnamsk" | |
7721 | .cindex "host" "lookup failures" | |
7722 | .cindex "unknown host name" | |
7723 | .cindex "host list" "matching host name" | |
168e428f | 7724 | If a pattern is of the form |
9b371988 PH |
7725 | .display |
7726 | <&'single-key-search-type'&>;<&'search-data'&> | |
7727 | .endd | |
168e428f | 7728 | for example |
9b371988 PH |
7729 | .code |
7730 | dbm;/host/accept/list | |
7731 | .endd | |
168e428f PH |
7732 | a single-key lookup is performend, using the host name as its key. If the |
7733 | lookup succeeds, the host matches the item. The actual data that is looked up | |
7734 | is not used. | |
7735 | ||
9b371988 | 7736 | &*Reminder*&: With this kind of pattern, you must have host &'names'& as |
168e428f | 7737 | keys in the file, not IP addresses. If you want to do lookups based on IP |
9b371988 PH |
7738 | addresses, you must precede the search type with &"net-"& (see section |
7739 | &<<SECThoslispatsikey>>&). There is, however, no reason why you could not use | |
7740 | two items in the same list, one doing an address lookup and one doing a name | |
168e428f PH |
7741 | lookup, both using the same file. |
7742 | ||
7743 | ||
7744 | ||
9b371988 | 7745 | .section "Host list patterns for query-style lookups" |
168e428f | 7746 | If a pattern is of the form |
9b371988 PH |
7747 | .display |
7748 | <&'query-style-search-type'&>;<&'query'&> | |
7749 | .endd | |
168e428f | 7750 | the query is obeyed, and if it succeeds, the host matches the item. The actual |
9b371988 PH |
7751 | data that is looked up is not used. The variables &$sender_host_address$& and |
7752 | &$sender_host_name$& can be used in the query. For example: | |
7753 | .code | |
168e428f PH |
7754 | hosts_lookup = pgsql;\ |
7755 | select ip from hostlist where ip='$sender_host_address' | |
9b371988 PH |
7756 | .endd |
7757 | The value of &$sender_host_address$& for an IPv6 address contains colons. You | |
7758 | can use the &%sg%& expansion item to change this if you need to. If you want to | |
7759 | use masked IP addresses in database queries, you can use the &%mask%& expansion | |
168e428f PH |
7760 | operator. |
7761 | ||
9b371988 | 7762 | If the query contains a reference to &$sender_host_name$&, Exim automatically |
168e428f | 7763 | looks up the host name if has not already done so. (See section |
9b371988 | 7764 | &<<SECThoslispatnam>>& for comments on finding host names.) |
168e428f PH |
7765 | |
7766 | Historical note: prior to release 4.30, Exim would always attempt to find a | |
7767 | host name before running the query, unless the search type was preceded by | |
9b371988 | 7768 | &`net-`&. This is no longer the case. For backwards compatibility, &`net-`& is |
168e428f | 7769 | still recognized for query-style lookups, but its presence or absence has no |
9b371988 PH |
7770 | effect. (Of course, for single-key lookups, &`net-`& &'is'& important. |
7771 | See section &<<SECThoslispatsikey>>&.) | |
168e428f PH |
7772 | |
7773 | ||
7774 | ||
9b371988 PH |
7775 | .section "Mixing wildcarded host names and addresses in host lists" &&& |
7776 | "SECTmixwilhos" | |
7777 | .cindex "host list" "mixing names and addresses in" | |
168e428f PH |
7778 | If you have name lookups or wildcarded host names and IP addresses in the same |
7779 | host list, you should normally put the IP addresses first. For example, in an | |
7780 | ACL you could have: | |
9b371988 PH |
7781 | .code |
7782 | accept hosts = 10.9.8.7 : *.friend.example | |
7783 | .endd | |
168e428f PH |
7784 | The reason for this lies in the left-to-right way that Exim processes lists. |
7785 | It can test IP addresses without doing any DNS lookups, but when it reaches an | |
7786 | item that requires a host name, it fails if it cannot find a host name to | |
7787 | compare with the pattern. If the above list is given in the opposite order, the | |
9b371988 | 7788 | &%accept%& statement fails for a host whose name cannot be found, even if its |
168e428f PH |
7789 | IP address is 10.9.8.7. |
7790 | ||
7791 | If you really do want to do the name check first, and still recognize the IP | |
7792 | address, you can rewrite the ACL like this: | |
9b371988 PH |
7793 | .code |
7794 | accept hosts = *.friend.example | |
7795 | accept hosts = 10.9.8.7 | |
7796 | .endd | |
7797 | If the first &%accept%& fails, Exim goes on to try the second one. See chapter | |
7798 | &<<CHAPACL>>& for details of ACLs. | |
168e428f PH |
7799 | |
7800 | ||
7801 | ||
7802 | ||
7803 | ||
9b371988 PH |
7804 | .section "Address lists" "SECTaddresslist" |
7805 | .cindex "list" "address list" | |
7806 | .cindex "address list" "empty item" | |
7807 | .cindex "address list" "patterns" | |
168e428f PH |
7808 | Address lists contain patterns that are matched against mail addresses. There |
7809 | is one special case to be considered: the sender address of a bounce message is | |
7810 | always empty. You can test for this by providing an empty item in an address | |
7811 | list. For example, you can set up a router to process bounce messages by | |
7812 | using this option setting: | |
9b371988 PH |
7813 | .code |
7814 | senders = : | |
7815 | .endd | |
168e428f PH |
7816 | The presence of the colon creates an empty item. If you do not provide any |
7817 | data, the list is empty and matches nothing. The empty sender can also be | |
7818 | detected by a regular expression that matches an empty string, | |
9b371988 | 7819 | and by a query-style lookup that succeeds when &$sender_address$& is empty. |
168e428f PH |
7820 | |
7821 | The following kinds of address list pattern can match any address, including | |
7822 | the empty address that is characteristic of bounce message senders: | |
7823 | ||
9b371988 PH |
7824 | .ilist |
7825 | As explained above, if a pattern item is empty, it matches the empty address | |
168e428f PH |
7826 | (and no others). |
7827 | ||
9b371988 PH |
7828 | .next |
7829 | .cindex "regular expressions" "in address list" | |
7830 | .cindex "address list" "regular expression in" | |
7831 | If (after expansion) a pattern starts with &"^"&, a regular expression match is | |
168e428f PH |
7832 | done against the complete address, with the pattern as the regular expression. |
7833 | You must take care that backslash and dollar characters are not misinterpreted | |
9b371988 | 7834 | as part of the string expansion. The simplest way to do this is to use &`\N`& |
168e428f | 7835 | to mark that part of the string as non-expandable. For example: |
9b371988 PH |
7836 | .code |
7837 | deny senders = \N^\d{8}.+@spamhaus.example$\N : ... | |
7838 | .endd | |
7839 | The &`\N`& sequences are removed by the expansion, so this item does indeed | |
7840 | start with &"^"& by the time it is being interpreted as an address pattern. | |
7841 | ||
7842 | .next | |
7843 | .cindex "address list" "lookup for complete address" | |
168e428f PH |
7844 | Complete addresses can be looked up by using a pattern that starts with a |
7845 | lookup type terminated by a semicolon, followed by the data for the lookup. For | |
7846 | example: | |
9b371988 | 7847 | .code |
168e428f PH |
7848 | deny senders = cdb;/etc/blocked.senders : \ |
7849 | mysql;select address from blocked where \ | |
7850 | address='${quote_mysql:$sender_address}' | |
9b371988 | 7851 | .endd |
168e428f PH |
7852 | Both query-style and single-key lookup types can be used. For a single-key |
7853 | lookup type, Exim uses the complete address as the key. However, empty keys are | |
7854 | not supported for single-key lookups, so a match against the empty address | |
7855 | always fails. This restriction does not apply to query-style lookups. | |
9b371988 PH |
7856 | |
7857 | Partial matching for single-key lookups (section &<<SECTpartiallookup>>&) | |
7858 | cannot be used, and is ignored if specified, with an entry being written to the | |
7859 | panic log. | |
7860 | .cindex "*@ with single-key lookup" | |
168e428f | 7861 | However, you can configure lookup defaults, as described in section |
9b371988 | 7862 | &<<SECTdefaultvaluelookups>>&, but this is useful only for the &"*@"& type of |
168e428f | 7863 | default. For example, with this lookup: |
9b371988 PH |
7864 | .code |
7865 | accept senders = lsearch*@;/some/file | |
7866 | .endd | |
168e428f | 7867 | the file could contains lines like this: |
9b371988 PH |
7868 | .code |
7869 | user1@domain1.example | |
7870 | *@domain2.example | |
7871 | .endd | |
7872 | and for the sender address &'nimrod@jaeger.example'&, the sequence of keys | |
168e428f | 7873 | that are tried is: |
9b371988 PH |
7874 | .code |
7875 | nimrod@jaeger.example | |
7876 | *@jaeger.example | |
7877 | * | |
7878 | .endd | |
7879 | &*Warning 1*&: Do not include a line keyed by &"*"& in the file, because that | |
168e428f | 7880 | would mean that every address matches, thus rendering the test useless. |
168e428f | 7881 | |
9b371988 PH |
7882 | &*Warning 2*&: Do not confuse these two kinds of item: |
7883 | .code | |
7884 | deny recipients = dbm*@;/some/file | |
7885 | deny recipients = *@dbm;/some/file | |
7886 | .endd | |
168e428f PH |
7887 | The first does a whole address lookup, with defaulting, as just described, |
7888 | because it starts with a lookup type. The second matches the local part and | |
7889 | domain independently, as described in a bullet point below. | |
9b371988 | 7890 | .endlist |
168e428f PH |
7891 | |
7892 | ||
7893 | The following kinds of address list pattern can match only non-empty addresses. | |
7894 | If the subject address is empty, a match against any of these pattern types | |
7895 | always fails. | |
7896 | ||
7897 | ||
9b371988 PH |
7898 | .ilist |
7899 | .cindex "@@ with single-key lookup" | |
7900 | .cindex "address list" "@@ lookup type" | |
7901 | .cindex "address list" "split local part and domain" | |
7902 | If a pattern starts with &"@@"& followed by a single-key lookup item | |
7903 | (for example, &`@@lsearch;/some/file`&), the address that is being checked is | |
168e428f PH |
7904 | split into a local part and a domain. The domain is looked up in the file. If |
7905 | it is not found, there is no match. If it is found, the data that is looked up | |
7906 | from the file is treated as a colon-separated list of local part patterns, each | |
7907 | of which is matched against the subject local part in turn. | |
168e428f | 7908 | |
9b371988 PH |
7909 | .cindex "asterisk" "in address list" |
7910 | The lookup may be a partial one, and/or one involving a search for a default | |
7911 | keyed by &"*"& (see section &<<SECTdefaultvaluelookups>>&). The local part | |
7912 | patterns that are looked up can be regular expressions or begin with &"*"&, or | |
7913 | even be further lookups. They may also be independently negated. For example, | |
7914 | with | |
7915 | .code | |
7916 | deny senders = @@dbm;/etc/reject-by-domain | |
7917 | .endd | |
168e428f | 7918 | the data from which the DBM file is built could contain lines like |
9b371988 PH |
7919 | .code |
7920 | baddomain.com: !postmaster : * | |
7921 | .endd | |
7922 | to reject all senders except &%postmaster%& from that domain. | |
168e428f | 7923 | |
9b371988 | 7924 | .cindex "local part" "starting with !" |
168e428f | 7925 | If a local part that actually begins with an exclamation mark is required, it |
9b371988 | 7926 | has to be specified using a regular expression. In &(lsearch)& files, an entry |
168e428f PH |
7927 | may be split over several lines by indenting the second and subsequent lines, |
7928 | but the separating colon must still be included at line breaks. White space | |
7929 | surrounding the colons is ignored. For example: | |
9b371988 PH |
7930 | .code |
7931 | aol.com: spammer1 : spammer2 : ^[0-9]+$ : | |
7932 | spammer3 : spammer4 | |
7933 | .endd | |
168e428f PH |
7934 | As in all colon-separated lists in Exim, a colon can be included in an item by |
7935 | doubling. | |
9b371988 | 7936 | |
168e428f PH |
7937 | If the last item in the list starts with a right angle-bracket, the remainder |
7938 | of the item is taken as a new key to look up in order to obtain a continuation | |
7939 | list of local parts. The new key can be any sequence of characters. Thus one | |
7940 | might have entries like | |
9b371988 PH |
7941 | .code |
7942 | aol.com: spammer1 : spammer 2 : >* | |
7943 | xyz.com: spammer3 : >* | |
7944 | *: ^\d{8}$ | |
7945 | .endd | |
7946 | in a file that was searched with &%@@dbm*%&, to specify a match for 8-digit | |
168e428f PH |
7947 | local parts for all domains, in addition to the specific local parts listed for |
7948 | each domain. Of course, using this feature costs another lookup each time a | |
7949 | chain is followed, but the effort needed to maintain the data is reduced. | |
9b371988 PH |
7950 | |
7951 | .cindex "loop" "in lookups" | |
168e428f PH |
7952 | It is possible to construct loops using this facility, and in order to catch |
7953 | them, the chains may be no more than fifty items long. | |
7954 | ||
9b371988 PH |
7955 | .next |
7956 | The @@<&'lookup'&> style of item can also be used with a query-style | |
168e428f PH |
7957 | lookup, but in this case, the chaining facility is not available. The lookup |
7958 | can only return a single list of local parts. | |
9b371988 PH |
7959 | .next |
7960 | If a pattern contains an @ character, but is not a regular expression and does | |
168e428f PH |
7961 | not begin with a lookup type as described above, the local part of the subject |
7962 | address is compared with the local part of the pattern, which may start with an | |
7963 | asterisk. If the local parts match, the domain is checked in exactly the same | |
7964 | way as for a pattern in a domain list. For example, the domain can be | |
7965 | wildcarded, refer to a named list, or be a lookup: | |
9b371988 | 7966 | .code |
168e428f PH |
7967 | deny senders = *@*.spamming.site:\ |
7968 | *@+hostile_domains:\ | |
7969 | bozo@partial-lsearch;/list/of/dodgy/sites:\ | |
7970 | *@dbm;/bad/domains.db | |
9b371988 PH |
7971 | .endd |
7972 | .cindex "local part" "starting with !" | |
7973 | .cindex "address list" "local part starting with !" | |
168e428f PH |
7974 | If a local part that begins with an exclamation mark is required, it has to be |
7975 | specified using a regular expression, because otherwise the exclamation mark is | |
7976 | treated as a sign of negation. | |
9b371988 PH |
7977 | .next |
7978 | If a pattern is not one of the above syntax forms, that is, if a | |
168e428f PH |
7979 | non-empty pattern that is not a regular expression or a lookup does not contain |
7980 | an @ character, it is matched against the domain part of the subject address. | |
7981 | The only two formats that are recognized this way are a literal domain, or a | |
9b371988 PH |
7982 | domain pattern that starts with *. In both these cases, the effect is the same |
7983 | as if &`*@`& preceded the pattern. | |
7984 | .endlist | |
168e428f | 7985 | |
9b371988 | 7986 | &*Warning*&: There is an important difference between the address list items |
168e428f | 7987 | in these two examples: |
9b371988 PH |
7988 | .code |
7989 | senders = +my_list | |
7990 | senders = *@+my_list | |
7991 | .endd | |
7992 | In the first one, &`my_list`& is a named address list, whereas in the second | |
168e428f PH |
7993 | example it is a named domain list. |
7994 | ||
7995 | ||
7996 | ||
7997 | ||
9b371988 PH |
7998 | .section "Case of letters in address lists" "SECTcasletadd" |
7999 | .cindex "case of local parts" | |
8000 | .cindex "address list" "case forcing" | |
8001 | .cindex "case forcing in address lists" | |
168e428f | 8002 | Domains in email addresses are always handled caselessly, but for local parts |
9b371988 PH |
8003 | case may be significant on some systems (see &%caseful_local_part%& for how |
8004 | Exim deals with this when routing addresses). However, RFC 2505 (&'Anti-Spam | |
8005 | Recommendations for SMTP MTAs'&) suggests that matching of addresses to | |
8006 | blocking lists should be done in a case-independent manner. Since most address | |
8007 | lists in Exim are used for this kind of control, Exim attempts to do this by | |
8008 | default. | |
168e428f PH |
8009 | |
8010 | The domain portion of an address is always lowercased before matching it to an | |
8011 | address list. The local part is lowercased by default, and any string | |
8012 | comparisons that take place are done caselessly. This means that the data in | |
8013 | the address list itself, in files included as plain file names, and in any file | |
9b371988 PH |
8014 | that is looked up using the &"@@"& mechanism, can be in any case. However, the |
8015 | keys in files that are looked up by a search type other than &(lsearch)& (which | |
168e428f PH |
8016 | works caselessly) must be in lower case, because these lookups are not |
8017 | case-independent. | |
8018 | ||
9b371988 | 8019 | .cindex "&`+caseful`&" |
168e428f | 8020 | To allow for the possibility of caseful address list matching, if an item in |
9b371988 | 8021 | an address list is the string &"+caseful"&, the original case of the local |
168e428f PH |
8022 | part is restored for any comparisons that follow, and string comparisons are no |
8023 | longer case-independent. This does not affect the domain, which remains in | |
8024 | lower case. However, although independent matches on the domain alone are still | |
8025 | performed caselessly, regular expressions that match against an entire address | |
9b371988 | 8026 | become case-sensitive after &"+caseful"& has been seen. |
168e428f PH |
8027 | |
8028 | ||
8029 | ||
9b371988 PH |
8030 | .section "Local part lists" "SECTlocparlis" |
8031 | .cindex "list" "local part list" | |
8032 | .cindex "local part" "list" | |
168e428f | 8033 | Case-sensitivity in local part lists is handled in the same way as for address |
9b371988 PH |
8034 | lists, as just described. The &"+caseful"& item can be used if required. In a |
8035 | setting of the &%local_parts%& option in a router with &%caseful_local_part%& | |
168e428f | 8036 | set false, the subject is lowercased and the matching is initially |
9b371988 PH |
8037 | case-insensitive. In this case, &"+caseful"& will restore case-sensitive |
8038 | matching in the local part list, but not elsewhere in the router. If | |
8039 | &%caseful_local_part%& is set true in a router, matching in the &%local_parts%& | |
168e428f PH |
8040 | option is case-sensitive from the start. |
8041 | ||
9b371988 PH |
8042 | If a local part list is indirected to a file (see section &<<SECTfilnamlis>>&), |
8043 | comments are handled in the same way as address lists &-- they are recognized | |
168e428f PH |
8044 | only if the # is preceded by white space or the start of the line. |
8045 | Otherwise, local part lists are matched in the same way as domain lists, except | |
9b371988 PH |
8046 | that the special items that refer to the local host (&`@`&, &`@[]`&, |
8047 | &`@mx_any`&, &`@mx_primary`&, and &`@mx_secondary`&) are not recognized. | |
8048 | Refer to section &<<SECTdomainlist>>& for details of the other available item | |
168e428f PH |
8049 | types. |
8050 | ||
8051 | ||
8052 | ||
8053 | ||
9b371988 PH |
8054 | . //////////////////////////////////////////////////////////////////////////// |
8055 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 8056 | |
9b371988 PH |
8057 | .chapter "String expansions" "CHAPexpand" |
8058 | .cindex "expansion" "of strings" | |
168e428f PH |
8059 | Many strings in Exim's run time configuration are expanded before use. Some of |
8060 | them are expanded every time they are used; others are expanded only once. | |
8061 | ||
8062 | When a string is being expanded it is copied verbatim from left to right except | |
8063 | when a dollar or backslash character is encountered. A dollar specifies the | |
068aaea8 | 8064 | start of a portion of the string that is interpreted and replaced as described |
9b371988 PH |
8065 | below in section &<<SECTexpansionitems>>& onwards. Backslash is used as an |
8066 | escape character, as described in the following section. | |
168e428f PH |
8067 | |
8068 | ||
8069 | ||
9b371988 PH |
8070 | .section "Literal text in expanded strings" "SECTlittext" |
8071 | .cindex "expansion" "including literal text" | |
168e428f PH |
8072 | An uninterpreted dollar can be included in an expanded string by putting a |
8073 | backslash in front of it. A backslash can be used to prevent any special | |
068aaea8 PH |
8074 | character being treated specially in an expansion, including backslash itself. |
8075 | If the string appears in quotes in the configuration file, two backslashes are | |
168e428f | 8076 | required because the quotes themselves cause interpretation of backslashes when |
9b371988 | 8077 | the string is read in (see section &<<SECTstrings>>&). |
168e428f | 8078 | |
9b371988 | 8079 | .cindex "expansion" "non-expandable substrings" |
168e428f | 8080 | A portion of the string can specified as non-expandable by placing it between |
9b371988 | 8081 | two occurrences of &`\N`&. This is particularly useful for protecting regular |
168e428f | 8082 | expressions, which often contain backslashes and dollar signs. For example: |
9b371988 PH |
8083 | .code |
8084 | deny senders = \N^\d{8}[a-z]@some\.site\.example$\N | |
8085 | .endd | |
8086 | On encountering the first &`\N`&, the expander copies subsequent characters | |
8087 | without interpretation until it reaches the next &`\N`& or the end of the | |
168e428f PH |
8088 | string. |
8089 | ||
8090 | ||
8091 | ||
9b371988 PH |
8092 | .section "Character escape sequences in expanded strings" |
8093 | .cindex "expansion" "escape sequences" | |
8094 | A backslash followed by one of the letters &"n"&, &"r"&, or &"t"& in an | |
8095 | expanded string is recognized as an escape sequence for the character newline, | |
8096 | carriage return, or tab, respectively. A backslash followed by up to three | |
8097 | octal digits is recognized as an octal encoding for a single character, and a | |
8098 | backslash followed by &"x"& and up to two hexadecimal digits is a hexadecimal | |
8099 | encoding. | |
168e428f PH |
8100 | |
8101 | These escape sequences are also recognized in quoted strings when they are read | |
8102 | in. Their interpretation in expansions as well is useful for unquoted strings, | |
8103 | and for other cases such as looked-up strings that are then expanded. | |
8104 | ||
8105 | ||
9b371988 PH |
8106 | .section "Testing string expansions" |
8107 | .cindex "expansion" "testing" | |
8108 | .cindex "testing" "string expansion" | |
8109 | .cindex "&%-be%& option" | |
8110 | Many expansions can be tested by calling Exim with the &%-be%& option. This | |
8111 | takes the command arguments, or lines from the standard input if there are no | |
168e428f PH |
8112 | arguments, runs them through the string expansion code, and writes the results |
8113 | to the standard output. Variables based on configuration values are set up, but | |
9b371988 PH |
8114 | since no message is being processed, variables such as &$local_part$& have no |
8115 | value. Nevertheless the &%-be%& option can be useful for checking out file and | |
8116 | database lookups, and the use of expansion operators such as &%sg%&, &%substr%& | |
8117 | and &%nhash%&. | |
168e428f | 8118 | |
9b371988 | 8119 | Exim gives up its root privilege when it is called with the &%-be%& option, and |
168e428f | 8120 | instead runs under the uid and gid it was called with, to prevent users from |
9b371988 | 8121 | using &%-be%& for reading files to which they do not have access. |
168e428f PH |
8122 | |
8123 | ||
8124 | ||
9b371988 PH |
8125 | .section "Forced expansion failure" "SECTforexpfai" |
8126 | .cindex "expansion" "forced failure" | |
168e428f | 8127 | A number of expansions that are described in the following section have |
9b371988 PH |
8128 | alternative &"true"& and &"false"& substrings, enclosed in brace characters |
8129 | (which are sometimes called &"curly brackets"&). Which of the two strings is | |
068aaea8 | 8130 | used depends on some condition that is evaluated as part of the expansion. If, |
9b371988 | 8131 | instead of a &"false"& substring, the word &"fail"& is used (not in braces), |
068aaea8 | 8132 | the entire string expansion fails in a way that can be detected by the code |
9b371988 | 8133 | that requested the expansion. This is called &"forced expansion failure"&, and |
068aaea8 PH |
8134 | its consequences depend on the circumstances. In some cases it is no different |
8135 | from any other expansion failure, but in others a different action may be | |
8136 | taken. Such variations are mentioned in the documentation of the option that is | |
8137 | being expanded. | |
168e428f PH |
8138 | |
8139 | ||
8140 | ||
8141 | ||
9b371988 | 8142 | .section "Expansion items" "SECTexpansionitems" |
168e428f PH |
8143 | The following items are recognized in expanded strings. White space may be used |
8144 | between sub-items that are keywords or substrings enclosed in braces inside an | |
9b371988 | 8145 | outer set of braces, to improve readability. &*Warning*&: Within braces, |
168e428f PH |
8146 | white space is significant. |
8147 | ||
9b371988 PH |
8148 | .vlist |
8149 | .vitem &*$*&<&'variable&~name'&>&~or&~&*${*&<&'variable&~name'&>&*}*& | |
8150 | .cindex "expansion" "variables" | |
8151 | Substitute the contents of the named variable, for example: | |
8152 | .code | |
8153 | $local_part | |
8154 | ${domain} | |
8155 | .endd | |
168e428f | 8156 | The second form can be used to separate the name from subsequent alphanumeric |
068aaea8 | 8157 | characters. This form (using braces) is available only for variables; it does |
9b371988 PH |
8158 | &'not'& apply to message headers. The names of the variables are given in |
8159 | section &<<SECTexpvar>>& below. If the name of a non-existent variable is | |
8160 | given, the expansion fails. | |
8161 | ||
8162 | .vitem &*${*&<&'op'&>&*:*&<&'string'&>&*}*& | |
8163 | .cindex "expansion" "operators" | |
8164 | The string is first itself expanded, and then the operation specified by | |
8165 | <&'op'&> is applied to it. For example: | |
8166 | .code | |
8167 | ${lc:$local_part} | |
8168 | .endd | |
168e428f | 8169 | The string starts with the first character after the colon, which may be |
9b371988 | 8170 | leading white space. A list of operators is given in section &<<SECTexpop>>& |
168e428f PH |
8171 | below. The operator notation is used for simple expansion items that have just |
8172 | one argument, because it reduces the number of braces and therefore makes the | |
8173 | string easier to understand. | |
8174 | ||
9b371988 PH |
8175 | .new |
8176 | .vitem "&*${dlfunc{*&<&'file'&>&*}{*&<&'function'&>&*}{*&<&'arg'&>&*}&&& | |
8177 | {*&<&'arg'&>&*}...}*&" | |
8178 | ||
068aaea8 PH |
8179 | This expansion dynamically loads and then calls a locally-written C function. |
8180 | This functionality is available only if Exim is compiled with | |
9b371988 PH |
8181 | .code |
8182 | EXPAND_DLFUNC=yes | |
8183 | .endd | |
8184 | set in &_Local/Makefile_&. Once loaded, Exim remembers the dynamically loaded | |
068aaea8 PH |
8185 | object so that it doesn't reload the same object file in the same Exim process |
8186 | (but of course Exim does start new processes frequently). | |
9b371988 | 8187 | |
068aaea8 | 8188 | There may be from zero to eight arguments to the function. When compiling |
9b371988 | 8189 | a local function that is to be called in this way, &_local_scan.h_& should be |
068aaea8 PH |
8190 | included. The Exim variables and functions that are defined by that API |
8191 | are also available for dynamically loaded functions. The function itself | |
8192 | must have the following type: | |
9b371988 | 8193 | .code |
068aaea8 | 8194 | int dlfunction(uschar **yield, int argc, uschar *argv[]) |
9b371988 PH |
8195 | .endd |
8196 | Where &`uschar`& is a typedef for &`unsigned char`& in &_local_scan.h_&. The | |
068aaea8 | 8197 | function should return one of the following values: |
068aaea8 | 8198 | |
9b371988 PH |
8199 | &`OK`&: Success. The string that is placed in the variable &'yield'& is put |
8200 | into the expanded string that is being built. | |
8201 | ||
8202 | &`FAIL`&: A non-forced expansion failure occurs, with the error message taken | |
8203 | from &'yield'&, if it is set. | |
8204 | ||
8205 | &`FAIL_FORCED`&: A forced expansion failure occurs, with the error message | |
8206 | taken from &'yield'& if it is set. | |
8207 | ||
8208 | &`ERROR`&: Same as &`FAIL`&, except that a panic log entry is written. | |
068aaea8 | 8209 | |
9b371988 PH |
8210 | When compiling a function that is to be used in this way with gcc, |
8211 | you need to add &%-shared%& to the gcc command. Also, in the Exim build-time | |
8212 | configuration, you must add &%-export-dynamic%& to EXTRALIBS. | |
8213 | .wen | |
8214 | ||
8215 | .vitem "&*${extract{*&<&'key'&>&*}{*&<&'string1'&>&*}{*&<&'string2'&>&*}&&& | |
8216 | {*&<&'string3'&>&*}}*&" | |
8217 | .cindex "expansion" "extracting substrings by key" | |
8218 | The key and <&'string1'&> are first expanded separately. Leading and trailing | |
068aaea8 | 8219 | white space is removed from the key (but not from any of the strings). The key |
9b371988 | 8220 | must not consist entirely of digits. The expanded <&'string1'&> must be of the |
068aaea8 | 8221 | form: |
9b371988 PH |
8222 | .display |
8223 | <&'key1'&> = <&'value1'&> <&'key2'&> = <&'value2'&> ... | |
8224 | .endd | |
8225 | .cindex "&$value$&" | |
068aaea8 PH |
8226 | where the equals signs and spaces (but not both) are optional. If any of the |
8227 | values contain white space, they must be enclosed in double quotes, and any | |
8228 | values that are enclosed in double quotes are subject to escape processing as | |
9b371988 PH |
8229 | described in section &<<SECTstrings>>&. The expanded <&'string1'&> is searched |
8230 | for the value that corresponds to the key. The search is case-insensitive. If | |
8231 | the key is found, <&'string2'&> is expanded, and replaces the whole item; | |
8232 | otherwise <&'string3'&> is used. During the expansion of <&'string2'&> the | |
8233 | variable &$value$& contains the value that has been extracted. Afterwards, it | |
8234 | is restored to any previous value it might have had. | |
8235 | ||
8236 | If {<&'string3'&>} is omitted, the item is replaced by an empty string if the | |
8237 | key is not found. If {<&'string2'&>} is also omitted, the value that was | |
168e428f | 8238 | extracted is used. Thus, for example, these two expansions are identical, and |
9b371988 PH |
8239 | yield &"2001"&: |
8240 | .code | |
8241 | ${extract{gid}{uid=1984 gid=2001}} | |
8242 | ${extract{gid}{uid=1984 gid=2001}{$value}} | |
8243 | .endd | |
8244 | Instead of {<&'string3'&>} the word &"fail"& (not in curly brackets) can | |
168e428f | 8245 | appear, for example: |
9b371988 PH |
8246 | .code |
8247 | ${extract{Z}{A=... B=...}{$value} fail } | |
8248 | .endd | |
8249 | This forces an expansion failure (see section &<<SECTforexpfai>>&); | |
8250 | {<&'string2'&>} must be present for &"fail"& to be recognized. | |
168e428f PH |
8251 | |
8252 | ||
9b371988 PH |
8253 | .vitem "&*${extract{*&<&'number'&>&*}{*&<&'separators'&>&*}&&& |
8254 | {*&<&'string1'&>&*}{*&<&'string2'&>&*}{*&<&'string3'&>&*}}*&" | |
8255 | .cindex "expansion" "extracting substrings by number" | |
8256 | The <&'number'&> argument must consist entirely of decimal digits, | |
068aaea8 | 8257 | apart from leading and trailing white space, which is ignored. |
9b371988 | 8258 | This is what distinguishes this form of &%extract%& from the previous kind. It |
168e428f | 8259 | behaves in the same way, except that, instead of extracting a named field, it |
9b371988 PH |
8260 | extracts from <&'string1'&> the field whose number is given as the first |
8261 | argument. You can use &$value$& in <&'string2'&> or &`fail`& instead of | |
8262 | <&'string3'&> as before. | |
8263 | ||
168e428f PH |
8264 | The fields in the string are separated by any one of the characters in the |
8265 | separator string. These may include space or tab characters. | |
8266 | The first field is numbered one. If the number is negative, the fields are | |
8267 | counted from the end of the string, with the rightmost one numbered -1. If the | |
8268 | number given is zero, the entire string is returned. If the modulus of the | |
8269 | number is greater than the number of fields in the string, the result is the | |
9b371988 PH |
8270 | expansion of <&'string3'&>, or the empty string if <&'string3'&> is not |
8271 | provided. For example: | |
8272 | .code | |
8273 | ${extract{2}{:}{x:42:99:& Mailer::/bin/bash}} | |
8274 | .endd | |
8275 | yields &"42"&, and | |
8276 | .code | |
8277 | ${extract{-4}{:}{x:42:99:& Mailer::/bin/bash}} | |
8278 | .endd | |
8279 | yields &"99"&. Two successive separators mean that the field between them is | |
168e428f PH |
8280 | empty (for example, the fifth field above). |
8281 | ||
8282 | ||
9b371988 PH |
8283 | .vitem &*${hash{*&<&'string1'&>&*}{*&<&'string2'&>&*}{*&<&'string3'&>&*}}*& |
8284 | .cindex "hash function" "textual" | |
8285 | .cindex "expansion" "textual hash" | |
168e428f PH |
8286 | This is a textual hashing function, and was the first to be implemented in |
8287 | early versions of Exim. In current releases, there are other hashing functions | |
8288 | (numeric, MD5, and SHA-1), which are described below. | |
9b371988 PH |
8289 | |
8290 | The first two strings, after expansion, must be numbers. Call them <&'m'&> and | |
8291 | <&'n'&>. If you are using fixed values for these numbers, that is, if | |
8292 | <&'string1'&> and <&'string2'&> do not change when they are expanded, you can | |
8293 | use the simpler operator notation that avoids some of the braces: | |
8294 | .code | |
8295 | ${hash_<n>_<m>:<string>} | |
8296 | .endd | |
8297 | The second number is optional (in both notations). If <&'n'&> is greater than | |
8298 | or equal to the length of the string, the expansion item returns the string. | |
8299 | Otherwise it computes a new string of length <&'n'&> by applying a hashing | |
8300 | function to the string. The new string consists of characters taken from the | |
8301 | first <&'m'&> characters of the string | |
8302 | .code | |
8303 | abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQWRSTUVWXYZ0123456789 | |
8304 | .endd | |
8305 | If <&'m'&> is not present the value 26 is used, so that only lower case | |
168e428f | 8306 | letters appear. For example: |
9b371988 PH |
8307 | .display |
8308 | &`$hash{3}{monty}} `& yields &`jmg`& | |
8309 | &`$hash{5}{monty}} `& yields &`monty`& | |
8310 | &`$hash{4}{62}{monty python}}`& yields &`fbWx`& | |
8311 | .endd | |
8312 | ||
8313 | .vitem "&*$header_*&<&'header&~name'&>&*:*&&~or&~&&& | |
8314 | &*$h_*&<&'header&~name'&>&*:*&" | |
8315 | See &*$rheader*& below. | |
8316 | ||
8317 | .vitem "&*$bheader_*&<&'header&~name'&>&*:*&&~or&~&&& | |
8318 | &*$bh_*&<&'header&~name'&>&*:*&" | |
8319 | See &*$rheader*& below. | |
8320 | ||
8321 | .vitem "&*$rheader_*&<&'header&~name'&>&*:*&&~or&~&&& | |
8322 | &*$rh_*&<&'header&~name'&>&*:*&" | |
8323 | .cindex "expansion" "header insertion" | |
8324 | .cindex "&$header_$&" | |
8325 | .cindex "&$bheader_$&" | |
8326 | .cindex "&$rheader_$&" | |
8327 | .cindex "header lines" "in expansion strings" | |
8328 | .cindex "header lines" "character sets" | |
8329 | .cindex "header lines" "decoding" | |
168e428f | 8330 | Substitute the contents of the named message header line, for example |
9b371988 PH |
8331 | .code |
8332 | $header_reply-to: | |
8333 | .endd | |
168e428f PH |
8334 | The newline that terminates a header line is not included in the expansion, but |
8335 | internal newlines (caused by splitting the header line over several physical | |
8336 | lines) may be present. | |
9b371988 PH |
8337 | |
8338 | The difference between &%rheader%&, &%bheader%&, and &%header%& is in the way | |
8339 | the data in the header line is interpreted. | |
8340 | ||
8341 | .ilist | |
8342 | .cindex "white space" "in header lines" | |
8343 | &%rheader%& gives the original &"raw"& content of the header line, with no | |
068aaea8 | 8344 | processing at all, and without the removal of leading and trailing white space. |
168e428f | 8345 | |
9b371988 PH |
8346 | .next |
8347 | .cindex "base64 encoding" "in header lines" | |
8348 | &%bheader%& removes leading and trailing white space, and then decodes base64 | |
8349 | or quoted-printable MIME &"words"& within the header text, but does no | |
8350 | character set translation. If decoding of what looks superficially like a MIME | |
8351 | &"word"& fails, the raw string is returned. If decoding | |
8352 | .cindex "binary zero" "in header line" | |
8353 | produces a binary zero character, it is replaced by a question mark &-- this is | |
168e428f PH |
8354 | what Exim does for binary zeros that are actually received in header lines. |
8355 | ||
9b371988 PH |
8356 | .next |
8357 | &%header%& tries to translate the string as decoded by &%bheader%& to a | |
8358 | standard character set. This is an attempt to produce the same string as would | |
8359 | be displayed on a user's MUA. If translation fails, the &%bheader%& string is | |
168e428f | 8360 | returned. Translation is attempted only on operating systems that support the |
9b371988 PH |
8361 | &[iconv()]& function. This is indicated by the compile-time macro HAVE_ICONV in |
8362 | a system Makefile or in &_Local/Makefile_&. | |
8363 | .endlist ilist | |
168e428f | 8364 | |
9b371988 PH |
8365 | In a filter file, the target character set for &%header%& can be specified by a |
8366 | command of the following form: | |
8367 | .code | |
8368 | headers charset "UTF-8" | |
8369 | .endd | |
8370 | This command affects all references to &$h_$& (or &$header_$&) expansions in | |
168e428f | 8371 | subsequently obeyed filter commands. In the absence of this command, the target |
9b371988 | 8372 | character set in a filter is taken from the setting of the &%headers_charset%& |
168e428f | 8373 | option in the runtime configuration. The value of this option defaults to the |
9b371988 | 8374 | value of HEADERS_CHARSET in &_Local/Makefile_&. The ultimate default is |
168e428f | 8375 | ISO-8859-1. |
9b371988 | 8376 | |
168e428f PH |
8377 | Header names follow the syntax of RFC 2822, which states that they may contain |
8378 | any printing characters except space and colon. Consequently, curly brackets | |
9b371988 | 8379 | &'do not'& terminate header names, and should not be used to enclose them as |
168e428f | 8380 | if they were variables. Attempting to do so causes a syntax error. |
9b371988 | 8381 | |
168e428f PH |
8382 | Only header lines that are common to all copies of a message are visible to |
8383 | this mechanism. These are the original header lines that are received with the | |
9b371988 | 8384 | message, and any that are added by an ACL &%warn%& statement or by a system |
168e428f PH |
8385 | filter. Header lines that are added to a particular copy of a message by a |
8386 | router or transport are not accessible. | |
9b371988 | 8387 | |
168e428f PH |
8388 | For incoming SMTP messages, no header lines are visible in ACLs that are obeyed |
8389 | before the DATA ACL, because the header structure is not set up until the | |
9b371988 | 8390 | message is received. Header lines that are added by &%warn%& statements in a |
168e428f PH |
8391 | RCPT ACL (for example) are saved until the message's incoming header lines |
8392 | are available, at which point they are added. When a DATA ACL is running, | |
8393 | however, header lines added by earlier ACLs are visible. | |
9b371988 | 8394 | |
168e428f PH |
8395 | Upper case and lower case letters are synonymous in header names. If the |
8396 | following character is white space, the terminating colon may be omitted, but | |
8397 | this is not recommended, because you may then forget it when it is needed. When | |
8398 | white space terminates the header name, it is included in the expanded string. | |
8399 | If the message does not contain the given header, the expansion item is | |
9b371988 PH |
8400 | replaced by an empty string. (See the &%def%& condition in section |
8401 | &<<SECTexpcond>>& for a means of testing for the existence of a header.) | |
8402 | ||
168e428f PH |
8403 | If there is more than one header with the same name, they are all |
8404 | concatenated to form the substitution string, up to a maximum length of 64K. A | |
9b371988 | 8405 | newline character is inserted between each line. For the &%header%& expansion, |
168e428f | 8406 | for those headers that contain lists of addresses, a comma is also inserted at |
9b371988 PH |
8407 | the junctions between lines. This does not happen for the &%rheader%& |
8408 | expansion. | |
168e428f PH |
8409 | |
8410 | ||
9b371988 PH |
8411 | .vitem &*${hmac{*&<&'hashname'&>&*}{*&<&'secret'&>&*}{*&<&'string'&>&*}}*& |
8412 | .cindex "expansion" "hmac hashing" | |
168e428f PH |
8413 | This function uses cryptographic hashing (either MD5 or SHA-1) to convert a |
8414 | shared secret and some text into a message authentication code, as specified in | |
9b371988 PH |
8415 | RFC 2104. This differs from &`${md5:secret_text...}`& or |
8416 | &`${sha1:secret_text...}`& in that the hmac step adds a signature to the | |
168e428f | 8417 | cryptographic hash, allowing for authentication that is not possible with MD5 |
9b371988 PH |
8418 | or SHA-1 alone. The hash name must expand to either &`md5`& or &`sha1`& at |
8419 | present. For example: | |
8420 | .code | |
8421 | ${hmac{md5}{somesecret}{$primary_hostname $tod_log}} | |
8422 | .endd | |
8423 | For the hostname &'mail.example.com'& and time 2002-10-17 11:30:59, this | |
168e428f | 8424 | produces: |
9b371988 PH |
8425 | .code |
8426 | dd97e3ba5d1a61b5006108f8c8252953 | |
8427 | .endd | |
168e428f PH |
8428 | As an example of how this might be used, you might put in the main part of |
8429 | an Exim configuration: | |
9b371988 PH |
8430 | .code |
8431 | SPAMSCAN_SECRET=cohgheeLei2thahw | |
8432 | .endd | |
168e428f | 8433 | In a router or a transport you could then have: |
9b371988 | 8434 | .code |
168e428f | 8435 | headers_add = \ |
d1e83bff | 8436 | X-Spam-Scanned: ${primary_hostname} ${message_exim_id} \ |
168e428f | 8437 | ${hmac{md5}{SPAMSCAN_SECRET}\ |
d1e83bff | 8438 | {${primary_hostname},${message_exim_id},$h_message-id:}} |
9b371988 | 8439 | .endd |
168e428f | 8440 | Then given a message, you can check where it was scanned by looking at the |
9b371988 PH |
8441 | &'X-Spam-Scanned:'& header line. If you know the secret, you can check that |
8442 | this header line is authentic by recomputing the authentication code from the | |
8443 | host name, message ID and the &'Message-id:'& header line. This can be done | |
8444 | using Exim's &%-be%& option, or by other means, for example by using the | |
8445 | &'hmac_md5_hex()'& function in Perl. | |
8446 | ||
8447 | ||
8448 | .vitem &*${if&~*&<&'condition'&>&*&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}}*& | |
8449 | .cindex "expansion" "conditional" | |
8450 | If <&'condition'&> is true, <&'string1'&> is expanded and replaces the whole | |
8451 | item; otherwise <&'string2'&> is used. The available conditions are described | |
8452 | in section &<<SECTexpcond>>& below. For example: | |
8453 | .code | |
8454 | ${if eq {$local_part}{postmaster} {yes}{no} } | |
8455 | .endd | |
168e428f | 8456 | The second string need not be present; if it is not and the condition is not |
9b371988 PH |
8457 | true, the item is replaced with nothing. Alternatively, the word &"fail"& may |
8458 | be present instead of the second string (without any curly brackets). In this | |
168e428f | 8459 | case, the expansion is forced to fail if the condition is not true (see section |
9b371988 PH |
8460 | &<<SECTforexpfai>>&). |
8461 | ||
8462 | If both strings are omitted, the result is the string &`true`& if the condition | |
168e428f PH |
8463 | is true, and the empty string if the condition is false. This makes it less |
8464 | cumbersome to write custom ACL and router conditions. For example, instead of | |
9b371988 PH |
8465 | .code |
8466 | condition = ${if >{$acl_m4}{3}{true}{false}} | |
8467 | .endd | |
168e428f | 8468 | you can use |
9b371988 PH |
8469 | .code |
8470 | condition = ${if >{$acl_m4}{3}} | |
8471 | .endd | |
8472 | ||
8473 | .vitem &*${length{*&<&'string1'&>&*}{*&<&'string2'&>&*}}*& | |
8474 | .cindex "expansion" "string truncation" | |
8475 | The &%length%& item is used to extract the initial portion of a string. Both | |
8476 | strings are expanded, and the first one must yield a number, <&'n'&>, say. If | |
8477 | you are using a fixed value for the number, that is, if <&'string1'&> does not | |
8478 | change when expanded, you can use the simpler operator notation that avoids | |
8479 | some of the braces: | |
8480 | .code | |
8481 | ${length_<n>:<string>} | |
8482 | .endd | |
8483 | The result of this item is either the first <&'n'&> characters or the whole | |
8484 | of <&'string2'&>, whichever is the shorter. Do not confuse &%length%& with | |
8485 | &%strlen%&, which gives the length of a string. | |
8486 | ||
8487 | ||
8488 | .vitem "&*${lookup{*&<&'key'&>&*}&~*&<&'search&~type'&>&*&~&&& | |
8489 | {*&<&'file'&>&*}&~{*&<&'string1'&>&*}&~{*&<&'string2'&>&*}}*&" | |
168e428f PH |
8490 | This is the first of one of two different types of lookup item, which are both |
8491 | described in the next item. | |
8492 | ||
9b371988 PH |
8493 | .vitem "&*${lookup&~*&<&'search&~type'&>&*&~{*&<&'query'&>&*}&~&&& |
8494 | {*&<&'string1'&>&*}&~{*&<&'string2'&>&*}}*&" | |
8495 | .cindex "expansion" "lookup in" | |
8496 | .cindex "file" "lookup" | |
8497 | .cindex "lookup" "in expanded string" | |
168e428f | 8498 | The two forms of lookup item specify data lookups in files and databases, as |
9b371988 PH |
8499 | discussed in chapter &<<CHAPfdlookup>>&. The first form is used for single-key |
8500 | lookups, and the second is used for query-style lookups. The <&'key'&>, | |
8501 | <&'file'&>, and <&'query'&> strings are expanded before use. | |
8502 | ||
168e428f | 8503 | If there is any white space in a lookup item which is part of a filter command, |
9b371988 | 8504 | a retry or rewrite rule, a routing rule for the &(manualroute)& router, or any |
168e428f PH |
8505 | other place where white space is significant, the lookup item must be enclosed |
8506 | in double quotes. The use of data lookups in users' filter files may be locked | |
8507 | out by the system administrator. | |
9b371988 PH |
8508 | |
8509 | .cindex "&$value$&" | |
8510 | If the lookup succeeds, <&'string1'&> is expanded and replaces the entire item. | |
8511 | During its expansion, the variable &$value$& contains the data returned by the | |
168e428f | 8512 | lookup. Afterwards it reverts to the value it had previously (at the outer |
9b371988 PH |
8513 | level it is empty). If the lookup fails, <&'string2'&> is expanded and replaces |
8514 | the entire item. If {<&'string2'&>} is omitted, the replacement is the empty | |
8515 | string on failure. If <&'string2'&> is provided, it can itself be a nested | |
168e428f PH |
8516 | lookup, thus providing a mechanism for looking up a default value when the |
8517 | original lookup fails. | |
9b371988 PH |
8518 | |
8519 | If a nested lookup is used as part of <&'string1'&>, &$value$& contains the | |
8520 | data for the outer lookup while the parameters of the second lookup are | |
8521 | expanded, and also while <&'string2'&> of the second lookup is expanded, should | |
8522 | the second lookup fail. Instead of {<&'string2'&>} the word &"fail"& can | |
8523 | appear, and in this case, if the lookup fails, the entire expansion is forced | |
8524 | to fail (see section &<<SECTforexpfai>>&). If both {<&'string1'&>} and | |
8525 | {<&'string2'&>} are omitted, the result is the looked up value in the case of a | |
8526 | successful lookup, and nothing in the case of failure. | |
8527 | ||
8528 | For single-key lookups, the string &"partial"& is permitted to precede the | |
8529 | search type in order to do partial matching, and * or *@ may follow a search | |
168e428f | 8530 | type to request default lookups if the key does not match (see sections |
9b371988 PH |
8531 | &<<SECTdefaultvaluelookups>>& and &<<SECTpartiallookup>>& for details). |
8532 | ||
8533 | .cindex "numerical variables (&$1$& &$2$& etc)" "in lookup expansion" | |
8534 | If a partial search is used, the variables &$1$& and &$2$& contain the wild | |
168e428f PH |
8535 | and non-wild parts of the key during the expansion of the replacement text. |
8536 | They return to their previous values at the end of the lookup item. | |
168e428f | 8537 | |
9b371988 PH |
8538 | This example looks up the postmaster alias in the conventional alias file: |
8539 | .code | |
8540 | ${lookup {postmaster} lsearch {/etc/aliases} {$value}} | |
8541 | .endd | |
168e428f PH |
8542 | This example uses NIS+ to look up the full name of the user corresponding to |
8543 | the local part of an address, forcing the expansion to fail if it is not found: | |
9b371988 | 8544 | .code |
168e428f PH |
8545 | ${lookup nisplus {[name=$local_part],passwd.org_dir:gcos} \ |
8546 | {$value}fail} | |
9b371988 | 8547 | .endd |
168e428f | 8548 | |
9b371988 PH |
8549 | .vitem &*${nhash{*&<&'string1'&>&*}{*&<&'string2'&>&*}{*&<&'string3'&>&*}}*& |
8550 | .cindex "expansion" "numeric hash" | |
8551 | .cindex "hash function" "numeric" | |
168e428f | 8552 | The three strings are expanded; the first two must yield numbers. Call them |
9b371988 PH |
8553 | <&'n'&> and <&'m'&>. If you are using fixed values for these numbers, that is, |
8554 | if <&'string1'&> and <&'string2'&> do not change when they are expanded, you | |
8555 | can use the simpler operator notation that avoids some of the braces: | |
8556 | .code | |
8557 | ${nhash_<n>_<m>:<string>} | |
8558 | .endd | |
168e428f | 8559 | The second number is optional (in both notations). If there is only one number, |
9b371988 | 8560 | the result is a number in the range 0&--<&'n'&>-1. Otherwise, the string is |
168e428f | 8561 | processed by a div/mod hash function that returns two numbers, separated by a |
9b371988 PH |
8562 | slash, in the ranges 0 to <&'n'&>-1 and 0 to <&'m'&>-1, respectively. For |
8563 | example, | |
8564 | .code | |
8565 | ${nhash{8}{64}{supercalifragilisticexpialidocious}} | |
8566 | .endd | |
8567 | returns the string &"6/33"&. | |
168e428f PH |
8568 | |
8569 | ||
8570 | ||
9b371988 PH |
8571 | .vitem &*${perl{*&<&'subroutine'&>&*}{*&<&'arg'&>&*}{*&<&'arg'&>&*}...}*& |
8572 | .cindex "Perl" "use in expanded string" | |
8573 | .cindex "expansion" "calling Perl from" | |
168e428f PH |
8574 | This item is available only if Exim has been built to include an embedded Perl |
8575 | interpreter. The subroutine name and the arguments are first separately | |
8576 | expanded, and then the Perl subroutine is called with those arguments. No | |
8577 | additional arguments need be given; the maximum number permitted, including the | |
8578 | name of the subroutine, is nine. | |
9b371988 | 8579 | |
168e428f | 8580 | The return value of the subroutine is inserted into the expanded string, unless |
9b371988 PH |
8581 | the return value is &%undef%&. In that case, the expansion fails in the same |
8582 | way as an explicit &"fail"& on a lookup item. The return value is a scalar. | |
8583 | Whatever you return is evaluated in a scalar context. For example, if you | |
8584 | return the name of a Perl vector, the return value is the size of the vector, | |
8585 | not its contents. | |
8586 | ||
8587 | If the subroutine exits by calling Perl's &%die%& function, the expansion fails | |
8588 | with the error message that was passed to &%die%&. More details of the embedded | |
8589 | Perl facility are given in chapter &<<CHAPperl>>&. | |
8590 | ||
8591 | The &(redirect)& router has an option called &%forbid_filter_perl%& which locks | |
168e428f PH |
8592 | out the use of this expansion item in filter files. |
8593 | ||
8594 | ||
9b371988 PH |
8595 | .new |
8596 | .vitem &*${prvs{*&<&'address'&>&*}{*&<&'secret'&>&*}{*&<&'keynumber'&>&*}}*& | |
8597 | .cindex "prvs" "expansion item" | |
068aaea8 PH |
8598 | The first argument is a complete email address and the second is secret |
8599 | keystring. The third argument, specifying a key number, is optional. If absent, | |
8600 | it defaults to 0. The result of the expansion is a prvs-signed email address, | |
9b371988 PH |
8601 | to be typically used with the &%return_path%& option on an &(smtp)& transport |
8602 | as part of a bounce address tag validation (BATV) scheme. For more discussion | |
8603 | and an example, see section &<<SECTverifyPRVS>>&. | |
8604 | .wen | |
8605 | ||
8606 | .new | |
8607 | .vitem "&*${prvscheck{*&<&'address'&>&*}{*&<&'secret'&>&*}&&& | |
8608 | {*&<&'string'&>&*}}*&" | |
8609 | .cindex "prvscheck" "expansion item" | |
8610 | This expansion item is the complement of the &%prvs%& item. It is used for | |
068aaea8 PH |
8611 | checking prvs-signed addresses. If the expansion of the first argument does not |
8612 | yield a syntactically valid prvs-signed address, the whole item expands to the | |
8613 | empty string. When the first argument does expand to a syntactically valid | |
8614 | prvs-signed address, the second argument is expanded, with the prvs-decoded | |
8615 | version of the address and the key number extracted from the address in the | |
9b371988 PH |
8616 | variables &$prvscheck_address$& and &$prvscheck_keynum$&, respectively. |
8617 | ||
068aaea8 PH |
8618 | These two variables can be used in the expansion of the second argument to |
8619 | retrieve the secret. The validity of the prvs-signed address is then checked | |
9b371988 PH |
8620 | against the secret. The result is stored in the variable &$prvscheck_result$&, |
8621 | which is empty for failure or &"1"& for success. | |
8622 | ||
068aaea8 PH |
8623 | The third argument is optional; if it is missing, it defaults to an empty |
8624 | string. This argument is now expanded. If the result is an empty string, the | |
8625 | result of the expansion is the decoded version of the address. This is the case | |
8626 | whether or not the signature was valid. Otherwise, the result of the expansion | |
8627 | is the expansion of the third argument. | |
068aaea8 | 8628 | |
9b371988 PH |
8629 | All three variables can be used in the expansion of the third argument. |
8630 | However, once the expansion is complete, only &$prvscheck_result$& remains set. | |
8631 | For more discussion and an example, see section &<<SECTverifyPRVS>>&. | |
8632 | .wen | |
068aaea8 | 8633 | |
9b371988 PH |
8634 | .vitem &*${readfile{*&<&'file&~name'&>&*}{*&<&'eol&~string'&>&*}}*& |
8635 | .cindex "expansion" "inserting an entire file" | |
8636 | .cindex "file" "inserting into expansion" | |
168e428f PH |
8637 | The file name and end-of-line string are first expanded separately. The file is |
8638 | then read, and its contents replace the entire item. All newline characters in | |
8639 | the file are replaced by the end-of-line string if it is present. Otherwise, | |
8640 | newlines are left in the string. | |
8641 | String expansion is not applied to the contents of the file. If you want this, | |
9b371988 PH |
8642 | you must wrap the item in an &%expand%& operator. If the file cannot be read, |
8643 | the string expansion fails. | |
8644 | ||
8645 | The &(redirect)& router has an option called &%forbid_filter_readfile%& which | |
168e428f PH |
8646 | locks out the use of this expansion item in filter files. |
8647 | ||
8648 | ||
8649 | ||
9b371988 PH |
8650 | .vitem "&*${readsocket{*&<&'name'&>&*}{*&<&'request'&>&*}&&& |
8651 | {*&<&'timeout'&>&*}{*&<&'eol&~string'&>&*}{*&<&'fail&~string'&>&*}}*&" | |
8652 | .cindex "expansion" "inserting from a socket" | |
8653 | .cindex "socket" "use of in expansion" | |
168e428f PH |
8654 | This item inserts data that is read from a Unix domain socket into the expanded |
8655 | string. The minimal way of using it uses just two arguments: | |
9b371988 PH |
8656 | .code |
8657 | ${readsocket{/socket/name}{request string}} | |
8658 | .endd | |
168e428f PH |
8659 | Exim connects to the socket, writes the request string (unless it is an |
8660 | empty string) and reads from the socket until an end-of-file is read. A timeout | |
8661 | of 5 seconds is applied. Additional, optional arguments extend what can be | |
8662 | done. Firstly, you can vary the timeout. For example: | |
9b371988 PH |
8663 | .code |
8664 | ${readsocket{/socket/name}{request-string}{3s}} | |
8665 | .endd | |
168e428f | 8666 | A fourth argument allows you to change any newlines that are in the data |
9b371988 PH |
8667 | that is read, in the same way as for &%readfile%& (see above). This example |
8668 | turns them into spaces: | |
8669 | .code | |
8670 | ${readsocket{/socket/name}{request-string}{3s}{ }} | |
8671 | .endd | |
168e428f PH |
8672 | As with all expansions, the substrings are expanded before the processing |
8673 | happens. Errors in these sub-expansions cause the expansion to fail. In | |
8674 | addition, the following errors can occur: | |
168e428f | 8675 | |
9b371988 PH |
8676 | .ilist |
8677 | Failure to create a socket file descriptor; | |
8678 | .next | |
8679 | Failure to connect the socket; | |
8680 | .next | |
8681 | Failure to write the request-string; | |
8682 | .next | |
8683 | Timeout on reading from the socket. | |
8684 | .endlist | |
168e428f | 8685 | |
168e428f PH |
8686 | By default, any of these errors causes the expansion to fail. However, if |
8687 | you supply a fifth substring, it is expanded and used when any of the above | |
8688 | errors occurs. For example: | |
9b371988 PH |
8689 | .code |
8690 | ${readsocket{/socket/name}{request-string}{3s}{\n}\ | |
8691 | {socket failure}} | |
8692 | .endd | |
168e428f | 8693 | You can test for the existence of the socket by wrapping this expansion in |
9b371988 | 8694 | &`${if exists`&, but there is a race condition between that test and the |
168e428f PH |
8695 | actual opening of the socket, so it is safer to use the fifth argument if you |
8696 | want to be absolutely sure of avoiding an expansion error for a non-existent | |
8697 | socket. | |
9b371988 PH |
8698 | |
8699 | The &(redirect)& router has an option called &%forbid_filter_readsocket%& which | |
168e428f PH |
8700 | locks out the use of this expansion item in filter files. |
8701 | ||
9b371988 PH |
8702 | .vitem &*$rheader_*&<&'header&~name'&>&*:&~or&~$rh_*&<&'header&~name'&>&*:*& |
8703 | This item inserts &"raw"& header lines. It is described with the &%header%& | |
168e428f PH |
8704 | expansion item above. |
8705 | ||
9b371988 PH |
8706 | .vitem "&*${run{*&<&'command'&>&*&~*&<&'args'&>&*}{*&<&'string1'&>&*}&&& |
8707 | {*&<&'string2'&>&*}}*&" | |
8708 | .cindex "expansion" "running a command" | |
168e428f PH |
8709 | The command and its arguments are first expanded separately, and then the |
8710 | command is run in a separate process, but under the same uid and gid. As in | |
8711 | other command executions from Exim, a shell is not used by default. If you want | |
8712 | a shell, you must explicitly code it. | |
168e428f | 8713 | |
9b371988 PH |
8714 | .new |
8715 | .cindex "return code" "from &%run%& expansion" | |
8716 | .cindex "&$value$&" | |
8717 | If the command succeeds (gives a zero return code) <&'string1'&> is expanded | |
8718 | and replaces the entire item; during this expansion, the standard output from | |
8719 | the command is in the variable &$value$&. If the command fails, <&'string2'&>, | |
8720 | if present, is expanded and used. Once again, during the expansion, the | |
8721 | standard output from the command is in the variable &$value$&. If <&'string2'&> | |
8722 | is absent, the result is empty. Alternatively, <&'string2'&> can be the word | |
8723 | &"fail"& (not in braces) to force expansion failure if the command does not | |
8724 | succeed. If both strings are omitted, the result is contents of the standard | |
8725 | output on success, and nothing on failure. | |
8726 | .wen | |
8727 | ||
8728 | .cindex "&$runrc$&" | |
8729 | The return code from the command is put in the variable &$runrc$&, and this | |
8730 | remains set afterwards, so in a filter file you can do things like this: | |
8731 | .code | |
8732 | if "${run{x y z}{}}$runrc" is 1 then ... | |
8733 | elif $runrc is 2 then ... | |
8734 | ... | |
8735 | endif | |
8736 | .endd | |
168e428f | 8737 | If execution of the command fails (for example, the command does not exist), |
9b371988 | 8738 | the return code is 127 &-- the same code that shells use for non-existent |
168e428f | 8739 | commands. |
9b371988 PH |
8740 | |
8741 | &*Warning*&: In a router or transport, you cannot assume the order in which | |
8742 | option values are expanded, except for those preconditions whose order of | |
8743 | testing is documented. Therefore, you cannot reliably expect to set &$runrc$& | |
168e428f | 8744 | by the expansion of one option, and use it in another. |
9b371988 PH |
8745 | |
8746 | The &(redirect)& router has an option called &%forbid_filter_run%& which locks | |
168e428f PH |
8747 | out the use of this expansion item in filter files. |
8748 | ||
8749 | ||
9b371988 PH |
8750 | .vitem &*${sg{*&<&'subject'&>&*}{*&<&'regex'&>&*}{*&<&'replacement'&>&*}}*& |
8751 | .cindex "expansion" "string substitution" | |
168e428f PH |
8752 | This item works like Perl's substitution operator (s) with the global (/g) |
8753 | option; hence its name. However, unlike the Perl equivalent, Exim does not | |
8754 | modify the subject string; instead it returns the modified string for insertion | |
8755 | into the overall expansion. The item takes three arguments: the subject string, | |
9b371988 PH |
8756 | a regular expression, and a substitution string. For example: |
8757 | .code | |
8758 | ${sg{abcdefabcdef}{abc}{xyz}} | |
8759 | .endd | |
8760 | yields &"xyzdefxyzdef"&. Because all three arguments are expanded before use, | |
8761 | if any $ or \ characters are required in the regular expression or in the | |
8762 | substitution string, they have to be escaped. For example: | |
8763 | .code | |
8764 | ${sg{abcdef}{^(...)(...)\$}{\$2\$1}} | |
8765 | .endd | |
8766 | yields &"defabc"&, and | |
8767 | .code | |
8768 | ${sg{1=A 4=D 3=C}{\N(\d+)=\N}{K\$1=}} | |
8769 | .endd | |
8770 | yields &"K1=A K4=D K3=C"&. Note the use of &`\N`& to protect the contents of | |
168e428f PH |
8771 | the regular expression from string expansion. |
8772 | ||
8773 | ||
8774 | ||
9b371988 PH |
8775 | .vitem &*${substr{*&<&'string1'&>&*}{*&<&'string2'&>&*}{*&<&'string3'&>&*}}*& |
8776 | .cindex "&%substr%&" | |
8777 | .cindex "substring extraction" | |
8778 | .cindex "expansion" "substring extraction" | |
168e428f | 8779 | The three strings are expanded; the first two must yield numbers. Call them |
9b371988 PH |
8780 | <&'n'&> and <&'m'&>. If you are using fixed values for these numbers, that is, |
8781 | if <&'string1'&> and <&'string2'&> do not change when they are expanded, you | |
8782 | can use the simpler operator notation that avoids some of the braces: | |
8783 | .code | |
8784 | ${substr_<n>_<m>:<string>} | |
8785 | .endd | |
168e428f PH |
8786 | The second number is optional (in both notations). |
8787 | If it is absent in the simpler format, the preceding underscore must also be | |
8788 | omitted. | |
168e428f | 8789 | |
9b371988 PH |
8790 | The &%substr%& item can be used to extract more general substrings than |
8791 | &%length%&. The first number, <&'n'&>, is a starting offset, and <&'m'&> is the | |
8792 | length required. For example | |
8793 | .code | |
8794 | ${substr{3}{2}{$local_part}} | |
8795 | .endd | |
168e428f PH |
8796 | If the starting offset is greater than the string length the result is the |
8797 | null string; if the length plus starting offset is greater than the string | |
8798 | length, the result is the right-hand part of the string, starting from the | |
8799 | given offset. The first character in the string has offset zero. | |
9b371988 PH |
8800 | |
8801 | The &%substr%& expansion item can take negative offset values to count | |
168e428f PH |
8802 | from the right-hand end of its operand. The last character is offset -1, the |
8803 | second-last is offset -2, and so on. Thus, for example, | |
9b371988 PH |
8804 | .code |
8805 | ${substr{-5}{2}{1234567}} | |
8806 | .endd | |
8807 | yields &"34"&. If the absolute value of a negative offset is greater than the | |
168e428f PH |
8808 | length of the string, the substring starts at the beginning of the string, and |
8809 | the length is reduced by the amount of overshoot. Thus, for example, | |
9b371988 PH |
8810 | .code |
8811 | ${substr{-5}{2}{12}} | |
8812 | .endd | |
168e428f | 8813 | yields an empty string, but |
9b371988 PH |
8814 | .code |
8815 | ${substr{-3}{2}{12}} | |
8816 | .endd | |
8817 | yields &"1"&. | |
168e428f | 8818 | |
9b371988 | 8819 | When the second number is omitted from &%substr%&, the remainder of the string |
168e428f PH |
8820 | is taken if the offset is positive. If it is negative, all characters in the |
8821 | string preceding the offset point are taken. For example, an offset of -1 and | |
8822 | no length, as in these semantically identical examples: | |
9b371988 PH |
8823 | .code |
8824 | ${substr_-1:abcde} | |
8825 | ${substr{-1}{abcde}} | |
8826 | .endd | |
8827 | yields all but the last character of the string, that is, &"abcd"&. | |
168e428f PH |
8828 | |
8829 | ||
8830 | ||
9b371988 PH |
8831 | .vitem "&*${tr{*&<&'subject'&>&*}{*&<&'characters'&>&*}&&& |
8832 | {*&<&'replacements'&>&*}}*&" | |
8833 | .cindex "expansion" "character translation" | |
168e428f PH |
8834 | This item does single-character translation on its subject string. The second |
8835 | argument is a list of characters to be translated in the subject string. Each | |
8836 | matching character is replaced by the corresponding character from the | |
8837 | replacement list. For example | |
9b371988 PH |
8838 | .code |
8839 | ${tr{abcdea}{ac}{13}} | |
8840 | .endd | |
8841 | yields &`1b3de1`&. If there are duplicates in the second character string, the | |
168e428f PH |
8842 | last occurrence is used. If the third string is shorter than the second, its |
8843 | last character is replicated. However, if it is empty, no translation takes | |
8844 | place. | |
9b371988 | 8845 | .endlist |
168e428f PH |
8846 | |
8847 | ||
8848 | ||
9b371988 PH |
8849 | .section "Expansion operators" "SECTexpop" |
8850 | .cindex "expansion" "operators" | |
168e428f | 8851 | For expansion items that perform transformations on a single argument string, |
9b371988 | 8852 | the &"operator"& notation is used because it is simpler and uses fewer braces. |
168e428f PH |
8853 | The substring is first expanded before the operation is applied to it. The |
8854 | following operations can be performed: | |
8855 | ||
9b371988 PH |
8856 | .vlist |
8857 | .vitem &*${address:*&<&'string'&>&*}*& | |
8858 | .cindex "expansion" "RFC 2822 address handling" | |
168e428f PH |
8859 | The string is interpreted as an RFC 2822 address, as it might appear in a |
8860 | header line, and the effective address is extracted from it. If the string does | |
8861 | not parse successfully, the result is empty. | |
8862 | ||
8863 | ||
9b371988 PH |
8864 | .new |
8865 | .vitem &*${base62:*&<&'digits'&>&*}*& | |
8866 | .cindex "base62" | |
8867 | .cindex "expansion" "conversion to base 62" | |
168e428f | 8868 | The string must consist entirely of decimal digits. The number is converted to |
068aaea8 PH |
8869 | base 62 and output as a string of six characters, including leading zeros. In |
8870 | the few operating environments where Exim uses base 36 instead of base 62 for | |
8871 | its message identifiers (because those systems do not have case-sensitive file | |
9b371988 PH |
8872 | names), base 36 is used by this operator, despite its name. &*Note*&: Just to |
8873 | be absolutely clear: this is &'not'& base64 encoding. | |
8874 | .wen | |
8875 | ||
8876 | .new | |
8877 | .vitem &*${base62d:*&<&'base-62&~digits'&>&*}*& | |
8878 | .cindex "base62" | |
8879 | .cindex "expansion" "conversion to base 62" | |
068aaea8 PH |
8880 | The string must consist entirely of base-62 digits, or, in operating |
8881 | environments where Exim uses base 36 instead of base 62 for its message | |
8882 | identifiers, base-36 digits. The number is converted to decimal and output as a | |
8883 | string. | |
9b371988 | 8884 | .wen |
168e428f | 8885 | |
9b371988 PH |
8886 | .vitem &*${domain:*&<&'string'&>&*}*& |
8887 | .cindex "domain" "extraction" | |
8888 | .cindex "expansion" "domain extraction" | |
168e428f PH |
8889 | The string is interpreted as an RFC 2822 address and the domain is extracted |
8890 | from it. If the string does not parse successfully, the result is empty. | |
8891 | ||
8892 | ||
9b371988 PH |
8893 | .vitem &*${escape:*&<&'string'&>&*}*& |
8894 | .cindex "expansion" "escaping non-printing characters" | |
168e428f PH |
8895 | If the string contains any non-printing characters, they are converted to |
8896 | escape sequences starting with a backslash. Whether characters with the most | |
9b371988 PH |
8897 | significant bit set (so-called &"8-bit characters"&) count as printing or not |
8898 | is controlled by the &%print_topbitchars%& option. | |
168e428f PH |
8899 | |
8900 | ||
9b371988 PH |
8901 | .vitem &*${eval:*&<&'string'&>&*}*&&~and&~&*${eval10:*&<&'string'&>&*}*& |
8902 | .cindex "expansion" "expression evaluation" | |
8903 | .cindex "expansion" "arithmetic expression" | |
8904 | .new | |
168e428f PH |
8905 | These items supports simple arithmetic in expansion strings. The string (after |
8906 | expansion) must be a conventional arithmetic expression, but it is limited to | |
068aaea8 PH |
8907 | five basic operators (plus, minus, times, divide, remainder) and parentheses. |
8908 | All operations are carried out using integer arithmetic. Plus and minus have a | |
8909 | lower priority than times, divide, and remainder; operators with the same | |
8910 | priority are evaluated from left to right. | |
9b371988 PH |
8911 | .wen |
8912 | ||
8913 | For &%eval%&, numbers may be decimal, octal (starting with &"0"&) or | |
8914 | hexadecimal (starting with &"0x"&). For &%eval10%&, all numbers are taken as | |
8915 | decimal, even if they start with a leading zero. This can be useful when | |
8916 | processing numbers extracted from dates or times, which often do have leading | |
8917 | zeros. | |
8918 | ||
8919 | A number may be followed by &"K"& or &"M"& to multiply it by 1024 or 1024*1024, | |
168e428f | 8920 | respectively. Negative numbers are supported. The result of the computation is |
9b371988 PH |
8921 | a decimal representation of the answer (without &"K"& or &"M"&). For example: |
8922 | ||
8923 | .new | |
8924 | .display | |
8925 | &`${eval:1+1} `& yields 2 | |
8926 | &`${eval:1+2*3} `& yields 7 | |
8927 | &`${eval:(1+2)*3} `& yields 9 | |
8928 | &`${eval:2+42%5} `& yields 4 | |
8929 | .endd | |
8930 | .wen | |
8931 | ||
168e428f | 8932 | As a more realistic example, in an ACL you might have |
9b371988 | 8933 | .code |
168e428f PH |
8934 | deny message = Too many bad recipients |
8935 | condition = \ | |
8936 | ${if and { \ | |
8937 | {>{$rcpt_count}{10}} \ | |
8938 | { \ | |
8939 | < \ | |
8940 | {$recipients_count} \ | |
8941 | {${eval:$rcpt_count/2}} \ | |
8942 | } \ | |
8943 | }{yes}{no}} | |
9b371988 | 8944 | .endd |
168e428f PH |
8945 | The condition is true if there have been more than 10 RCPT commands and |
8946 | fewer than half of them have resulted in a valid recipient. | |
8947 | ||
8948 | ||
9b371988 PH |
8949 | .vitem &*${expand:*&<&'string'&>&*}*& |
8950 | .cindex "expansion" "re-expansion of substring" | |
8951 | The &%expand%& operator causes a string to be expanded for a second time. For | |
168e428f | 8952 | example, |
9b371988 PH |
8953 | .code |
8954 | ${expand:${lookup{$domain}dbm{/some/file}{$value}}} | |
8955 | .endd | |
8956 | first looks up a string in a file while expanding the operand for &%expand%&, | |
8957 | and then re-expands what it has found. | |
168e428f | 8958 | |
168e428f | 8959 | |
9b371988 PH |
8960 | .vitem &*${from_utf8:*&<&'string'&>&*}*& |
8961 | .cindex "Unicode" | |
8962 | .cindex "UTF-8" "conversion from" | |
8963 | .cindex "expansion" "UTF-8 conversion" | |
168e428f PH |
8964 | The world is slowly moving towards Unicode, although there are no standards for |
8965 | email yet. However, other applications (including some databases) are starting | |
8966 | to store data in Unicode, using UTF-8 encoding. This operator converts from a | |
8967 | UTF-8 string to an ISO-8859-1 string. UTF-8 code values greater than 255 are | |
8968 | converted to underscores. The input must be a valid UTF-8 string. If it is not, | |
8969 | the result is an undefined sequence of bytes. | |
9b371988 | 8970 | |
168e428f PH |
8971 | Unicode code points with values less than 256 are compatible with ASCII and |
8972 | ISO-8859-1 (also known as Latin-1). | |
8973 | For example, character 169 is the copyright symbol in both cases, though the | |
8974 | way it is encoded is different. In UTF-8, more than one byte is needed for | |
8975 | characters with code values greater than 127, whereas ISO-8859-1 is a | |
8976 | single-byte encoding (but thereby limited to 256 characters). This makes | |
8977 | translation from UTF-8 to ISO-8859-1 straightforward. | |
8978 | ||
8979 | ||
9b371988 PH |
8980 | .vitem &*${hash_*&<&'n'&>&*_*&<&'m'&>&*:*&<&'string'&>&*}*& |
8981 | .cindex "hash function" "textual" | |
8982 | .cindex "expansion" "textual hash" | |
8983 | The &%hash%& operator is a simpler interface to the hashing function that can | |
8984 | be used when the two parameters are fixed numbers (as opposed to strings that | |
168e428f | 8985 | change when expanded). The effect is the same as |
9b371988 PH |
8986 | .code |
8987 | ${hash{<n>}{<m>}{<string>}} | |
8988 | .endd | |
8989 | See the description of the general &%hash%& item above for details. The | |
8990 | abbreviation &%h%& can be used when &%hash%& is used as an operator. | |
168e428f PH |
8991 | |
8992 | ||
8993 | ||
9b371988 PH |
8994 | .vitem &*${hex2b64:*&<&'hexstring'&>&*}*& |
8995 | .cindex "base64 encoding" "conversion from hex" | |
8996 | .cindex "expansion" "hex to base64" | |
168e428f PH |
8997 | This operator converts a hex string into one that is base64 encoded. This can |
8998 | be useful for processing the output of the MD5 and SHA-1 hashing functions. | |
8999 | ||
9000 | ||
9b371988 PH |
9001 | .vitem &*${lc:*&<&'string'&>&*}*& |
9002 | .cindex "case forcing in strings" | |
9003 | .cindex "string" "case forcing" | |
9004 | .cindex "lower casing" | |
9005 | .cindex "expansion" "case forcing" | |
168e428f | 9006 | This forces the letters in the string into lower-case, for example: |
9b371988 PH |
9007 | .code |
9008 | ${lc:$local_part} | |
9009 | .endd | |
9010 | ||
9011 | .vitem &*${length_*&<&'number'&>&*:*&<&'string'&>&*}*& | |
9012 | .cindex "expansion" "string truncation" | |
9013 | The &%length%& operator is a simpler interface to the &%length%& function that | |
9014 | can be used when the parameter is a fixed number (as opposed to a string that | |
168e428f | 9015 | changes when expanded). The effect is the same as |
9b371988 PH |
9016 | .code |
9017 | ${length{<number>}{<string>}} | |
9018 | .endd | |
9019 | See the description of the general &%length%& item above for details. Note that | |
9020 | &%length%& is not the same as &%strlen%&. The abbreviation &%l%& can be used | |
9021 | when &%length%& is used as an operator. | |
168e428f | 9022 | |
168e428f | 9023 | |
9b371988 PH |
9024 | .vitem &*${local_part:*&<&'string'&>&*}*& |
9025 | .cindex "expansion" "local part extraction" | |
168e428f PH |
9026 | The string is interpreted as an RFC 2822 address and the local part is |
9027 | extracted from it. If the string does not parse successfully, the result is | |
9028 | empty. | |
9029 | ||
9030 | ||
9b371988 PH |
9031 | .vitem &*${mask:*&<&'IP&~address'&>&*/*&<&'bit&~count'&>&*}*& |
9032 | .cindex "masked IP address" | |
9033 | .cindex "IP address" "masking" | |
9034 | .cindex "CIDR notation" | |
9035 | .cindex "expansion" "IP address masking" | |
168e428f PH |
9036 | If the form of the string to be operated on is not an IP address followed by a |
9037 | slash and an integer (that is, a network address in CIDR notation), the | |
9038 | expansion fails. Otherwise, this operator converts the IP address to binary, | |
9039 | masks off the least significant bits according to the bit count, and converts | |
9040 | the result back to text, with mask appended. For example, | |
9b371988 PH |
9041 | .code |
9042 | ${mask:10.111.131.206/28} | |
9043 | .endd | |
9044 | returns the string &"10.111.131.192/28"&. Since this operation is expected to | |
9045 | be mostly used for looking up masked addresses in files, the result for an IPv6 | |
168e428f PH |
9046 | address uses dots to separate components instead of colons, because colon |
9047 | terminates a key string in lsearch files. So, for example, | |
9b371988 PH |
9048 | .code |
9049 | ${mask:3ffe:ffff:836f:0a00:000a:0800:200a:c031/99} | |
9050 | .endd | |
168e428f | 9051 | returns the string |
9b371988 PH |
9052 | .code |
9053 | 3ffe.ffff.836f.0a00.000a.0800.2000.0000/99 | |
9054 | .endd | |
168e428f PH |
9055 | Letters in IPv6 addresses are always output in lower case. |
9056 | ||
9057 | ||
9b371988 PH |
9058 | .vitem &*${md5:*&<&'string'&>&*}*& |
9059 | .cindex "MD5 hash" | |
9060 | .cindex "expansion" "MD5 hash" | |
9061 | The &%md5%& operator computes the MD5 hash value of the string, and returns it | |
9062 | as a 32-digit hexadecimal number, in which any letters are in lower case. | |
168e428f PH |
9063 | |
9064 | ||
9b371988 PH |
9065 | .vitem &*${nhash_*&<&'n'&>&*_*&<&'m'&>&*:*&<&'string'&>&*}*& |
9066 | .cindex "expansion" "numeric hash" | |
9067 | .cindex "hash function" "numeric" | |
9068 | The &%nhash%& operator is a simpler interface to the numeric hashing function | |
168e428f PH |
9069 | that can be used when the two parameters are fixed numbers (as opposed to |
9070 | strings that change when expanded). The effect is the same as | |
9b371988 PH |
9071 | .code |
9072 | ${nhash{<n>}{<m>}{<string>}} | |
9073 | .endd | |
9074 | See the description of the general &%nhash%& item above for details. | |
168e428f | 9075 | |
168e428f | 9076 | |
9b371988 PH |
9077 | .vitem &*${quote:*&<&'string'&>&*}*& |
9078 | .cindex "quoting" "in string expansions" | |
9079 | .cindex "expansion" "quoting" | |
9080 | The &%quote%& operator puts its argument into double quotes if it | |
168e428f PH |
9081 | is an empty string or |
9082 | contains anything other than letters, digits, underscores, dots, and hyphens. | |
9083 | Any occurrences of double quotes and backslashes are escaped with a backslash. | |
9b371988 | 9084 | Newlines and carriage returns are converted to &`\n`& and &`\r`&, |
168e428f | 9085 | respectively For example, |
9b371988 PH |
9086 | .code |
9087 | ${quote:ab"*"cd} | |
9088 | .endd | |
168e428f | 9089 | becomes |
9b371988 PH |
9090 | .code |
9091 | "ab\"*\"cd" | |
9092 | .endd | |
168e428f PH |
9093 | The place where this is useful is when the argument is a substitution from a |
9094 | variable or a message header. | |
9095 | ||
9b371988 PH |
9096 | .vitem &*${quote_local_part:*&<&'string'&>&*}*& |
9097 | This operator is like &%quote%&, except that it quotes the string only if | |
168e428f | 9098 | required to do so by the rules of RFC 2822 for quoting local parts. For |
9b371988 PH |
9099 | example, a plus sign would not cause quoting (but it would for &%quote%&). |
9100 | If you are creating a new email address from the contents of &$local_part$& | |
168e428f PH |
9101 | (or any other unknown data), you should always use this operator. |
9102 | ||
9103 | ||
9b371988 PH |
9104 | .vitem &*${quote_*&<&'lookup-type'&>&*:*&<&'string'&>&*}*& |
9105 | .cindex "quoting" "lookup-specific" | |
168e428f PH |
9106 | This operator applies lookup-specific quoting rules to the string. Each |
9107 | query-style lookup type has its own quoting rules which are described with | |
9b371988 PH |
9108 | the lookups in chapter &<<CHAPfdlookup>>&. For example, |
9109 | .code | |
9110 | ${quote_ldap:two * two} | |
9111 | .endd | |
168e428f | 9112 | returns |
9b371988 PH |
9113 | .code |
9114 | two%20%5C2A%20two | |
9115 | .endd | |
168e428f PH |
9116 | For single-key lookup types, no quoting is ever necessary and this operator |
9117 | yields an unchanged string. | |
9118 | ||
9119 | ||
9b371988 PH |
9120 | .vitem &*${rxquote:*&<&'string'&>&*}*& |
9121 | .cindex "quoting" "in regular expressions" | |
9122 | .cindex "regular expressions" "quoting" | |
9123 | The &%rxquote%& operator inserts a backslash before any non-alphanumeric | |
168e428f PH |
9124 | characters in its argument. This is useful when substituting the values of |
9125 | variables or headers inside regular expressions. | |
9126 | ||
9127 | ||
9b371988 PH |
9128 | .vitem &*${rfc2047:*&<&'string'&>&*}*& |
9129 | .cindex "expansion" "RFC 2047" | |
9130 | .cindex "RFC 2047" "expansion operator" | |
168e428f PH |
9131 | This operator encodes text according to the rules of RFC 2047. This is an |
9132 | encoding that is used in header lines to encode non-ASCII characters. It is | |
9133 | assumed that the input string is in the encoding specified by the | |
9b371988 PH |
9134 | &%headers_charset%& option, which defaults to ISO-8859-1. If the string |
9135 | contains only characters in the range 33&--126, and no instances of the | |
9136 | characters | |
9137 | .code | |
9138 | ? = ( ) < > @ , ; : \ " . [ ] _ | |
9139 | .endd | |
168e428f | 9140 | it is not modified. Otherwise, the result is the RFC 2047 encoding of the |
9b371988 | 9141 | string, using as many &"encoded words"& as necessary to encode all the |
168e428f PH |
9142 | characters. |
9143 | ||
9144 | ||
9145 | ||
9b371988 PH |
9146 | .vitem &*${sha1:*&<&'string'&>&*}*& |
9147 | .cindex "SHA-1 hash" | |
9148 | .cindex "expansion" "SHA-1 hashing" | |
9149 | The &%sha1%& operator computes the SHA-1 hash value of the string, and returns | |
9150 | it as a 40-digit hexadecimal number, in which any letters are in upper case. | |
168e428f PH |
9151 | |
9152 | ||
9b371988 PH |
9153 | .vitem &*${stat:*&<&'string'&>&*}*& |
9154 | .cindex "expansion" "statting a file" | |
9155 | .cindex "file" "extracting characteristics" | |
9156 | The string, after expansion, must be a file path. A call to the &[stat()]& | |
9157 | function is made for this path. If &[stat()]& fails, an error occurs and the | |
168e428f | 9158 | expansion fails. If it succeeds, the data from the stat replaces the item, as a |
9b371988 PH |
9159 | series of <&'name'&>=<&'value'&> pairs, where the values are all numerical, |
9160 | except for the value of &"smode"&. The names are: &"mode"& (giving the mode as | |
9161 | a 4-digit octal number), &"smode"& (giving the mode in symbolic format as a | |
9162 | 10-character string, as for the &'ls'& command), &"inode"&, &"device"&, | |
9163 | &"links"&, &"uid"&, &"gid"&, &"size"&, &"atime"&, &"mtime"&, and &"ctime"&. You | |
9164 | can extract individual fields using the &%extract%& expansion item. | |
9165 | ||
9166 | .new | |
9167 | The use of the &%stat%& expansion in users' filter files can be locked out by | |
9168 | the system administrator. &*Warning*&: The file size may be incorrect on 32-bit | |
068aaea8 | 9169 | systems for files larger than 2GB. |
9b371988 | 9170 | .wen |
168e428f | 9171 | |
9b371988 PH |
9172 | .vitem &*${str2b64:*&<&'string'&>&*}*& |
9173 | .cindex "expansion" "base64 encoding" | |
9174 | .cindex "base64 encoding" "in string expansion" | |
168e428f PH |
9175 | This operator converts a string into one that is base64 encoded. |
9176 | ||
9177 | ||
9178 | ||
9b371988 PH |
9179 | .vitem &*${strlen:*&<&'string'&>&*}*& |
9180 | .cindex "expansion" "string length" | |
9181 | .cindex "string" "length in expansion" | |
168e428f | 9182 | The item is replace by the length of the expanded string, expressed as a |
9b371988 PH |
9183 | decimal number. &*Note*&: Do not confuse &%strlen%& with &%length%&. |
9184 | ||
9185 | ||
9186 | .vitem &*${substr_*&<&'start'&>&*_*&<&'length'&>&*:*&<&'string'&>&*}*& | |
9187 | .cindex "&%substr%&" | |
9188 | .cindex "substring extraction" | |
9189 | .cindex "expansion" "substring expansion" | |
9190 | The &%substr%& operator is a simpler interface to the &%substr%& function that | |
9191 | can be used when the two parameters are fixed numbers (as opposed to strings | |
9192 | that change when expanded). The effect is the same as | |
9193 | .code | |
9194 | ${substr{<start>}{<length>}{<string>}} | |
9195 | .endd | |
9196 | See the description of the general &%substr%& item above for details. The | |
9197 | abbreviation &%s%& can be used when &%substr%& is used as an operator. | |
9198 | ||
9199 | .vitem &*${time_interval:*&<&'string'&>&*}*& | |
9200 | .cindex "&%time_interval%&" | |
9201 | .cindex "time interval" "formatting" | |
168e428f PH |
9202 | The argument (after sub-expansion) must be a sequence of decimal digits that |
9203 | represents an interval of time as a number of seconds. It is converted into a | |
9204 | number of larger units and output in Exim's normal time format, for example, | |
9b371988 | 9205 | &`1w3d4h2m6s`&. |
168e428f | 9206 | |
9b371988 PH |
9207 | .vitem &*${uc:*&<&'string'&>&*}*& |
9208 | .cindex "case forcing in strings" | |
9209 | .cindex "string" "case forcing" | |
9210 | .cindex "upper casing" | |
9211 | .cindex "expansion" "case forcing" | |
168e428f | 9212 | This forces the letters in the string into upper-case. |
9b371988 | 9213 | .endlist |
168e428f PH |
9214 | |
9215 | ||
9216 | ||
9217 | ||
9218 | ||
9219 | ||
9b371988 PH |
9220 | .section "Expansion conditions" "SECTexpcond" |
9221 | .cindex "expansion" "conditions" | |
9222 | The following conditions are available for testing by the &%${if%& construct | |
168e428f PH |
9223 | while expanding strings: |
9224 | ||
9b371988 PH |
9225 | .vlist |
9226 | .vitem &*!*&<&'condition'&> | |
9227 | .cindex "expansion" "negating a condition" | |
168e428f PH |
9228 | Preceding any condition with an exclamation mark negates the result of the |
9229 | condition. | |
9230 | ||
9b371988 PH |
9231 | .vitem <&'symbolic&~operator'&>&~&*{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& |
9232 | .cindex "numeric comparison" | |
9233 | .cindex "expansion" "numeric comparison" | |
168e428f PH |
9234 | There are a number of symbolic operators for doing numeric comparisons. They |
9235 | are: | |
9b371988 PH |
9236 | .display |
9237 | &`= `& equal | |
9238 | &`== `& equal | |
9239 | &`> `& greater | |
9240 | &`>= `& greater or equal | |
9241 | &`< `& less | |
9242 | &`<= `& less or equal | |
9243 | .endd | |
9244 | For example: | |
9245 | .code | |
9246 | ${if >{$message_size}{10M} ... | |
9247 | .endd | |
168e428f PH |
9248 | Note that the general negation operator provides for inequality testing. The |
9249 | two strings must take the form of optionally signed decimal integers, | |
9b371988 PH |
9250 | optionally followed by one of the letters &"K"& or &"M"& (in either upper or |
9251 | lower case), signifying multiplication by 1024 or 1024*1024, respectively. | |
168e428f | 9252 | |
9b371988 PH |
9253 | .vitem &*crypteq&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& |
9254 | .cindex "expansion" "encrypted comparison" | |
9255 | .cindex "encrypted strings" "comparing" | |
168e428f | 9256 | This condition is included in the Exim binary if it is built to support any |
9b371988 PH |
9257 | authentication mechanisms (see chapter &<<CHAPSMTPAUTH>>&). Otherwise, it is |
9258 | necessary to define SUPPORT_CRYPTEQ in &_Local/Makefile_& to get &%crypteq%& | |
168e428f | 9259 | included in the binary. |
9b371988 PH |
9260 | |
9261 | The &%crypteq%& condition has two arguments. The first is encrypted and | |
9262 | compared against the second, which is already encrypted. The second string may | |
9263 | be in the LDAP form for storing encrypted strings, which starts with the | |
9264 | encryption type in curly brackets, followed by the data. If the second string | |
9265 | does not begin with &"{"& it is assumed to be encrypted with &[crypt()]& or | |
9266 | &[crypt16()]& (see below), since such strings cannot begin with &"{"&. | |
9267 | Typically this will be a field from a password file. An example of an encrypted | |
9268 | string in LDAP form is: | |
9269 | .code | |
9270 | {md5}CY9rzUYh03PK3k6DJie09g== | |
9271 | .endd | |
168e428f PH |
9272 | If such a string appears directly in an expansion, the curly brackets have to |
9273 | be quoted, because they are part of the expansion syntax. For example: | |
9b371988 PH |
9274 | .code |
9275 | ${if crypteq {test}{\{md5\}CY9rzUYh03PK3k6DJie09g==}{yes}{no}} | |
9276 | .endd | |
168e428f PH |
9277 | The following encryption types (whose names are matched case-independently) are |
9278 | supported: | |
9b371988 PH |
9279 | |
9280 | .ilist | |
9281 | .cindex "MD5 hash" | |
9282 | .cindex "base64 encoding" "in encrypted password" | |
9283 | &%{md5}%& computes the MD5 digest of the first string, and expresses this as | |
168e428f PH |
9284 | printable characters to compare with the remainder of the second string. If the |
9285 | length of the comparison string is 24, Exim assumes that it is base64 encoded | |
9286 | (as in the above example). If the length is 32, Exim assumes that it is a | |
9287 | hexadecimal encoding of the MD5 digest. If the length not 24 or 32, the | |
9288 | comparison fails. | |
9289 | ||
9b371988 PH |
9290 | .next |
9291 | .cindex "SHA-1 hash" | |
9292 | &%{sha1}%& computes the SHA-1 digest of the first string, and expresses this as | |
168e428f PH |
9293 | printable characters to compare with the remainder of the second string. If the |
9294 | length of the comparison string is 28, Exim assumes that it is base64 encoded. | |
9295 | If the length is 40, Exim assumes that it is a hexadecimal encoding of the | |
9296 | SHA-1 digest. If the length is not 28 or 40, the comparison fails. | |
9297 | ||
9b371988 PH |
9298 | .next |
9299 | .cindex "&[crypt()]&" | |
9300 | &%{crypt}%& calls the &[crypt()]& function, which traditionally used to use | |
9301 | only the first eight characters of the password. However, in modern operating | |
168e428f PH |
9302 | systems this is no longer true, and in many cases the entire password is used, |
9303 | whatever its length. | |
9b371988 PH |
9304 | .next |
9305 | .cindex "&[crypt16()]&" | |
9306 | &%{crypt16}%& calls the &[crypt16()]& function (also known as &[bigcrypt()]&), | |
168e428f PH |
9307 | which was orginally created to use up to 16 characters of the password. Again, |
9308 | in modern operating systems, more characters may be used. | |
9b371988 PH |
9309 | .endlist |
9310 | ||
9311 | Exim has its own version of &[crypt16()]& (which is just a double call to | |
9312 | &[crypt()]&). For operating systems that have their own version, setting | |
9313 | HAVE_CRYPT16 in &_Local/Makefile_& when building Exim causes it to use the | |
168e428f | 9314 | operating system version instead of its own. This option is set by default in |
9b371988 PH |
9315 | the OS-dependent &_Makefile_& for those operating systems that are known to |
9316 | support &[crypt16()]&. | |
9317 | ||
9318 | If you do not put any curly bracket encryption type in a &%crypteq%& | |
9319 | comparison, the default is either &`{crypt}`& or &`{crypt16}`&, as determined | |
9320 | by the setting of DEFAULT_CRYPT in &_Local/Makefile_&. The default default is | |
9321 | &`{crypt}`&. Whatever the default, you can always use either function by | |
168e428f | 9322 | specifying it explicitly in curly brackets. |
9b371988 | 9323 | |
168e428f | 9324 | Note that if a password is no longer than 8 characters, the results of |
9b371988 PH |
9325 | encrypting it with &[crypt()]& and &[crypt16()]& are identical. That means that |
9326 | &[crypt16()]& is backwards compatible, as long as nobody feeds it a password | |
168e428f PH |
9327 | longer than 8 characters. |
9328 | ||
9b371988 PH |
9329 | .vitem &*def:*&<&'variable&~name'&> |
9330 | .cindex "expansion" "checking for empty variable" | |
9331 | The &%def%& condition must be followed by the name of one of the expansion | |
9332 | variables defined in section &<<SECTexpvar>>&. The condition is true if the | |
9333 | variable does not contain the empty string. For example: | |
9334 | .code | |
9335 | ${if def:sender_ident {from $sender_ident}} | |
9336 | .endd | |
9337 | Note that the variable name is given without a leading &%$%& character. If the | |
168e428f PH |
9338 | variable does not exist, the expansion fails. |
9339 | ||
9b371988 PH |
9340 | .vitem "&*def:header_*&<&'header&~name'&>&*:*&&~&~or&~&&& |
9341 | &~&*def:h_*&<&'header&~name'&>&*:*&" | |
9342 | .cindex "expansion" "checking header line existence" | |
168e428f PH |
9343 | This condition is true if a message is being processed and the named header |
9344 | exists in the message. For example, | |
9b371988 PH |
9345 | .code |
9346 | ${if def:header_reply-to:{$h_reply-to:}{$h_from:}} | |
9347 | .endd | |
9348 | &*Note*&: No &%$%& appears before &%header_%& or &%h_%& in the condition, and | |
9349 | the header name must be terminated by a colon if white space does not follow. | |
9350 | ||
9351 | .vitem &*eq&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& | |
9352 | .cindex "string" "comparison" | |
9353 | .cindex "expansion" "string comparison" | |
168e428f PH |
9354 | The two substrings are first expanded. The condition is true if the two |
9355 | resulting strings are identical, including the case of letters. | |
9356 | ||
9b371988 PH |
9357 | .vitem &*eqi&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& |
9358 | .cindex "string" "comparison" | |
9359 | .cindex "expansion" "string comparison" | |
168e428f PH |
9360 | The two substrings are first expanded. The condition is true if the two |
9361 | resulting strings are identical when compared in a case-independent way. | |
9362 | ||
9b371988 PH |
9363 | .vitem &*exists&~{*&<&'file&~name'&>&*}*& |
9364 | .cindex "expansion" "file existence test" | |
9365 | .cindex "file" "existence test" | |
168e428f PH |
9366 | The substring is first expanded and then interpreted as an absolute path. The |
9367 | condition is true if the named file (or directory) exists. The existence test | |
9b371988 | 9368 | is done by calling the &[stat()]& function. The use of the &%exists%& test in |
168e428f PH |
9369 | users' filter files may be locked out by the system administrator. |
9370 | ||
9b371988 PH |
9371 | .vitem &*first_delivery*& |
9372 | .cindex "delivery" "first" | |
9373 | .cindex "first delivery" | |
9374 | .cindex "expansion" "first delivery test" | |
168e428f PH |
9375 | This condition, which has no data, is true during a message's first delivery |
9376 | attempt. It is false during any subsequent delivery attempts. | |
9377 | ||
9b371988 PH |
9378 | .vitem &*ge&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& |
9379 | See &*gei*&. | |
168e428f | 9380 | |
9b371988 PH |
9381 | .vitem &*gei&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& |
9382 | .cindex "string" "comparison" | |
9383 | .cindex "expansion" "string comparison" | |
168e428f | 9384 | The two substrings are first expanded. The condition is true if the first |
9b371988 PH |
9385 | string is lexically greater than or equal to the second string: for &%ge%& the |
9386 | comparison includes the case of letters, whereas for &%gei%& the comparison is | |
168e428f PH |
9387 | case-independent. |
9388 | ||
9b371988 PH |
9389 | .vitem &*gt&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& |
9390 | See &*gti*&. | |
168e428f | 9391 | |
9b371988 PH |
9392 | .vitem &*gti&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& |
9393 | .cindex "string" "comparison" | |
9394 | .cindex "expansion" "string comparison" | |
168e428f | 9395 | The two substrings are first expanded. The condition is true if the first |
9b371988 PH |
9396 | string is lexically greater than the second string: for &%gt%& the comparison |
9397 | includes the case of letters, whereas for &%gti%& the comparison is | |
168e428f PH |
9398 | case-independent. |
9399 | ||
9b371988 PH |
9400 | .vitem &*isip&~{*&<&'string'&>&*}*& |
9401 | See &*isip6*&. | |
168e428f | 9402 | |
9b371988 PH |
9403 | .vitem &*isip4&~{*&<&'string'&>&*}*& |
9404 | See &*isip6*&. | |
168e428f | 9405 | |
9b371988 PH |
9406 | .vitem &*isip6&~{*&<&'string'&>&*}*& |
9407 | .cindex "IP address" "testing string format" | |
9408 | .cindex "string" "testing for IP address" | |
168e428f | 9409 | The substring is first expanded, and then tested to see if it has the form of |
9b371988 PH |
9410 | an IP address. Both IPv4 and IPv6 addresses are valid for &%isip%&, whereas |
9411 | &%isip4%& and &%isip6%& test just for IPv4 or IPv6 addresses, respectively. For | |
168e428f | 9412 | example, you could use |
9b371988 PH |
9413 | .code |
9414 | ${if isip4{$sender_host_address}... | |
9415 | .endd | |
168e428f PH |
9416 | to test which version of IP an incoming SMTP connection is using. |
9417 | ||
9418 | ||
9b371988 PH |
9419 | .vitem &*ldapauth&~{*&<&'ldap&~query'&>&*}*& |
9420 | .cindex "LDAP" "use for authentication" | |
9421 | .cindex "expansion" "LDAP authentication test" | |
168e428f | 9422 | This condition supports user authentication using LDAP. See section |
9b371988 | 9423 | &<<SECTldap>>& for details of how to use LDAP in lookups and the syntax of |
168e428f PH |
9424 | queries. For this use, the query must contain a user name and password. The |
9425 | query itself is not used, and can be empty. The condition is true if the | |
9426 | password is not empty, and the user name and password are accepted by the LDAP | |
9427 | server. An empty password is rejected without calling LDAP because LDAP binds | |
9428 | with an empty password are considered anonymous regardless of the username, and | |
9b371988 PH |
9429 | will succeed in most configurations. See chapter &<<CHAPSMTPAUTH>>& for details |
9430 | of SMTP authentication, and chapter &<<CHAPplaintext>>& for an example of how | |
168e428f PH |
9431 | this can be used. |
9432 | ||
9433 | ||
9b371988 PH |
9434 | .vitem &*le&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& |
9435 | See &*lei*&. | |
168e428f | 9436 | |
9b371988 PH |
9437 | .vitem &*lei&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& |
9438 | .cindex "string" "comparison" | |
9439 | .cindex "expansion" "string comparison" | |
168e428f | 9440 | The two substrings are first expanded. The condition is true if the first |
9b371988 PH |
9441 | string is lexically less than or equal to the second string: for &%le%& the |
9442 | comparison includes the case of letters, whereas for &%lei%& the comparison is | |
168e428f PH |
9443 | case-independent. |
9444 | ||
9b371988 PH |
9445 | .vitem &*lt&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& |
9446 | See &*lti*&. | |
168e428f | 9447 | |
9b371988 PH |
9448 | .vitem &*lti&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& |
9449 | .cindex "string" "comparison" | |
9450 | .cindex "expansion" "string comparison" | |
168e428f | 9451 | The two substrings are first expanded. The condition is true if the first |
9b371988 PH |
9452 | string is lexically less than the second string: for &%lt%& the comparison |
9453 | includes the case of letters, whereas for &%lti%& the comparison is | |
168e428f PH |
9454 | case-independent. |
9455 | ||
9456 | ||
9b371988 PH |
9457 | .vitem &*match&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& |
9458 | .cindex "expansion" "regular expression comparison" | |
9459 | .cindex "regular expressions" "match in expanded string" | |
168e428f PH |
9460 | The two substrings are first expanded. The second is then treated as a regular |
9461 | expression and applied to the first. Because of the pre-expansion, if the | |
9462 | regular expression contains dollar, or backslash characters, they must be | |
9463 | escaped. Care must also be taken if the regular expression contains braces | |
9464 | (curly brackets). A closing brace must be escaped so that it is not taken as a | |
9b371988 PH |
9465 | premature termination of <&'string2'&>. The easiest approach is to use the |
9466 | &`\N`& feature to disable expansion of the regular expression. | |
168e428f | 9467 | For example, |
9b371988 PH |
9468 | .code |
9469 | ${if match {$local_part}{\N^\d{3}\N} ... | |
9470 | .endd | |
168e428f PH |
9471 | If the whole expansion string is in double quotes, further escaping of |
9472 | backslashes is also required. | |
9b371988 | 9473 | |
168e428f PH |
9474 | The condition is true if the regular expression match succeeds. |
9475 | The regular expression is not required to begin with a circumflex | |
9476 | metacharacter, but if there is no circumflex, the expression is not anchored, | |
9477 | and it may match anywhere in the subject, not just at the start. If you want | |
9b371988 | 9478 | the pattern to match at the end of the subject, you must include the &`$`& |
168e428f | 9479 | metacharacter at an appropriate point. |
9b371988 PH |
9480 | |
9481 | .cindex "numerical variables (&$1$& &$2$& etc)" "in &%if%& expansion" | |
9482 | At the start of an &%if%& expansion the values of the numeric variable | |
9483 | substitutions &$1$& etc. are remembered. Obeying a &%match%& condition that | |
168e428f PH |
9484 | succeeds causes them to be reset to the substrings of that condition and they |
9485 | will have these values during the expansion of the success string. At the end | |
9b371988 PH |
9486 | of the &%if%& expansion, the previous values are restored. After testing a |
9487 | combination of conditions using &%or%&, the subsequent values of the numeric | |
168e428f PH |
9488 | variables are those of the condition that succeeded. |
9489 | ||
9b371988 PH |
9490 | .vitem &*match_address&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& |
9491 | See &*match_local_part*&. | |
168e428f | 9492 | |
9b371988 PH |
9493 | .vitem &*match_domain&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& |
9494 | See &*match_local_part*&. | |
168e428f | 9495 | |
9b371988 PH |
9496 | .new |
9497 | .vitem &*match_ip&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& | |
068aaea8 PH |
9498 | This condition matches an IP address to a list of IP address patterns. It must |
9499 | be followed by two argument strings. The first (after expansion) must be an IP | |
9500 | address or an empty string. The second (after expansion) is a restricted host | |
9501 | list that can match only an IP address, not a host name. For example: | |
9b371988 | 9502 | .code |
068aaea8 | 9503 | ${if match_ip{$sender_host_address}{1.2.3.4:5.6.7.8}{...}{...}} |
9b371988 | 9504 | .endd |
068aaea8 | 9505 | The specific types of host list item that are permitted in the list are: |
068aaea8 | 9506 | |
9b371988 PH |
9507 | .ilist |
9508 | An IP address, optionally with a CIDR mask. | |
9509 | .next | |
9510 | A single asterisk, which matches any IP address. | |
9511 | .next | |
9512 | An empty item, which matches only if the IP address is empty. This could be | |
068aaea8 PH |
9513 | useful for testing for a locally submitted message or one from specific hosts |
9514 | in a single test such as | |
9b371988 PH |
9515 | . ==== As this is a nested list, any displays it contains must be indented |
9516 | . ==== as otherwise they are too far to the left. | |
9517 | .code | |
9518 | ${if match_ip{$sender_host_address}{:4.3.2.1:...}{...}{...}} | |
9519 | .endd | |
068aaea8 | 9520 | where the first item in the list is the empty string. |
9b371988 PH |
9521 | .next |
9522 | The item @[] matches any of the local host's interface addresses. | |
9523 | .next | |
9524 | Lookups are assumed to be &"net-"& style lookups, even if &`net-`& is not | |
068aaea8 | 9525 | specified. Thus, the following are equivalent: |
9b371988 PH |
9526 | .code |
9527 | ${if match_ip{$sender_host_address}{lsearch;/some/file}... | |
9528 | ${if match_ip{$sender_host_address}{net-lsearch;/some/file}... | |
9529 | .endd | |
9530 | You do need to specify the &`net-`& prefix if you want to specify a | |
9531 | specific address mask, for example, by using &`net24-`&. | |
9532 | .endlist ilist | |
9533 | ||
9534 | Consult section &<<SECThoslispatip>>& for further details of these patterns. | |
9535 | .wen | |
9536 | ||
9537 | .vitem &*match_local_part&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& | |
9538 | .cindex "domain list" "in expansion condition" | |
9539 | .cindex "address list" "in expansion condition" | |
9540 | .cindex "local part list" "in expansion condition" | |
9541 | This condition, together with &%match_address%& and &%match_domain%&, make it | |
068aaea8 PH |
9542 | possible to test domain, address, and local part lists within expansions. Each |
9543 | condition requires two arguments: an item and a list to match. A trivial | |
9544 | example is: | |
9b371988 PH |
9545 | .code |
9546 | ${if match_domain{a.b.c}{x.y.z:a.b.c:p.q.r}{yes}{no}} | |
9547 | .endd | |
168e428f PH |
9548 | In each case, the second argument may contain any of the allowable items for a |
9549 | list of the appropriate type. Also, because the second argument (after | |
9550 | expansion) is a standard form of list, it is possible to refer to a named list. | |
9551 | Thus, you can use conditions like this: | |
9b371988 PH |
9552 | .code |
9553 | ${if match_domain{$domain}{+local_domains}{... | |
9554 | .endd | |
9555 | .cindex "&`+caseful`&" | |
9556 | For address lists, the matching starts off caselessly, but the &`+caseful`& | |
168e428f PH |
9557 | item can be used, as in all address lists, to cause subsequent items to |
9558 | have their local parts matched casefully. Domains are always matched | |
9559 | caselessly. | |
9b371988 PH |
9560 | |
9561 | &*Note*&: Host lists are &'not'& supported in this way. This is because | |
168e428f | 9562 | hosts have two identities: a name and an IP address, and it is not clear |
068aaea8 | 9563 | how to specify cleanly how such a test would work. However, IP addresses can be |
9b371988 PH |
9564 | matched using &%match_ip%&. |
9565 | ||
9566 | .vitem &*pam&~{*&<&'string1'&>&*:*&<&'string2'&>&*:...}*& | |
9567 | .cindex "PAM authentication" | |
9568 | .cindex "AUTH" "with PAM" | |
9569 | .cindex "Solaris" "PAM support" | |
9570 | .cindex "expansion" "PAM authentication test" | |
9571 | &'Pluggable Authentication Modules'& | |
9572 | (&url(http://www.kernel.org/pub/linux/libs/pam/)) are a facility that is | |
9573 | available in the latest releases of Solaris and in some GNU/Linux | |
9574 | distributions. The Exim support, which is intended for use in conjunction with | |
9575 | the SMTP AUTH command, is available only if Exim is compiled with | |
9576 | .code | |
9577 | SUPPORT_PAM=yes | |
9578 | .endd | |
9579 | in &_Local/Makefile_&. You probably need to add &%-lpam%& to EXTRALIBS, and | |
9580 | in some releases of GNU/Linux &%-ldl%& is also needed. | |
9581 | ||
168e428f | 9582 | The argument string is first expanded, and the result must be a |
068aaea8 | 9583 | colon-separated list of strings. Leading and trailing white space is ignored. |
9b371988 PH |
9584 | The PAM module is initialized with the service name &"exim"& and the user name |
9585 | taken from the first item in the colon-separated data string (<&'string1'&>). | |
9586 | The remaining items in the data string are passed over in response to requests | |
9587 | from the authentication function. In the simple case there will only be one | |
9588 | request, for a password, so the data consists of just two strings. | |
9589 | ||
168e428f PH |
9590 | There can be problems if any of the strings are permitted to contain colon |
9591 | characters. In the usual way, these have to be doubled to avoid being taken as | |
9b371988 | 9592 | separators. If the data is being inserted from a variable, the &%sg%& expansion |
168e428f PH |
9593 | item can be used to double any existing colons. For example, the configuration |
9594 | of a LOGIN authenticator might contain this setting: | |
9b371988 PH |
9595 | .code |
9596 | server_condition = ${if pam{$1:${sg{$2}{:}{::}}}{yes}{no}} | |
9597 | .endd | |
168e428f | 9598 | For a PLAIN authenticator you could use: |
9b371988 PH |
9599 | .code |
9600 | server_condition = ${if pam{$2:${sg{$3}{:}{::}}}{yes}{no}} | |
9601 | .endd | |
168e428f PH |
9602 | In some operating systems, PAM authentication can be done only from a process |
9603 | running as root. Since Exim is running as the Exim user when receiving | |
9604 | messages, this means that PAM cannot be used directly in those systems. | |
9b371988 PH |
9605 | A patched version of the &'pam_unix'& module that comes with the |
9606 | Linux PAM package is available from &url(http://www.e-admin.de/pam_exim/). | |
168e428f PH |
9607 | The patched module allows one special uid/gid combination, in addition to root, |
9608 | to authenticate. If you build the patched module to allow the Exim user and | |
9609 | group, PAM can then be used from an Exim authenticator. | |
9610 | ||
9611 | ||
9b371988 PH |
9612 | .vitem &*pwcheck&~{*&<&'string1'&>&*:*&<&'string2'&>&*}*& |
9613 | .cindex "&'pwcheck'& daemon" | |
9614 | .cindex "Cyrus" | |
9615 | .cindex "expansion" "&'pwcheck'& authentication test" | |
9616 | This condition supports user authentication using the Cyrus &'pwcheck'& daemon. | |
168e428f | 9617 | This is one way of making it possible for passwords to be checked by a process |
9b371988 PH |
9618 | that is not running as root. &*Note*&: The use of &'pwcheck'& is now |
9619 | deprecated. Its replacement is &'saslauthd'& (see below). | |
9620 | ||
168e428f | 9621 | The pwcheck support is not included in Exim by default. You need to specify |
9b371988 | 9622 | the location of the pwcheck daemon's socket in &_Local/Makefile_& before |
168e428f | 9623 | building Exim. For example: |
9b371988 PH |
9624 | .code |
9625 | CYRUS_PWCHECK_SOCKET=/var/pwcheck/pwcheck | |
9626 | .endd | |
168e428f PH |
9627 | You do not need to install the full Cyrus software suite in order to use |
9628 | the pwcheck daemon. You can compile and install just the daemon alone | |
9b371988 PH |
9629 | from the Cyrus SASL library. Ensure that &'exim'& is the only user that has |
9630 | access to the &_/var/pwcheck_& directory. | |
9631 | ||
9632 | The &%pwcheck%& condition takes one argument, which must be the user name and | |
168e428f PH |
9633 | password, separated by a colon. For example, in a LOGIN authenticator |
9634 | configuration, you might have this: | |
9b371988 PH |
9635 | .code |
9636 | server_condition = ${if pwcheck{$1:$2}{1}{0}} | |
9637 | .endd | |
9638 | .vitem &*queue_running*& | |
9639 | .cindex "queue runner" "detecting when delivering from" | |
9640 | .cindex "expansion" "queue runner test" | |
168e428f PH |
9641 | This condition, which has no data, is true during delivery attempts that are |
9642 | initiated by queue runner processes, and false otherwise. | |
9643 | ||
9644 | ||
9b371988 PH |
9645 | .vitem &*radius&~{*&<&'authentication&~string'&>&*}*& |
9646 | .cindex "Radius" | |
9647 | .cindex "expansion" "Radius authentication" | |
168e428f | 9648 | Radius authentication (RFC 2865) is supported in a similar way to PAM. You must |
9b371988 | 9649 | set RADIUS_CONFIG_FILE in &_Local/Makefile_& to specify the location of |
168e428f PH |
9650 | the Radius client configuration file in order to build Exim with Radius |
9651 | support. | |
9b371988 PH |
9652 | |
9653 | .new | |
9654 | With just that one setting, Exim expects to be linked with the &%radiusclient%& | |
068aaea8 PH |
9655 | library, using the original API. If you are using release 0.4.0 or later of |
9656 | this library, you need to set | |
9b371988 | 9657 | .code |
068aaea8 | 9658 | RADIUS_LIB_TYPE=RADIUSCLIENTNEW |
9b371988 PH |
9659 | .endd |
9660 | in &_Local/Makefile_& when building Exim. You can also link Exim with the | |
9661 | &%libradius%& library that comes with FreeBSD. To do this, set | |
9662 | .wen | |
9663 | .code | |
9664 | RADIUS_LIB_TYPE=RADLIB | |
9665 | .endd | |
9666 | in &_Local/Makefile_&, in addition to setting RADIUS_CONFIGURE_FILE. | |
168e428f PH |
9667 | You may also have to supply a suitable setting in EXTRALIBS so that the |
9668 | Radius library can be found when Exim is linked. | |
9b371988 | 9669 | |
168e428f PH |
9670 | The string specified by RADIUS_CONFIG_FILE is expanded and passed to the |
9671 | Radius client library, which calls the Radius server. The condition is true if | |
9b371988 PH |
9672 | the authentication is successful. For example: |
9673 | .code | |
9674 | server_condition = ${if radius{<arguments>}{yes}{no}} | |
9675 | .endd | |
9676 | ||
9677 | ||
9678 | .vitem "&*saslauthd&~{{*&<&'user'&>&*}{*&<&'password'&>&*}&&& | |
9679 | {*&<&'service'&>&*}{*&<&'realm'&>&*}}*&" | |
9680 | .cindex "&'saslauthd'& daemon" | |
9681 | .cindex "Cyrus" | |
9682 | .cindex "expansion" "&'saslauthd'& authentication test" | |
9683 | This condition supports user authentication using the Cyrus &'saslauthd'& | |
9684 | daemon. This replaces the older &'pwcheck'& daemon, which is now deprecated. | |
168e428f PH |
9685 | Using this daemon is one way of making it possible for passwords to be checked |
9686 | by a process that is not running as root. | |
9b371988 | 9687 | |
168e428f | 9688 | The saslauthd support is not included in Exim by default. You need to specify |
9b371988 | 9689 | the location of the saslauthd daemon's socket in &_Local/Makefile_& before |
168e428f | 9690 | building Exim. For example: |
9b371988 PH |
9691 | .code |
9692 | CYRUS_SASLAUTHD_SOCKET=/var/state/saslauthd/mux | |
9693 | .endd | |
168e428f PH |
9694 | You do not need to install the full Cyrus software suite in order to use |
9695 | the saslauthd daemon. You can compile and install just the daemon alone | |
9696 | from the Cyrus SASL library. | |
168e428f | 9697 | |
9b371988 PH |
9698 | Up to four arguments can be supplied to the &%saslauthd%& condition, but only |
9699 | two are mandatory. For example: | |
9700 | .code | |
9701 | server_condition = ${if saslauthd{{$1}{$2}}{1}{0}} | |
9702 | .endd | |
168e428f PH |
9703 | The service and the realm are optional (which is why the arguments are enclosed |
9704 | in their own set of braces). For details of the meaning of the service and | |
9705 | realm, and how to run the daemon, consult the Cyrus documentation. | |
9b371988 | 9706 | .endlist vlist |
168e428f PH |
9707 | |
9708 | ||
9709 | ||
9b371988 PH |
9710 | .section "Combining expansion conditions" |
9711 | .cindex "expansion" "combining conditions" | |
9712 | Several conditions can be tested at once by combining them using the &%and%& | |
9713 | and &%or%& combination conditions. Note that &%and%& and &%or%& are complete | |
9714 | conditions on their own, and precede their lists of sub-conditions. Each | |
9715 | sub-condition must be enclosed in braces within the overall braces that contain | |
9716 | the list. No repetition of &%if%& is used. | |
168e428f PH |
9717 | |
9718 | ||
9b371988 PH |
9719 | .vlist |
9720 | .vitem &*or&~{{*&<&'cond1'&>&*}{*&<&'cond2'&>&*}...}*& | |
9721 | .cindex "&""or""& expansion condition" | |
9722 | .cindex "expansion" "&""or""& of conditions" | |
168e428f PH |
9723 | The sub-conditions are evaluated from left to right. The condition is true if |
9724 | any one of the sub-conditions is true. | |
9725 | For example, | |
9b371988 PH |
9726 | .code |
9727 | ${if or {{eq{$local_part}{spqr}}{eq{$domain}{testing.com}}}... | |
9728 | .endd | |
168e428f | 9729 | When a true sub-condition is found, the following ones are parsed but not |
9b371988 | 9730 | evaluated. If there are several &"match"& sub-conditions the values of the |
168e428f PH |
9731 | numeric variables afterwards are taken from the first one that succeeds. |
9732 | ||
9b371988 PH |
9733 | .vitem &*and&~{{*&<&'cond1'&>&*}{*&<&'cond2'&>&*}...}*& |
9734 | .cindex "&""and""& expansion condition" | |
9735 | .cindex "expansion" "&""and""& of conditions" | |
168e428f | 9736 | The sub-conditions are evaluated from left to right. The condition is true if |
9b371988 | 9737 | all of the sub-conditions are true. If there are several &"match"& |
168e428f PH |
9738 | sub-conditions, the values of the numeric variables afterwards are taken from |
9739 | the last one. When a false sub-condition is found, the following ones are | |
9740 | parsed but not evaluated. | |
9b371988 | 9741 | .endlist |
168e428f PH |
9742 | |
9743 | ||
9744 | ||
9745 | ||
9b371988 PH |
9746 | .section "Expansion variables" "SECTexpvar" |
9747 | .cindex "expansion variables" "list of" | |
168e428f PH |
9748 | This section contains an alphabetical list of all the expansion variables. Some |
9749 | of them are available only when Exim is compiled with specific options such as | |
9750 | support for TLS or the content scanning extension. | |
9751 | ||
9b371988 PH |
9752 | .vlist |
9753 | .vitem "&$0$&, &$1$&, etc" | |
9754 | .cindex "numerical variables (&$1$& &$2$& etc)" | |
9755 | When a &%match%& expansion condition succeeds, these variables contain the | |
168e428f | 9756 | captured substrings identified by the regular expression during subsequent |
9b371988 | 9757 | processing of the success string of the containing &%if%& expansion item. They |
168e428f PH |
9758 | may also be set externally by some other matching process which precedes the |
9759 | expansion of the string. For example, the commands available in Exim filter | |
9b371988 | 9760 | files include an &%if%& command with its own regular expression matching |
168e428f PH |
9761 | condition. |
9762 | ||
9b371988 PH |
9763 | .vitem "&$acl_c0$& &-- &$acl_c9$&" |
9764 | Values can be placed in these variables by the &%set%& modifier in an ACL. The | |
168e428f PH |
9765 | values persist throughout the lifetime of an SMTP connection. They can be used |
9766 | to pass information between ACLs and different invocations of the same ACL. | |
9767 | When a message is received, the values of these variables are saved with the | |
9768 | message, and can be accessed by filters, routers, and transports during | |
9769 | subsequent delivery. | |
9770 | ||
9b371988 PH |
9771 | .vitem "&$acl_m0$& &-- &$acl_m9$&" |
9772 | Values can be placed in these variables by the &%set%& modifier in an ACL. They | |
168e428f PH |
9773 | retain their values while a message is being received, but are reset |
9774 | afterwards. They are also reset by MAIL, RSET, EHLO, HELO, and after starting a | |
9775 | TLS session. When a message is received, the values of these variables are | |
9776 | saved with the message, and can be accessed by filters, routers, and transports | |
9777 | during subsequent delivery. | |
9778 | ||
9b371988 PH |
9779 | .new |
9780 | .vitem &$acl_verify_message$& | |
9781 | .cindex "&$acl_verify_message$&" | |
068aaea8 PH |
9782 | After an address verification has failed, this variable contains the failure |
9783 | message. It retains its value for use in subsequent modifiers. The message can | |
9784 | be preserved by coding like this: | |
9b371988 | 9785 | .code |
068aaea8 PH |
9786 | warn !verify = sender |
9787 | set acl_m0 = $acl_verify_message | |
9b371988 PH |
9788 | .endd |
9789 | You can use &$acl_verify_message$& during the expansion of the &%message%& or | |
9790 | &%log_message%& modifiers, to include information about the verification | |
9791 | failure. | |
9792 | .wen | |
9793 | ||
9794 | .vitem &$address_data$& | |
9795 | .cindex "&$address_data$&" | |
9796 | This variable is set by means of the &%address_data%& option in routers. The | |
168e428f PH |
9797 | value then remains with the address while it is processed by subsequent routers |
9798 | and eventually a transport. If the transport is handling multiple addresses, | |
9b371988 PH |
9799 | the value from the first address is used. See chapter &<<CHAProutergeneric>>& |
9800 | for more details. &*Note*&: The contents of &$address_data$& are visible in | |
9801 | user filter files. | |
9802 | ||
9803 | If &$address_data$& is set when the routers are called from an ACL to verify | |
168e428f PH |
9804 | a recipient address, the final value is still in the variable for subsequent |
9805 | conditions and modifiers of the ACL statement. If routing the address caused it | |
9806 | to be redirected to just one address, the child address is also routed as part | |
9b371988 | 9807 | of the verification, and in this case the final value of &$address_data$& is |
168e428f | 9808 | from the child's routing. |
9b371988 PH |
9809 | |
9810 | If &$address_data$& is set when the routers are called from an ACL to verify a | |
168e428f | 9811 | sender address, the final value is also preserved, but this time in |
9b371988 | 9812 | &$sender_address_data$&, to distinguish it from data from a recipient |
168e428f | 9813 | address. |
9b371988 | 9814 | |
168e428f PH |
9815 | In both cases (recipient and sender verification), the value does not persist |
9816 | after the end of the current ACL statement. If you want to preserve | |
9817 | these values for longer, you can save them in ACL variables. | |
9818 | ||
9b371988 PH |
9819 | .vitem &$address_file$& |
9820 | .cindex "&$address_file$&" | |
168e428f PH |
9821 | When, as a result of aliasing, forwarding, or filtering, a message is directed |
9822 | to a specific file, this variable holds the name of the file when the transport | |
9823 | is running. At other times, the variable is empty. For example, using the | |
9b371988 PH |
9824 | default configuration, if user &%r2d2%& has a &_.forward_& file containing |
9825 | .code | |
9826 | /home/r2d2/savemail | |
9827 | .endd | |
9828 | then when the &(address_file)& transport is running, &$address_file$& | |
9829 | contains &"/home/r2d2/savemail"&. | |
9830 | ||
9831 | .cindex "Sieve filter" "value of &$address_file$&" | |
9832 | For Sieve filters, the value may be &"inbox"& or a relative folder name. It is | |
168e428f PH |
9833 | then up to the transport configuration to generate an appropriate absolute path |
9834 | to the relevant file. | |
9835 | ||
9b371988 PH |
9836 | .vitem &$address_pipe$& |
9837 | .cindex "&$address_pipe$&" | |
168e428f PH |
9838 | When, as a result of aliasing or forwarding, a message is directed to a pipe, |
9839 | this variable holds the pipe command when the transport is running. | |
9840 | ||
9b371988 PH |
9841 | .vitem &$authenticated_id$& |
9842 | .cindex "authentication" "id" | |
9843 | .cindex "&$authenticated_id$&" | |
168e428f PH |
9844 | When a server successfully authenticates a client it may be configured to |
9845 | preserve some of the authentication information in the variable | |
9b371988 PH |
9846 | &$authenticated_id$& (see chapter &<<CHAPSMTPAUTH>>&). For example, a |
9847 | user/password authenticator configuration might preserve the user name for use | |
9848 | in the routers. Note that this is not the same information that is saved in | |
9849 | &$sender_host_authenticated$&. When a message is submitted locally (that is, | |
9850 | not over a TCP connection), the value of &$authenticated_id$& is the login name | |
9851 | of the calling process. | |
9852 | ||
9853 | .vitem &$authenticated_sender$& | |
9854 | .cindex "sender" "authenticated" | |
9855 | .cindex "authentication" "sender" | |
9856 | .cindex "AUTH" "on MAIL command" | |
9857 | .cindex "&$authenticated_sender$&" | |
168e428f PH |
9858 | When acting as a server, Exim takes note of the AUTH= parameter on an incoming |
9859 | SMTP MAIL command if it believes the sender is sufficiently trusted, as | |
9b371988 PH |
9860 | described in section &<<SECTauthparamail>>&. Unless the data is the string |
9861 | &"<>"&, it is set as the authenticated sender of the message, and the value is | |
9862 | available during delivery in the &$authenticated_sender$& variable. If the | |
9863 | sender is not trusted, Exim accepts the syntax of AUTH=, but ignores the data. | |
9864 | ||
9865 | .cindex "&$qualify_domain$&" | |
168e428f | 9866 | When a message is submitted locally (that is, not over a TCP connection), the |
9b371988 PH |
9867 | value of &$authenticated_sender$& is an address constructed from the login |
9868 | name of the calling process and &$qualify_domain$&. | |
9869 | ||
9870 | ||
9871 | .vitem &$authentication_failed$& | |
9872 | .cindex "authentication" "failure" | |
9873 | .cindex "&$authentication_failed$&" | |
9874 | This variable is set to &"1"& in an Exim server if a client issues an AUTH | |
9875 | command that does not succeed. Otherwise it is set to &"0"&. This makes it | |
9876 | possible to distinguish between &"did not try to authenticate"& | |
9877 | (&$sender_host_authenticated$& is empty and &$authentication_failed$& is set to | |
9878 | &"0"&) and &"tried to authenticate but failed"& (&$sender_host_authenticated$& | |
9879 | is empty and &$authentication_failed$& is set to &"1"&). Failure includes any | |
168e428f PH |
9880 | negative response to an AUTH command, including (for example) an attempt to use |
9881 | an undefined mechanism. | |
9882 | ||
9b371988 PH |
9883 | .vitem &$body_linecount$& |
9884 | .cindex "message body" "line count" | |
9885 | .cindex "body of message" "line count" | |
9886 | .cindex "&$body_linecount$&" | |
168e428f | 9887 | When a message is being received or delivered, this variable contains the |
9b371988 | 9888 | number of lines in the message's body. See also &$message_linecount$&. |
168e428f | 9889 | |
9b371988 PH |
9890 | .vitem &$body_zerocount$& |
9891 | .cindex "message body" "binary zero count" | |
9892 | .cindex "body of message" "binary zero count" | |
9893 | .cindex "binary zero" "in message body" | |
9894 | .cindex "&$body_zerocount$&" | |
168e428f PH |
9895 | When a message is being received or delivered, this variable contains the |
9896 | number of binary zero bytes in the message's body. | |
9897 | ||
9b371988 PH |
9898 | .vitem &$bounce_recipient$& |
9899 | .cindex "&$bounce_recipient$&" | |
168e428f PH |
9900 | This is set to the recipient address of a bounce message while Exim is creating |
9901 | it. It is useful if a customized bounce message text file is in use (see | |
9b371988 | 9902 | chapter &<<CHAPemsgcust>>&). |
168e428f | 9903 | |
9b371988 PH |
9904 | .vitem &$bounce_return_size_limit$& |
9905 | .cindex "&$bounce_return_size_limit$&" | |
9906 | This contains the value set in the &%bounce_return_size_limit%& option, rounded | |
168e428f | 9907 | up to a multiple of 1000. It is useful when a customized error message text |
9b371988 | 9908 | file is in use (see chapter &<<CHAPemsgcust>>&). |
168e428f | 9909 | |
9b371988 PH |
9910 | .vitem &$caller_gid$& |
9911 | .cindex "gid (group id)" "caller" | |
9912 | .cindex "&$caller_gid$&" | |
168e428f PH |
9913 | The real group id under which the process that called Exim was running. This is |
9914 | not the same as the group id of the originator of a message (see | |
9b371988 | 9915 | &$originator_gid$&). If Exim re-execs itself, this variable in the new |
168e428f PH |
9916 | incarnation normally contains the Exim gid. |
9917 | ||
9b371988 PH |
9918 | .vitem &$caller_uid$& |
9919 | .cindex "uid (user id)" "caller" | |
9920 | .cindex "&$caller_uid$&" | |
168e428f PH |
9921 | The real user id under which the process that called Exim was running. This is |
9922 | not the same as the user id of the originator of a message (see | |
9b371988 | 9923 | &$originator_uid$&). If Exim re-execs itself, this variable in the new |
168e428f PH |
9924 | incarnation normally contains the Exim uid. |
9925 | ||
9b371988 PH |
9926 | .vitem &$compile_date$& |
9927 | .cindex "&$compile_date$&" | |
168e428f PH |
9928 | The date on which the Exim binary was compiled. |
9929 | ||
9b371988 PH |
9930 | .vitem &$compile_number$& |
9931 | .cindex "&$compile_number$&" | |
168e428f PH |
9932 | The building process for Exim keeps a count of the number |
9933 | of times it has been compiled. This serves to distinguish different | |
9934 | compilations of the same version of the program. | |
9935 | ||
9b371988 PH |
9936 | .vitem &$demime_errorlevel$& |
9937 | .cindex "&$demime_errorlevel$&" | |
168e428f | 9938 | This variable is available when Exim is compiled with |
9b371988 PH |
9939 | the content-scanning extension and the obsolete &%demime%& condition. For |
9940 | details, see section &<<SECTdemimecond>>&. | |
168e428f | 9941 | |
9b371988 PH |
9942 | .vitem &$demime_reason$& |
9943 | .cindex "&$demime_reason$&" | |
168e428f | 9944 | This variable is available when Exim is compiled with the |
9b371988 PH |
9945 | content-scanning extension and the obsolete &%demime%& condition. For details, |
9946 | see section &<<SECTdemimecond>>&. | |
168e428f PH |
9947 | |
9948 | ||
9b371988 PH |
9949 | .vitem &$dnslist_domain$& |
9950 | .cindex "black list (DNS)" | |
9951 | .cindex "&$dnslist_domain$&" | |
168e428f PH |
9952 | When a client host is found to be on a DNS (black) list, |
9953 | the list's domain name is put into this variable so that it can be included in | |
9954 | the rejection message. | |
9955 | ||
9b371988 PH |
9956 | .vitem &$dnslist_text$& |
9957 | .cindex "&$dnslist_text$&" | |
168e428f PH |
9958 | When a client host is found to be on a DNS (black) list, the |
9959 | contents of any associated TXT record are placed in this variable. | |
9960 | ||
9b371988 PH |
9961 | .vitem &$dnslist_value$& |
9962 | .cindex "&$dnslist_value$&" | |
168e428f PH |
9963 | When a client host is found to be on a DNS (black) list, |
9964 | the IP address from the resource record is placed in this variable. | |
9965 | If there are multiple records, all the addresses are included, comma-space | |
9966 | separated. | |
9967 | ||
9b371988 PH |
9968 | .vitem &$domain$& |
9969 | .cindex "&$domain$&" | |
068aaea8 PH |
9970 | When an address is being routed, or delivered on its own, this variable |
9971 | contains the domain. Global address rewriting happens when a message is | |
9b371988 PH |
9972 | received, so the value of &$domain$& during routing and delivery is the value |
9973 | after rewriting. &$domain$& is set during user filtering, but not during system | |
068aaea8 PH |
9974 | filtering, because a message may have many recipients and the system filter is |
9975 | called just once. | |
9b371988 | 9976 | |
168e428f | 9977 | When more than one address is being delivered at once (for example, several |
9b371988 | 9978 | RCPT commands in one SMTP delivery), &$domain$& is set only if they all |
168e428f | 9979 | have the same domain. Transports can be restricted to handling only one domain |
9b371988 | 9980 | at a time if the value of &$domain$& is required at transport time &-- this is |
168e428f | 9981 | the default for local transports. For further details of the environment in |
9b371988 PH |
9982 | which local transports are run, see chapter &<<CHAPenvironment>>&. |
9983 | ||
9984 | .cindex "&%delay_warning_condition%&" | |
168e428f | 9985 | At the end of a delivery, if all deferred addresses have the same domain, it is |
9b371988 PH |
9986 | set in &$domain$& during the expansion of &%delay_warning_condition%&. |
9987 | ||
9988 | The &$domain$& variable is also used in some other circumstances: | |
9989 | ||
9990 | .ilist | |
9991 | When an ACL is running for a RCPT command, &$domain$& contains the domain of | |
9992 | the recipient address. The domain of the &'sender'& address is in | |
9993 | &$sender_address_domain$& at both MAIL time and at RCPT time. &$domain$& is not | |
068aaea8 PH |
9994 | normally set during the running of the MAIL ACL. However, if the sender address |
9995 | is verified with a callout during the MAIL ACL, the sender domain is placed in | |
9b371988 PH |
9996 | &$domain$& during the expansions of &%hosts%&, &%interface%&, and &%port%& in |
9997 | the &(smtp)& transport. | |
9998 | ||
9999 | .next | |
10000 | When a rewrite item is being processed (see chapter &<<CHAPrewrite>>&), | |
10001 | &$domain$& contains the domain portion of the address that is being rewritten; | |
10002 | it can be used in the expansion of the replacement address, for example, to | |
10003 | rewrite domains by file lookup. | |
10004 | ||
10005 | .next | |
10006 | With one important exception, whenever a domain list is being scanned, | |
10007 | &$domain$& contains the subject domain. &*Exception*&: When a domain list in | |
10008 | a &%sender_domains%& condition in an ACL is being processed, the subject domain | |
10009 | is in &$sender_address_domain$& and not in &$domain$&. It works this way so | |
168e428f | 10010 | that, in a RCPT ACL, the sender domain list can be dependent on the |
9b371988 | 10011 | recipient domain (which is what is in &$domain$& at this time). |
168e428f | 10012 | |
9b371988 PH |
10013 | .next |
10014 | .cindex "ETRN" "value of &$domain$&" | |
10015 | .cindex "&%smtp_etrn_command%&" | |
10016 | When the &%smtp_etrn_command%& option is being expanded, &$domain$& contains | |
10017 | the complete argument of the ETRN command (see section &<<SECTETRN>>&). | |
10018 | .endlist | |
168e428f PH |
10019 | |
10020 | ||
9b371988 PH |
10021 | .vitem &$domain_data$& |
10022 | .cindex "&$domain_data$&" | |
10023 | When the &%domains%& option on a router matches a domain by | |
168e428f | 10024 | means of a lookup, the data read by the lookup is available during the running |
9b371988 | 10025 | of the router as &$domain_data$&. In addition, if the driver routes the |
168e428f PH |
10026 | address to a transport, the value is available in that transport. If the |
10027 | transport is handling multiple addresses, the value from the first address is | |
10028 | used. | |
9b371988 PH |
10029 | |
10030 | &$domain_data$& is also set when the &%domains%& condition in an ACL matches a | |
168e428f PH |
10031 | domain by means of a lookup. The data read by the lookup is available during |
10032 | the rest of the ACL statement. In all other situations, this variable expands | |
10033 | to nothing. | |
10034 | ||
9b371988 PH |
10035 | .vitem &$exim_gid$& |
10036 | .cindex "&$exim_gid$&" | |
168e428f PH |
10037 | This variable contains the numerical value of the Exim group id. |
10038 | ||
9b371988 PH |
10039 | .vitem &$exim_path$& |
10040 | .cindex "&$exim_path$&" | |
168e428f PH |
10041 | This variable contains the path to the Exim binary. |
10042 | ||
9b371988 PH |
10043 | .vitem &$exim_uid$& |
10044 | .cindex "&$exim_uid$&" | |
168e428f PH |
10045 | This variable contains the numerical value of the Exim user id. |
10046 | ||
9b371988 PH |
10047 | .vitem &$found_extension$& |
10048 | .cindex "&$found_extension$&" | |
168e428f | 10049 | This variable is available when Exim is compiled with the |
9b371988 PH |
10050 | content-scanning extension and the obsolete &%demime%& condition. For details, |
10051 | see section &<<SECTdemimecond>>&. | |
168e428f | 10052 | |
9b371988 | 10053 | .vitem &$header_$&<&'name'&> |
068aaea8 PH |
10054 | This is not strictly an expansion variable. It is expansion syntax for |
10055 | inserting the message header line with the given name. Note that the name must | |
10056 | be terminated by colon or white space, because it may contain a wide variety of | |
9b371988 | 10057 | characters. Note also that braces must &'not'& be used. |
168e428f | 10058 | |
9b371988 PH |
10059 | .vitem &$home$& |
10060 | .cindex "&$home$&" | |
10061 | When the &%check_local_user%& option is set for a router, the user's home | |
10062 | directory is placed in &$home$& when the check succeeds. In particular, this | |
168e428f PH |
10063 | means it is set during the running of users' filter files. A router may also |
10064 | explicitly set a home directory for use by a transport; this can be overridden | |
10065 | by a setting on the transport itself. | |
9b371988 PH |
10066 | |
10067 | When running a filter test via the &%-bf%& option, &$home$& is set to the value | |
168e428f PH |
10068 | of the environment variable HOME. |
10069 | ||
9b371988 PH |
10070 | .vitem &$host$& |
10071 | .cindex "&$host$&" | |
10072 | When the &(smtp)& transport is expanding its options for encryption using TLS, | |
10073 | &$host$& contains the name of the host to which it is connected. Likewise, when | |
168e428f | 10074 | used in the client part of an authenticator configuration (see chapter |
9b371988 PH |
10075 | &<<CHAPSMTPAUTH>>&), &$host$& contains the name of the server to which the |
10076 | client is connected. | |
10077 | ||
10078 | .cindex "transport" "filter" | |
10079 | .cindex "filter" "transport filter" | |
10080 | When used in a transport filter (see chapter &<<CHAPtransportgeneric>>&) | |
10081 | &$host$& refers to the host involved in the current connection. When a local | |
10082 | transport is run as a result of a router that sets up a host list, &$host$& | |
10083 | contains the name of the first host. | |
10084 | ||
10085 | .vitem &$host_address$& | |
10086 | .cindex "&$host_address$&" | |
10087 | This variable is set to the remote host's IP address whenever &$host$& is set | |
10088 | for a remote connection. It is also set to the IP address that is being checked | |
10089 | when the &%ignore_target_hosts%& option is being processed. | |
10090 | ||
10091 | .vitem &$host_data$& | |
10092 | .cindex "&$host_data$&" | |
10093 | If a &%hosts%& condition in an ACL is satisfied by means of a lookup, the | |
10094 | result of the lookup is made available in the &$host_data$& variable. This | |
168e428f | 10095 | allows you, for example, to do things like this: |
9b371988 PH |
10096 | .code |
10097 | deny hosts = net-lsearch;/some/file | |
10098 | message = $host_data | |
10099 | .endd | |
10100 | .vitem &$host_lookup_deferred$& | |
10101 | .cindex "host name lookup" "failure of" | |
10102 | .cindex "&$host_lookup_deferred$&" | |
10103 | This variable normally contains &"0"&, as does &$host_lookup_failed$&. When a | |
168e428f PH |
10104 | message comes from a remote host and there is an attempt to look up the host's |
10105 | name from its IP address, and the attempt is not successful, one of these | |
9b371988 | 10106 | variables is set to &"1"&. |
168e428f | 10107 | |
9b371988 PH |
10108 | .ilist |
10109 | If the lookup receives a definite negative response (for example, a DNS lookup | |
10110 | succeeded, but no records were found), &$host_lookup_failed$& is set to &"1"&. | |
10111 | ||
10112 | .next | |
10113 | If there is any kind of problem during the lookup, such that Exim cannot | |
168e428f | 10114 | tell whether or not the host name is defined (for example, a timeout for a DNS |
9b371988 PH |
10115 | lookup), &$host_lookup_deferred$& is set to &"1"&. |
10116 | .endlist ilist | |
10117 | ||
168e428f PH |
10118 | Looking up a host's name from its IP address consists of more than just a |
10119 | single reverse lookup. Exim checks that a forward lookup of at least one of the | |
10120 | names it receives from a reverse lookup yields the original IP address. If this | |
10121 | is not the case, Exim does not accept the looked up name(s), and | |
9b371988 | 10122 | &$host_lookup_failed$& is set to &"1"&. Thus, being able to find a name from an |
168e428f PH |
10123 | IP address (for example, the existence of a PTR record in the DNS) is not |
10124 | sufficient on its own for the success of a host name lookup. If the reverse | |
10125 | lookup succeeds, but there is a lookup problem such as a timeout when checking | |
9b371988 PH |
10126 | the result, the name is not accepted, and &$host_lookup_deferred$& is set to |
10127 | &"1"&. See also &$sender_host_name$&. | |
168e428f | 10128 | |
9b371988 PH |
10129 | .vitem &$host_lookup_failed$& |
10130 | .cindex "&$host_lookup_failed$&" | |
10131 | See &$host_lookup_deferred$&. | |
168e428f PH |
10132 | |
10133 | ||
9b371988 PH |
10134 | .vitem &$inode$& |
10135 | .cindex "&$inode$&" | |
10136 | The only time this variable is set is while expanding the &%directory_file%& | |
10137 | option in the &(appendfile)& transport. The variable contains the inode number | |
168e428f PH |
10138 | of the temporary file which is about to be renamed. It can be used to construct |
10139 | a unique name for the file. | |
10140 | ||
9b371988 PH |
10141 | .new |
10142 | .vitem &$interface_address$& | |
10143 | .cindex "&$interface_address$&" | |
068aaea8 | 10144 | As soon as a server starts processing a TCP/IP connection, this variable is set |
9b371988 PH |
10145 | to the address of the local IP interface, and &$interface_port$& is set to the |
10146 | port number. These values are therefore available for use in the &"connect"& | |
10147 | ACL. See also the &%-oMi%& command line option. As well as being used in ACLs, | |
068aaea8 PH |
10148 | these variable could be used, for example, to make the file name for a TLS |
10149 | certificate depend on which interface and/or port is being used. | |
9b371988 | 10150 | .wen |
168e428f | 10151 | |
9b371988 PH |
10152 | .vitem &$interface_port$& |
10153 | .cindex "&$interface_port$&" | |
10154 | See &$interface_address$&. | |
168e428f | 10155 | |
9b371988 PH |
10156 | .vitem &$ldap_dn$& |
10157 | .cindex "&$ldap_dn$&" | |
168e428f PH |
10158 | This variable, which is available only when Exim is compiled with LDAP support, |
10159 | contains the DN from the last entry in the most recently successful LDAP | |
10160 | lookup. | |
10161 | ||
9b371988 PH |
10162 | .vitem &$load_average$& |
10163 | .cindex "&$load_average$&" | |
168e428f PH |
10164 | This variable contains the system load average, multiplied by 1000 to that it |
10165 | is an integer. For example, if the load average is 0.21, the value of the | |
10166 | variable is 210. The value is recomputed every time the variable is referenced. | |
10167 | ||
9b371988 PH |
10168 | .vitem &$local_part$& |
10169 | .cindex "&$local_part$&" | |
168e428f PH |
10170 | When an address is being routed, or delivered on its own, this |
10171 | variable contains the local part. When a number of addresses are being | |
10172 | delivered together (for example, multiple RCPT commands in an SMTP | |
9b371988 PH |
10173 | session), &$local_part$& is not set. |
10174 | ||
168e428f | 10175 | Global address rewriting happens when a message is received, so the value of |
9b371988 PH |
10176 | &$local_part$& during routing and delivery is the value after rewriting. |
10177 | &$local_part$& is set during user filtering, but not during system filtering, | |
168e428f PH |
10178 | because a message may have many recipients and the system filter is called just |
10179 | once. | |
9b371988 PH |
10180 | |
10181 | .cindex "&$local_part_prefix$&" | |
10182 | .cindex "&$local_part_suffix$&" | |
168e428f | 10183 | If a local part prefix or suffix has been recognized, it is not included in the |
9b371988 PH |
10184 | value of &$local_part$& during routing and subsequent delivery. The values of |
10185 | any prefix or suffix are in &$local_part_prefix$& and | |
10186 | &$local_part_suffix$&, respectively. | |
10187 | ||
168e428f | 10188 | When a message is being delivered to a file, pipe, or autoreply transport as a |
9b371988 PH |
10189 | result of aliasing or forwarding, &$local_part$& is set to the local part of |
10190 | the parent address, not to the file name or command (see &$address_file$& and | |
10191 | &$address_pipe$&). | |
10192 | ||
10193 | When an ACL is running for a RCPT command, &$local_part$& contains the | |
168e428f | 10194 | local part of the recipient address. |
9b371988 PH |
10195 | |
10196 | When a rewrite item is being processed (see chapter &<<CHAPrewrite>>&), | |
10197 | &$local_part$& contains the local part of the address that is being rewritten; | |
168e428f | 10198 | it can be used in the expansion of the replacement address, for example. |
9b371988 | 10199 | |
168e428f PH |
10200 | In all cases, all quoting is removed from the local part. For example, for both |
10201 | the addresses | |
9b371988 PH |
10202 | .code |
10203 | "abc:xyz"@test.example | |
10204 | abc\:xyz@test.example | |
10205 | .endd | |
10206 | the value of &$local_part$& is | |
10207 | .code | |
10208 | abc:xyz | |
10209 | .endd | |
10210 | If you use &$local_part$& to create another address, you should always wrap it | |
10211 | inside a quoting operator. For example, in a &(redirect)& router you could | |
10212 | have: | |
10213 | .code | |
10214 | data = ${quote_local_part:$local_part}@new.domain.example | |
10215 | .endd | |
10216 | &*Note*&: The value of &$local_part$& is normally lower cased. If you want | |
168e428f | 10217 | to process local parts in a case-dependent manner in a router, you can set the |
9b371988 | 10218 | &%caseful_local_part%& option (see chapter &<<CHAProutergeneric>>&). |
168e428f | 10219 | |
9b371988 PH |
10220 | .vitem &$local_part_data$& |
10221 | .cindex "&$local_part_data$&" | |
10222 | When the &%local_parts%& option on a router matches a local part by means of a | |
168e428f | 10223 | lookup, the data read by the lookup is available during the running of the |
9b371988 | 10224 | router as &$local_part_data$&. In addition, if the driver routes the address |
168e428f PH |
10225 | to a transport, the value is available in that transport. If the transport is |
10226 | handling multiple addresses, the value from the first address is used. | |
9b371988 PH |
10227 | |
10228 | &$local_part_data$& is also set when the &%local_parts%& condition in an ACL | |
168e428f PH |
10229 | matches a local part by means of a lookup. The data read by the lookup is |
10230 | available during the rest of the ACL statement. In all other situations, this | |
10231 | variable expands to nothing. | |
10232 | ||
9b371988 PH |
10233 | .vitem &$local_part_prefix$& |
10234 | .cindex "&$local_part_prefix$&" | |
168e428f PH |
10235 | When an address is being routed or delivered, and a |
10236 | specific prefix for the local part was recognized, it is available in this | |
9b371988 | 10237 | variable, having been removed from &$local_part$&. |
168e428f | 10238 | |
9b371988 PH |
10239 | .vitem &$local_part_suffix$& |
10240 | .cindex "&$local_part_suffix$&" | |
168e428f PH |
10241 | When an address is being routed or delivered, and a |
10242 | specific suffix for the local part was recognized, it is available in this | |
9b371988 PH |
10243 | variable, having been removed from &$local_part$&. |
10244 | ||
10245 | .vitem &$local_scan_data$& | |
10246 | .cindex "&$local_scan_data$&" | |
10247 | This variable contains the text returned by the &[local_scan()]& function when | |
10248 | a message is received. See chapter &<<CHAPlocalscan>>& for more details. | |
10249 | ||
10250 | .vitem &$local_user_gid$& | |
10251 | .cindex "&$local_user_gid$&" | |
10252 | See &$local_user_uid$&. | |
10253 | ||
10254 | .vitem &$local_user_uid$& | |
10255 | .cindex "&$local_user_uid$&" | |
10256 | This variable and &$local_user_gid$& are set to the uid and gid after the | |
10257 | &%check_local_user%& router precondition succeeds. This means that their values | |
10258 | are available for the remaining preconditions (&%senders%&, &%require_files%&, | |
10259 | and &%condition%&), for the &%address_data%& expansion, and for any | |
10260 | router-specific expansions. At all other times, the values in these variables | |
10261 | are &`(uid_t)(-1)`& and &`(gid_t)(-1)`&, respectively. | |
10262 | ||
10263 | .vitem &$localhost_number$& | |
10264 | .cindex "&$localhost_number$&" | |
168e428f | 10265 | This contains the expanded value of the |
9b371988 | 10266 | &%localhost_number%& option. The expansion happens after the main options have |
168e428f PH |
10267 | been read. |
10268 | ||
9b371988 PH |
10269 | .vitem &$log_inodes$& |
10270 | .cindex "&$log_inodes$&" | |
168e428f PH |
10271 | The number of free inodes in the disk partition where Exim's |
10272 | log files are being written. The value is recalculated whenever the variable is | |
10273 | referenced. If the relevant file system does not have the concept of inodes, | |
9b371988 | 10274 | the value of is -1. See also the &%check_log_inodes%& option. |
168e428f | 10275 | |
9b371988 PH |
10276 | .vitem &$log_space$& |
10277 | .cindex "&$log_space$&" | |
168e428f PH |
10278 | The amount of free space (as a number of kilobytes) in the disk |
10279 | partition where Exim's log files are being written. The value is recalculated | |
10280 | whenever the variable is referenced. If the operating system does not have the | |
10281 | ability to find the amount of free space (only true for experimental systems), | |
9b371988 | 10282 | the space value is -1. See also the &%check_log_space%& option. |
168e428f PH |
10283 | |
10284 | ||
9b371988 PH |
10285 | .vitem &$mailstore_basename$& |
10286 | .cindex "&$mailstore_basename$&" | |
10287 | This variable is set only when doing deliveries in &"mailstore"& format in the | |
10288 | &(appendfile)& transport. During the expansion of the &%mailstore_prefix%&, | |
10289 | &%mailstore_suffix%&, &%message_prefix%&, and &%message_suffix%& options, it | |
10290 | contains the basename of the files that are being written, that is, the name | |
10291 | without the &".tmp"&, &".env"&, or &".msg"& suffix. At all other times, this | |
10292 | variable is empty. | |
168e428f | 10293 | |
9b371988 PH |
10294 | .vitem &$malware_name$& |
10295 | .cindex "&$malware_name$&" | |
168e428f PH |
10296 | This variable is available when Exim is compiled with the |
10297 | content-scanning extension. It is set to the name of the virus that was found | |
9b371988 | 10298 | when the ACL &%malware%& condition is true (see section &<<SECTscanvirus>>&). |
168e428f PH |
10299 | |
10300 | ||
9b371988 PH |
10301 | .vitem &$message_age$& |
10302 | .cindex "message" "age of" | |
10303 | .cindex "&$message_age$&" | |
068aaea8 PH |
10304 | This variable is set at the start of a delivery attempt to contain the number |
10305 | of seconds since the message was received. It does not change during a single | |
10306 | delivery attempt. | |
168e428f | 10307 | |
9b371988 PH |
10308 | .vitem &$message_body$& |
10309 | .cindex "body of message" "expansion variable" | |
10310 | .cindex "message body" "in expansion" | |
10311 | .cindex "binary zero" "in message body" | |
10312 | .cindex "&$message_body$&" | |
168e428f PH |
10313 | This variable contains the initial portion of a message's |
10314 | body while it is being delivered, and is intended mainly for use in filter | |
10315 | files. The maximum number of characters of the body that are put into the | |
9b371988 | 10316 | variable is set by the &%message_body_visible%& configuration option; the |
168e428f PH |
10317 | default is 500. Newlines are converted into spaces to make it easier to search |
10318 | for phrases that might be split over a line break. | |
10319 | Binary zeros are also converted into spaces. | |
10320 | ||
9b371988 PH |
10321 | .vitem &$message_body_end$& |
10322 | .cindex "body of message" "expansion variable" | |
10323 | .cindex "message body" "in expansion" | |
10324 | .cindex "&$message_body_end$&" | |
168e428f PH |
10325 | This variable contains the final portion of a message's |
10326 | body while it is being delivered. The format and maximum size are as for | |
9b371988 | 10327 | &$message_body$&. |
168e428f | 10328 | |
9b371988 PH |
10329 | .vitem &$message_body_size$& |
10330 | .cindex "body of message" "size" | |
10331 | .cindex "message body" "size" | |
10332 | .cindex "&$message_body_size$&" | |
068aaea8 PH |
10333 | When a message is being delivered, this variable contains the size of the body |
10334 | in bytes. The count starts from the character after the blank line that | |
10335 | separates the body from the header. Newlines are included in the count. See | |
9b371988 | 10336 | also &$message_size$&, &$body_linecount$&, and &$body_zerocount$&. |
068aaea8 | 10337 | |
9b371988 PH |
10338 | .new |
10339 | .vitem &$message_exim_id$& | |
10340 | .cindex "&$message_exim_id$&" | |
068aaea8 PH |
10341 | When a message is being received or delivered, this variable contains the |
10342 | unique message id that is generated and used by Exim to identify the message. | |
10343 | An id is not created for a message until after its header has been successfully | |
9b371988 PH |
10344 | received. &*Note*&: This is &'not'& the contents of the &'Message-ID:'& header |
10345 | line; it is the local id that Exim assigns to the message, for example: | |
10346 | &`1BXTIK-0001yO-VA`&. | |
10347 | .wen | |
168e428f | 10348 | |
9b371988 | 10349 | .vitem &$message_headers$& |
168e428f PH |
10350 | This variable contains a concatenation of all the header lines when a message |
10351 | is being processed, except for lines added by routers or transports. The header | |
10352 | lines are separated by newline characters. | |
10353 | ||
9b371988 PH |
10354 | .vitem &$message_id$& |
10355 | .new | |
10356 | This is an old name for &$message_exim_id$&, which is now deprecated. | |
10357 | .wen | |
068aaea8 | 10358 | |
9b371988 PH |
10359 | .new |
10360 | .vitem &$message_linecount$& | |
10361 | .cindex "&$message_linecount$&" | |
068aaea8 | 10362 | This variable contains the total number of lines in the header and body of the |
9b371988 PH |
10363 | message. Compare &$body_linecount$&, which is the count for the body only. |
10364 | During the DATA and content-scanning ACLs, &$message_linecount$& contains the | |
10365 | number of lines received. Before delivery happens (that is, before filters, | |
10366 | routers, and transports run) the count is increased to include the | |
10367 | &'Received:'& header line that Exim standardly adds, and also any other header | |
10368 | lines that are added by ACLs. The blank line that separates the message header | |
10369 | from the body is not counted. Here is an example of the use of this variable in | |
10370 | a DATA ACL: | |
10371 | .code | |
068aaea8 PH |
10372 | deny message = Too many lines in message header |
10373 | condition = \ | |
9b371988 PH |
10374 | ${if <{250}{${eval:$message_linecount - $body_linecount}}} |
10375 | .endd | |
068aaea8 PH |
10376 | In the MAIL and RCPT ACLs, the value is zero because at that stage the |
10377 | message has not yet been received. | |
9b371988 | 10378 | .wen |
168e428f | 10379 | |
9b371988 PH |
10380 | .vitem &$message_size$& |
10381 | .cindex "size" "of message" | |
10382 | .cindex "message" "size" | |
10383 | .cindex "&$message_size$&" | |
168e428f PH |
10384 | When a message is being processed, this variable contains its size in bytes. In |
10385 | most cases, the size includes those headers that were received with the | |
9b371988 | 10386 | message, but not those (such as &'Envelope-to:'&) that are added to individual |
168e428f | 10387 | deliveries as they are written. However, there is one special case: during the |
9b371988 PH |
10388 | expansion of the &%maildir_tag%& option in the &(appendfile)& transport while |
10389 | doing a delivery in maildir format, the value of &$message_size$& is the | |
168e428f | 10390 | precise size of the file that has been written. See also |
9b371988 PH |
10391 | &$message_body_size$&, &$body_linecount$&, and &$body_zerocount$&. |
10392 | ||
10393 | .cindex "RCPT" "value of &$message_size$&" | |
10394 | While running an ACL at the time of an SMTP RCPT command, &$message_size$& | |
168e428f PH |
10395 | contains the size supplied on the MAIL command, or -1 if no size was given. The |
10396 | value may not, of course, be truthful. | |
10397 | ||
9b371988 PH |
10398 | .vitem &$mime_$&&'xxx'& |
10399 | A number of variables whose names start with &$mime$& are | |
168e428f | 10400 | available when Exim is compiled with the content-scanning extension. For |
9b371988 | 10401 | details, see section &<<SECTscanmimepart>>&. |
168e428f | 10402 | |
9b371988 | 10403 | .vitem "&$n0$& &-- &$n9$&" |
168e428f | 10404 | These variables are counters that can be incremented by means |
9b371988 | 10405 | of the &%add%& command in filter files. |
168e428f | 10406 | |
9b371988 PH |
10407 | .vitem &$original_domain$& |
10408 | .cindex "&$domain$&" | |
10409 | .cindex "&$original_domain$&" | |
068aaea8 | 10410 | When a top-level address is being processed for delivery, this contains the |
9b371988 PH |
10411 | same value as &$domain$&. However, if a &"child"& address (for example, |
10412 | generated by an alias, forward, or filter file) is being processed, this | |
10413 | variable contains the domain of the original address. This differs from | |
10414 | &$parent_domain$& only when there is more than one level of aliasing or | |
10415 | forwarding. When more than one address is being delivered in a single transport | |
10416 | run, &$original_domain$& is not set. | |
10417 | ||
10418 | If a new address is created by means of a &%deliver%& command in a system | |
10419 | filter, it is set up with an artificial &"parent"& address. This has the local | |
10420 | part &'system-filter'& and the default qualify domain. | |
10421 | ||
10422 | .vitem &$original_local_part$& | |
10423 | .cindex "&$local_part$&" | |
10424 | .cindex "&$original_local_part$&" | |
068aaea8 | 10425 | When a top-level address is being processed for delivery, this contains the |
9b371988 PH |
10426 | same value as &$local_part$&, unless a prefix or suffix was removed from the |
10427 | local part, because &$original_local_part$& always contains the full local | |
10428 | part. When a &"child"& address (for example, generated by an alias, forward, or | |
068aaea8 PH |
10429 | filter file) is being processed, this variable contains the full local part of |
10430 | the original address. | |
9b371988 | 10431 | |
168e428f | 10432 | If the router that did the redirection processed the local part |
9b371988 PH |
10433 | case-insensitively, the value in &$original_local_part$& is in lower case. |
10434 | This variable differs from &$parent_local_part$& only when there is more than | |
168e428f | 10435 | one level of aliasing or forwarding. When more than one address is being |
9b371988 PH |
10436 | delivered in a single transport run, &$original_local_part$& is not set. |
10437 | ||
10438 | If a new address is created by means of a &%deliver%& command in a system | |
10439 | filter, it is set up with an artificial &"parent"& address. This has the local | |
10440 | part &'system-filter'& and the default qualify domain. | |
10441 | ||
10442 | .vitem &$originator_gid$& | |
10443 | .cindex "gid (group id)" "of originating user" | |
10444 | .cindex "sender" "gid" | |
10445 | .cindex "&$caller_gid$&" | |
10446 | .cindex "&$originator_gid$&" | |
10447 | This variable contains the value of &$caller_gid$& that was set when the | |
10448 | message was received. For messages received via the command line, this is the | |
10449 | gid of the sending user. For messages received by SMTP over TCP/IP, this is | |
10450 | normally the gid of the Exim user. | |
10451 | ||
10452 | .vitem &$originator_uid$& | |
10453 | .cindex "uid (user id)" "of originating user" | |
10454 | .cindex "sender" "uid" | |
10455 | .cindex "&$caller_uid$&" | |
10456 | .cindex "&$originaltor_uid$&" | |
10457 | The value of &$caller_uid$& that was set when the message was received. For | |
068aaea8 PH |
10458 | messages received via the command line, this is the uid of the sending user. |
10459 | For messages received by SMTP over TCP/IP, this is normally the uid of the Exim | |
10460 | user. | |
168e428f | 10461 | |
9b371988 PH |
10462 | .vitem &$parent_domain$& |
10463 | .cindex "&$parent_domain$&" | |
10464 | This variable is similar to &$original_domain$& (see | |
168e428f PH |
10465 | above), except that it refers to the immediately preceding parent address. |
10466 | ||
9b371988 PH |
10467 | .vitem &$parent_local_part$& |
10468 | .cindex "&$parent_local_part$&" | |
10469 | This variable is similar to &$original_local_part$& | |
168e428f PH |
10470 | (see above), except that it refers to the immediately preceding parent address. |
10471 | ||
9b371988 PH |
10472 | .vitem &$pid$& |
10473 | .cindex "pid (process id)" "of current process" | |
10474 | .cindex "&$pid$&" | |
168e428f PH |
10475 | This variable contains the current process id. |
10476 | ||
9b371988 PH |
10477 | .vitem &$pipe_addresses$& |
10478 | .cindex "filter" "transport filter" | |
10479 | .cindex "transport" "filter" | |
10480 | .cindex "&$pipe_addresses$&" | |
068aaea8 | 10481 | This is not an expansion variable, but is mentioned here because the string |
9b371988 PH |
10482 | &"$pipe_addresses"& is handled specially in the command specification for the |
10483 | &(pipe)& transport (chapter &<<CHAPpipetransport>>&) and in transport filters | |
10484 | (described under &%transport_filter%& in chapter &<<CHAPtransportgeneric>>&). | |
10485 | It cannot be used in general expansion strings, and provokes an &"unknown | |
10486 | variable"& error if encountered. | |
10487 | ||
10488 | .vitem &$primary_hostname$& | |
10489 | .cindex "&$primary_hostname$&" | |
10490 | This variable contains the value set by &%primary_hostname%& in the | |
10491 | configuration file, or read by the &[uname()]& function. If &[uname()]& returns | |
10492 | a single-component name, Exim calls &[gethostbyname()]& (or | |
10493 | &[getipnodebyname()]& where available) in an attempt to acquire a fully | |
10494 | qualified host name. See also &$smtp_active_hostname$&. | |
10495 | ||
10496 | ||
10497 | .new | |
10498 | .vitem &$prvscheck_address$& | |
10499 | This variable is used in conjunction with the &%prvscheck%& expansion item, | |
10500 | which is described in sections &<<SECTexpansionitems>>& and | |
10501 | &<<SECTverifyPRVS>>&. | |
10502 | ||
10503 | .vitem &$prvscheck_keynum$& | |
10504 | This variable is used in conjunction with the &%prvscheck%& expansion item, | |
10505 | which is described in sections &<<SECTexpansionitems>>& and | |
10506 | &<<SECTverifyPRVS>>&. | |
10507 | ||
10508 | .vitem &$prvscheck_result$& | |
10509 | This variable is used in conjunction with the &%prvscheck%& expansion item, | |
10510 | which is described in sections &<<SECTexpansionitems>>& and | |
10511 | &<<SECTverifyPRVS>>&. | |
10512 | .wen | |
10513 | ||
10514 | .vitem &$qualify_domain$& | |
10515 | .cindex "&$qualify_domain$&" | |
10516 | The value set for the &%qualify_domain%& option in the configuration file. | |
10517 | ||
10518 | .vitem &$qualify_recipient$& | |
10519 | .cindex "&$qualify_recipient$&" | |
10520 | The value set for the &%qualify_recipient%& option in the configuration file, | |
10521 | or if not set, the value of &$qualify_domain$&. | |
10522 | ||
10523 | .vitem &$rcpt_count$& | |
10524 | .cindex "&$rcpt_count$&" | |
068aaea8 PH |
10525 | When a message is being received by SMTP, this variable contains the number of |
10526 | RCPT commands received for the current message. If this variable is used in a | |
10527 | RCPT ACL, its value includes the current command. | |
168e428f | 10528 | |
9b371988 PH |
10529 | .vitem &$rcpt_defer_count$& |
10530 | .cindex "&$rcpt_defer_count$&" | |
068aaea8 PH |
10531 | When a message is being received by SMTP, this variable contains the number of |
10532 | RCPT commands in the current message that have previously been rejected with a | |
9b371988 | 10533 | temporary (4&'xx'&) response. |
168e428f | 10534 | |
9b371988 PH |
10535 | .vitem &$rcpt_fail_count$& |
10536 | .cindex "&$rcpt_fail_count$&" | |
068aaea8 PH |
10537 | When a message is being received by SMTP, this variable contains the number of |
10538 | RCPT commands in the current message that have previously been rejected with a | |
9b371988 | 10539 | permanent (5&'xx'&) response. |
168e428f | 10540 | |
9b371988 PH |
10541 | .vitem &$received_count$& |
10542 | .cindex "&$received_count$&" | |
10543 | This variable contains the number of &'Received:'& header lines in the message, | |
068aaea8 PH |
10544 | including the one added by Exim (so its value is always greater than zero). It |
10545 | is available in the DATA ACL, the non-SMTP ACL, and while routing and | |
10546 | delivering. | |
168e428f | 10547 | |
9b371988 PH |
10548 | .vitem &$received_for$& |
10549 | .cindex "&$received_for$&" | |
068aaea8 | 10550 | If there is only a single recipient address in an incoming message, this |
9b371988 PH |
10551 | variable contains that address when the &'Received:'& header line is being |
10552 | built. The value is copied after recipient rewriting has happened, but before | |
10553 | the &[local_scan()]& function is run. | |
168e428f | 10554 | |
9b371988 PH |
10555 | .vitem &$received_protocol$& |
10556 | .cindex "&$received_protocol$&" | |
068aaea8 PH |
10557 | When a message is being processed, this variable contains the name of the |
10558 | protocol by which it was received. Most of the names used by Exim are defined | |
9b371988 PH |
10559 | by RFCs 821, 2821, and 3848. They start with &"smtp"& (the client used HELO) or |
10560 | &"esmtp"& (the client used EHLO). This can be followed by &"s"& for secure | |
10561 | (encrypted) and/or &"a"& for authenticated. Thus, for example, if the protocol | |
10562 | is set to &"esmtpsa"&, the message was received over an encrypted SMTP | |
068aaea8 | 10563 | connection and the client was successfully authenticated. |
9b371988 PH |
10564 | |
10565 | Exim uses the protocol name &"smtps"& for the case when encryption is | |
168e428f | 10566 | automatically set up on connection without the use of STARTTLS (see |
9b371988 PH |
10567 | &%tls_on_connect_ports%&), and the client uses HELO to initiate the |
10568 | encrypted SMTP session. The name &"smtps"& is also used for the rare situation | |
168e428f PH |
10569 | where the client initially uses EHLO, sets up an encrypted connection using |
10570 | STARTTLS, and then uses HELO afterwards. | |
9b371988 PH |
10571 | |
10572 | The &%-oMr%& option provides a way of specifying a custom protocol name for | |
168e428f PH |
10573 | messages that are injected locally by trusted callers. This is commonly used to |
10574 | identify messages that are being re-injected after some kind of scanning. | |
10575 | ||
9b371988 PH |
10576 | .new |
10577 | .vitem &$received_time$& | |
10578 | .cindex "&$received_time$&" | |
068aaea8 PH |
10579 | This variable contains the date and time when the current message was received, |
10580 | as a number of seconds since the start of the Unix epoch. | |
9b371988 | 10581 | .wen |
168e428f | 10582 | |
9b371988 PH |
10583 | .vitem &$recipient_data$& |
10584 | .cindex "&$recipient_data$&" | |
10585 | This variable is set after an indexing lookup success in an ACL &%recipients%& | |
068aaea8 | 10586 | condition. It contains the data from the lookup, and the value remains set |
9b371988 PH |
10587 | until the next &%recipients%& test. Thus, you can do things like this: |
10588 | .display | |
10589 | &`require recipients = cdb*@;/some/file`& | |
10590 | &`deny `&&'some further test involving'& &`$recipient_data`& | |
10591 | .endd | |
10592 | &*Warning*&: This variable is set only when a lookup is used as an indexing | |
168e428f PH |
10593 | method in the address list, using the semicolon syntax as in the example above. |
10594 | The variable is not set for a lookup that is used as part of the string | |
10595 | expansion that all such lists undergo before being interpreted. | |
10596 | ||
9b371988 PH |
10597 | .vitem &$recipient_verify_failure$& |
10598 | .cindex "&$recipient_verify_failure$&" | |
068aaea8 PH |
10599 | In an ACL, when a recipient verification fails, this variable contains |
10600 | information about the failure. It is set to one of the following words: | |
9b371988 PH |
10601 | |
10602 | .ilist | |
10603 | &"qualify"&: The address was unqualified (no domain), and the message | |
168e428f PH |
10604 | was neither local nor came from an exempted host. |
10605 | ||
9b371988 PH |
10606 | .next |
10607 | &"route"&: Routing failed. | |
168e428f | 10608 | |
9b371988 PH |
10609 | .next |
10610 | &"mail"&: Routing succeeded, and a callout was attempted; rejection occurred at | |
168e428f PH |
10611 | or before the MAIL command (that is, on initial connection, HELO, or |
10612 | MAIL). | |
10613 | ||
9b371988 PH |
10614 | .next |
10615 | &"recipient"&: The RCPT command in a callout was rejected. | |
10616 | .next | |
10617 | ||
10618 | &"postmaster"&: The postmaster check in a callout was rejected. | |
10619 | .endlist | |
168e428f | 10620 | |
168e428f PH |
10621 | The main use of this variable is expected to be to distinguish between |
10622 | rejections of MAIL and rejections of RCPT. | |
10623 | ||
9b371988 PH |
10624 | .vitem &$recipients$& |
10625 | .cindex "&$recipients$&" | |
168e428f PH |
10626 | This variable contains a list of envelope recipients for a |
10627 | message. A comma and a space separate the addresses in the replacement text. | |
10628 | However, the variable is not generally available, to prevent exposure of Bcc | |
9b371988 | 10629 | recipients in unprivileged users' filter files. You can use &$recipients$& only |
168e428f PH |
10630 | in these two cases: |
10631 | ||
9b371988 PH |
10632 | .olist |
10633 | In a system filter file. | |
10634 | .next | |
10635 | In the ACLs associated with the DATA command, that is, the ACLs defined by | |
10636 | &%acl_smtp_predata%& and &%acl_smtp_data%&. | |
10637 | .endlist | |
168e428f | 10638 | |
168e428f | 10639 | |
9b371988 PH |
10640 | .vitem &$recipients_count$& |
10641 | .cindex "&$recipients_count$&" | |
068aaea8 PH |
10642 | When a message is being processed, this variable contains the number of |
10643 | envelope recipients that came with the message. Duplicates are not excluded | |
10644 | from the count. While a message is being received over SMTP, the number | |
10645 | increases for each accepted recipient. It can be referenced in an ACL. | |
168e428f | 10646 | |
9b371988 PH |
10647 | .vitem &$reply_address$& |
10648 | .cindex "&$reply_address$&" | |
068aaea8 | 10649 | When a message is being processed, this variable contains the contents of the |
9b371988 PH |
10650 | &'Reply-To:'& header line if one exists and it is not empty, or otherwise the |
10651 | contents of the &'From:'& header line. | |
168e428f | 10652 | |
9b371988 PH |
10653 | .vitem &$return_path$& |
10654 | .cindex "&$return_path$&" | |
10655 | When a message is being delivered, this variable contains the return path &-- | |
168e428f | 10656 | the sender field that will be sent as part of the envelope. It is not enclosed |
9b371988 PH |
10657 | in <> characters. At the start of routing an address, &$return_path$& has the |
10658 | same value as &$sender_address$&, but if, for example, an incoming message to a | |
168e428f | 10659 | mailing list has been expanded by a router which specifies a different address |
9b371988 PH |
10660 | for bounce messages, &$return_path$& subsequently contains the new bounce |
10661 | address, whereas &$sender_address$& always contains the original sender address | |
10662 | that was received with the message. In other words, &$sender_address$& contains | |
10663 | the incoming envelope sender, and &$return_path$& contains the outgoing | |
10664 | envelope sender. | |
10665 | ||
10666 | .vitem &$return_size_limit$& | |
10667 | .cindex "&$return_size_limit$&" | |
10668 | This is an obsolete name for &$bounce_return_size_limit$&. | |
10669 | ||
10670 | .vitem &$runrc$& | |
10671 | .cindex "return code" "from &%run%& expansion" | |
10672 | .cindex "&$runrc$&" | |
168e428f | 10673 | This variable contains the return code from a command that is run by the |
9b371988 | 10674 | &%${run...}%& expansion item. &*Warning*&: In a router or transport, you cannot |
168e428f | 10675 | assume the order in which option values are expanded, except for those |
9b371988 PH |
10676 | preconditions whose order of testing is documented. Therefore, you cannot |
10677 | reliably expect to set &$runrc$& by the expansion of one option, and use it in | |
168e428f PH |
10678 | another. |
10679 | ||
9b371988 PH |
10680 | .vitem &$self_hostname$& |
10681 | .cindex "&%self%& option" "value of host name" | |
10682 | .cindex "&$self_hostname$&" | |
068aaea8 | 10683 | When an address is routed to a supposedly remote host that turns out to be the |
9b371988 PH |
10684 | local host, what happens is controlled by the &%self%& generic router option. |
10685 | One of its values causes the address to be passed to another router. When this | |
10686 | happens, &$self_hostname$& is set to the name of the local host that the | |
10687 | original router encountered. In other circumstances its contents are null. | |
168e428f | 10688 | |
9b371988 PH |
10689 | .vitem &$sender_address$& |
10690 | .cindex "&$sender_address$&" | |
068aaea8 PH |
10691 | When a message is being processed, this variable contains the sender's address |
10692 | that was received in the message's envelope. For bounce messages, the value of | |
9b371988 | 10693 | this variable is the empty string. See also &$return_path$&. |
168e428f | 10694 | |
9b371988 PH |
10695 | .vitem &$sender_address_data$& |
10696 | .cindex "&$address_data$&" | |
10697 | .cindex "&$sender_address_data$&" | |
10698 | If &$address_data$& is set when the routers are called from an ACL to verify a | |
10699 | sender address, the final value is preserved in &$sender_address_data$&, to | |
168e428f PH |
10700 | distinguish it from data from a recipient address. The value does not persist |
10701 | after the end of the current ACL statement. If you want to preserve it for | |
10702 | longer, you can save it in an ACL variable. | |
10703 | ||
9b371988 PH |
10704 | .vitem &$sender_address_domain$& |
10705 | .cindex "&$sender_address_domain$&" | |
10706 | The domain portion of &$sender_address$&. | |
10707 | ||
10708 | .vitem &$sender_address_local_part$& | |
10709 | .cindex "&$sender_address_local_part$&" | |
10710 | The local part portion of &$sender_address$&. | |
10711 | ||
10712 | .vitem &$sender_data$& | |
10713 | .cindex "&$sender_data$&" | |
10714 | This variable is set after a lookup success in an ACL &%senders%& condition or | |
10715 | in a router &%senders%& option. It contains the data from the lookup, and the | |
10716 | value remains set until the next &%senders%& test. Thus, you can do things like | |
10717 | this: | |
10718 | .display | |
10719 | &`require senders = cdb*@;/some/file`& | |
10720 | &`deny `&&'some further test involving'& &`$sender_data`& | |
10721 | .endd | |
10722 | &*Warning*&: This variable is set only when a lookup is used as an indexing | |
168e428f PH |
10723 | method in the address list, using the semicolon syntax as in the example above. |
10724 | The variable is not set for a lookup that is used as part of the string | |
10725 | expansion that all such lists undergo before being interpreted. | |
10726 | ||
9b371988 PH |
10727 | .vitem &$sender_fullhost$& |
10728 | .cindex "&$sender_fullhost$&" | |
168e428f PH |
10729 | When a message is received from a remote host, this variable contains the host |
10730 | name and IP address in a single string. It ends with the IP address in square | |
10731 | brackets, followed by a colon and a port number if the logging of ports is | |
10732 | enabled. The format of the rest of the string depends on whether the host | |
10733 | issued a HELO or EHLO SMTP command, and whether the host name was verified by | |
10734 | looking up its IP address. (Looking up the IP address can be forced by the | |
9b371988 | 10735 | &%host_lookup%& option, independent of verification.) A plain host name at the |
168e428f PH |
10736 | start of the string is a verified host name; if this is not present, |
10737 | verification either failed or was not requested. A host name in parentheses is | |
10738 | the argument of a HELO or EHLO command. This is omitted if it is identical to | |
10739 | the verified host name or to the host's IP address in square brackets. | |
10740 | ||
9b371988 PH |
10741 | .vitem &$sender_helo_name$& |
10742 | .cindex "&$sender_hslo_name$&" | |
068aaea8 PH |
10743 | When a message is received from a remote host that has issued a HELO or EHLO |
10744 | command, the argument of that command is placed in this variable. It is also | |
10745 | set if HELO or EHLO is used when a message is received using SMTP locally via | |
9b371988 | 10746 | the &%-bs%& or &%-bS%& options. |
168e428f | 10747 | |
9b371988 PH |
10748 | .vitem &$sender_host_address$& |
10749 | .cindex "&$sender_host_address$&" | |
068aaea8 PH |
10750 | When a message is received from a remote host, this variable contains that |
10751 | host's IP address. For locally submitted messages, it is empty. | |
168e428f | 10752 | |
9b371988 PH |
10753 | .vitem &$sender_host_authenticated$& |
10754 | .cindex "&$sender_host_authenticated$&" | |
168e428f | 10755 | This variable contains the name (not the public name) of the authenticator |
068aaea8 PH |
10756 | driver that successfully authenticated the client from which the message was |
10757 | received. It is empty if there was no successful authentication. See also | |
9b371988 | 10758 | &$authenticated_id$&. |
168e428f | 10759 | |
9b371988 PH |
10760 | .vitem &$sender_host_name$& |
10761 | .cindex "&$sender_host_name$&" | |
168e428f PH |
10762 | When a message is received from a remote host, this variable contains the |
10763 | host's name as obtained by looking up its IP address. For messages received by | |
10764 | other means, this variable is empty. | |
9b371988 PH |
10765 | |
10766 | .cindex "&$host_lookup_failed$&" | |
168e428f | 10767 | If the host name has not previously been looked up, a reference to |
9b371988 | 10768 | &$sender_host_name$& triggers a lookup (for messages from remote hosts). |
168e428f PH |
10769 | A looked up name is accepted only if it leads back to the original IP address |
10770 | via a forward lookup. If either the reverse or the forward lookup fails to find | |
10771 | any data, or if the forward lookup does not yield the original IP address, | |
9b371988 PH |
10772 | &$sender_host_name$& remains empty, and &$host_lookup_failed$& is set to &"1"&. |
10773 | ||
10774 | .cindex "&$host_lookup_deferred$&" | |
168e428f | 10775 | However, if either of the lookups cannot be completed (for example, there is a |
9b371988 PH |
10776 | DNS timeout), &$host_lookup_deferred$& is set to &"1"&, and |
10777 | &$host_lookup_failed$& remains set to &"0"&. | |
10778 | ||
10779 | Once &$host_lookup_failed$& is set to &"1"&, Exim does not try to look up the | |
10780 | host name again if there is a subsequent reference to &$sender_host_name$& | |
10781 | in the same Exim process, but it does try again if &$sender_host_deferred$& | |
10782 | is set to &"1"&. | |
10783 | ||
168e428f PH |
10784 | Exim does not automatically look up every calling host's name. If you want |
10785 | maximum efficiency, you should arrange your configuration so that it avoids | |
10786 | these lookups altogether. The lookup happens only if one or more of the | |
10787 | following are true: | |
10788 | ||
9b371988 PH |
10789 | .ilist |
10790 | A string containing &$sender_host_name$& is expanded. | |
10791 | .next | |
10792 | The calling host matches the list in &%host_lookup%&. In the default | |
10793 | configuration, this option is set to *, so it must be changed if lookups are | |
10794 | to be avoided. (In the code, the default for &%host_lookup%& is unset.) | |
10795 | .next | |
10796 | Exim needs the host name in order to test an item in a host list. The items | |
10797 | that require this are described in sections &<<SECThoslispatnam>>& and | |
10798 | &<<SECThoslispatnamsk>>&. | |
10799 | .next | |
10800 | The calling host matches &%helo_try_verify_hosts%& or &%helo_verify_hosts%&. | |
168e428f PH |
10801 | In this case, the host name is required to compare with the name quoted in any |
10802 | EHLO or HELO commands that the client issues. | |
9b371988 PH |
10803 | .next |
10804 | The remote host issues a EHLO or HELO command that quotes one of the | |
10805 | domains in &%helo_lookup_domains%&. The default value of this option is | |
10806 | . ==== As this is a nested list, any displays it contains must be indented | |
10807 | . ==== as otherwise they are too far to the left. | |
10808 | .code | |
10809 | helo_lookup_domains = @ : @[] | |
10810 | .endd | |
168e428f PH |
10811 | which causes a lookup if a remote host (incorrectly) gives the server's name or |
10812 | IP address in an EHLO or HELO command. | |
9b371988 | 10813 | .endlist |
168e428f PH |
10814 | |
10815 | ||
9b371988 PH |
10816 | .vitem &$sender_host_port$& |
10817 | .cindex "&$sender_host_port$&" | |
068aaea8 PH |
10818 | When a message is received from a remote host, this variable contains the port |
10819 | number that was used on the remote host. | |
168e428f | 10820 | |
9b371988 PH |
10821 | .vitem &$sender_ident$& |
10822 | .cindex "&$sender_ident$&" | |
168e428f PH |
10823 | When a message is received from a remote host, this variable contains the |
10824 | identification received in response to an RFC 1413 request. When a message has | |
10825 | been received locally, this variable contains the login name of the user that | |
10826 | called Exim. | |
10827 | ||
9b371988 PH |
10828 | .new |
10829 | .vitem &$sender_rate_$&&'xxx'& | |
10830 | A number of variables whose names begin &$sender_rate_$& are set as part of the | |
10831 | &%ratelimit%& ACL condition. Details are given in section | |
10832 | &<<SECTratelimiting>>&. | |
10833 | .wen | |
10834 | ||
10835 | .vitem &$sender_rcvhost$& | |
10836 | .cindex "DNS" "reverse lookup" | |
10837 | .cindex "reverse DNS lookup" | |
10838 | .cindex "&$sender_rcvhost$&" | |
10839 | This is provided specifically for use in &'Received:'& headers. It starts with | |
068aaea8 PH |
10840 | either the verified host name (as obtained from a reverse DNS lookup) or, if |
10841 | there is no verified host name, the IP address in square brackets. After that | |
10842 | there may be text in parentheses. When the first item is a verified host name, | |
10843 | the first thing in the parentheses is the IP address in square brackets, | |
10844 | followed by a colon and a port number if port logging is enabled. When the | |
9b371988 | 10845 | first item is an IP address, the port is recorded as &"port=&'xxxx'&"& inside |
068aaea8 | 10846 | the parentheses. |
9b371988 PH |
10847 | |
10848 | There may also be items of the form &"helo=&'xxxx'&"& if HELO or EHLO | |
168e428f | 10849 | was used and its argument was not identical to the real host name or IP |
9b371988 PH |
10850 | address, and &"ident=&'xxxx'&"& if an RFC 1413 ident string is available. If |
10851 | all three items are present in the parentheses, a newline and tab are inserted | |
10852 | into the string, to improve the formatting of the &'Received:'& header. | |
168e428f | 10853 | |
9b371988 PH |
10854 | .vitem &$sender_verify_failure$& |
10855 | .cindex "&$sender_verify_failure$&" | |
168e428f | 10856 | In an ACL, when a sender verification fails, this variable contains information |
9b371988 PH |
10857 | about the failure. The details are the same as for |
10858 | &$recipient_verify_failure$&. | |
168e428f | 10859 | |
9b371988 PH |
10860 | .vitem &$smtp_active_hostname$& |
10861 | .cindex "&$smtp_active_hostname$&" | |
168e428f | 10862 | During an SMTP session, this variable contains the value of the active host |
9b371988 PH |
10863 | name, as specified by the &%smtp_active_hostname%& option. The value of |
10864 | &$smtp_active_hostname$& is saved with any message that is received, so its | |
10865 | value can be consulted during routing and delivery. | |
10866 | ||
10867 | .new | |
10868 | .vitem &$smtp_command$& | |
10869 | .cindex "&$smtp_command$&" | |
068aaea8 PH |
10870 | During the processing of an incoming SMTP command, this variable contains the |
10871 | entire command. This makes it possible to distinguish between HELO and EHLO in | |
10872 | the HELO ACL, and also to distinguish between commands such as these: | |
9b371988 | 10873 | .code |
068aaea8 PH |
10874 | MAIL FROM:<> |
10875 | MAIL FROM: <> | |
9b371988 | 10876 | .endd |
068aaea8 | 10877 | For a MAIL command, extra parameters such as SIZE can be inspected. For a RCPT |
9b371988 PH |
10878 | command, the address in &$smtp_command$& is the original address before any |
10879 | rewriting, whereas the values in &$local_part$& and &$domain$& are taken from | |
10880 | the address after SMTP-time rewriting. | |
10881 | .wen | |
10882 | ||
10883 | .vitem &$smtp_command_argument$& | |
10884 | .new | |
10885 | .cindex "SMTP command" "argument for" | |
10886 | .cindex "&$smtp_command_argument$&" | |
068aaea8 PH |
10887 | While an ACL is running to check an SMTP command, this variable contains the |
10888 | argument, that is, the text that follows the command name, with leading white | |
9b371988 | 10889 | space removed. Following the introduction of &$smtp_command$&, this variable is |
068aaea8 | 10890 | somewhat redundant, but is retained for backwards compatibility. |
9b371988 | 10891 | .wen |
168e428f | 10892 | |
9b371988 PH |
10893 | .vitem "&$sn0$& &-- &$sn9$&" |
10894 | These variables are copies of the values of the &$n0$& &-- &$n9$& accumulators | |
10895 | that were current at the end of the system filter file. This allows a system | |
10896 | filter file to set values that can be tested in users' filter files. For | |
10897 | example, a system filter could set a value indicating how likely it is that a | |
10898 | message is junk mail. | |
168e428f | 10899 | |
9b371988 PH |
10900 | .vitem &$spam_$&&'xxx'& |
10901 | A number of variables whose names start with &$spam$& are available when Exim | |
10902 | is compiled with the content-scanning extension. For details, see section | |
10903 | &<<SECTscanspamass>>&. | |
168e428f PH |
10904 | |
10905 | ||
9b371988 PH |
10906 | .vitem &$spool_directory$& |
10907 | .cindex "&$spool_directory$&" | |
168e428f PH |
10908 | The name of Exim's spool directory. |
10909 | ||
9b371988 PH |
10910 | .vitem &$spool_inodes$& |
10911 | .cindex "&$spool_inodes$&" | |
168e428f PH |
10912 | The number of free inodes in the disk partition where Exim's spool files are |
10913 | being written. The value is recalculated whenever the variable is referenced. | |
10914 | If the relevant file system does not have the concept of inodes, the value of | |
9b371988 | 10915 | is -1. See also the &%check_spool_inodes%& option. |
168e428f | 10916 | |
9b371988 PH |
10917 | .vitem &$spool_space$& |
10918 | .cindex "&$spool_space$&" | |
168e428f PH |
10919 | The amount of free space (as a number of kilobytes) in the disk partition where |
10920 | Exim's spool files are being written. The value is recalculated whenever the | |
10921 | variable is referenced. If the operating system does not have the ability to | |
10922 | find the amount of free space (only true for experimental systems), the space | |
10923 | value is -1. For example, to check in an ACL that there is at least 50 | |
10924 | megabytes free on the spool, you could write: | |
9b371988 PH |
10925 | .code |
10926 | condition = ${if > {$spool_space}{50000}} | |
10927 | .endd | |
10928 | See also the &%check_spool_space%& option. | |
10929 | ||
10930 | ||
10931 | .vitem &$thisaddress$& | |
10932 | .cindex "&$thisaddress$&" | |
10933 | This variable is set only during the processing of the &%foranyaddress%& | |
10934 | command in a filter file. Its use is explained in the description of that | |
10935 | command, which can be found in the separate document entitled &'Exim's | |
10936 | interfaces to mail filtering'&. | |
10937 | ||
10938 | .vitem &$tls_certificate_verified$& | |
10939 | .cindex "&$tls_certificate_verified$&" | |
10940 | This variable is set to &"1"& if a TLS certificate was verified when the | |
10941 | message was received, and &"0"& otherwise. | |
10942 | ||
10943 | .vitem &$tls_cipher$& | |
10944 | .cindex "&$tls_cipher$&" | |
168e428f PH |
10945 | When a message is received from a remote host over an encrypted SMTP |
10946 | connection, this variable is set to the cipher suite that was negotiated, for | |
10947 | example DES-CBC3-SHA. In other circumstances, in particular, for message | |
10948 | received over unencrypted connections, the variable is empty. See chapter | |
9b371988 | 10949 | &<<CHAPTLS>>& for details of TLS support. |
168e428f | 10950 | |
9b371988 PH |
10951 | .vitem &$tls_peerdn$& |
10952 | .cindex "&$tls_peerdn$&" | |
068aaea8 | 10953 | When a message is received from a remote host over an encrypted SMTP |
168e428f PH |
10954 | connection, and Exim is configured to request a certificate from the client, |
10955 | the value of the Distinguished Name of the certificate is made available in the | |
9b371988 | 10956 | &$tls_peerdn$& during subsequent processing. |
168e428f | 10957 | |
9b371988 PH |
10958 | .vitem &$tod_bsdinbox$& |
10959 | .cindex "&$tod_bsdinbox$&" | |
10960 | The time of day and the date, in the format required for BSD-style mailbox | |
10961 | files, for example: Thu Oct 17 17:14:09 1995. | |
168e428f | 10962 | |
9b371988 PH |
10963 | .vitem &$tod_epoch$& |
10964 | .cindex "&$tod_epoch$&" | |
168e428f PH |
10965 | The time and date as a number of seconds since the start of the Unix epoch. |
10966 | ||
9b371988 PH |
10967 | .vitem &$tod_full$& |
10968 | .cindex "&$tod_full$&" | |
168e428f PH |
10969 | A full version of the time and date, for example: Wed, 16 Oct 1995 09:51:40 |
10970 | +0100. The timezone is always given as a numerical offset from UTC, with | |
10971 | positive values used for timezones that are ahead (east) of UTC, and negative | |
10972 | values for those that are behind (west). | |
10973 | ||
9b371988 PH |
10974 | .vitem &$tod_log$& |
10975 | .cindex "&$tod_log$&" | |
168e428f PH |
10976 | The time and date in the format used for writing Exim's log files, for example: |
10977 | 1995-10-12 15:32:29, but without a timezone. | |
10978 | ||
9b371988 PH |
10979 | .vitem &$tod_logfile$& |
10980 | .cindex "&$tod_logfile$&" | |
168e428f | 10981 | This variable contains the date in the format yyyymmdd. This is the format that |
9b371988 | 10982 | is used for datestamping log files when &%log_file_path%& contains the &`%D`& |
168e428f PH |
10983 | flag. |
10984 | ||
9b371988 PH |
10985 | .vitem &$tod_zone$& |
10986 | .cindex "&$tod_zone$&" | |
168e428f PH |
10987 | This variable contains the numerical value of the local timezone, for example: |
10988 | -0500. | |
10989 | ||
9b371988 PH |
10990 | .vitem &$tod_zulu$& |
10991 | .cindex "&$tod_zulu$&" | |
10992 | This variable contains the UTC date and time in &"Zulu"& format, as specified | |
10993 | by ISO 8601, for example: 20030221154023Z. | |
168e428f | 10994 | |
9b371988 PH |
10995 | .vitem &$value$& |
10996 | .cindex "&$value$&" | |
168e428f PH |
10997 | This variable contains the result of an expansion lookup, extraction operation, |
10998 | or external command, as described above. | |
10999 | ||
9b371988 PH |
11000 | .vitem &$version_number$& |
11001 | .cindex "&$version_number$&" | |
168e428f PH |
11002 | The version number of Exim. |
11003 | ||
9b371988 PH |
11004 | .vitem &$warn_message_delay$& |
11005 | .cindex "&$warn_message_delay$&" | |
168e428f | 11006 | This variable is set only during the creation of a message warning about a |
9b371988 | 11007 | delivery delay. Details of its use are explained in section &<<SECTcustwarn>>&. |
168e428f | 11008 | |
9b371988 PH |
11009 | .vitem &$warn_message_recipients$& |
11010 | .cindex "&$warn_message_recipients$&" | |
168e428f | 11011 | This variable is set only during the creation of a message warning about a |
9b371988 PH |
11012 | delivery delay. Details of its use are explained in section &<<SECTcustwarn>>&. |
11013 | .endlist | |
168e428f PH |
11014 | |
11015 | ||
11016 | ||
9b371988 PH |
11017 | . //////////////////////////////////////////////////////////////////////////// |
11018 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 11019 | |
9b371988 PH |
11020 | .chapter "Embedded Perl" "CHAPperl" |
11021 | .cindex "Perl" "calling from Exim" | |
168e428f PH |
11022 | Exim can be built to include an embedded Perl interpreter. When this is done, |
11023 | Perl subroutines can be called as part of the string expansion process. To make | |
11024 | use of the Perl support, you need version 5.004 or later of Perl installed on | |
11025 | your system. To include the embedded interpreter in the Exim binary, include | |
11026 | the line | |
9b371988 PH |
11027 | .code |
11028 | EXIM_PERL = perl.o | |
11029 | .endd | |
11030 | in your &_Local/Makefile_& and then build Exim in the normal way. | |
168e428f PH |
11031 | |
11032 | ||
9b371988 PH |
11033 | .section "Setting up so Perl can be used" |
11034 | .cindex "&%perl_startup%&" | |
168e428f | 11035 | Access to Perl subroutines is via a global configuration option called |
9b371988 PH |
11036 | &%perl_startup%& and an expansion string operator &%${perl ...}%&. If there is |
11037 | no &%perl_startup%& option in the Exim configuration file then no Perl | |
168e428f | 11038 | interpreter is started and there is almost no overhead for Exim (since none of |
9b371988 | 11039 | the Perl library will be paged in unless used). If there is a &%perl_startup%& |
168e428f PH |
11040 | option then the associated value is taken to be Perl code which is executed in |
11041 | a newly created Perl interpreter. | |
11042 | ||
9b371988 | 11043 | The value of &%perl_startup%& is not expanded in the Exim sense, so you do not |
168e428f PH |
11044 | need backslashes before any characters to escape special meanings. The option |
11045 | should usually be something like | |
9b371988 PH |
11046 | .code |
11047 | perl_startup = do '/etc/exim.pl' | |
11048 | .endd | |
11049 | where &_/etc/exim.pl_& is Perl code which defines any subroutines you want to | |
168e428f PH |
11050 | use from Exim. Exim can be configured either to start up a Perl interpreter as |
11051 | soon as it is entered, or to wait until the first time it is needed. Starting | |
11052 | the interpreter at the beginning ensures that it is done while Exim still has | |
11053 | its setuid privilege, but can impose an unnecessary overhead if Perl is not in | |
11054 | fact used in a particular run. Also, note that this does not mean that Exim is | |
11055 | necessarily running as root when Perl is called at a later time. By default, | |
11056 | the interpreter is started only when it is needed, but this can be changed in | |
11057 | two ways: | |
11058 | ||
9b371988 PH |
11059 | .ilist |
11060 | .cindex "&%perl_at_start%&" | |
11061 | Setting &%perl_at_start%& (a boolean option) in the configuration requests | |
168e428f | 11062 | a startup when Exim is entered. |
9b371988 PH |
11063 | .next |
11064 | The command line option &%-ps%& also requests a startup when Exim is entered, | |
11065 | overriding the setting of &%perl_at_start%&. | |
11066 | .endlist | |
168e428f | 11067 | |
9b371988 PH |
11068 | There is also a command line option &%-pd%& (for delay) which suppresses the |
11069 | initial startup, even if &%perl_at_start%& is set. | |
168e428f | 11070 | |
168e428f | 11071 | |
9b371988 PH |
11072 | .section "Calling Perl subroutines" |
11073 | When the configuration file includes a &%perl_startup%& option you can make use | |
168e428f | 11074 | of the string expansion item to call the Perl subroutines that are defined |
9b371988 | 11075 | by the &%perl_startup%& code. The operator is used in any of the following |
168e428f | 11076 | forms: |
9b371988 PH |
11077 | .code |
11078 | ${perl{foo}} | |
11079 | ${perl{foo}{argument}} | |
11080 | ${perl{foo}{argument1}{argument2} ... } | |
11081 | .endd | |
11082 | which calls the subroutine &%foo%& with the given arguments. A maximum of eight | |
168e428f PH |
11083 | arguments may be passed. Passing more than this results in an expansion failure |
11084 | with an error message of the form | |
9b371988 PH |
11085 | .code |
11086 | Too many arguments passed to Perl subroutine "foo" (max is 8) | |
11087 | .endd | |
168e428f PH |
11088 | The return value of the Perl subroutine is evaluated in a scalar context before |
11089 | it is passed back to Exim to be inserted into the expanded string. If the | |
9b371988 PH |
11090 | return value is &'undef'&, the expansion is forced to fail in the same way as |
11091 | an explicit &"fail"& on an &%if%& or &%lookup%& item. If the subroutine aborts | |
11092 | by obeying Perl's &%die%& function, the expansion fails with the error message | |
11093 | that was passed to &%die%&. | |
168e428f PH |
11094 | |
11095 | ||
9b371988 PH |
11096 | .section "Calling Exim functions from Perl" |
11097 | Within any Perl code called from Exim, the function &'Exim::expand_string()'& | |
168e428f PH |
11098 | is available to call back into Exim's string expansion function. For example, |
11099 | the Perl code | |
9b371988 PH |
11100 | .code |
11101 | my $lp = Exim::expand_string('$local_part'); | |
11102 | .endd | |
11103 | makes the current Exim &$local_part$& available in the Perl variable &$lp$&. | |
168e428f | 11104 | Note those are single quotes and not double quotes to protect against |
9b371988 | 11105 | &$local_part$& being interpolated as a Perl variable. |
168e428f | 11106 | |
9b371988 PH |
11107 | If the string expansion is forced to fail by a &"fail"& item, the result of |
11108 | &'Exim::expand_string()'& is &%undef%&. If there is a syntax error in the | |
168e428f | 11109 | expansion string, the Perl call from the original expansion string fails with |
9b371988 | 11110 | an appropriate error message, in the same way as if &%die%& were used. |
168e428f | 11111 | |
9b371988 PH |
11112 | .cindex "debugging" "from embedded Perl" |
11113 | .cindex "log" "writing from embedded Perl" | |
168e428f | 11114 | Two other Exim functions are available for use from within Perl code. |
9b371988 PH |
11115 | &'Exim::debug_write()'& writes a string to the standard error stream if Exim's |
11116 | debugging is enabled. If you want a newline at the end, you must supply it. | |
11117 | &'Exim::log_write()'& writes a string to Exim's main log, adding a leading | |
11118 | timestamp. In this case, you should not supply a terminating newline. | |
168e428f PH |
11119 | |
11120 | ||
9b371988 PH |
11121 | .section "Use of standard output and error by Perl" |
11122 | .cindex "Perl" "standard output and error" | |
168e428f PH |
11123 | You should not write to the standard error or output streams from within your |
11124 | Perl code, as it is not defined how these are set up. In versions of Exim | |
11125 | before 4.50, it is possible for the standard output or error to refer to the | |
11126 | SMTP connection during message reception via the daemon. Writing to this stream | |
11127 | is certain to cause chaos. From Exim 4.50 onwards, the standard output and | |
9b371988 | 11128 | error streams are connected to &_/dev/null_& in the daemon. The chaos is |
168e428f PH |
11129 | avoided, but the output is lost. |
11130 | ||
9b371988 PH |
11131 | .cindex "Perl" "use of &%warn%&" |
11132 | The Perl &%warn%& statement writes to the standard error stream by default. | |
11133 | Calls to &%warn%& may be embedded in Perl modules that you use, but over which | |
11134 | you have no control. When Exim starts up the Perl interpreter, it arranges for | |
11135 | output from the &%warn%& statement to be written to the Exim main log. You can | |
11136 | change this by including appropriate Perl magic somewhere in your Perl code. | |
11137 | For example, to discard &%warn%& output completely, you need this: | |
11138 | .code | |
11139 | $SIG{__WARN__} = sub { }; | |
11140 | .endd | |
11141 | Whenever a &%warn%& is obeyed, the anonymous subroutine is called. In this | |
168e428f | 11142 | example, the code for the subroutine is empty, so it does nothing, but you can |
9b371988 | 11143 | include any Perl code that you like. The text of the &%warn%& message is passed |
168e428f PH |
11144 | as the first subroutine argument. |
11145 | ||
11146 | ||
11147 | ||
9b371988 PH |
11148 | . //////////////////////////////////////////////////////////////////////////// |
11149 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 11150 | |
9b371988 PH |
11151 | .chapter "Starting the daemon and the use of network interfaces" &&& |
11152 | "CHAPinterfaces" &&& | |
11153 | "Starting the daemon" | |
11154 | .cindex "daemon" "starting" | |
11155 | .cindex "interface" "listening" | |
11156 | .cindex "network interface" | |
11157 | .cindex "interface" "network" | |
11158 | .cindex "IP address" "for listening" | |
11159 | .cindex "daemon" "listening IP addresses" | |
11160 | .cindex "TCP/IP" "setting listening interfaces" | |
11161 | .cindex "TCP/IP" "setting listening ports" | |
168e428f PH |
11162 | A host that is connected to a TCP/IP network may have one or more physical |
11163 | hardware network interfaces. Each of these interfaces may be configured as one | |
9b371988 | 11164 | or more &"logical"& interfaces, which are the entities that a program actually |
168e428f | 11165 | works with. Each of these logical interfaces is associated with an IP address. |
9b371988 PH |
11166 | In addition, TCP/IP software supports &"loopback"& interfaces (127.0.0.1 in |
11167 | IPv4 and ::1 in IPv6), which do not use any physical hardware. Exim requires | |
168e428f PH |
11168 | knowledge about the host's interfaces for use in three different circumstances: |
11169 | ||
9b371988 PH |
11170 | .olist |
11171 | When a listening daemon is started, Exim needs to know which interfaces | |
168e428f | 11172 | and ports to listen on. |
9b371988 PH |
11173 | .next |
11174 | When Exim is routing an address, it needs to know which IP addresses | |
168e428f PH |
11175 | are associated with local interfaces. This is required for the correct |
11176 | processing of MX lists by removing the local host and others with the | |
11177 | same or higher priority values. Also, Exim needs to detect cases | |
11178 | when an address is routed to an IP address that in fact belongs to the | |
9b371988 | 11179 | local host. Unless the &%self%& router option or the &%allow_localhost%& |
168e428f PH |
11180 | option of the smtp transport is set (as appropriate), this is treated |
11181 | as an error situation. | |
9b371988 PH |
11182 | .next |
11183 | When Exim connects to a remote host, it may need to know which interface to use | |
168e428f | 11184 | for the outgoing connection. |
9b371988 | 11185 | .endlist |
168e428f PH |
11186 | |
11187 | ||
11188 | Exim's default behaviour is likely to be appropriate in the vast majority | |
11189 | of cases. If your host has only one interface, and you want all its IP | |
11190 | addresses to be treated in the same way, and you are using only the | |
11191 | standard SMTP port, you should not need to take any special action. The | |
11192 | rest of this chapter does not apply to you. | |
11193 | ||
11194 | In a more complicated situation you may want to listen only on certain | |
11195 | interfaces, or on different ports, and for this reason there are a number of | |
11196 | options that can be used to influence Exim's behaviour. The rest of this | |
11197 | chapter describes how they operate. | |
11198 | ||
11199 | When a message is received over TCP/IP, the interface and port that were | |
9b371988 | 11200 | actually used are set in &$interface_address$& and &$interface_port$&. |
168e428f PH |
11201 | |
11202 | ||
11203 | ||
9b371988 PH |
11204 | .section "Starting a listening daemon" |
11205 | When a listening daemon is started (by means of the &%-bd%& command line | |
168e428f PH |
11206 | option), the interfaces and ports on which it listens are controlled by the |
11207 | following options: | |
11208 | ||
9b371988 PH |
11209 | .ilist |
11210 | &%daemon_smtp_ports%& contains a list of default ports. (For backward | |
168e428f | 11211 | compatibility, this option can also be specified in the singular.) |
9b371988 PH |
11212 | .next |
11213 | &%local_interfaces%& contains list of interface IP addresses on which to | |
168e428f | 11214 | listen. Each item may optionally also specify a port. |
9b371988 | 11215 | .endlist |
168e428f PH |
11216 | |
11217 | The default list separator in both cases is a colon, but this can be changed as | |
9b371988 PH |
11218 | described in section &<<SECTlistconstruct>>&. When IPv6 addresses are involved, |
11219 | it is usually best to change the separator to avoid having to double all the | |
168e428f | 11220 | colons. For example: |
9b371988 | 11221 | .code |
168e428f PH |
11222 | local_interfaces = <; 127.0.0.1 ; \ |
11223 | 192.168.23.65 ; \ | |
11224 | ::1 ; \ | |
11225 | 3ffe:ffff:836f::fe86:a061 | |
9b371988 | 11226 | .endd |
168e428f | 11227 | There are two different formats for specifying a port along with an IP address |
9b371988 | 11228 | in &%local_interfaces%&: |
168e428f | 11229 | |
9b371988 PH |
11230 | .olist |
11231 | The port is added onto the address with a dot separator. For example, to listen | |
168e428f | 11232 | on port 1234 on two different IP addresses: |
9b371988 | 11233 | .code |
168e428f PH |
11234 | local_interfaces = <; 192.168.23.65.1234 ; \ |
11235 | 3ffe:ffff:836f::fe86:a061.1234 | |
9b371988 PH |
11236 | .endd |
11237 | .next | |
11238 | The IP address is enclosed in square brackets, and the port is added | |
168e428f | 11239 | with a colon separator, for example: |
9b371988 | 11240 | .code |
168e428f PH |
11241 | local_interfaces = <; [192.168.23.65]:1234 ; \ |
11242 | [3ffe:ffff:836f::fe86:a061]:1234 | |
9b371988 PH |
11243 | .endd |
11244 | .endlist | |
168e428f | 11245 | |
9b371988 | 11246 | When a port is not specified, the value of &%daemon_smtp_ports%& is used. The |
168e428f | 11247 | default setting contains just one port: |
9b371988 PH |
11248 | .code |
11249 | daemon_smtp_ports = smtp | |
11250 | .endd | |
168e428f PH |
11251 | If more than one port is listed, each interface that does not have its own port |
11252 | specified listens on all of them. Ports that are listed in | |
9b371988 PH |
11253 | &%daemon_smtp_ports%& can be identified either by name (defined in |
11254 | &_/etc/services_&) or by number. However, when ports are given with individual | |
11255 | IP addresses in &%local_interfaces%&, only numbers (not names) can be used. | |
168e428f PH |
11256 | |
11257 | ||
11258 | ||
9b371988 | 11259 | .section "Special IP listening addresses" |
168e428f | 11260 | The addresses 0.0.0.0 and ::0 are treated specially. They are interpreted |
9b371988 PH |
11261 | as &"all IPv4 interfaces"& and &"all IPv6 interfaces"&, respectively. In each |
11262 | case, Exim tells the TCP/IP stack to &"listen on all IPv&'x'& interfaces"& | |
168e428f | 11263 | instead of setting up separate listening sockets for each interface. The |
9b371988 PH |
11264 | default value of &%local_interfaces%& is |
11265 | .code | |
11266 | local_interfaces = 0.0.0.0 | |
11267 | .endd | |
168e428f | 11268 | when Exim is built without IPv6 support; otherwise it is: |
9b371988 PH |
11269 | .code |
11270 | local_interfaces = <; ::0 ; 0.0.0.0 | |
11271 | .endd | |
168e428f PH |
11272 | Thus, by default, Exim listens on all available interfaces, on the SMTP port. |
11273 | ||
11274 | ||
11275 | ||
9b371988 PH |
11276 | .section "Overriding local_interfaces and daemon_smtp_ports" |
11277 | The &%-oX%& command line option can be used to override the values of | |
11278 | &%daemon_smtp_ports%& and/or &%local_interfaces%& for a particular daemon | |
11279 | instance. Another way of doing this would be to use macros and the &%-D%& | |
11280 | option. However, &%-oX%& can be used by any admin user, whereas modification of | |
11281 | the runtime configuration by &%-D%& is allowed only when the caller is root or | |
168e428f PH |
11282 | exim. |
11283 | ||
9b371988 | 11284 | The value of &%-oX%& is a list of items. The default colon separator can be |
168e428f PH |
11285 | changed in the usual way if required. If there are any items that do not |
11286 | contain dots or colons (that is, are not IP addresses), the value of | |
9b371988 PH |
11287 | &%daemon_smtp_ports%& is replaced by the list of those items. If there are any |
11288 | items that do contain dots or colons, the value of &%local_interfaces%& is | |
168e428f | 11289 | replaced by those items. Thus, for example, |
9b371988 PH |
11290 | .code |
11291 | -oX 1225 | |
11292 | .endd | |
11293 | overrides &%daemon_smtp_ports%&, but leaves &%local_interfaces%& unchanged, | |
168e428f | 11294 | whereas |
9b371988 PH |
11295 | .code |
11296 | -oX 192.168.34.5.1125 | |
11297 | .endd | |
11298 | overrides &%local_interfaces%&, leaving &%daemon_smtp_ports%& unchanged. | |
11299 | (However, since &%local_interfaces%& now contains no items without ports, the | |
11300 | value of &%daemon_smtp_ports%& is no longer relevant in this example.) | |
168e428f PH |
11301 | |
11302 | ||
11303 | ||
9b371988 PH |
11304 | .section "Support for the obsolete SSMTP (or SMTPS) protocol" "SECTsupobssmt" |
11305 | .cindex "ssmtp protocol" | |
11306 | .cindex "smtps protocol" | |
11307 | .cindex "SMTP" "ssmtp protocol" | |
11308 | .cindex "SMTP" "smtps protocol" | |
168e428f PH |
11309 | Exim supports the obsolete SSMTP protocol (also known as SMTPS) that was used |
11310 | before the STARTTLS command was standardized for SMTP. Some legacy clients | |
9b371988 | 11311 | still use this protocol. If the &%tls_on_connect_ports%& option is set to a |
168e428f PH |
11312 | list of port numbers, connections to those ports must use SSMTP. The most |
11313 | common use of this option is expected to be | |
9b371988 PH |
11314 | .code |
11315 | tls_on_connect_ports = 465 | |
11316 | .endd | |
168e428f | 11317 | because 465 is the usual port number used by the legacy clients. There is also |
9b371988 | 11318 | a command line option &%-tls-on-connect%&, which forces all ports to behave in |
168e428f PH |
11319 | this way when a daemon is started. |
11320 | ||
9b371988 | 11321 | &*Warning*&: Setting &%tls_on_connect_ports%& does not of itself cause the |
168e428f | 11322 | daemon to listen on those ports. You must still specify them in |
9b371988 PH |
11323 | &%daemon_smtp_ports%&, &%local_interfaces%&, or the &%-oX%& option. (This is |
11324 | because &%tls_on_connect_ports%& applies to &%inetd%& connections as well as to | |
168e428f PH |
11325 | connections via the daemon.) |
11326 | ||
11327 | ||
11328 | ||
11329 | ||
9b371988 PH |
11330 | .section "IPv6 address scopes" |
11331 | IPv6 addresses have &"scopes"&, and a host with multiple hardware interfaces | |
168e428f PH |
11332 | can, in principle, have the same link-local IPv6 address on different |
11333 | interfaces. Thus, additional information is needed, over and above the IP | |
11334 | address, to distinguish individual interfaces. A convention of using a | |
11335 | percent sign followed by something (often the interface name) has been | |
11336 | adopted in some cases, leading to addresses like this: | |
9b371988 PH |
11337 | .code |
11338 | fe80::202:b3ff:fe03:45c1%eth0 | |
11339 | .endd | |
168e428f | 11340 | To accommodate this usage, a percent sign followed by an arbitrary string is |
9b371988 | 11341 | allowed at the end of an IPv6 address. By default, Exim calls &[getaddrinfo()]& |
168e428f PH |
11342 | to convert a textual IPv6 address for actual use. This function recognizes the |
11343 | percent convention in operating systems that support it, and it processes the | |
11344 | address appropriately. Unfortunately, some older libraries have problems with | |
9b371988 PH |
11345 | &[getaddrinfo()]&. If |
11346 | .code | |
11347 | IPV6_USE_INET_PTON=yes | |
11348 | .endd | |
11349 | is set in &_Local/Makefile_& (or an OS-dependent Makefile) when Exim is built, | |
11350 | Exim uses &'inet_pton()'& to convert a textual IPv6 address for actual use, | |
11351 | instead of &[getaddrinfo()]&. (Before version 4.14, it always used this | |
168e428f | 11352 | function.) Of course, this means that the additional functionality of |
9b371988 | 11353 | &[getaddrinfo()]& &-- recognizing scoped addresses &-- is lost. |
168e428f PH |
11354 | |
11355 | ||
11356 | ||
9b371988 | 11357 | .section "Examples of starting a listening daemon" |
168e428f | 11358 | The default case in an IPv6 environment is |
9b371988 PH |
11359 | .code |
11360 | daemon_smtp_ports = smtp | |
11361 | local_interfaces = <; ::0 ; 0.0.0.0 | |
11362 | .endd | |
168e428f PH |
11363 | This specifies listening on the smtp port on all IPv6 and IPv4 interfaces. |
11364 | Either one or two sockets may be used, depending on the characteristics of | |
11365 | the TCP/IP stack. (This is complicated and messy; for more information, | |
9b371988 | 11366 | read the comments in the &_daemon.c_& source file.) |
168e428f PH |
11367 | |
11368 | To specify listening on ports 25 and 26 on all interfaces: | |
9b371988 PH |
11369 | .code |
11370 | daemon_smtp_ports = 25 : 26 | |
11371 | .endd | |
11372 | (leaving &%local_interfaces%& at the default setting) or, more explicitly: | |
11373 | .code | |
168e428f PH |
11374 | local_interfaces = <; ::0.25 ; ::0.26 \ |
11375 | 0.0.0.0.25 ; 0.0.0.0.26 | |
9b371988 | 11376 | .endd |
168e428f PH |
11377 | To listen on the default port on all IPv4 interfaces, and on port 26 on the |
11378 | IPv4 loopback address only: | |
9b371988 PH |
11379 | .code |
11380 | local_interfaces = 0.0.0.0 : 127.0.0.1.26 | |
11381 | .endd | |
168e428f | 11382 | To specify listening on the default port on specific interfaces only: |
9b371988 PH |
11383 | .code |
11384 | local_interfaces = 192.168.34.67 : 192.168.34.67 | |
11385 | .endd | |
11386 | &*Warning*&: Such a setting excludes listening on the loopback interfaces. | |
168e428f | 11387 | |
168e428f | 11388 | |
168e428f | 11389 | |
9b371988 PH |
11390 | .section "Recognising the local host" "SECTreclocipadd" |
11391 | The &%local_interfaces%& option is also used when Exim needs to determine | |
168e428f PH |
11392 | whether or not an IP address refers to the local host. That is, the IP |
11393 | addresses of all the interfaces on which a daemon is listening are always | |
11394 | treated as local. | |
11395 | ||
9b371988 | 11396 | For this usage, port numbers in &%local_interfaces%& are ignored. If either of |
168e428f PH |
11397 | the items 0.0.0.0 or ::0 are encountered, Exim gets a complete list of |
11398 | available interfaces from the operating system, and extracts the relevant | |
11399 | (that is, IPv4 or IPv6) addresses to use for checking. | |
11400 | ||
11401 | Some systems set up large numbers of virtual interfaces in order to provide | |
11402 | many virtual web servers. In this situation, you may want to listen for | |
11403 | email on only a few of the available interfaces, but nevertheless treat all | |
11404 | interfaces as local when routing. You can do this by setting | |
9b371988 PH |
11405 | &%extra_local_interfaces%& to a list of IP addresses, possibly including the |
11406 | &"all"& wildcard values. These addresses are recognized as local, but are not | |
168e428f | 11407 | used for listening. Consider this example: |
9b371988 | 11408 | .code |
168e428f PH |
11409 | local_interfaces = <; 127.0.0.1 ; ::1 ; \ |
11410 | 192.168.53.235 ; \ | |
11411 | 3ffe:2101:12:1:a00:20ff:fe86:a061 | |
11412 | ||
11413 | extra_local_interfaces = <; ::0 ; 0.0.0.0 | |
9b371988 | 11414 | .endd |
168e428f PH |
11415 | The daemon listens on the loopback interfaces and just one IPv4 and one IPv6 |
11416 | address, but all available interface addresses are treated as local when | |
11417 | Exim is routing. | |
11418 | ||
11419 | In some environments the local host name may be in an MX list, but with an IP | |
11420 | address that is not assigned to any local interface. In other cases it may be | |
11421 | desirable to treat other host names as if they referred to the local host. Both | |
9b371988 | 11422 | these cases can be handled by setting the &%hosts_treat_as_local%& option. |
168e428f PH |
11423 | This contains host names rather than IP addresses. When a host is referenced |
11424 | during routing, either via an MX record or directly, it is treated as the local | |
9b371988 PH |
11425 | host if its name matches &%hosts_treat_as_local%&, or if any of its IP |
11426 | addresses match &%local_interfaces%& or &%extra_local_interfaces%&. | |
168e428f PH |
11427 | |
11428 | ||
11429 | ||
9b371988 | 11430 | .section "Delivering to a remote host" |
168e428f PH |
11431 | Delivery to a remote host is handled by the smtp transport. By default, it |
11432 | allows the system's TCP/IP functions to choose which interface to use (if | |
11433 | there is more than one) when connecting to a remote host. However, the | |
9b371988 PH |
11434 | &%interface%& option can be set to specify which interface is used. See the |
11435 | description of the smtp transport in chapter &<<CHAPsmtptrans>>& for more | |
11436 | details. | |
168e428f PH |
11437 | |
11438 | ||
11439 | ||
11440 | ||
9b371988 PH |
11441 | . //////////////////////////////////////////////////////////////////////////// |
11442 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 11443 | |
9b371988 PH |
11444 | .chapter "Main configuration" "CHAPmainconfig" |
11445 | .cindex "configuration file" "main section" | |
11446 | .cindex "main configuration" | |
168e428f PH |
11447 | The first part of the run time configuration file contains three types of item: |
11448 | ||
9b371988 PH |
11449 | .ilist |
11450 | Macro definitions: These lines start with an upper case letter. See section | |
11451 | &<<SECTmacrodefs>>& for details of macro processing. | |
11452 | .next | |
11453 | Named list definitions: These lines start with one of the words &"domainlist"&, | |
11454 | &"hostlist"&, &"addresslist"&, or &"localpartlist"&. Their use is described in | |
11455 | section &<<SECTnamedlists>>&. | |
11456 | .next | |
11457 | Main configuration settings: Each setting occupies one line of the file | |
168e428f | 11458 | (with possible continuations). If any setting is preceded by the word |
9b371988 PH |
11459 | &"hide"&, the &%-bP%& command line option displays its value to admin users |
11460 | only. See section &<<SECTcos>>& for a description of the syntax of these option | |
11461 | settings. | |
11462 | .endlist | |
168e428f PH |
11463 | |
11464 | This chapter specifies all the main configuration options, along with their | |
11465 | types and default values. For ease of finding a particular option, they appear | |
9b371988 PH |
11466 | in alphabetical order in section &<<SECTalomo>>& below. However, because there |
11467 | are now so many options, they are first listed briefly in functional groups, as | |
11468 | an aid to finding the name of the option you are looking for. Some options are | |
168e428f PH |
11469 | listed in more than one group. |
11470 | ||
9b371988 PH |
11471 | .section "Miscellaneous" |
11472 | .table2 | |
11473 | .row &%bi_command%& "to run for &%-bi%& command line option" | |
11474 | .row &%keep_malformed%& "for broken files &-- should not happen" | |
11475 | .row &%localhost_number%& "for unique message ids in clusters" | |
11476 | .row &%message_body_visible%& "how much to show in &$message_body$&" | |
11477 | .row &%mua_wrapper%& "run in &""MUA wrapper""& mode" | |
11478 | .row &%print_topbitchars%& "top-bit characters are printing" | |
11479 | .row &%timezone%& "force time zone" | |
11480 | .endtable | |
11481 | ||
11482 | ||
11483 | .section "Exim parameters" | |
11484 | .table2 | |
11485 | .row &%exim_group%& "override compiled-in value" | |
11486 | .row &%exim_path%& "override compiled-in value" | |
11487 | .row &%exim_user%& "override compiled-in value" | |
11488 | .row &%primary_hostname%& "default from &[uname()]&" | |
11489 | .row &%split_spool_directory%& "use multiple directories" | |
11490 | .row &%spool_directory%& "override compiled-in value" | |
11491 | .endtable | |
11492 | ||
11493 | ||
11494 | ||
11495 | .section "Privilege controls" | |
11496 | .table2 | |
11497 | .row &%admin_groups%& "groups that are Exim admin users" | |
11498 | .row &%deliver_drop_privilege%& "drop root for delivery processes" | |
11499 | .row &%local_from_check%& "insert &'Sender:'& if necessary" | |
11500 | .row &%local_from_prefix%& "for testing &'From:'& for local sender" | |
11501 | .row &%local_from_suffix%& "for testing &'From:'& for local sender" | |
11502 | .row &%local_sender_retain%& "keep &'Sender:'& from untrusted user" | |
11503 | .row &%never_users%& "do not run deliveries as these" | |
11504 | .row &%prod_requires_admin%& "forced delivery requires admin user" | |
11505 | .row &%queue_list_requires_admin%& "queue listing requires admin user" | |
11506 | .row &%trusted_groups%& "groups that are trusted" | |
11507 | .row &%trusted_users%& "users that are trusted" | |
11508 | .endtable | |
11509 | ||
11510 | ||
11511 | ||
11512 | .section "Logging" | |
11513 | .table2 | |
11514 | .row &%hosts_connection_nolog%& "exemption from connect logging" | |
11515 | .row &%log_file_path%& "override compiled-in value" | |
11516 | .row &%log_selector%& "set/unset optional logging" | |
11517 | .row &%log_timezone%& "add timezone to log lines" | |
11518 | .row &%message_logs%& "create per-message logs" | |
11519 | .row &%preserve_message_logs%& "after message completion" | |
11520 | .row &%process_log_path%& "for SIGUSR1 and &'exiwhat'&" | |
11521 | .row &%syslog_duplication%& "controls duplicate log lines on syslog" | |
11522 | .row &%syslog_facility%& "set syslog &""facility""& field" | |
11523 | .row &%syslog_processname%& "set syslog &""ident""& field" | |
11524 | .row &%syslog_timestamp%& "timestamp syslog lines" | |
11525 | .row &%write_rejectlog%& "control use of message log" | |
11526 | .endtable | |
11527 | ||
11528 | ||
11529 | ||
11530 | .section "Frozen messages" | |
11531 | .table2 | |
11532 | .row &%auto_thaw%& "sets time for retrying frozen messages" | |
11533 | .row &%freeze_tell%& "send message when freezing" | |
11534 | .row &%move_frozen_messages%& "to another directory" | |
11535 | .row &%timeout_frozen_after%& "keep frozen messages only so long" | |
11536 | .endtable | |
11537 | ||
11538 | ||
11539 | ||
11540 | .section "Data lookups" | |
11541 | .table2 | |
11542 | .row &%ldap_default_servers%& "used if no server in query" | |
11543 | .row &%ldap_version%& "set protocol version" | |
11544 | .row &%lookup_open_max%& "lookup files held open" | |
11545 | .row &%mysql_servers%& "as it says" | |
11546 | .row &%oracle_servers%& "as it says" | |
11547 | .row &%pgsql_servers%& "as it says" | |
11548 | .row &%sqlite_lock_timeout%& "as it says" | |
11549 | .endtable | |
11550 | ||
11551 | ||
11552 | ||
11553 | .section "Message ids" | |
11554 | .table2 | |
11555 | .row &%message_id_header_domain%& "used to build &'Message-ID:'& header" | |
11556 | .row &%message_id_header_text%& "ditto" | |
11557 | .endtable | |
11558 | ||
11559 | ||
11560 | ||
11561 | .section "Embedded Perl Startup" | |
11562 | .table2 | |
11563 | .row &%perl_at_start%& "always start the interpreter" | |
11564 | .row &%perl_startup%& "code to obey when starting Perl" | |
11565 | .endtable | |
11566 | ||
11567 | ||
11568 | ||
11569 | .section "Daemon" | |
11570 | .table2 | |
11571 | .row &%daemon_smtp_ports%& "default ports" | |
11572 | .row &%daemon_startup_retries%& "number of times to retry" | |
11573 | .row &%daemon_startup_sleep%& "time to sleep between tries" | |
11574 | .row &%extra_local_interfaces%& "not necessarily listened on" | |
11575 | .row &%local_interfaces%& "on which to listen, with optional ports" | |
11576 | .row &%pid_file_path%& "override compiled-in value" | |
11577 | .row &%queue_run_max%& "maximum simultaneous queue runners" | |
11578 | .endtable | |
11579 | ||
11580 | ||
11581 | ||
11582 | .section "Resource control" | |
11583 | .table2 | |
11584 | .row &%check_log_inodes%& "before accepting a message" | |
11585 | .row &%check_log_space%& "before accepting a message" | |
11586 | .row &%check_spool_inodes%& "before accepting a message" | |
11587 | .row &%check_spool_space%& "before accepting a message" | |
11588 | .row &%deliver_queue_load_max%& "no queue deliveries if load high" | |
11589 | .row &%queue_only_load%& "queue incoming if load high" | |
11590 | .row &%queue_run_max%& "maximum simultaneous queue runners" | |
11591 | .row &%remote_max_parallel%& "parallel SMTP delivery per message" | |
11592 | .row &%smtp_accept_max%& "simultaneous incoming connections" | |
11593 | .row &%smtp_accept_max_nommail%& "non-mail commands" | |
11594 | .row &%smtp_accept_max_nonmail_hosts%& "hosts to which the limit applies" | |
11595 | .row &%smtp_accept_max_per_connection%& "messages per connection" | |
11596 | .row &%smtp_accept_max_per_host%& "connections from one host" | |
11597 | .row &%smtp_accept_queue%& "queue mail if more connections" | |
11598 | .row &%smtp_accept_queue_per_connection%& "queue if more messages per &&& | |
11599 | connection" | |
11600 | .row &%smtp_accept_reserve%& "only reserve hosts if more connections" | |
11601 | .row &%smtp_check_spool_space%& "from SIZE on MAIL command" | |
11602 | .row &%smtp_connect_backlog%& "passed to TCP/IP stack" | |
11603 | .row &%smtp_load_reserve%& "SMTP from reserved hosts if load high" | |
11604 | .row &%smtp_reserve_hosts%& "these are the reserve hosts" | |
11605 | .endtable | |
11606 | ||
11607 | ||
11608 | ||
11609 | .section "Policy controls" | |
11610 | .table2 | |
11611 | .row &%acl_not_smtp%& "ACL for non-SMTP messages" | |
11612 | .row &%acl_not_smtp_mime%& "ACL for non-SMTP MIME parts" | |
11613 | .row &%acl_smtp_auth%& "ACL for AUTH" | |
11614 | .row &%acl_smtp_connect%& "ACL for connection" | |
11615 | .row &%acl_smtp_data%& "ACL for DATA" | |
11616 | .row &%acl_smtp_etrn%& "ACL for ETRN" | |
11617 | .row &%acl_smtp_expn%& "ACL for EXPN" | |
11618 | .row &%acl_smtp_helo%& "ACL for EHLO or HELO" | |
11619 | .row &%acl_smtp_mail%& "ACL for MAIL" | |
11620 | .row &%acl_smtp_mailauth%& "ACL for AUTH on MAIL command" | |
11621 | .row &%acl_smtp_mime%& "ACL for MIME parts" | |
11622 | .row &%acl_smtp_predata%& "ACL for start of data" | |
11623 | .row &%acl_smtp_quit%& "ACL for QUIT" | |
11624 | .row &%acl_smtp_rcpt%& "ACL for RCPT" | |
11625 | .row &%acl_smtp_starttls%& "ACL for STARTTLS" | |
11626 | .row &%acl_smtp_vrfy%& "ACL for VRFY" | |
11627 | .row &%av_scanner%& "specify virus scanner" | |
11628 | .row &%check_rfc2047_length%& "check length of RFC 2047 &""encoded &&& | |
11629 | words""&" | |
11630 | .row &%dns_csa_search_limit%& "control CSA parent search depth" | |
11631 | .row &%dns_csa_use_reverse%& "en/disable CSA IP reverse search" | |
11632 | .row &%header_maxsize%& "total size of message header" | |
11633 | .row &%header_line_maxsize%& "individual header line limit" | |
11634 | .row &%helo_accept_junk_hosts%& "allow syntactic junk from these hosts" | |
11635 | .row &%helo_allow_chars%& "allow illegal chars in HELO names" | |
11636 | .row &%helo_lookup_domains%& "lookup hostname for these HELO names" | |
11637 | .row &%helo_try_verify_hosts%& "HELO soft-checked for these hosts" | |
11638 | .row &%helo_verify_hosts%& "HELO hard-checked for these hosts" | |
11639 | .row &%host_lookup%& "host name looked up for these hosts" | |
11640 | .row &%host_lookup_order%& "order of DNS and local name lookups" | |
11641 | .row &%host_reject_connection%& "reject connection from these hosts" | |
11642 | .row &%hosts_treat_as_local%& "useful in some cluster configurations" | |
11643 | .row &%local_scan_timeout%& "timeout for &[local_scan()]&" | |
11644 | .row &%message_size_limit%& "for all messages" | |
11645 | .row &%percent_hack_domains%& "recognize %-hack for these domains" | |
11646 | .row &%spamd_address%& "set interface to SpamAssassin" | |
11647 | .endtable | |
11648 | ||
11649 | ||
11650 | ||
11651 | .section "Callout cache" | |
11652 | .table2 | |
11653 | .row &%callout_domain_negative_expire%& "timeout for negative domain cache &&& | |
11654 | item" | |
11655 | .row &%callout_domain_positive_expire%& "timeout for positive domain cache &&& | |
11656 | item" | |
11657 | .row &%callout_negative_expire%& "timeout for negative address cache item" | |
11658 | .row &%callout_positive_expire%& "timeout for positive address cache item" | |
11659 | .row &%callout_random_local_part%& "string to use for &""random""& testing" | |
11660 | .endtable | |
11661 | ||
11662 | ||
11663 | ||
11664 | .section "TLS" | |
11665 | .table2 | |
11666 | .row &%tls_advertise_hosts%& "advertise TLS to these hosts" | |
11667 | .row &%tls_certificate%& "location of server certificate" | |
11668 | .row &%tls_crl%& "certificate revocation list" | |
11669 | .row &%tls_dhparam%& "DH parameters for server" | |
11670 | .row &%tls_on_connect_ports%& "specify SSMTP (SMTPS) ports" | |
11671 | .row &%tls_privatekey%& "location of server private key" | |
11672 | .row &%tls_remember_esmtp%& "don't reset after starting TLS" | |
11673 | .row &%tls_require_ciphers%& "specify acceptable cipers" | |
11674 | .row &%tls_try_verify_hosts%& "try to verify client certificate" | |
11675 | .row &%tls_verify_certificates%& "expected client certificates" | |
11676 | .row &%tls_verify_hosts%& "insist on client certificate verify" | |
11677 | .endtable | |
11678 | ||
11679 | ||
11680 | ||
11681 | .section "Local user handling" | |
11682 | .table2 | |
11683 | .row &%finduser_retries%& "useful in NIS environments" | |
11684 | .row &%gecos_name%& "used when creating &'Sender:'&" | |
11685 | .row &%gecos_pattern%& "ditto" | |
11686 | .row &%max_username_length%& "for systems that truncate" | |
11687 | .row &%unknown_login%& "used when no login name found" | |
11688 | .row &%unknown_username%& "ditto" | |
11689 | .row &%uucp_from_pattern%& "for recognizing &""From ""& lines" | |
11690 | .row &%uucp_from_sender%& "ditto" | |
11691 | .endtable | |
11692 | ||
11693 | ||
11694 | ||
11695 | .section "All incoming messages (SMTP and non-SMTP)" | |
11696 | .table2 | |
11697 | .row &%header_maxsize%& "total size of message header" | |
11698 | .row &%header_line_maxsize%& "individual header line limit" | |
11699 | .row &%message_size_limit%& "applies to all messages" | |
11700 | .row &%percent_hack_domains%& "recognize %-hack for these domains" | |
11701 | .row &%received_header_text%& "expanded to make &'Received:'&" | |
11702 | .row &%received_headers_max%& "for mail loop detection" | |
11703 | .row &%recipients_max%& "limit per message" | |
11704 | .row &%recipients_max_reject%& "permanently reject excess" | |
11705 | .endtable | |
11706 | ||
11707 | ||
11708 | ||
11709 | ||
11710 | .section "Non-SMTP incoming messages" | |
11711 | .table2 | |
11712 | .row &%receive_timeout%& "for non-SMTP messages" | |
11713 | .endtable | |
11714 | ||
11715 | ||
11716 | ||
11717 | ||
11718 | ||
11719 | .section "Incoming SMTP messages" | |
11720 | See also the &'Policy controls'& section above. | |
11721 | ||
11722 | .table2 | |
11723 | .row &%host_lookup%& "host name looked up for these hosts" | |
11724 | .row &%host_lookup_order%& "order of DNS and local name lookups" | |
11725 | .row &%recipient_unqualified_hosts%& "may send unqualified recipients" | |
11726 | .row &%rfc1413_hosts%& "make ident calls to these hosts" | |
11727 | .row &%rfc1413_query_timeout%& "zero disables ident calls" | |
11728 | .row &%sender_unqualified_hosts%& "may send unqualified senders" | |
11729 | .row &%smtp_accept_keepalive%& "some TCP/IP magic" | |
11730 | .row &%smtp_accept_max%& "simultaneous incoming connections" | |
11731 | .row &%smtp_accept_max_nonmail%& "non-mail commands" | |
11732 | .row &%smtp_accept_max_nonmail_hosts%& "hosts to which the limit applies" | |
11733 | .row &%smtp_accept_max_per_connection%& "messages per connection" | |
11734 | .row &%smtp_accept_max_per_host%& "connections from one host" | |
11735 | .row &%smtp_accept_queue%& "queue mail if more connections" | |
11736 | .row &%smtp_accept_queue_per_connection%& "queue if more messages per &&& | |
11737 | connection" | |
11738 | .row &%smtp_accept_reserve%& "only reserve hosts if more connections" | |
11739 | .row &%smtp_active_hostname%& "host name to use in messages" | |
11740 | .row &%smtp_banner%& "text for welcome banner" | |
11741 | .row &%smtp_check_spool_space%& "from SIZE on MAIL command" | |
11742 | .row &%smtp_connect_backlog%& "passed to TCP/IP stack" | |
11743 | .row &%smtp_enforce_sync%& "of SMTP command/responses" | |
11744 | .row &%smtp_etrn_command%& "what to run for ETRN" | |
11745 | .row &%smtp_etrn_serialize%& "only one at once" | |
11746 | .row &%smtp_load_reserve%& "only reserve hosts if this load" | |
11747 | .row &%smtp_max_unknown_commands%& "before dropping connection" | |
11748 | .row &%smtp_ratelimit_hosts%& "apply ratelimiting to these hosts" | |
11749 | .row &%smtp_ratelimit_mail%& "ratelimit for MAIL commands" | |
11750 | .row &%smtp_ratelimit_rcpt%& "ratelimit for RCPT commands" | |
11751 | .row &%smtp_receive_timeout%& "per command or data line" | |
11752 | .row &%smtp_reserve_hosts%& "these are the reserve hosts" | |
11753 | .row &%smtp_return_error_details%& "give detail on rejections" | |
11754 | .endtable | |
11755 | ||
11756 | ||
11757 | ||
11758 | .section "SMTP extensions" | |
11759 | .table2 | |
11760 | .row &%accept_8bitmime%& "advertise 8BITMIME" | |
11761 | .row &%auth_advertise_hosts%& "advertise AUTH to these hosts" | |
11762 | .row &%ignore_fromline_hosts%& "allow &""From ""& from these hosts" | |
11763 | .row &%ignore_fromline_local%& "allow &""From ""& from local SMTP" | |
11764 | .row &%pipelining_advertise_hosts%& "advertise pipelining to these hosts" | |
11765 | .row &%tls_advertise_hosts%& "advertise TLS to these hosts" | |
11766 | .endtable | |
11767 | ||
11768 | ||
11769 | ||
11770 | .section "Processing messages" | |
11771 | .table2 | |
11772 | .row &%allow_domain_literals%& "recognize domain literal syntax" | |
11773 | .row &%allow_mx_to_ip%& "allow MX to point to IP address" | |
11774 | .row &%allow_utf8_domains%& "in addresses" | |
11775 | .row &%check_rfc2047_length%& "check length of RFC 2047 &""encoded &&& | |
11776 | words""&" | |
11777 | .row &%delivery_date_remove%& "from incoming messages" | |
11778 | .row &%envelope_to_remote%& "from incoming messages" | |
11779 | .row &%extract_addresses_remove_arguments%& "affects &%-t%& processing" | |
11780 | .row &%headers_charset%& "default for translations" | |
11781 | .row &%qualify_domain%& "default for senders" | |
11782 | .row &%qualify_recipient%& "default for recipients" | |
11783 | .row &%return_path_remove%& "from incoming messages" | |
11784 | .row &%strip_excess_angle_brackets%& "in addresses" | |
11785 | .row &%strip_trailing_dot%& "at end of addresses" | |
11786 | .row &%untrusted_set_sender%& "untrusted can set envelope sender" | |
11787 | .endtable | |
11788 | ||
11789 | ||
11790 | ||
11791 | .section "System filter" | |
11792 | .table2 | |
11793 | .row &%system_filter%& "locate system filter" | |
11794 | .row &%system_filter_directory_transport%& "transport for delivery to a &&& | |
11795 | directory" | |
11796 | .row &%system_filter_file_transport%& "transport for delivery to a file" | |
11797 | .row &%system_filter_group%& "group for filter running" | |
11798 | .row &%system_filter_pipe_transport%& "transport for delivery to a pipe" | |
11799 | .row &%system_filter_reply_transport%& "transport for autoreply delivery" | |
11800 | .row &%system_filter_user%& "user for filter running" | |
11801 | .endtable | |
11802 | ||
11803 | ||
11804 | ||
11805 | .section "Routing and delivery" | |
11806 | .table2 | |
11807 | .row &%dns_again_means_nonexist%& "for broken domains" | |
11808 | .row &%dns_check_names_pattern%& "pre-DNS syntax check" | |
11809 | .row &%dns_ipv4_lookup%& "only v4 lookup for these domains" | |
11810 | .row &%dns_retrans%& "parameter for resolver" | |
11811 | .row &%dns_retry%& "parameter for resolver" | |
11812 | .row &%hold_domains%& "hold delivery for these domains" | |
11813 | .row &%local_interfaces%& "for routing checks" | |
11814 | .row &%queue_domains%& "no immediate delivery for these" | |
11815 | .row &%queue_only%& "no immediate delivery at all" | |
11816 | .row &%queue_only_file%& "no immediate delivery if file exists" | |
11817 | .row &%queue_only_load%& "no immediate delivery if load is high" | |
11818 | .row &%queue_only_override%& "allow command line to override" | |
11819 | .row &%queue_run_in_order%& "order of arrival" | |
11820 | .row &%queue_run_max%& "of simultaneous queue runners" | |
11821 | .row &%queue_smtp_domains%& "no immediate SMTP delivery for these" | |
11822 | .row &%remote_max_parallel%& "parallel SMTP delivery per message" | |
11823 | .row &%remote_sort_domains%& "order of remote deliveries" | |
11824 | .row &%retry_data_expire%& "timeout for retry data" | |
11825 | .row &%retry_interval_max%& "safety net for retry rules" | |
11826 | .endtable | |
11827 | ||
11828 | ||
11829 | ||
11830 | .section "Bounce and warning messages" | |
11831 | .table2 | |
11832 | .row &%bounce_message_file%& "content of bounce" | |
11833 | .row &%bounce_message_text%& "content of bounce" | |
11834 | .row &%bounce_return_body%& "include body if returning message" | |
11835 | .row &%bounce_return_message%& "include original message in bounce" | |
11836 | .row &%bounce_return_size_limit%& "limit on returned message" | |
11837 | .row &%bounce_sender_authentication%& "send authenticated sender with bounce" | |
11838 | .row &%errors_copy%& "copy bounce messages" | |
11839 | .row &%errors_reply_to%& "&'Reply-to:'& in bounces" | |
11840 | .row &%delay_warning%& "time schedule" | |
11841 | .row &%delay_warning_condition%& "condition for warning messages" | |
11842 | .row &%ignore_bounce_errors_after%& "discard undeliverable bounces" | |
11843 | .row &%smtp_return_error_details%& "give detail on rejections" | |
11844 | .row &%warn_message_file%& "content of warning message" | |
11845 | .endtable | |
11846 | ||
11847 | ||
11848 | ||
11849 | .section "Alphabetical list of main options" "SECTalomo" | |
11850 | Those options that undergo string expansion before use are marked with | |
11851 | †. | |
11852 | ||
11853 | .option accept_8bitmime main boolean false | |
11854 | .cindex "8BITMIME" | |
11855 | .cindex "8-bit characters" | |
168e428f PH |
11856 | This option causes Exim to send 8BITMIME in its response to an SMTP |
11857 | EHLO command, and to accept the BODY= parameter on MAIL commands. | |
11858 | However, though Exim is 8-bit clean, it is not a protocol converter, and it | |
11859 | takes no steps to do anything special with messages received by this route. | |
11860 | Consequently, this option is turned off by default. | |
11861 | ||
9b371988 PH |
11862 | .option acl_not_smtp main string&!! unset |
11863 | .cindex "&ACL;" "for non-SMTP messages" | |
11864 | .cindex "non-SMTP messages" "ACLs for" | |
168e428f | 11865 | This option defines the ACL that is run when a non-SMTP message is on the point |
9b371988 | 11866 | of being accepted. See chapter &<<CHAPACL>>& for further details. |
068aaea8 | 11867 | |
9b371988 PH |
11868 | .new |
11869 | .option acl_not_smtp_mime main string&!! unset | |
068aaea8 | 11870 | This option defines the ACL that is run for individual MIME parts of non-SMTP |
9b371988 | 11871 | messages. It operates in exactly the same way as &%acl_smtp_mime%& operates for |
068aaea8 | 11872 | SMTP messages. |
9b371988 | 11873 | .wen |
068aaea8 | 11874 | |
9b371988 PH |
11875 | .option acl_smtp_auth main string&!! unset |
11876 | .cindex "&ACL;" "setting up for SMTP commands" | |
11877 | .cindex "AUTH" "ACL for" | |
168e428f | 11878 | This option defines the ACL that is run when an SMTP AUTH command is |
9b371988 | 11879 | received. See chapter &<<CHAPACL>>& for further details. |
168e428f | 11880 | |
9b371988 PH |
11881 | .option acl_smtp_connect main string&!! unset |
11882 | .cindex "&ACL;" "on SMTP connection" | |
168e428f | 11883 | This option defines the ACL that is run when an SMTP connection is received. |
9b371988 | 11884 | See chapter &<<CHAPACL>>& for further details. |
168e428f | 11885 | |
9b371988 PH |
11886 | .option acl_smtp_data main string&!! unset |
11887 | .cindex "DATA" "ACL for" | |
168e428f PH |
11888 | This option defines the ACL that is run after an SMTP DATA command has been |
11889 | processed and the message itself has been received, but before the final | |
9b371988 | 11890 | acknowledgement is sent. See chapter &<<CHAPACL>>& for further details. |
168e428f | 11891 | |
9b371988 PH |
11892 | .option acl_smtp_etrn main string&!! unset |
11893 | .cindex "ETRN" "ACL for" | |
168e428f | 11894 | This option defines the ACL that is run when an SMTP ETRN command is |
9b371988 | 11895 | received. See chapter &<<CHAPACL>>& for further details. |
168e428f | 11896 | |
9b371988 PH |
11897 | .option acl_smtp_expn main string&!! unset |
11898 | .cindex "EXPN" "ACL for" | |
168e428f | 11899 | This option defines the ACL that is run when an SMTP EXPN command is |
9b371988 | 11900 | received. See chapter &<<CHAPACL>>& for further details. |
168e428f | 11901 | |
9b371988 PH |
11902 | .option acl_smtp_helo main string&!! unset |
11903 | .cindex "EHLO" "ACL for" | |
11904 | .cindex "HELO" "ACL for" | |
168e428f | 11905 | This option defines the ACL that is run when an SMTP EHLO or HELO |
9b371988 | 11906 | command is received. See chapter &<<CHAPACL>>& for further details. |
168e428f | 11907 | |
168e428f | 11908 | |
9b371988 PH |
11909 | .option acl_smtp_mail main string&!! unset |
11910 | .cindex "MAIL" "ACL for" | |
168e428f | 11911 | This option defines the ACL that is run when an SMTP MAIL command is |
9b371988 | 11912 | received. See chapter &<<CHAPACL>>& for further details. |
168e428f | 11913 | |
9b371988 PH |
11914 | .option acl_smtp_mailauth main string&!! unset |
11915 | .cindex "AUTH" "on MAIL command" | |
168e428f | 11916 | This option defines the ACL that is run when there is an AUTH parameter on |
9b371988 PH |
11917 | a MAIL command. See chapter &<<CHAPACL>>& for details of ACLs, and chapter |
11918 | &<<CHAPSMTPAUTH>>& for details of authentication. | |
168e428f | 11919 | |
9b371988 PH |
11920 | .option acl_smtp_mime main string&!! unset |
11921 | .cindex "MIME content scanning" "ACL for" | |
168e428f PH |
11922 | This option is available when Exim is built with the content-scanning |
11923 | extension. It defines the ACL that is run for each MIME part in a message. See | |
9b371988 | 11924 | section &<<SECTscanmimepart>>& for details. |
168e428f | 11925 | |
9b371988 | 11926 | .option acl_smtp_predata main string&!! unset |
168e428f | 11927 | This option defines the ACL that is run when an SMTP DATA command is |
9b371988 | 11928 | received, before the message itself is received. See chapter &<<CHAPACL>>& for |
168e428f PH |
11929 | further details. |
11930 | ||
9b371988 PH |
11931 | .option acl_smtp_quit main string&!! unset |
11932 | .cindex "QUIT" "ACL for" | |
168e428f | 11933 | This option defines the ACL that is run when an SMTP QUIT command is |
9b371988 | 11934 | received. See chapter &<<CHAPACL>>& for further details. |
168e428f | 11935 | |
9b371988 PH |
11936 | .option acl_smtp_rcpt main string&!! unset |
11937 | .cindex "RCPT" "ACL for" | |
168e428f | 11938 | This option defines the ACL that is run when an SMTP RCPT command is |
9b371988 | 11939 | received. See chapter &<<CHAPACL>>& for further details. |
168e428f | 11940 | |
9b371988 PH |
11941 | .option acl_smtp_starttls main string&!! unset |
11942 | .cindex "STARTTLS" "ACL for" | |
168e428f | 11943 | This option defines the ACL that is run when an SMTP STARTTLS command is |
9b371988 | 11944 | received. See chapter &<<CHAPACL>>& for further details. |
168e428f | 11945 | |
9b371988 PH |
11946 | .option acl_smtp_vrfy main string&!! unset |
11947 | .cindex "VRFY" "ACL for" | |
168e428f | 11948 | This option defines the ACL that is run when an SMTP VRFY command is |
9b371988 | 11949 | received. See chapter &<<CHAPACL>>& for further details. |
168e428f | 11950 | |
9b371988 PH |
11951 | .option admin_groups main "string list&!!" unset |
11952 | .cindex "admin user" | |
11953 | .new | |
068aaea8 PH |
11954 | This option is expanded just once, at the start of Exim's processing. If the |
11955 | current group or any of the supplementary groups of an Exim caller is in this | |
11956 | colon-separated list, the caller has admin privileges. If all your system | |
168e428f | 11957 | programmers are in a specific group, for example, you can give them all Exim |
9b371988 | 11958 | admin privileges by putting that group in &%admin_groups%&. However, this does |
168e428f PH |
11959 | not permit them to read Exim's spool files (whose group owner is the Exim gid). |
11960 | To permit this, you have to add individuals to the Exim group. | |
9b371988 | 11961 | .wen |
168e428f | 11962 | |
9b371988 PH |
11963 | .option allow_domain_literals main boolean false |
11964 | .cindex "domain literal" | |
168e428f PH |
11965 | If this option is set, the RFC 2822 domain literal format is permitted in |
11966 | email addresses. The option is not set by default, because the domain literal | |
11967 | format is not normally required these days, and few people know about it. It | |
11968 | has, however, been exploited by mail abusers. | |
11969 | ||
11970 | Unfortunately, it seems that some DNS black list maintainers are using this | |
11971 | format to report black listing to postmasters. If you want to accept messages | |
11972 | addressed to your hosts by IP address, you need to set | |
9b371988 PH |
11973 | &%allow_domain_literals%& true, and also to add &`@[]`& to the list of local |
11974 | domains (defined in the named domain list &%local_domains%& in the default | |
11975 | configuration). This &"magic string"& matches the domain literal form of all | |
11976 | the local host's IP addresses. | |
168e428f | 11977 | |
168e428f | 11978 | |
9b371988 PH |
11979 | .option allow_mx_to_ip main boolean false |
11980 | .cindex "MX record" "pointing to IP address" | |
168e428f PH |
11981 | It appears that more and more DNS zone administrators are breaking the rules |
11982 | and putting domain names that look like IP addresses on the right hand side of | |
11983 | MX records. Exim follows the rules and rejects this, giving an error message | |
11984 | that explains the mis-configuration. However, some other MTAs support this | |
9b371988 PH |
11985 | practice, so to avoid &"Why can't Exim do this?"& complaints, |
11986 | &%allow_mx_to_ip%& exists, in order to enable this heinous activity. It is not | |
11987 | recommended, except when you have no other choice. | |
168e428f | 11988 | |
9b371988 PH |
11989 | .option allow_utf8_domains main boolean false |
11990 | .cindex "domain" "UTF-8 characters in" | |
11991 | .cindex "UTF-8" "in domain name" | |
168e428f PH |
11992 | Lots of discussion is going on about internationalized domain names. One |
11993 | camp is strongly in favour of just using UTF-8 characters, and it seems | |
11994 | that at least two other MTAs permit this. This option allows Exim users to | |
11995 | experiment if they wish. | |
11996 | ||
11997 | If it is set true, Exim's domain parsing function allows valid | |
11998 | UTF-8 multicharacters to appear in domain name components, in addition to | |
11999 | letters, digits, and hyphens. However, just setting this option is not | |
12000 | enough; if you want to look up these domain names in the DNS, you must also | |
9b371988 | 12001 | adjust the value of &%dns_check_names_pattern%& to match the extended form. A |
168e428f | 12002 | suitable setting is: |
9b371988 | 12003 | .code |
168e428f PH |
12004 | dns_check_names_pattern = (?i)^(?>(?(1)\.|())[a-z0-9\xc0-\xff]\ |
12005 | (?>[-a-z0-9\x80-\xff]*[a-z0-9\x80-\xbf])?)+$ | |
9b371988 | 12006 | .endd |
168e428f | 12007 | Alternatively, you can just disable this feature by setting |
9b371988 PH |
12008 | .code |
12009 | dns_check_names_pattern = | |
12010 | .endd | |
168e428f PH |
12011 | That is, set the option to an empty string so that no check is done. |
12012 | ||
12013 | ||
9b371988 PH |
12014 | .option auth_advertise_hosts main "host list&!!" * |
12015 | .cindex "authentication" "advertising" | |
12016 | .cindex "AUTH" "advertising" | |
168e428f PH |
12017 | If any server authentication mechanisms are configured, Exim advertises them in |
12018 | response to an EHLO command only if the calling host matches this list. | |
12019 | Otherwise, Exim does not advertise AUTH. | |
12020 | Exim does not accept AUTH commands from clients to which it has not | |
12021 | advertised the availability of AUTH. The advertising of individual | |
12022 | authentication mechanisms can be controlled by the use of the | |
9b371988 PH |
12023 | &%server_advertise_condition%& generic authenticator option on the individual |
12024 | authenticators. See chapter &<<CHAPSMTPAUTH>>& for further details. | |
168e428f PH |
12025 | |
12026 | Certain mail clients (for example, Netscape) require the user to provide a name | |
12027 | and password for authentication if AUTH is advertised, even though it may | |
12028 | not be needed (the host may accept messages from hosts on its local LAN without | |
9b371988 | 12029 | authentication, for example). The &%auth_advertise_hosts%& option can be used |
168e428f PH |
12030 | to make these clients more friendly by excluding them from the set of hosts to |
12031 | which Exim advertises AUTH. | |
12032 | ||
9b371988 | 12033 | .cindex "AUTH" "advertising when encrypted" |
168e428f PH |
12034 | If you want to advertise the availability of AUTH only when the connection |
12035 | is encrypted using TLS, you can make use of the fact that the value of this | |
12036 | option is expanded, with a setting like this: | |
9b371988 PH |
12037 | .code |
12038 | auth_advertise_hosts = ${if eq{$tls_cipher}{}{}{*}} | |
12039 | .endd | |
12040 | .cindex "&$tls_cipher$&" | |
12041 | If &$tls_cipher$& is empty, the session is not encrypted, and the result of | |
168e428f | 12042 | the expansion is empty, thus matching no hosts. Otherwise, the result of the |
9b371988 | 12043 | expansion is *, which matches all hosts. |
168e428f | 12044 | |
168e428f | 12045 | |
9b371988 PH |
12046 | .option auto_thaw main time 0s |
12047 | .new | |
12048 | .cindex "thawing messages" | |
12049 | .cindex "unfreezing messages" | |
168e428f | 12050 | If this option is set to a time greater than zero, a queue runner will try a |
068aaea8 PH |
12051 | new delivery attempt on any frozen message, other than a bounce message, if |
12052 | this much time has passed since it was frozen. This may result in the message | |
12053 | being re-frozen if nothing has changed since the last attempt. It is a way of | |
9b371988 | 12054 | saying &"keep on trying, even though there are big problems"&. |
068aaea8 | 12055 | |
9b371988 PH |
12056 | &*Note*&: This is an old option, which predates &%timeout_frozen_after%& and |
12057 | &%ignore_bounce_errors_after%&. It is retained for compatibility, but it is not | |
068aaea8 | 12058 | thought to be very useful any more, and its use should probably be avoided. |
9b371988 | 12059 | .wen |
168e428f | 12060 | |
9b371988 | 12061 | .option av_scanner main string "see below" |
168e428f PH |
12062 | This option is available if Exim is built with the content-scanning extension. |
12063 | It specifies which anti-virus scanner to use. The default value is: | |
9b371988 PH |
12064 | .code |
12065 | sophie:/var/run/sophie | |
12066 | .endd | |
12067 | If the value of &%av_scanner%& starts with dollar character, it is expanded | |
12068 | before use. See section &<<SECTscanvirus>>& for further details. | |
168e428f PH |
12069 | |
12070 | ||
168e428f | 12071 | |
9b371988 PH |
12072 | .option bi_command main string unset |
12073 | .cindex "&%-bi%& option" | |
168e428f | 12074 | This option supplies the name of a command that is run when Exim is called with |
9b371988 PH |
12075 | the &%-bi%& option (see chapter &<<CHAPcommandline>>&). The string value is |
12076 | just the command name, it is not a complete command line. If an argument is | |
12077 | required, it must come from the &%-oA%& command line option. | |
168e428f PH |
12078 | |
12079 | ||
9b371988 PH |
12080 | .option bounce_message_file main string unset |
12081 | .cindex "bounce message" "customizing" | |
12082 | .cindex "customizing" "bounce message" | |
168e428f PH |
12083 | This option defines a template file containing paragraphs of text to be used |
12084 | for constructing bounce messages. Details of the file's contents are given in | |
9b371988 | 12085 | chapter &<<CHAPemsgcust>>&. See also &%warn_message_file%&. |
168e428f | 12086 | |
168e428f | 12087 | |
9b371988 | 12088 | .option bounce_message_text main string unset |
168e428f | 12089 | When this option is set, its contents are included in the default bounce |
9b371988 PH |
12090 | message immediately after &"This message was created automatically by mail |
12091 | delivery software."& It is not used if &%bounce_message_file%& is set. | |
168e428f | 12092 | |
9b371988 PH |
12093 | .option bounce_return_body main boolean true |
12094 | .cindex "bounce message" "including body" | |
168e428f | 12095 | This option controls whether the body of an incoming message is included in a |
9b371988 | 12096 | bounce message when &%bounce_return_message%& is true. If it is not set, only |
168e428f | 12097 | the message header is included. |
9b371988 | 12098 | .cindex "bounce message" "including original" |
168e428f | 12099 | |
9b371988 | 12100 | .option bounce_return_message main boolean true |
168e428f | 12101 | If this option is set false, the original message is not included in bounce |
9b371988 | 12102 | messages generated by Exim. See also &%bounce_return_size_limit%&. |
168e428f | 12103 | |
168e428f | 12104 | |
9b371988 PH |
12105 | .option bounce_return_size_limit main integer 100K |
12106 | .cindex "size limit" "of bounce" | |
12107 | .cindex "bounce message" "size limit" | |
12108 | .cindex "limit" "bounce message size" | |
168e428f | 12109 | This option sets a limit in bytes on the size of messages that are returned to |
9b371988 PH |
12110 | senders as part of bounce messages when &%bounce_return_message%& is true. The |
12111 | limit should be less than the value of the global &%message_size_limit%& and of | |
12112 | any &%message_size_limit%& settings on transports, to allow for the bounce text | |
168e428f PH |
12113 | that Exim generates. If this option is set to zero there is no limit. |
12114 | ||
12115 | When the body of any message that is to be included in a bounce message is | |
12116 | greater than the limit, it is truncated, and a comment pointing this out is | |
12117 | added at the top. The actual cutoff may be greater than the value given, owing | |
12118 | to the use of buffering for transferring the message in chunks (typically 8K in | |
12119 | size). The idea is to save bandwidth on those undeliverable 15-megabyte | |
12120 | messages. | |
12121 | ||
9b371988 PH |
12122 | .option bounce_sender_authentication main string unset |
12123 | .cindex "bounce message" "sender authentication" | |
12124 | .cindex "authentication" "bounce message" | |
12125 | .cindex "AUTH" "on bounce message" | |
168e428f PH |
12126 | This option provides an authenticated sender address that is sent with any |
12127 | bounce messages generated by Exim that are sent over an authenticated SMTP | |
12128 | connection. A typical setting might be: | |
9b371988 PH |
12129 | .code |
12130 | bounce_sender_authentication = mailer-daemon@my.domain.example | |
12131 | .endd | |
168e428f | 12132 | which would cause bounce messages to be sent using the SMTP command: |
9b371988 PH |
12133 | .code |
12134 | MAIL FROM:<> AUTH=mailer-daemon@my.domain.example | |
12135 | .endd | |
12136 | The value of &%bounce_sender_authentication%& must always be a complete email | |
168e428f PH |
12137 | address. |
12138 | ||
9b371988 PH |
12139 | .option callout_domain_negative_expire main time 3h |
12140 | .cindex "caching" "callout timeouts" | |
12141 | .cindex "callout" "caching timeouts" | |
168e428f | 12142 | This option specifies the expiry time for negative callout cache data for a |
9b371988 PH |
12143 | domain. See section &<<SECTcallver>>& for details of callout verification, and |
12144 | section &<<SECTcallvercache>>& for details of the caching. | |
168e428f | 12145 | |
168e428f | 12146 | |
9b371988 | 12147 | .option callout_domain_positive_expire main time 7d |
168e428f | 12148 | This option specifies the expiry time for positive callout cache data for a |
9b371988 PH |
12149 | domain. See section &<<SECTcallver>>& for details of callout verification, and |
12150 | section &<<SECTcallvercache>>& for details of the caching. | |
168e428f PH |
12151 | |
12152 | ||
9b371988 | 12153 | .option callout_negative_expire main time 2h |
168e428f | 12154 | This option specifies the expiry time for negative callout cache data for an |
9b371988 PH |
12155 | address. See section &<<SECTcallver>>& for details of callout verification, and |
12156 | section &<<SECTcallvercache>>& for details of the caching. | |
168e428f | 12157 | |
168e428f | 12158 | |
9b371988 | 12159 | .option callout_positive_expire main time 24h |
168e428f | 12160 | This option specifies the expiry time for positive callout cache data for an |
9b371988 PH |
12161 | address. See section &<<SECTcallver>>& for details of callout verification, and |
12162 | section &<<SECTcallvercache>>& for details of the caching. | |
168e428f | 12163 | |
168e428f | 12164 | |
9b371988 PH |
12165 | .option callout_random_local_part main string&!! "see below" |
12166 | This option defines the &"random"& local part that can be used as part of | |
12167 | callout verification. The default value is | |
12168 | .code | |
12169 | $primary_host_name-$tod_epoch-testing | |
12170 | .endd | |
12171 | See section &<<CALLaddparcall>>& for details of how this value is used. | |
168e428f | 12172 | |
168e428f | 12173 | |
9b371988 PH |
12174 | .option check_log_inodes main integer 0 |
12175 | See &%check_spool_space%& below. | |
168e428f PH |
12176 | |
12177 | ||
9b371988 PH |
12178 | .option check_log_space main integer 0 |
12179 | See &%check_spool_space%& below. | |
d1e83bff | 12180 | |
9b371988 PH |
12181 | .oindex "&%check_rfc2047_length%&" |
12182 | .cindex "RFC 2047" "disabling length check" | |
12183 | .option check_rfc2047_length " User: main" boolean true | |
d1e83bff | 12184 | RFC 2047 defines a way of encoding non-ASCII characters in headers using a |
9b371988 | 12185 | system of &"encoded words"&. The RFC specifies a maximum length for an encoded |
d1e83bff PH |
12186 | word; strings to be encoded that exceed this length are supposed to use |
12187 | multiple encoded words. By default, Exim does not recognize encoded words that | |
12188 | exceed the maximum length. However, it seems that some software, in violation | |
9b371988 PH |
12189 | of the RFC, generates overlong encoded words. If &%check_rfc2047_length%& is |
12190 | set false, Exim recognizes encoded words of any length. | |
168e428f | 12191 | |
168e428f | 12192 | |
9b371988 PH |
12193 | .option check_spool_inodes main integer 0 |
12194 | See &%check_spool_space%& below. | |
168e428f PH |
12195 | |
12196 | ||
9b371988 PH |
12197 | .option check_spool_space main integer 0 |
12198 | .cindex "checking disk space" | |
12199 | .cindex "disk space" "checking" | |
12200 | .cindex "spool directory" "checking space" | |
12201 | The four &%check_...%& options allow for checking of disk resources before a | |
168e428f PH |
12202 | message is accepted. |
12203 | ||
9b371988 PH |
12204 | .cindex "&$log_inodes$&" |
12205 | .cindex "&$log_space$&" | |
12206 | .cindex "&$spool_inodes$&" | |
12207 | .cindex "&$spool_space$&" | |
168e428f | 12208 | When any of these options are set, they apply to all incoming messages. If you |
068aaea8 | 12209 | want to apply different checks to different kinds of message, you can do so by |
9b371988 PH |
12210 | testing the the variables &$log_inodes$&, &$log_space$&, &$spool_inodes$&, and |
12211 | &$spool_space$& in an ACL with appropriate additional conditions. | |
168e428f PH |
12212 | |
12213 | ||
9b371988 | 12214 | &%check_spool_space%& and &%check_spool_inodes%& check the spool partition if |
168e428f | 12215 | either value is greater than zero, for example: |
9b371988 PH |
12216 | .code |
12217 | check_spool_space = 10M | |
12218 | check_spool_inodes = 100 | |
12219 | .endd | |
168e428f | 12220 | The spool partition is the one that contains the directory defined by |
9b371988 | 12221 | SPOOL_DIRECTORY in &_Local/Makefile_&. It is used for holding messages in |
168e428f PH |
12222 | transit. |
12223 | ||
9b371988 | 12224 | &%check_log_space%& and &%check_log_inodes%& check the partition in which log |
168e428f | 12225 | files are written if either is greater than zero. These should be set only if |
9b371988 | 12226 | &%log_file_path%& and &%spool_directory%& refer to different partitions. |
168e428f PH |
12227 | |
12228 | If there is less space or fewer inodes than requested, Exim refuses to accept | |
12229 | incoming mail. In the case of SMTP input this is done by giving a 452 temporary | |
12230 | error response to the MAIL command. If ESMTP is in use and there was a | |
12231 | SIZE parameter on the MAIL command, its value is added to the | |
9b371988 PH |
12232 | &%check_spool_space%& value, and the check is performed even if |
12233 | &%check_spool_space%& is zero, unless &%no_smtp_check_spool_space%& is set. | |
168e428f | 12234 | |
9b371988 | 12235 | The values for &%check_spool_space%& and &%check_log_space%& are held as a |
168e428f PH |
12236 | number of kilobytes. If a non-multiple of 1024 is specified, it is rounded up. |
12237 | ||
12238 | For non-SMTP input and for batched SMTP input, the test is done at start-up; on | |
12239 | failure a message is written to stderr and Exim exits with a non-zero code, as | |
12240 | it obviously cannot send an error message of any kind. | |
12241 | ||
9b371988 PH |
12242 | .option daemon_smtp_ports main string &`smtp`& |
12243 | .cindex "port" "for daemon" | |
12244 | .cindex "TCP/IP" "setting listening ports" | |
168e428f | 12245 | This option specifies one or more default SMTP ports on which the Exim daemon |
9b371988 PH |
12246 | listens. See chapter &<<CHAPinterfaces>>& for details of how it is used. For |
12247 | backward compatibility, &%daemon_smtp_port%& (singular) is a synonym. | |
068aaea8 | 12248 | |
9b371988 PH |
12249 | .new |
12250 | .option daemon_startup_retries main integer 9 | |
12251 | .cindex "daemon startup" "retrying" | |
12252 | This option, along with &%daemon_startup_sleep%&, controls the retrying done by | |
068aaea8 | 12253 | the daemon at startup when it cannot immediately bind a listening socket |
9b371988 | 12254 | (typically because the socket is already in use): &%daemon_startup_retries%& |
068aaea8 | 12255 | defines the number of retries after the first failure, and |
9b371988 | 12256 | &%daemon_startup_sleep%& defines the length of time to wait between retries. |
068aaea8 | 12257 | |
9b371988 PH |
12258 | .option daemon_startup_sleep main time 30s |
12259 | See &%daemon_startup_retries%&. | |
12260 | .wen | |
068aaea8 | 12261 | |
9b371988 PH |
12262 | .option delay_warning main "time list" 24h |
12263 | .cindex "warning of delay" | |
12264 | .cindex "delay warning" "specifying" | |
168e428f PH |
12265 | When a message is delayed, Exim sends a warning message to the sender at |
12266 | intervals specified by this option. The data is a colon-separated list of times | |
9b371988 PH |
12267 | after which to send warning messages. If the value of the option is an empty |
12268 | string or a zero time, no warnings are sent. Up to 10 times may be given. If a | |
12269 | message has been on the queue for longer than the last time, the last interval | |
12270 | between the times is used to compute subsequent warning times. For example, | |
12271 | with | |
12272 | .code | |
12273 | delay_warning = 4h:8h:24h | |
12274 | .endd | |
168e428f PH |
12275 | the first message is sent after 4 hours, the second after 8 hours, and |
12276 | the third one after 24 hours. After that, messages are sent every 16 hours, | |
12277 | because that is the interval between the last two times on the list. If you set | |
12278 | just one time, it specifies the repeat interval. For example, with: | |
9b371988 PH |
12279 | .code |
12280 | delay_warning = 6h | |
12281 | .endd | |
168e428f PH |
12282 | messages are repeated every six hours. To stop warnings after a given time, set |
12283 | a very large time at the end of the list. For example: | |
9b371988 PH |
12284 | .code |
12285 | delay_warning = 2h:12h:99d | |
12286 | .endd | |
168e428f | 12287 | |
9b371988 PH |
12288 | .option delay_warning_condition main string&!! "see below" |
12289 | .cindex "&$domain$&" | |
168e428f | 12290 | The string is expanded at the time a warning message might be sent. If all the |
9b371988 PH |
12291 | deferred addresses have the same domain, it is set in &$domain$& during the |
12292 | expansion. Otherwise &$domain$& is empty. If the result of the expansion is a | |
12293 | forced failure, an empty string, or a string matching any of &"0"&, &"no"& or | |
12294 | &"false"& (the comparison being done caselessly) then the warning message is | |
12295 | not sent. The default is | |
12296 | .code | |
168e428f PH |
12297 | delay_warning_condition = \ |
12298 | ${if match{$h_precedence:}{(?i)bulk|list|junk}{no}{yes}} | |
9b371988 PH |
12299 | .endd |
12300 | which suppresses the sending of warnings about messages that have &"bulk"&, | |
12301 | &"list"& or &"junk"& in a &'Precedence:'& header. | |
168e428f | 12302 | |
9b371988 PH |
12303 | .option deliver_drop_privilege main boolean false |
12304 | .cindex "unprivileged delivery" | |
12305 | .cindex "delivery" "unprivileged" | |
168e428f PH |
12306 | If this option is set true, Exim drops its root privilege at the start of a |
12307 | delivery process, and runs as the Exim user throughout. This severely restricts | |
12308 | the kinds of local delivery that are possible, but is viable in certain types | |
12309 | of configuration. There is a discussion about the use of root privilege in | |
9b371988 | 12310 | chapter &<<CHAPsecurity>>&. |
168e428f | 12311 | |
9b371988 PH |
12312 | .option deliver_queue_load_max main fixed-point unset |
12313 | .cindex "load average" | |
12314 | .cindex "queue runner" "abandoning" | |
168e428f PH |
12315 | When this option is set, a queue run is abandoned if the system load average |
12316 | becomes greater than the value of the option. The option has no effect on | |
12317 | ancient operating systems on which Exim cannot determine the load average. | |
9b371988 | 12318 | See also &%queue_only_load%& and &%smtp_load_reserve%&. |
168e428f | 12319 | |
168e428f | 12320 | |
9b371988 PH |
12321 | .option delivery_date_remove main boolean true |
12322 | .cindex "&'Delivery-date:'& header line" | |
12323 | Exim's transports have an option for adding a &'Delivery-date:'& header to a | |
12324 | message when it is delivered, in exactly the same way as &'Return-path:'& is | |
12325 | handled. &'Delivery-date:'& records the actual time of delivery. Such headers | |
168e428f PH |
12326 | should not be present in incoming messages, and this option causes them to be |
12327 | removed at the time the message is received, to avoid any problems that might | |
12328 | occur when a delivered message is subsequently sent on to some other recipient. | |
12329 | ||
9b371988 PH |
12330 | .option dns_again_means_nonexist main "domain list&!!" unset |
12331 | .cindex "DNS" "&""try again""& response; overriding" | |
12332 | DNS lookups give a &"try again"& response for the DNS errors | |
12333 | &"non-authoritative host not found"& and &"SERVERFAIL"&. This can cause Exim to | |
12334 | keep trying to deliver a message, or to give repeated temporary errors to | |
12335 | incoming mail. Sometimes the effect is caused by a badly set up name server and | |
12336 | may persist for a long time. If a domain which exhibits this problem matches | |
12337 | anything in &%dns_again_means_nonexist%&, it is treated as if it did not exist. | |
12338 | This option should be used with care. You can make it apply to reverse lookups | |
12339 | by a setting such as this: | |
12340 | .code | |
12341 | dns_again_means_nonexist = *.in-addr.arpa | |
12342 | .endd | |
12343 | This option applies to all DNS lookups that Exim does. The &(dnslookup)& router | |
168e428f PH |
12344 | has some options of its own for controlling what happens when lookups for MX or |
12345 | SRV records give temporary errors. These more specific options are applied | |
12346 | after the global option. | |
12347 | ||
9b371988 PH |
12348 | .option dns_check_names_pattern main string "see below" |
12349 | .cindex "DNS" "pre-check of name syntax" | |
168e428f PH |
12350 | When this option is set to a non-empty string, it causes Exim to check domain |
12351 | names for illegal characters before handing them to the DNS resolver, because | |
12352 | some resolvers give temporary errors for malformed names. If a domain name | |
9b371988 | 12353 | contains any illegal characters, a &"not found"& result is forced, and the |
168e428f PH |
12354 | resolver is not called. The check is done by matching the domain name against a |
12355 | regular expression, which is the value of this option. The default pattern is | |
9b371988 | 12356 | .code |
168e428f PH |
12357 | dns_check_names_pattern = \ |
12358 | (?i)^(?>(?(1)\.|())[^\W_](?>[a-z0-9-]*[^\W_])?)+$ | |
9b371988 | 12359 | .endd |
168e428f PH |
12360 | which permits only letters, digits, and hyphens in components, but they may not |
12361 | start or end with a hyphen. | |
9b371988 | 12362 | If you set &%allow_utf8_domains%&, you must modify this pattern, or set the |
168e428f PH |
12363 | option to an empty string. |
12364 | ||
9b371988 PH |
12365 | .new |
12366 | .option dns_csa_search_limit main integer 5 | |
068aaea8 | 12367 | This option controls the depth of parental searching for CSA SRV records in the |
9b371988 | 12368 | DNS, as described in more detail in section &<<SECTverifyCSA>>&. |
068aaea8 | 12369 | |
9b371988 | 12370 | .option dns_csa_use_reverse main boolean true |
068aaea8 PH |
12371 | This option controls whether or not an IP address, given as a CSA domain, is |
12372 | reversed and looked up in the reverse DNS, as described in more detail in | |
9b371988 PH |
12373 | section &<<SECTverifyCSA>>&. |
12374 | .wen | |
068aaea8 | 12375 | |
9b371988 PH |
12376 | .option dns_ipv4_lookup main "domain list&!!" unset |
12377 | .cindex "IPv6" "DNS lookup for AAAA records" | |
12378 | .cindex "DNS" "IPv6 lookup for AAAA records" | |
168e428f PH |
12379 | When Exim is compiled with IPv6 support, it looks for IPv6 address records |
12380 | (AAAA and, if configured, A6) as well as IPv4 address records when trying to | |
12381 | find IP addresses for hosts, unless the host's domain matches this list. | |
12382 | ||
12383 | This is a fudge to help with name servers that give big delays or otherwise do | |
12384 | not work for the new IPv6 record types. If Exim is handed an IPv6 address | |
12385 | record as a result of an MX lookup, it always recognizes it, and may as a | |
12386 | result make an outgoing IPv6 connection. All this option does is to make Exim | |
12387 | look only for IPv4-style A records when it needs to find an IP address for a | |
12388 | host name. In due course, when the world's name servers have all been upgraded, | |
12389 | there should be no need for this option. | |
12390 | ||
12391 | ||
9b371988 PH |
12392 | .option dns_retrans main time 0s |
12393 | .cindex "DNS" "resolver options" | |
12394 | The options &%dns_retrans%& and &%dns_retry%& can be used to set the | |
168e428f PH |
12395 | retransmission and retry parameters for DNS lookups. Values of zero (the |
12396 | defaults) leave the system default settings unchanged. The first value is the | |
12397 | time between retries, and the second is the number of retries. It isn't | |
12398 | totally clear exactly how these settings affect the total time a DNS lookup may | |
12399 | take. I haven't found any documentation about timeouts on DNS lookups; these | |
12400 | parameter values are available in the external resolver interface structure, | |
12401 | but nowhere does it seem to describe how they are used or what you might want | |
12402 | to set in them. | |
12403 | ||
12404 | ||
9b371988 PH |
12405 | .option dns_retry main integer 0 |
12406 | See &%dns_retrans%& above. | |
168e428f | 12407 | |
168e428f | 12408 | |
9b371988 | 12409 | .option drop_cr main boolean false |
168e428f PH |
12410 | This is an obsolete option that is now a no-op. It used to affect the way Exim |
12411 | handled CR and LF characters in incoming messages. What happens now is | |
9b371988 | 12412 | described in section &<<SECTlineendings>>&. |
168e428f | 12413 | |
168e428f | 12414 | |
9b371988 PH |
12415 | .option envelope_to_remove main boolean true |
12416 | .cindex "&'Envelope-to:'& header line" | |
12417 | Exim's transports have an option for adding an &'Envelope-to:'& header to a | |
12418 | message when it is delivered, in exactly the same way as &'Return-path:'& is | |
12419 | handled. &'Envelope-to:'& records the original recipient address from the | |
168e428f PH |
12420 | messages's envelope that caused the delivery to happen. Such headers should not |
12421 | be present in incoming messages, and this option causes them to be removed at | |
12422 | the time the message is received, to avoid any problems that might occur when a | |
12423 | delivered message is subsequently sent on to some other recipient. | |
12424 | ||
12425 | ||
9b371988 PH |
12426 | .option errors_copy main "string list&!!" unset |
12427 | .cindex "bounce message" "copy to other address" | |
12428 | .cindex "copy of bounce message" | |
168e428f | 12429 | Setting this option causes Exim to send bcc copies of bounce messages that it |
9b371988 | 12430 | generates to other addresses. &*Note*&: This does not apply to bounce messages |
168e428f PH |
12431 | coming from elsewhere. The value of the option is a colon-separated list of |
12432 | items. Each item consists of a pattern, terminated by white space, followed by | |
12433 | a comma-separated list of email addresses. If a pattern contains spaces, it | |
12434 | must be enclosed in double quotes. | |
12435 | ||
12436 | Each pattern is processed in the same way as a single item in an address list | |
9b371988 PH |
12437 | (see section &<<SECTaddresslist>>&). When a pattern matches the recipient of |
12438 | the bounce message, the message is copied to the addresses on the list. The | |
12439 | items are scanned in order, and once a matching one is found, no further items | |
12440 | are examined. For example: | |
12441 | .code | |
168e428f PH |
12442 | errors_copy = spqr@mydomain postmaster@mydomain.example :\ |
12443 | rqps@mydomain hostmaster@mydomain.example,\ | |
12444 | postmaster@mydomain.example | |
9b371988 PH |
12445 | .endd |
12446 | .cindex "&$domain$&" | |
12447 | .cindex "&$local_part$&" | |
12448 | The address list is expanded before use. The expansion variables &$local_part$& | |
12449 | and &$domain$& are set from the original recipient of the error message, and if | |
12450 | there was any wildcard matching in the pattern, the expansion | |
12451 | .cindex "numerical variables (&$1$& &$2$& etc)" "in &%errors_copy%&" | |
12452 | variables &$0$&, &$1$&, etc. are set in the normal way. | |
12453 | ||
12454 | ||
12455 | .option errors_reply_to main string unset | |
12456 | .cindex "bounce message" "&'Reply-to:'& in" | |
168e428f | 12457 | Exim's bounce and delivery warning messages contain the header line |
9b371988 PH |
12458 | .display |
12459 | &`From: Mail Delivery System <Mailer-Daemon@`&&'qualify-domain'&&`>`& | |
12460 | .endd | |
12461 | where &'qualify-domain'& is the value of the &%qualify_domain%& option. | |
168e428f | 12462 | Experience shows that people reply to bounce messages. If the |
9b371988 PH |
12463 | &%errors_reply_to%& option is set, a &'Reply-To:'& header is added to bounce |
12464 | and warning messages. For example: | |
12465 | .code | |
12466 | errors_reply_to = postmaster@my.domain.example | |
12467 | .endd | |
168e428f PH |
12468 | The value of the option is not expanded. It must specify a valid RFC 2822 |
12469 | address. | |
12470 | ||
12471 | ||
9b371988 PH |
12472 | .option exim_group main string "compile-time configured" |
12473 | .cindex "gid (group id)" "Exim's own" | |
12474 | .cindex "Exim group" | |
168e428f PH |
12475 | This option changes the gid under which Exim runs when it gives up root |
12476 | privilege. The default value is compiled into the binary. The value of this | |
9b371988 PH |
12477 | option is used only when &%exim_user%& is also set. Unless it consists entirely |
12478 | of digits, the string is looked up using &[getgrnam()]&, and failure causes a | |
12479 | configuration error. See chapter &<<CHAPsecurity>>& for a discussion of | |
12480 | security issues. | |
168e428f | 12481 | |
168e428f | 12482 | |
9b371988 PH |
12483 | .option exim_path main string "see below" |
12484 | .cindex "Exim binary" "path name" | |
168e428f | 12485 | This option specifies the path name of the Exim binary, which is used when Exim |
9b371988 | 12486 | needs to re-exec itself. The default is set up to point to the file &'exim'& in |
168e428f | 12487 | the directory configured at compile time by the BIN_DIRECTORY setting. It |
9b371988 | 12488 | is necessary to change &%exim_path%& if, exceptionally, Exim is run from some |
168e428f | 12489 | other place. |
9b371988 | 12490 | &*Warning*&: Do not use a macro to define the value of this option, because |
168e428f | 12491 | you will break those Exim utilities that scan the configuration file to find |
9b371988 PH |
12492 | where the binary is. (They then use the &%-bP%& option to extract option |
12493 | settings such as the value of &%spool_directory%&.) | |
168e428f PH |
12494 | |
12495 | ||
9b371988 PH |
12496 | .option exim_user main string "compile-time configured" |
12497 | .cindex "uid (user id)" "Exim's own" | |
12498 | .cindex "Exim user" | |
168e428f PH |
12499 | This option changes the uid under which Exim runs when it gives up root |
12500 | privilege. The default value is compiled into the binary. Ownership of the run | |
9b371988 PH |
12501 | time configuration file and the use of the &%-C%& and &%-D%& command line |
12502 | options is checked against the values in the binary, not what is set here. | |
168e428f PH |
12503 | |
12504 | Unless it consists entirely of digits, the string is looked up using | |
9b371988 PH |
12505 | &[getpwnam()]&, and failure causes a configuration error. If &%exim_group%& is |
12506 | not also supplied, the gid is taken from the result of &[getpwnam()]& if it is | |
12507 | used. See chapter &<<CHAPsecurity>>& for a discussion of security issues. | |
168e428f | 12508 | |
168e428f | 12509 | |
9b371988 | 12510 | .option extra_local_interfaces main "string list" unset |
168e428f PH |
12511 | This option defines network interfaces that are to be considered local when |
12512 | routing, but which are not used for listening by the daemon. See section | |
9b371988 | 12513 | &<<SECTreclocipadd>>& for details. |
168e428f | 12514 | |
168e428f | 12515 | |
9b371988 PH |
12516 | .option "extract_addresses_remove_ &~arguments" main boolean true |
12517 | .cindex "&%-t%& option" | |
12518 | .cindex "command line" "addresses with &%-t%&" | |
12519 | .cindex "Sendmail compatibility" "&%-t%& option" | |
168e428f | 12520 | According to some Sendmail documentation (Sun, IRIX, HP-UX), if any addresses |
9b371988 PH |
12521 | are present on the command line when the &%-t%& option is used to build an |
12522 | envelope from a message's &'To:'&, &'Cc:'& and &'Bcc:'& headers, the command | |
12523 | line addresses are removed from the recipients list. This is also how Smail | |
12524 | behaves. However, other Sendmail documentation (the O'Reilly book) states that | |
12525 | command line addresses are added to those obtained from the header lines. When | |
12526 | &%extract_addresses_remove_arguments%& is true (the default), Exim subtracts | |
168e428f PH |
12527 | argument headers. If it is set false, Exim adds rather than removes argument |
12528 | addresses. | |
12529 | ||
12530 | ||
9b371988 PH |
12531 | .option finduser_retries main integer 0 |
12532 | .cindex "NIS" "looking up users; retrying" | |
168e428f | 12533 | On systems running NIS or other schemes in which user and group information is |
9b371988 | 12534 | distributed from a remote system, there can be times when &[getpwnam()]& and |
168e428f | 12535 | related functions fail, even when given valid data, because things time out. |
9b371988 PH |
12536 | Unfortunately these failures cannot be distinguished from genuine &"not found"& |
12537 | errors. If &%finduser_retries%& is set greater than zero, Exim will try that | |
168e428f PH |
12538 | many extra times to find a user or a group, waiting for one second between |
12539 | retries. | |
12540 | ||
9b371988 | 12541 | .cindex "&_/etc/passwd_&" "multiple reading of" |
168e428f | 12542 | You should not set this option greater than zero if your user information is in |
9b371988 | 12543 | a traditional &_/etc/passwd_& file, because it will cause Exim needlessly to |
168e428f PH |
12544 | search the file multiple times for non-existent users, and also cause delay. |
12545 | ||
12546 | ||
12547 | ||
9b371988 PH |
12548 | .option freeze_tell main "string list, comma separated" unset |
12549 | .cindex "freezing messages" "sending a message when freezing" | |
168e428f | 12550 | On encountering certain errors, or when configured to do so in a system filter, |
9b371988 PH |
12551 | ACL, or special router, Exim freezes a message. This means that no further |
12552 | delivery attempts take place until an administrator thaws the message, or the | |
12553 | &%auto_thaw%&, &%ignore_bounce_errors_after%&, or &%timeout_frozen_after%& | |
12554 | feature cause it to be processed. If &%freeze_tell%& is set, Exim generates a | |
12555 | warning message whenever it freezes something, unless the message it is | |
12556 | freezing is a locally-generated bounce message. (Without this exception there | |
12557 | is the possibility of looping.) The warning message is sent to the addresses | |
12558 | supplied as the comma-separated value of this option. If several of the | |
12559 | message's addresses cause freezing, only a single message is sent. If the | |
12560 | freezing was automatic, the reason(s) for freezing can be found in the message | |
12561 | log. If you configure freezing in a filter or ACL, you must arrange for any | |
12562 | logging that you require. | |
12563 | ||
12564 | ||
12565 | .option gecos_name main string&!! unset | |
12566 | .cindex "HP-UX" | |
12567 | .cindex "&""gecos""& field" "parsing" | |
12568 | Some operating systems, notably HP-UX, use the &"gecos"& field in the system | |
168e428f | 12569 | password file to hold other information in addition to users' real names. Exim |
9b371988 PH |
12570 | looks up this field for use when it is creating &'Sender:'& or &'From:'& |
12571 | headers. If either &%gecos_pattern%& or &%gecos_name%& are unset, the contents | |
12572 | of the field are used unchanged, except that, if an ampersand is encountered, | |
12573 | it is replaced by the user's login name with the first character forced to | |
168e428f PH |
12574 | upper case, since this is a convention that is observed on many systems. |
12575 | ||
9b371988 PH |
12576 | When these options are set, &%gecos_pattern%& is treated as a regular |
12577 | expression that is to be applied to the field (again with && replaced by the | |
12578 | login name), and if it matches, &%gecos_name%& is expanded and used as the | |
12579 | user's name. | |
168e428f | 12580 | |
9b371988 PH |
12581 | .cindex "numerical variables (&$1$& &$2$& etc)" "in &%gecos_name%&" |
12582 | Numeric variables such as &$1$&, &$2$&, etc. can be used in the expansion to | |
168e428f PH |
12583 | pick up sub-fields that were matched by the pattern. In HP-UX, where the user's |
12584 | name terminates at the first comma, the following can be used: | |
9b371988 PH |
12585 | .code |
12586 | gecos_pattern = ([^,]*) | |
12587 | gecos_name = $1 | |
12588 | .endd | |
168e428f | 12589 | |
9b371988 PH |
12590 | .option gecos_pattern main string unset |
12591 | See &%gecos_name%& above. | |
168e428f PH |
12592 | |
12593 | ||
9b371988 | 12594 | .option headers_charset main string "see below" |
168e428f | 12595 | This option sets a default character set for translating from encoded MIME |
9b371988 PH |
12596 | &"words"& in header lines, when referenced by an &$h_xxx$& expansion item. The |
12597 | default is the value of HEADERS_CHARSET in &_Local/Makefile_&. The | |
168e428f | 12598 | ultimate default is ISO-8859-1. For more details see the description of header |
9b371988 | 12599 | insertions in section &<<SECTexpansionitems>>&. |
168e428f PH |
12600 | |
12601 | ||
168e428f | 12602 | |
9b371988 PH |
12603 | .option header_maxsize main integer "see below" |
12604 | .cindex "header section" "maximum size of" | |
12605 | .cindex "limit" "size of message header section" | |
168e428f PH |
12606 | This option controls the overall maximum size of a message's header |
12607 | section. The default is the value of HEADER_MAXSIZE in | |
9b371988 | 12608 | &_Local/Makefile_&; the default for that is 1M. Messages with larger header |
168e428f PH |
12609 | sections are rejected. |
12610 | ||
12611 | ||
9b371988 PH |
12612 | .option header_line_maxsize main integer 0 |
12613 | .cindex "header lines" "maximum size of" | |
12614 | .cindex "limit" "size of one header line" | |
168e428f PH |
12615 | This option limits the length of any individual header line in a message, after |
12616 | all the continuations have been joined together. Messages with individual | |
12617 | header lines that are longer than the limit are rejected. The default value of | |
9b371988 | 12618 | zero means &"no limit"&. |
168e428f PH |
12619 | |
12620 | ||
12621 | ||
12622 | ||
9b371988 PH |
12623 | .option helo_accept_junk_hosts main "host list&!!" unset |
12624 | .cindex "HELO" "accepting junk data" | |
12625 | .cindex "EHLO" "accepting junk data" | |
168e428f PH |
12626 | Exim checks the syntax of HELO and EHLO commands for incoming SMTP |
12627 | mail, and gives an error response for invalid data. Unfortunately, there are | |
12628 | some SMTP clients that send syntactic junk. They can be accommodated by setting | |
9b371988 | 12629 | this option. Note that this is a syntax check only. See &%helo_verify_hosts%& |
168e428f | 12630 | if you want to do semantic checking. |
9b371988 | 12631 | See also &%helo_allow_chars%& for a way of extending the permitted character |
168e428f PH |
12632 | set. |
12633 | ||
12634 | ||
9b371988 PH |
12635 | .option helo_allow_chars main string unset |
12636 | .cindex "HELO" "underscores in" | |
12637 | .cindex "EHLO" "underscores in" | |
12638 | .cindex "underscore in EHLO/HELO" | |
168e428f PH |
12639 | This option can be set to a string of rogue characters that are permitted in |
12640 | all EHLO and HELO names in addition to the standard letters, digits, | |
12641 | hyphens, and dots. If you really must allow underscores, you can set | |
9b371988 PH |
12642 | .code |
12643 | helo_allow_chars = _ | |
12644 | .endd | |
168e428f PH |
12645 | Note that the value is one string, not a list. |
12646 | ||
12647 | ||
9b371988 PH |
12648 | .option helo_lookup_domains main "domain list&!!" &`@:@[]`& |
12649 | .cindex "HELO" "forcing reverse lookup" | |
12650 | .cindex "EHLO" "forcing reverse lookup" | |
168e428f PH |
12651 | If the domain given by a client in a HELO or EHLO command matches this |
12652 | list, a reverse lookup is done in order to establish the host's true name. The | |
12653 | default forces a lookup if the client host gives the server's name or any of | |
12654 | its IP addresses (in brackets), something that broken clients have been seen to | |
12655 | do. | |
12656 | ||
12657 | ||
9b371988 PH |
12658 | .option helo_try_verify_hosts main "host list&!!" unset |
12659 | .new | |
12660 | .cindex "HELO verifying" "optional" | |
12661 | .cindex "EHLO verifying" "optional" | |
068aaea8 | 12662 | By default, Exim just checks the syntax of HELO and EHLO commands (see |
9b371988 PH |
12663 | &%helo_accept_junk_hosts%& and &%helo_allow_chars%&). However, some sites like |
12664 | to do more extensive checking of the data supplied by these commands. The ACL | |
12665 | condition &`verify`& &`=`& &`helo`& is provided to make this possible. | |
12666 | Formerly, it was necessary also to set this option (&%helo_try_verify_hosts%&) | |
12667 | to force the check to occur. From release 4.53 onwards, this is no longer | |
12668 | necessary. If the check has not been done before &`verify`& &`=`& &`helo`& is | |
12669 | encountered, it is done at that time. Consequently, this option is obsolete. | |
12670 | Its specification is retained here for backwards compatibility. | |
12671 | ||
068aaea8 | 12672 | When an EHLO or HELO command is received, if the calling host matches |
9b371988 | 12673 | &%helo_try_verify_hosts%&, Exim checks that the host name given in the HELO or |
068aaea8 | 12674 | EHLO command either: |
168e428f | 12675 | |
9b371988 PH |
12676 | .ilist |
12677 | is an IP literal matching the calling address of the host, or | |
12678 | .next | |
12679 | .cindex "DNS" "reverse lookup" | |
12680 | .cindex "reverse DNS lookup" | |
168e428f PH |
12681 | matches the host name that Exim obtains by doing a reverse lookup of the |
12682 | calling host address, or | |
9b371988 PH |
12683 | .next |
12684 | when looked up using &[gethostbyname()]& (or &[getipnodebyname()]& when | |
168e428f | 12685 | available) yields the calling host address. |
9b371988 | 12686 | .endlist |
168e428f PH |
12687 | |
12688 | However, the EHLO or HELO command is not rejected if any of the checks | |
12689 | fail. Processing continues, but the result of the check is remembered, and can | |
9b371988 | 12690 | be detected later in an ACL by the &`verify`& &`=`& &`helo`& condition. |
168e428f | 12691 | |
9b371988 PH |
12692 | .option helo_verify_hosts main "host list&!!" unset |
12693 | .cindex "HELO verifying" "mandatory" | |
12694 | .cindex "EHLO verifying" "mandatory" | |
12695 | Like &%helo_try_verify_hosts%&, this option is obsolete, and retained only for | |
068aaea8 | 12696 | backwards compatibility. For hosts that match this option, Exim checks the host |
9b371988 PH |
12697 | name given in the HELO or EHLO in the same way as for |
12698 | &%helo_try_verify_hosts%&. If the check fails, the HELO or EHLO command is | |
12699 | rejected with a 550 error, and entries are written to the main and reject logs. | |
12700 | If a MAIL command is received before EHLO or HELO, it is rejected with a 503 | |
12701 | error. | |
12702 | .wen | |
168e428f | 12703 | |
9b371988 PH |
12704 | .option hold_domains main "domain list&!!" unset |
12705 | .cindex "domain" "delaying delivery" | |
12706 | .cindex "delivery" "delaying certain domains" | |
168e428f PH |
12707 | This option allows mail for particular domains to be held on the queue |
12708 | manually. The option is overridden if a message delivery is forced with the | |
9b371988 PH |
12709 | &%-M%&, &%-qf%&, &%-Rf%& or &%-Sf%& options, and also while testing or |
12710 | verifying addresses using &%-bt%& or &%-bv%&. Otherwise, if a domain matches an | |
12711 | item in &%hold_domains%&, no routing or delivery for that address is done, and | |
12712 | it is deferred every time the message is looked at. | |
168e428f PH |
12713 | |
12714 | This option is intended as a temporary operational measure for delaying the | |
12715 | delivery of mail while some problem is being sorted out, or some new | |
12716 | configuration tested. If you just want to delay the processing of some | |
9b371988 PH |
12717 | domains until a queue run occurs, you should use &%queue_domains%& or |
12718 | &%queue_smtp_domains%&, not &%hold_domains%&. | |
168e428f | 12719 | |
9b371988 | 12720 | A setting of &%hold_domains%& does not override Exim's code for removing |
168e428f PH |
12721 | messages from the queue if they have been there longer than the longest retry |
12722 | time in any retry rule. If you want to hold messages for longer than the normal | |
12723 | retry times, insert a dummy retry rule with a long retry time. | |
12724 | ||
12725 | ||
9b371988 PH |
12726 | .option host_lookup main "host list&!!" unset |
12727 | .cindex "host name lookup" "forcing" | |
168e428f PH |
12728 | Exim does not look up the name of a calling host from its IP address unless it |
12729 | is required to compare against some host list, or the host matches | |
9b371988 | 12730 | &%helo_try_verify_hosts%& or &%helo_verify_hosts%&, or the host matches this |
168e428f PH |
12731 | option (which normally contains IP addresses rather than host names). The |
12732 | default configuration file contains | |
9b371988 PH |
12733 | .code |
12734 | host_lookup = * | |
12735 | .endd | |
168e428f PH |
12736 | which causes a lookup to happen for all hosts. If the expense of these lookups |
12737 | is felt to be too great, the setting can be changed or removed. | |
12738 | ||
12739 | After a successful reverse lookup, Exim does a forward lookup on the name it | |
12740 | has obtained, to verify that it yields the IP address that it started with. If | |
12741 | this check fails, Exim behaves as if the name lookup failed. | |
12742 | ||
9b371988 PH |
12743 | .cindex "&$host_lookup_failed$&" |
12744 | .cindex "&$sender_host_name$&" | |
12745 | After any kind of failure, the host name (in &$sender_host_name$&) remains | |
12746 | unset, and &$host_lookup_failed$& is set to the string &"1"&. See also | |
12747 | &%dns_again_means_nonexist%&, &%helo_lookup_domains%&, and &`verify`& &`=`& | |
12748 | &`reverse_host_lookup`& in ACLs. | |
168e428f PH |
12749 | |
12750 | ||
9b371988 | 12751 | .option host_lookup_order main "string list" &`bydns:byaddr`& |
168e428f PH |
12752 | This option specifies the order of different lookup methods when Exim is trying |
12753 | to find a host name from an IP address. The default is to do a DNS lookup | |
9b371988 | 12754 | first, and then to try a local lookup (using &[gethostbyaddr()]& or equivalent) |
168e428f PH |
12755 | if that fails. You can change the order of these lookups, or omit one entirely, |
12756 | if you want. | |
12757 | ||
9b371988 | 12758 | &*Warning*&: The &"byaddr"& method does not always yield aliases when there are |
168e428f | 12759 | multiple PTR records in the DNS and the IP address is not listed in |
9b371988 | 12760 | &_/etc/hosts_&. Different operating systems give different results in this |
168e428f PH |
12761 | case. That is why the default tries a DNS lookup first. |
12762 | ||
12763 | ||
12764 | ||
9b371988 PH |
12765 | .option host_reject_connection main "host list&!!" unset |
12766 | .cindex "host" "rejecting connections from" | |
168e428f PH |
12767 | If this option is set, incoming SMTP calls from the hosts listed are rejected |
12768 | as soon as the connection is made. | |
12769 | This option is obsolete, and retained only for backward compatibility, because | |
9b371988 | 12770 | nowadays the ACL specified by &%acl_smtp_connect%& can also reject incoming |
168e428f PH |
12771 | connections immediately. |
12772 | ||
12773 | The ability to give an immediate rejection (either by this option or using an | |
12774 | ACL) is provided for use in unusual cases. Many hosts will just try again, | |
12775 | sometimes without much delay. Normally, it is better to use an ACL to reject | |
12776 | incoming messages at a later stage, such as after RCPT commands. See | |
9b371988 | 12777 | chapter &<<CHAPACL>>&. |
168e428f PH |
12778 | |
12779 | ||
9b371988 PH |
12780 | .option hosts_connection_nolog main "host list&!!" unset |
12781 | .cindex "host" "not logging connections from" | |
168e428f | 12782 | This option defines a list of hosts for which connection logging does not |
9b371988 | 12783 | happen, even though the &%smtp_connection%& log selector is set. For example, |
168e428f PH |
12784 | you might want not to log SMTP connections from local processes, or from |
12785 | 127.0.0.1, or from your local LAN. This option is consulted in the main loop of | |
12786 | the daemon; you should therefore strive to restrict its value to a short inline | |
12787 | list of IP addresses and networks. To disable logging SMTP connections from | |
12788 | local processes, you must create a host list with an empty item. For example: | |
9b371988 PH |
12789 | .code |
12790 | hosts_connection_nolog = : | |
12791 | .endd | |
12792 | If the &%smtp_connection%& log selector is not set, this option has no effect. | |
168e428f PH |
12793 | |
12794 | ||
12795 | ||
9b371988 PH |
12796 | .option hosts_treat_as_local main "domain list&!!" unset |
12797 | .cindex "local host" "domains treated as" | |
12798 | .cindex "host" "treated as local" | |
168e428f PH |
12799 | If this option is set, any host names that match the domain list are treated as |
12800 | if they were the local host when Exim is scanning host lists obtained from MX | |
12801 | records | |
12802 | or other sources. Note that the value of this option is a domain list, not a | |
12803 | host list, because it is always used to check host names, not IP addresses. | |
12804 | ||
12805 | This option also applies when Exim is matching the special items | |
9b371988 PH |
12806 | &`@mx_any`&, &`@mx_primary`&, and &`@mx_secondary`& in a domain list (see |
12807 | section &<<SECTdomainlist>>&), and when checking the &%hosts%& option in the | |
12808 | &(smtp)& transport for the local host (see the &%allow_localhost%& option in | |
12809 | that transport). See also &%local_interfaces%&, &%extra_local_interfaces%&, and | |
12810 | chapter &<<CHAPinterfaces>>&, which contains a discussion about local network | |
12811 | interfaces and recognising the local host. | |
12812 | ||
12813 | ||
12814 | .option ignore_bounce_errors_after main time 10w | |
12815 | .cindex "bounce message" "discarding" | |
12816 | .cindex "discarding bounce message" | |
168e428f PH |
12817 | This option affects the processing of bounce messages that cannot be delivered, |
12818 | that is, those that suffer a permanent delivery failure. (Bounce messages that | |
12819 | suffer temporary delivery failures are of course retried in the usual way.) | |
12820 | ||
12821 | After a permanent delivery failure, bounce messages are frozen, | |
12822 | because there is no sender to whom they can be returned. When a frozen bounce | |
12823 | message has been on the queue for more than the given time, it is unfrozen at | |
12824 | the next queue run, and a further delivery is attempted. If delivery fails | |
12825 | again, the bounce message is discarded. This makes it possible to keep failed | |
12826 | bounce messages around for a shorter time than the normal maximum retry time | |
12827 | for frozen messages. For example, | |
9b371988 PH |
12828 | .code |
12829 | ignore_bounce_errors_after = 12h | |
12830 | .endd | |
168e428f PH |
12831 | retries failed bounce message deliveries after 12 hours, discarding any further |
12832 | failures. If the value of this option is set to a zero time period, bounce | |
12833 | failures are discarded immediately. Setting a very long time (as in the default | |
12834 | value) has the effect of disabling this option. For ways of automatically | |
9b371988 PH |
12835 | dealing with other kinds of frozen message, see &%auto_thaw%& and |
12836 | &%timeout_frozen_after%&. | |
168e428f PH |
12837 | |
12838 | ||
9b371988 PH |
12839 | .option ignore_fromline_hosts main "host list&!!" unset |
12840 | .cindex "&""From""& line" | |
12841 | .cindex "UUCP" "&""From""& line" | |
12842 | Some broken SMTP clients insist on sending a UUCP-like &"From&~"& line before | |
12843 | the headers of a message. By default this is treated as the start of the | |
12844 | message's body, which means that any following headers are not recognized as | |
12845 | such. Exim can be made to ignore it by setting &%ignore_fromline_hosts%& to | |
12846 | match those hosts that insist on sending it. If the sender is actually a local | |
12847 | process rather than a remote host, and is using &%-bs%& to inject the messages, | |
12848 | &%ignore_fromline_local%& must be set to achieve this effect. | |
168e428f | 12849 | |
168e428f | 12850 | |
9b371988 PH |
12851 | .option ignore_fromline_local main boolean false |
12852 | See &%ignore_fromline_hosts%& above. | |
168e428f | 12853 | |
168e428f | 12854 | |
9b371988 | 12855 | .option keep_malformed main time 4d |
168e428f PH |
12856 | This option specifies the length of time to keep messages whose spool files |
12857 | have been corrupted in some way. This should, of course, never happen. At the | |
12858 | next attempt to deliver such a message, it gets removed. The incident is | |
12859 | logged. | |
12860 | ||
12861 | ||
9b371988 PH |
12862 | .option ldap_default_servers main "string list" unset |
12863 | .cindex "LDAP" "default servers" | |
168e428f | 12864 | This option provides a list of LDAP servers which are tried in turn when an |
9b371988 PH |
12865 | LDAP query does not contain a server. See section &<<SECTforldaque>>& for |
12866 | details of LDAP queries. This option is available only when Exim has been built | |
12867 | with LDAP support. | |
168e428f | 12868 | |
168e428f | 12869 | |
9b371988 PH |
12870 | .option ldap_version main integer unset |
12871 | .cindex "LDAP protocol version" "forcing" | |
168e428f | 12872 | This option can be used to force Exim to set a specific protocol version for |
9b371988 | 12873 | LDAP. If it option is unset, it is shown by the &%-bP%& command line option as |
168e428f PH |
12874 | -1. When this is the case, the default is 3 if LDAP_VERSION3 is defined in |
12875 | the LDAP headers; otherwise it is 2. This option is available only when Exim | |
12876 | has been built with LDAP support. | |
12877 | ||
12878 | ||
12879 | ||
9b371988 PH |
12880 | .option local_from_check main boolean true |
12881 | .cindex "&'Sender:'& header line" "disabling addition of" | |
12882 | .cindex "&'From:'& header line" "disabling checking of" | |
168e428f | 12883 | When a message is submitted locally (that is, not over a TCP/IP connection) by |
9b371988 PH |
12884 | an untrusted user, Exim removes any existing &'Sender:'& header line, and |
12885 | checks that the &'From:'& header line matches the login of the calling user and | |
12886 | the domain specified by &%qualify_domain%&. | |
168e428f | 12887 | |
9b371988 | 12888 | &*Note*&: An unqualified address (no domain) in the &'From:'& header in a |
168e428f | 12889 | locally submitted message is automatically qualified by Exim, unless the |
9b371988 | 12890 | &%-bnq%& command line option is used. |
168e428f | 12891 | |
9b371988 PH |
12892 | You can use &%local_from_prefix%& and &%local_from_suffix%& to permit affixes |
12893 | on the local part. If the &'From:'& header line does not match, Exim adds a | |
12894 | &'Sender:'& header with an address constructed from the calling user's login | |
12895 | and the default qualify domain. | |
168e428f | 12896 | |
9b371988 PH |
12897 | If &%local_from_check%& is set false, the &'From:'& header check is disabled, |
12898 | and no &'Sender:'& header is ever added. If, in addition, you want to retain | |
12899 | &'Sender:'& header lines supplied by untrusted users, you must also set | |
12900 | &%local_sender_retain%& to be true. | |
168e428f | 12901 | |
9b371988 | 12902 | .cindex "envelope sender" |
168e428f PH |
12903 | These options affect only the header lines in the message. The envelope sender |
12904 | is still forced to be the login id at the qualify domain unless | |
9b371988 | 12905 | &%untrusted_set_sender%& permits the user to supply an envelope sender. |
168e428f | 12906 | |
9b371988 PH |
12907 | For messages received over TCP/IP, an ACL can specify &"submission mode"& to |
12908 | request similar header line checking. See section &<<SECTthesenhea>>&, which | |
12909 | has more details about &'Sender:'& processing. | |
168e428f PH |
12910 | |
12911 | ||
12912 | ||
12913 | ||
9b371988 PH |
12914 | .option local_from_prefix main string unset |
12915 | When Exim checks the &'From:'& header line of locally submitted messages for | |
12916 | matching the login id (see &%local_from_check%& above), it can be configured to | |
168e428f | 12917 | ignore certain prefixes and suffixes in the local part of the address. This is |
9b371988 PH |
12918 | done by setting &%local_from_prefix%& and/or &%local_from_suffix%& to |
12919 | appropriate lists, in the same form as the &%local_part_prefix%& and | |
12920 | &%local_part_suffix%& router options (see chapter &<<CHAProutergeneric>>&). For | |
168e428f | 12921 | example, if |
9b371988 PH |
12922 | .code |
12923 | local_from_prefix = *- | |
12924 | .endd | |
12925 | is set, a &'From:'& line containing | |
12926 | .code | |
12927 | From: anything-user@your.domain.example | |
12928 | .endd | |
12929 | will not cause a &'Sender:'& header to be added if &'user@your.domain.example'& | |
168e428f PH |
12930 | matches the actual sender address that is constructed from the login name and |
12931 | qualify domain. | |
12932 | ||
12933 | ||
9b371988 PH |
12934 | .option local_from_suffix main string unset |
12935 | See &%local_from_prefix%& above. | |
168e428f PH |
12936 | |
12937 | ||
9b371988 | 12938 | .option local_interfaces main "string list" "see below" |
168e428f PH |
12939 | This option controls which network interfaces are used by the daemon for |
12940 | listening; they are also used to identify the local host when routing. Chapter | |
9b371988 PH |
12941 | &<<CHAPinterfaces>>& contains a full description of this option and the related |
12942 | options &%daemon_smtp_ports%&, &%extra_local_interfaces%&, | |
12943 | &%hosts_treat_as_local%&, and &%tls_on_connect_ports%&. The default value for | |
12944 | &%local_interfaces%& is | |
12945 | .code | |
12946 | local_interfaces = 0.0.0.0 | |
12947 | .endd | |
168e428f | 12948 | when Exim is built without IPv6 support; otherwise it is |
9b371988 PH |
12949 | .code |
12950 | local_interfaces = <; ::0 ; 0.0.0.0 | |
12951 | .endd | |
168e428f | 12952 | |
9b371988 PH |
12953 | .option local_scan_timeout main time 5m |
12954 | .cindex "timeout" "for &[local_scan()]& function" | |
12955 | .cindex "&[local_scan()]& function" "timeout" | |
12956 | This timeout applies to the &[local_scan()]& function (see chapter | |
12957 | &<<CHAPlocalscan>>&). Zero means &"no timeout"&. If the timeout is exceeded, | |
12958 | the incoming message is rejected with a temporary error if it is an SMTP | |
12959 | message. For a non-SMTP message, the message is dropped and Exim ends with a | |
12960 | non-zero code. The incident is logged on the main and reject logs. | |
168e428f PH |
12961 | |
12962 | ||
168e428f | 12963 | |
9b371988 PH |
12964 | .option local_sender_retain main boolean false |
12965 | .cindex "&'Sender:'& header line" "retaining from local submission" | |
168e428f | 12966 | When a message is submitted locally (that is, not over a TCP/IP connection) by |
9b371988 PH |
12967 | an untrusted user, Exim removes any existing &'Sender:'& header line. If you |
12968 | do not want this to happen, you must set &%local_sender_retain%&, and you must | |
12969 | also set &%local_from_check%& to be false (Exim will complain if you do not). | |
12970 | See also the ACL modifier &`control = suppress_local_fixups`&. Section | |
12971 | &<<SECTthesenhea>>& has more details about &'Sender:'& processing. | |
168e428f PH |
12972 | |
12973 | ||
12974 | ||
168e428f | 12975 | |
9b371988 PH |
12976 | .option localhost_number main string&!! unset |
12977 | .cindex "host" "locally unique number for" | |
12978 | .cindex "message ids" "with multiple hosts" | |
12979 | .cindex "&$localhost_number$&" | |
168e428f PH |
12980 | Exim's message ids are normally unique only within the local host. If |
12981 | uniqueness among a set of hosts is required, each host must set a different | |
9b371988 | 12982 | value for the &%localhost_number%& option. The string is expanded immediately |
168e428f PH |
12983 | after reading the configuration file (so that a number can be computed from the |
12984 | host name, for example) and the result of the expansion must be a number in the | |
9b371988 PH |
12985 | range 0&--16 (or 0&--10 on operating systems with case-insensitive file |
12986 | systems). This is available in subsequent string expansions via the variable | |
12987 | &$localhost_number$&. When &%localhost_number is set%&, the final two | |
168e428f PH |
12988 | characters of the message id, instead of just being a fractional part of the |
12989 | time, are computed from the time and the local host number as described in | |
9b371988 | 12990 | section &<<SECTmessiden>>&. |
168e428f PH |
12991 | |
12992 | ||
12993 | ||
9b371988 PH |
12994 | .option log_file_path main "string list&!!" "set at compile time" |
12995 | .cindex "log" "file path for" | |
168e428f PH |
12996 | This option sets the path which is used to determine the names of Exim's log |
12997 | files, or indicates that logging is to be to syslog, or both. It is expanded | |
12998 | when Exim is entered, so it can, for example, contain a reference to the host | |
12999 | name. If no specific path is set for the log files at compile or run time, they | |
9b371988 PH |
13000 | are written in a sub-directory called &_log_& in Exim's spool directory. |
13001 | Chapter &<<CHAPlog>>& contains further details about Exim's logging, and | |
13002 | section &<<SECTwhelogwri>>& describes how the contents of &%log_file_path%& are | |
13003 | used. If this string is fixed at your installation (contains no expansion | |
13004 | variables) it is recommended that you do not set this option in the | |
13005 | configuration file, but instead supply the path using LOG_FILE_PATH in | |
13006 | &_Local/Makefile_& so that it is available to Exim for logging errors detected | |
13007 | early on &-- in particular, failure to read the configuration file. | |
13008 | ||
13009 | ||
13010 | .option log_selector main string unset | |
13011 | .cindex "log" "selectors" | |
168e428f PH |
13012 | This option can be used to reduce or increase the number of things that Exim |
13013 | writes to its log files. Its argument is made up of names preceded by plus or | |
13014 | minus characters. For example: | |
9b371988 PH |
13015 | .code |
13016 | log_selector = +arguments -retry_defer | |
13017 | .endd | |
168e428f | 13018 | A list of possible names and what they control is given in the chapter on |
9b371988 | 13019 | logging, in section &<<SECTlogselector>>&. |
168e428f PH |
13020 | |
13021 | ||
9b371988 PH |
13022 | .option log_timezone main boolean false |
13023 | .cindex "log" "timezone for entries" | |
13024 | .cindex "&$tod_log$&" | |
13025 | .cindex "&$tod_zone$&" | |
168e428f PH |
13026 | By default, the timestamps on log lines are in local time without the |
13027 | timezone. This means that if your timezone changes twice a year, the timestamps | |
13028 | in log lines are ambiguous for an hour when the clocks go back. One way of | |
13029 | avoiding this problem is to set the timezone to UTC. An alternative is to set | |
9b371988 | 13030 | &%log_timezone%& true. This turns on the addition of the timezone offset to |
168e428f PH |
13031 | timestamps in log lines. Turning on this option can add quite a lot to the size |
13032 | of log files because each line is extended by 6 characters. Note that the | |
9b371988 PH |
13033 | &$tod_log$& variable contains the log timestamp without the zone, but there is |
13034 | another variable called &$tod_zone$& that contains just the timezone offset. | |
168e428f | 13035 | |
168e428f | 13036 | |
9b371988 PH |
13037 | .option lookup_open_max main integer 25 |
13038 | .cindex "too many open files" | |
13039 | .cindex "open files" "too many" | |
13040 | .cindex "file" "too many open" | |
13041 | .cindex "lookup" "maximum open files" | |
13042 | .cindex "limit" "open files for lookups" | |
168e428f | 13043 | This option limits the number of simultaneously open files for single-key |
9b371988 PH |
13044 | lookups that use regular files (that is, &(lsearch)&, &(dbm)&, and &(cdb)&). |
13045 | Exim normally keeps these files open during routing, because often the same | |
13046 | file is required several times. If the limit is reached, Exim closes the least | |
13047 | recently used file. Note that if you are using the &'ndbm'& library, it | |
13048 | actually opens two files for each logical DBM database, though it still counts | |
13049 | as one for the purposes of &%lookup_open_max%&. If you are getting &"too many | |
13050 | open files"& errors with NDBM, you need to reduce the value of | |
13051 | &%lookup_open_max%&. | |
13052 | ||
13053 | ||
13054 | .option max_username_length main integer 0 | |
13055 | .cindex "length of login name" | |
13056 | .cindex "user name" "maximum length" | |
13057 | .cindex "limit" "user name length" | |
168e428f | 13058 | Some operating systems are broken in that they truncate long arguments to |
9b371988 PH |
13059 | &[getpwnam()]& to eight characters, instead of returning &"no such user"&. If |
13060 | this option is set greater than zero, any attempt to call &[getpwnam()]& with | |
13061 | an argument that is longer behaves as if &[getpwnam()]& failed. | |
168e428f PH |
13062 | |
13063 | ||
168e428f | 13064 | |
9b371988 PH |
13065 | .option message_body_visible main integer 500 |
13066 | .cindex "body of message" "visible size" | |
13067 | .cindex "message body" "visible size" | |
13068 | .cindex "&$message_body$&" | |
13069 | .cindex "&$message_body_end$&" | |
168e428f | 13070 | This option specifies how much of a message's body is to be included in the |
9b371988 | 13071 | &$message_body$& and &$message_body_end$& expansion variables. |
168e428f PH |
13072 | |
13073 | ||
9b371988 PH |
13074 | .option message_id_header_domain main string&!! unset |
13075 | .cindex "&'Message-ID:'& header line" | |
168e428f | 13076 | If this option is set, the string is expanded and used as the right hand side |
9b371988 PH |
13077 | (domain) of the &'Message-ID:'& header that Exim creates if a |
13078 | locally-originated incoming message does not have one. &"Locally-originated"& | |
13079 | means &"not received over TCP/IP."& | |
168e428f PH |
13080 | Otherwise, the primary host name is used. |
13081 | Only letters, digits, dot and hyphen are accepted; any other characters are | |
13082 | replaced by hyphens. If the expansion is forced to fail, or if the result is an | |
13083 | empty string, the option is ignored. | |
13084 | ||
13085 | ||
9b371988 | 13086 | .option message_id_header_text main string&!! unset |
168e428f | 13087 | If this variable is set, the string is expanded and used to augment the text of |
9b371988 | 13088 | the &'Message-id:'& header that Exim creates if a locally-originated incoming |
068aaea8 PH |
13089 | message does not have one. The text of this header is required by RFC 2822 to |
13090 | take the form of an address. By default, Exim uses its internal message id as | |
13091 | the local part, and the primary host name as the domain. If this option is set, | |
13092 | it is expanded, and provided the expansion is not forced to fail, and does not | |
13093 | yield an empty string, the result is inserted into the header immediately | |
13094 | before the @, separated from the internal message id by a dot. Any characters | |
13095 | that are illegal in an address are automatically converted into hyphens. This | |
9b371988 | 13096 | means that variables such as &$tod_log$& can be used, because the spaces and |
068aaea8 | 13097 | colons will become hyphens. |
168e428f PH |
13098 | |
13099 | ||
9b371988 PH |
13100 | .option message_logs main boolean true |
13101 | .cindex "message log" "disabling" | |
13102 | .cindex "log" "message log; disabling" | |
168e428f | 13103 | If this option is turned off, per-message log files are not created in the |
9b371988 | 13104 | &_msglog_& spool sub-directory. This reduces the amount of disk I/O required by |
168e428f PH |
13105 | Exim, by reducing the number of files involved in handling a message from a |
13106 | minimum of four (header spool file, body spool file, delivery journal, and | |
13107 | per-message log) to three. The other major I/O activity is Exim's main log, | |
13108 | which is not affected by this option. | |
13109 | ||
13110 | ||
9b371988 PH |
13111 | .option message_size_limit main string&!! 50M |
13112 | .cindex "message" "size limit" | |
13113 | .cindex "limit" "message size" | |
13114 | .cindex "size of message" "limit" | |
168e428f PH |
13115 | This option limits the maximum size of message that Exim will process. The |
13116 | value is expanded for each incoming | |
13117 | connection so, for example, it can be made to depend on the IP address of the | |
9b371988 | 13118 | remote host for messages arriving via TCP/IP. &*Note*&: This limit cannot be |
168e428f PH |
13119 | made to depend on a message's sender or any other properties of an individual |
13120 | message, because it has to be advertised in the server's response to EHLO. | |
13121 | String expansion failure causes a temporary error. A value of zero means no | |
9b371988 | 13122 | limit, but its use is not recommended. See also &%bounce_return_size_limit%&. |
168e428f PH |
13123 | |
13124 | Incoming SMTP messages are failed with a 552 error if the limit is | |
13125 | exceeded; locally-generated messages either get a stderr message or a delivery | |
9b371988 PH |
13126 | failure message to the sender, depending on the &%-oe%& setting. Rejection of |
13127 | an oversized message is logged in both the main and the reject logs. See also | |
13128 | the generic transport option &%message_size_limit%&, which limits the size of | |
168e428f PH |
13129 | message that an individual transport can process. |
13130 | ||
13131 | ||
9b371988 PH |
13132 | .option move_frozen_messages main boolean false |
13133 | .cindex "frozen messages" "moving" | |
168e428f | 13134 | This option, which is available only if Exim has been built with the setting |
9b371988 PH |
13135 | .code |
13136 | SUPPORT_MOVE_FROZEN_MESSAGES=yes | |
13137 | .endd | |
13138 | in &_Local/Makefile_&, causes frozen messages and their message logs to be | |
13139 | moved from the &_input_& and &_msglog_& directories on the spool to &_Finput_& | |
13140 | and &_Fmsglog_&, respectively. There is currently no support in Exim or the | |
168e428f | 13141 | standard utilities for handling such moved messages, and they do not show up in |
9b371988 | 13142 | lists generated by &%-bp%& or by the Exim monitor. |
168e428f | 13143 | |
168e428f | 13144 | |
9b371988 | 13145 | .option mua_wrapper main boolean false |
168e428f | 13146 | Setting this option true causes Exim to run in a very restrictive mode in which |
9b371988 | 13147 | it passes messages synchronously to a smart host. Chapter &<<CHAPnonqueueing>>& |
168e428f PH |
13148 | contains a full description of this facility. |
13149 | ||
13150 | ||
13151 | ||
9b371988 PH |
13152 | .option mysql_servers main "string list" unset |
13153 | .cindex "MySQL" "server list" | |
168e428f | 13154 | This option provides a list of MySQL servers and associated connection data, to |
9b371988 | 13155 | be used in conjunction with &(mysql)& lookups (see section &<<SECTsql>>&). The |
168e428f PH |
13156 | option is available only if Exim has been built with MySQL support. |
13157 | ||
13158 | ||
9b371988 PH |
13159 | .option never_users main "string list&!!" unset |
13160 | .new | |
068aaea8 PH |
13161 | This option is expanded just once, at the start of Exim's processing. Local |
13162 | message deliveries are normally run in processes that are setuid to the | |
168e428f PH |
13163 | recipient, and remote deliveries are normally run under Exim's own uid and gid. |
13164 | It is usually desirable to prevent any deliveries from running as root, as a | |
13165 | safety precaution. | |
9b371988 | 13166 | .wen |
168e428f PH |
13167 | |
13168 | When Exim is built, an option called FIXED_NEVER_USERS can be set to a | |
13169 | list of users that must not be used for local deliveries. This list is fixed in | |
13170 | the binary and cannot be overridden by the configuration file. By default, it | |
9b371988 | 13171 | contains just the single user name &"root"&. The &%never_users%& runtime option |
168e428f PH |
13172 | can be used to add more users to the fixed list. |
13173 | ||
13174 | If a message is to be delivered as one of the users on the fixed list or the | |
9b371988 | 13175 | &%never_users%& list, an error occurs, and delivery is deferred. A common |
168e428f | 13176 | example is |
9b371988 PH |
13177 | .code |
13178 | never_users = root:daemon:bin | |
13179 | .endd | |
168e428f | 13180 | Including root is redundant if it is also on the fixed list, but it does no |
9b371988 | 13181 | harm. This option overrides the &%pipe_as_creator%& option of the &(pipe)& |
168e428f PH |
13182 | transport driver. |
13183 | ||
13184 | ||
9b371988 PH |
13185 | .option oracle_servers main "string list" unset |
13186 | .cindex "Oracle" "server list" | |
168e428f | 13187 | This option provides a list of Oracle servers and associated connection data, |
9b371988 PH |
13188 | to be used in conjunction with &(oracle)& lookups (see section &<<SECTsql>>&). |
13189 | The option is available only if Exim has been built with Oracle support. | |
13190 | ||
13191 | ||
13192 | .option percent_hack_domains main "domain list&!!" unset | |
13193 | .cindex "&""percent hack""&" | |
13194 | .cindex "source routing" "in email address" | |
13195 | .cindex "address" "source-routed" | |
13196 | The &"percent hack"& is the convention whereby a local part containing a | |
13197 | percent sign is re-interpreted as a new email address, with the percent | |
13198 | replaced by @. This is sometimes called &"source routing"&, though that term is | |
13199 | also applied to RFC 2822 addresses that begin with an @ character. If this | |
13200 | option is set, Exim implements the percent facility for those domains listed, | |
13201 | but no others. This happens before an incoming SMTP address is tested against | |
13202 | an ACL. | |
13203 | ||
13204 | &*Warning*&: The &"percent hack"& has often been abused by people who are | |
168e428f PH |
13205 | trying to get round relaying restrictions. For this reason, it is best avoided |
13206 | if at all possible. Unfortunately, a number of less security-conscious MTAs | |
13207 | implement it unconditionally. If you are running Exim on a gateway host, and | |
13208 | routing mail through to internal MTAs without processing the local parts, it is | |
13209 | a good idea to reject recipient addresses with percent characters in their | |
13210 | local parts. Exim's default configuration does this. | |
13211 | ||
13212 | ||
9b371988 | 13213 | .option perl_at_start main boolean false |
168e428f | 13214 | This option is available only when Exim is built with an embedded Perl |
9b371988 | 13215 | interpreter. See chapter &<<CHAPperl>>& for details of its use. |
168e428f | 13216 | |
168e428f | 13217 | |
9b371988 | 13218 | .option perl_startup main string unset |
168e428f | 13219 | This option is available only when Exim is built with an embedded Perl |
9b371988 | 13220 | interpreter. See chapter &<<CHAPperl>>& for details of its use. |
168e428f PH |
13221 | |
13222 | ||
9b371988 PH |
13223 | .option pgsql_servers main "string list" unset |
13224 | .cindex "PostgreSQL lookup type" "server list" | |
168e428f | 13225 | This option provides a list of PostgreSQL servers and associated connection |
9b371988 PH |
13226 | data, to be used in conjunction with &(pgsql)& lookups (see section |
13227 | &<<SECTsql>>&). The option is available only if Exim has been built with | |
13228 | PostgreSQL support. | |
168e428f | 13229 | |
168e428f | 13230 | |
9b371988 PH |
13231 | .option pid_file_path main string&!! "set at compile time" |
13232 | .cindex "daemon" "pid file path" | |
13233 | .cindex "pid file" "path for" | |
168e428f PH |
13234 | This option sets the name of the file to which the Exim daemon writes its |
13235 | process id. The string is expanded, so it can contain, for example, references | |
13236 | to the host name: | |
9b371988 PH |
13237 | .code |
13238 | pid_file_path = /var/log/$primary_hostname/exim.pid | |
13239 | .endd | |
13240 | If no path is set, the pid is written to the file &_exim-daemon.pid_& in Exim's | |
168e428f | 13241 | spool directory. |
9b371988 PH |
13242 | The value set by the option can be overridden by the &%-oP%& command line |
13243 | option. A pid file is not written if a &"non-standard"& daemon is run by means | |
13244 | of the &%-oX%& option, unless a path is explicitly supplied by &%-oP%&. | |
168e428f | 13245 | |
168e428f | 13246 | |
9b371988 PH |
13247 | .option pipelining_advertise_hosts main "host list&!!" * |
13248 | .cindex "PIPELINING advertising" "suppressing" | |
168e428f PH |
13249 | This option can be used to suppress the advertisement of the SMTP |
13250 | PIPELINING extension to specific hosts. When PIPELINING is not | |
9b371988 | 13251 | advertised and &%smtp_enforce_sync%& is true, an Exim server enforces strict |
168e428f | 13252 | synchronization for each SMTP command and response. |
9b371988 PH |
13253 | When PIPELINING is advertised, Exim assumes that clients will use it; &"out |
13254 | of order"& commands that are &"expected"& do not count as protocol errors (see | |
13255 | &%smtp_max_synprot_errors%&). | |
168e428f PH |
13256 | |
13257 | ||
9b371988 PH |
13258 | .option preserve_message_logs main boolean false |
13259 | .cindex "message logs" "preserving" | |
168e428f PH |
13260 | If this option is set, message log files are not deleted when messages are |
13261 | completed. Instead, they are moved to a sub-directory of the spool directory | |
9b371988 | 13262 | called &_msglog.OLD_&, where they remain available for statistical or debugging |
168e428f PH |
13263 | purposes. This is a dangerous option to set on systems with any appreciable |
13264 | volume of mail. Use with care! | |
13265 | ||
13266 | ||
9b371988 PH |
13267 | .option primary_hostname main string "see below" |
13268 | .cindex "name" "of local host" | |
13269 | .cindex "host" "name of local" | |
13270 | .cindex "local host" "name of" | |
13271 | .cindex "&$primary_hostname$&" | |
068aaea8 | 13272 | This specifies the name of the current host. It is used in the default EHLO or |
9b371988 PH |
13273 | HELO command for outgoing SMTP messages (changeable via the &%helo_data%& |
13274 | option in the &(smtp)& transport), and as the default for &%qualify_domain%&. | |
13275 | The value is also used by default in some SMTP response messages from an Exim | |
13276 | server. This can be changed dynamically by setting &%smtp_active_hostname%&. | |
13277 | ||
13278 | If &%primary_hostname%& is not set, Exim calls &[uname()]& to find the host | |
13279 | name. If this fails, Exim panics and dies. If the name returned by &[uname()]& | |
13280 | contains only one component, Exim passes it to &[gethostbyname()]& (or | |
13281 | &[getipnodebyname()]& when available) in order to obtain the fully qualified | |
13282 | version. The variable &$primary_hostname$& contains the host name, whether set | |
13283 | explicitly by this option, or defaulted. | |
13284 | ||
13285 | ||
13286 | .option print_topbitchars main boolean false | |
13287 | .cindex "printing characters" | |
13288 | .cindex "8-bit characters" | |
168e428f | 13289 | By default, Exim considers only those characters whose codes lie in the range |
9b371988 | 13290 | 32&--126 to be printing characters. In a number of circumstances (for example, |
168e428f | 13291 | when writing log entries) non-printing characters are converted into escape |
9b371988 PH |
13292 | sequences, primarily to avoid messing up the layout. If &%print_topbitchars%& |
13293 | is set, code values of 128 and above are also considered to be printing | |
168e428f PH |
13294 | characters. |
13295 | ||
13296 | ||
9b371988 PH |
13297 | .option process_log_path main string unset |
13298 | .cindex "process log path" | |
13299 | .cindex "log" "process log" | |
13300 | .cindex "&'exiwhat'&" | |
168e428f | 13301 | This option sets the name of the file to which an Exim process writes its |
9b371988 PH |
13302 | &"process log"& when sent a USR1 signal. This is used by the &'exiwhat'& |
13303 | utility script. If this option is unset, the file called &_exim-process.info_& | |
13304 | in Exim's spool directory is used. The ability to specify the name explicitly | |
13305 | can be useful in environments where two different Exims are running, using | |
168e428f PH |
13306 | different spool directories. |
13307 | ||
13308 | ||
9b371988 PH |
13309 | .option prod_requires_admin main boolean true |
13310 | .cindex "&%-M%& option" | |
13311 | .cindex "&%-R%& option" | |
13312 | .cindex "&%-q%& option" | |
13313 | The &%-M%&, &%-R%&, and &%-q%& command-line options require the caller to be an | |
13314 | admin user unless &%prod_requires_admin%& is set false. See also | |
13315 | &%queue_list_requires_admin%&. | |
168e428f | 13316 | |
168e428f | 13317 | |
9b371988 PH |
13318 | .option qualify_domain main string "see below" |
13319 | .cindex "domain" "for qualifying addresses" | |
13320 | .cindex "address" "qualification" | |
168e428f PH |
13321 | This option specifies the domain name that is added to any envelope sender |
13322 | addresses that do not have a domain qualification. It also applies to | |
9b371988 PH |
13323 | recipient addresses if &%qualify_recipient%& is not set. Unqualified addresses |
13324 | are accepted by default only for locally-generated messages. Qualification is | |
13325 | also applied to addresses in header lines such as &'From:'& and &'To:'& for | |
13326 | locally-generated messages, unless the &%-bnq%& command line option is used. | |
168e428f PH |
13327 | |
13328 | Messages from external sources must always contain fully qualified addresses, | |
9b371988 PH |
13329 | unless the sending host matches &%sender_unqualified_hosts%& or |
13330 | &%recipient_unqualified_hosts%& (as appropriate), in which case incoming | |
13331 | addresses are qualified with &%qualify_domain%& or &%qualify_recipient%& as | |
168e428f | 13332 | necessary. Internally, Exim always works with fully qualified envelope |
9b371988 PH |
13333 | addresses. If &%qualify_domain%& is not set, it defaults to the |
13334 | &%primary_hostname%& value. | |
168e428f PH |
13335 | |
13336 | ||
9b371988 | 13337 | .option qualify_recipient main string "see below" |
168e428f | 13338 | This option allows you to specify a different domain for qualifying recipient |
9b371988 | 13339 | addresses to the one that is used for senders. See &%qualify_domain%& above. |
168e428f PH |
13340 | |
13341 | ||
168e428f | 13342 | |
9b371988 PH |
13343 | .option queue_domains main "domain list&!!" unset |
13344 | .cindex "domain" "specifying non-immediate delivery" | |
13345 | .cindex "queueing incoming messages" | |
13346 | .cindex "message" "queueing certain domains" | |
168e428f PH |
13347 | This option lists domains for which immediate delivery is not required. |
13348 | A delivery process is started whenever a message is received, but only those | |
13349 | domains that do not match are processed. All other deliveries wait until the | |
9b371988 | 13350 | next queue run. See also &%hold_domains%& and &%queue_smtp_domains%&. |
168e428f | 13351 | |
168e428f | 13352 | |
9b371988 PH |
13353 | .option queue_list_requires_admin main boolean true |
13354 | .cindex "&%-bp%& option" | |
13355 | The &%-bp%& command-line option, which lists the messages that are on the | |
13356 | queue, requires the caller to be an admin user unless | |
13357 | &%queue_list_requires_admin%& is set false. See also &%prod_requires_admin%&. | |
168e428f PH |
13358 | |
13359 | ||
9b371988 PH |
13360 | .option queue_only main boolean false |
13361 | .cindex "queueing incoming messages" | |
13362 | .cindex "message" "queueing unconditionally" | |
13363 | If &%queue_only%& is set, a delivery process is not automatically started | |
168e428f | 13364 | whenever a message is received. Instead, the message waits on the queue for the |
9b371988 | 13365 | next queue run. Even if &%queue_only%& is false, incoming messages may not get |
168e428f PH |
13366 | delivered immediately when certain conditions (such as heavy load) occur. |
13367 | ||
9b371988 PH |
13368 | The &%-odq%& command line has the same effect as &%queue_only%&. The &%-odb%& |
13369 | and &%-odi%& command line options override &%queue_only%& unless | |
13370 | &%queue_only_override%& is set false. See also &%queue_only_file%&, | |
13371 | &%queue_only_load%&, and &%smtp_accept_queue%&. | |
168e428f | 13372 | |
168e428f | 13373 | |
9b371988 PH |
13374 | .option queue_only_file main string unset |
13375 | .cindex "queueing incoming messages" | |
13376 | .cindex "message" "queueing by file existence" | |
168e428f | 13377 | This option can be set to a colon-separated list of absolute path names, each |
9b371988 PH |
13378 | one optionally preceded by &"smtp"&. When Exim is receiving a message, |
13379 | it tests for the existence of each listed path using a call to &[stat()]&. For | |
168e428f | 13380 | each path that exists, the corresponding queuing option is set. |
9b371988 PH |
13381 | For paths with no prefix, &%queue_only%& is set; for paths prefixed by |
13382 | &"smtp"&, &%queue_smtp_domains%& is set to match all domains. So, for example, | |
13383 | .code | |
13384 | queue_only_file = smtp/some/file | |
13385 | .endd | |
13386 | causes Exim to behave as if &%queue_smtp_domains%& were set to &"*"& whenever | |
13387 | &_/some/file_& exists. | |
13388 | ||
13389 | ||
13390 | .option queue_only_load main fixed-point unset | |
13391 | .cindex "load average" | |
13392 | .cindex "queueing incoming messages" | |
13393 | .cindex "message" "queueing by load" | |
168e428f PH |
13394 | If the system load average is higher than this value, incoming messages from |
13395 | all sources are queued, and no automatic deliveries are started. If this | |
13396 | happens during local or remote SMTP input, all subsequent messages on the same | |
13397 | connection are queued. Deliveries will subsequently be performed by queue | |
13398 | runner processes. This option has no effect on ancient operating systems on | |
13399 | which Exim cannot determine the load average. See also | |
9b371988 | 13400 | &%deliver_queue_load_max%& and &%smtp_load_reserve%&. |
168e428f | 13401 | |
168e428f | 13402 | |
9b371988 PH |
13403 | .option queue_only_override main boolean true |
13404 | .cindex "queueing incoming messages" | |
13405 | When this option is true, the &%-od%&&'x'& command line options override the | |
13406 | setting of &%queue_only%& or &%queue_only_file%& in the configuration file. If | |
13407 | &%queue_only_override%& is set false, the &%-od%&&'x'& options cannot be used | |
13408 | to override; they are accepted, but ignored. | |
168e428f PH |
13409 | |
13410 | ||
9b371988 PH |
13411 | .option queue_run_in_order main boolean false |
13412 | .cindex "queue runner" "processing messages in order" | |
168e428f PH |
13413 | If this option is set, queue runs happen in order of message arrival instead of |
13414 | in an arbitrary order. For this to happen, a complete list of the entire queue | |
13415 | must be set up before the deliveries start. When the queue is all held in a | |
13416 | single directory (the default), | |
13417 | ||
13418 | a single list is created for both the ordered and the non-ordered cases. | |
9b371988 PH |
13419 | However, if &%split_spool_directory%& is set, a single list is not created when |
13420 | &%queue_run_in_order%& is false. In this case, the sub-directories are | |
168e428f | 13421 | processed one at a time (in a random order), and this avoids setting up one |
9b371988 PH |
13422 | huge list for the whole queue. Thus, setting &%queue_run_in_order%& with |
13423 | &%split_spool_directory%& may degrade performance when the queue is large, | |
168e428f | 13424 | because of the extra work in setting up the single, large list. In most |
9b371988 | 13425 | situations, &%queue_run_in_order%& should not be set. |
168e428f PH |
13426 | |
13427 | ||
168e428f | 13428 | |
9b371988 PH |
13429 | .option queue_run_max main integer 5 |
13430 | .cindex "queue runner" "maximum number of" | |
168e428f PH |
13431 | This controls the maximum number of queue runner processes that an Exim daemon |
13432 | can run simultaneously. This does not mean that it starts them all at once, | |
13433 | but rather that if the maximum number are still running when the time comes to | |
13434 | start another one, it refrains from starting another one. This can happen with | |
13435 | very large queues and/or very sluggish deliveries. This option does not, | |
13436 | however, interlock with other processes, so additional queue runners can be | |
13437 | started by other means, or by killing and restarting the daemon. | |
13438 | ||
9b371988 | 13439 | .new |
068aaea8 PH |
13440 | Setting this option to zero does not suppress queue runs; rather, it disables |
13441 | the limit, allowing any number of simultaneous queue runner processes to be | |
9b371988 PH |
13442 | run. If you do not want queue runs to occur, omit the &%-q%&&'xx'& setting on |
13443 | the daemon's command line. | |
13444 | .wen | |
168e428f | 13445 | |
9b371988 PH |
13446 | .option queue_smtp_domains main "domain list&!!" unset |
13447 | .cindex "queueing incoming messages" | |
13448 | .cindex "message" "queueing remote deliveries" | |
168e428f PH |
13449 | When this option is set, a delivery process is started whenever a message is |
13450 | received, routing is performed, and local deliveries take place. | |
13451 | However, if any SMTP deliveries are required for domains that match | |
9b371988 | 13452 | &%queue_smtp_domains%&, they are not immediately delivered, but instead the |
168e428f PH |
13453 | message waits on the queue for the next queue run. Since routing of the message |
13454 | has taken place, Exim knows to which remote hosts it must be delivered, and so | |
13455 | when the queue run happens, multiple messages for the same host are delivered | |
9b371988 PH |
13456 | over a single SMTP connection. The &%-odqs%& command line option causes all |
13457 | SMTP deliveries to be queued in this way, and is equivalent to setting | |
13458 | &%queue_smtp_domains%& to &"*"&. See also &%hold_domains%& and | |
13459 | &%queue_domains%&. | |
168e428f | 13460 | |
168e428f | 13461 | |
9b371988 PH |
13462 | .option receive_timeout main time 0s |
13463 | .cindex "timeout" "for non-SMTP input" | |
168e428f PH |
13464 | This option sets the timeout for accepting a non-SMTP message, that is, the |
13465 | maximum time that Exim waits when reading a message on the standard input. If | |
13466 | the value is zero, it will wait for ever. This setting is overridden by the | |
9b371988 PH |
13467 | &%-or%& command line option. The timeout for incoming SMTP messages is |
13468 | controlled by &%smtp_receive_timeout%&. | |
168e428f | 13469 | |
9b371988 PH |
13470 | .option received_header_text main string&!! "see below" |
13471 | .cindex "customizing" "&'Received:'& header" | |
13472 | .cindex "&'Received:'& header line" "customizing" | |
13473 | This string defines the contents of the &'Received:'& message header that is | |
168e428f PH |
13474 | added to each message, except for the timestamp, which is automatically added |
13475 | on at the end (preceded by a semicolon). The string is expanded each time it is | |
9b371988 | 13476 | used. If the expansion yields an empty string, no &'Received:'& header line is |
168e428f | 13477 | added to the message. Otherwise, the string should start with the text |
9b371988 PH |
13478 | &"Received:"& and conform to the RFC 2822 specification for &'Received:'& |
13479 | header lines. The default setting is: | |
168e428f | 13480 | |
9b371988 PH |
13481 | .new |
13482 | .code | |
168e428f | 13483 | received_header_text = Received: \ |
d1e83bff | 13484 | ${if def:sender_rcvhost {from $sender_rcvhost\n\t}\ |
9b371988 PH |
13485 | {${if def:sender_ident \ |
13486 | {from ${quote_local_part: $sender_ident} }}\ | |
d1e83bff PH |
13487 | ${if def:sender_helo_name {(helo=$sender_helo_name)\n\t}}}}\ |
13488 | by $primary_hostname \ | |
13489 | ${if def:received_protocol {with $received_protocol}} \ | |
13490 | ${if def:tls_cipher {($tls_cipher)\n\t}}\ | |
13491 | (Exim $version_number)\n\t\ | |
9b371988 PH |
13492 | ${if def:sender_address \ |
13493 | {(envelope-from <$sender_address>)\n\t}}\ | |
d1e83bff PH |
13494 | id $message_exim_id\ |
13495 | ${if def:received_for {\n\tfor $received_for}} | |
9b371988 PH |
13496 | .endd |
13497 | .wen | |
168e428f | 13498 | |
d1e83bff PH |
13499 | The reference to the TLS cipher is omitted when Exim is built without TLS |
13500 | support. The use of conditional expansions ensures that this works for both | |
13501 | locally generated messages and messages received from remote hosts, giving | |
13502 | header lines such as the following: | |
9b371988 PH |
13503 | .code |
13504 | Received: from scrooge.carol.example ([192.168.12.25] ident=root) | |
13505 | by marley.carol.example with esmtp (Exim 4.00) | |
13506 | (envelope-from <bob@carol.example>) | |
13507 | id 16IOWa-00019l-00 | |
13508 | for chas@dickens.example; Tue, 25 Dec 2001 14:43:44 +0000 | |
13509 | Received: by scrooge.carol.example with local (Exim 4.00) | |
13510 | id 16IOWW-000083-00; Tue, 25 Dec 2001 14:43:41 +0000 | |
13511 | .endd | |
168e428f PH |
13512 | Until the body of the message has been received, the timestamp is the time when |
13513 | the message started to be received. Once the body has arrived, and all policy | |
13514 | checks have taken place, the timestamp is updated to the time at which the | |
13515 | message was accepted. | |
13516 | ||
13517 | ||
9b371988 PH |
13518 | .option received_headers_max main integer 30 |
13519 | .cindex "loop" "prevention" | |
13520 | .cindex "mail loop prevention" | |
13521 | .cindex "&'Received:'& header line" "counting" | |
13522 | When a message is to be delivered, the number of &'Received:'& headers is | |
168e428f PH |
13523 | counted, and if it is greater than this parameter, a mail loop is assumed to |
13524 | have occurred, the delivery is abandoned, and an error message is generated. | |
13525 | This applies to both local and remote deliveries. | |
13526 | ||
13527 | ||
9b371988 PH |
13528 | .option recipient_unqualified_hosts main "host list&!!" unset |
13529 | .cindex "unqualified addresses" | |
13530 | .cindex "host" "unqualified addresses from" | |
168e428f PH |
13531 | This option lists those hosts from which Exim is prepared to accept unqualified |
13532 | recipient addresses in message envelopes. The addresses are made fully | |
9b371988 | 13533 | qualified by the addition of the &%qualify_recipient%& value. This option also |
168e428f PH |
13534 | affects message header lines. Exim does not reject unqualified recipient |
13535 | addresses in headers, but it qualifies them only if the message came from a | |
9b371988 PH |
13536 | host that matches &%recipient_unqualified_hosts%&, |
13537 | or if the message was submitted locally (not using TCP/IP), and the &%-bnq%& | |
168e428f PH |
13538 | option was not set. |
13539 | ||
13540 | ||
9b371988 PH |
13541 | .option recipients_max main integer 0 |
13542 | .cindex "limit" "number of recipients" | |
13543 | .cindex "recipient" "maximum number" | |
168e428f PH |
13544 | If this option is set greater than zero, it specifies the maximum number of |
13545 | original recipients for any message. Additional recipients that are generated | |
13546 | by aliasing or forwarding do not count. SMTP messages get a 452 response for | |
13547 | all recipients over the limit; earlier recipients are delivered as normal. | |
13548 | Non-SMTP messages with too many recipients are failed, and no deliveries are | |
13549 | done. | |
13550 | ||
9b371988 PH |
13551 | .cindex "RCPT" "maximum number of incoming" |
13552 | &*Note*&: The RFCs specify that an SMTP server should accept at least 100 | |
168e428f PH |
13553 | RCPT commands in a single message. |
13554 | ||
13555 | ||
9b371988 | 13556 | .option recipients_max_reject main boolean false |
168e428f PH |
13557 | If this option is set true, Exim rejects SMTP messages containing too many |
13558 | recipients by giving 552 errors to the surplus RCPT commands, and a 554 | |
13559 | error to the eventual DATA command. Otherwise (the default) it gives a 452 | |
13560 | error to the surplus RCPT commands and accepts the message on behalf of the | |
13561 | initial set of recipients. The remote server should then re-send the message | |
13562 | for the remaining recipients at a later time. | |
13563 | ||
13564 | ||
9b371988 PH |
13565 | .option remote_max_parallel main integer 2 |
13566 | .cindex "delivery" "parallelism for remote" | |
168e428f PH |
13567 | This option controls parallel delivery of one message to a number of remote |
13568 | hosts. If the value is less than 2, parallel delivery is disabled, and Exim | |
13569 | does all the remote deliveries for a message one by one. Otherwise, if a single | |
13570 | message has to be delivered to more than one remote host, or if several copies | |
9b371988 PH |
13571 | have to be sent to the same remote host, up to &%remote_max_parallel%& |
13572 | deliveries are done simultaneously. If more than &%remote_max_parallel%& | |
168e428f PH |
13573 | deliveries are required, the maximum number of processes are started, and as |
13574 | each one finishes, another is begun. The order of starting processes is the | |
13575 | same as if sequential delivery were being done, and can be controlled by the | |
9b371988 | 13576 | &%remote_sort_domains%& option. If parallel delivery takes place while running |
168e428f PH |
13577 | with debugging turned on, the debugging output from each delivery process is |
13578 | tagged with its process id. | |
13579 | ||
13580 | This option controls only the maximum number of parallel deliveries for one | |
13581 | message in one Exim delivery process. Because Exim has no central queue | |
13582 | manager, there is no way of controlling the total number of simultaneous | |
13583 | deliveries if the configuration allows a delivery attempt as soon as a message | |
13584 | is received. | |
13585 | ||
9b371988 PH |
13586 | .cindex "number of deliveries" |
13587 | .cindex "delivery" "maximum number of" | |
168e428f | 13588 | If you want to control the total number of deliveries on the system, you |
9b371988 | 13589 | need to set the &%queue_only%& option. This ensures that all incoming messages |
168e428f PH |
13590 | are added to the queue without starting a delivery process. Then set up an Exim |
13591 | daemon to start queue runner processes at appropriate intervals (probably | |
13592 | fairly often, for example, every minute), and limit the total number of queue | |
9b371988 | 13593 | runners by setting the &%queue_run_max%& parameter. Because each queue runner |
168e428f | 13594 | delivers only one message at a time, the maximum number of deliveries that can |
9b371988 PH |
13595 | then take place at once is &%queue_run_max%& multiplied by |
13596 | &%remote_max_parallel%&. | |
168e428f PH |
13597 | |
13598 | If it is purely remote deliveries you want to control, use | |
9b371988 | 13599 | &%queue_smtp_domains%& instead of &%queue_only%&. This has the added benefit of |
168e428f PH |
13600 | doing the SMTP routing before queuing, so that several messages for the same |
13601 | host will eventually get delivered down the same connection. | |
13602 | ||
13603 | ||
9b371988 PH |
13604 | .option remote_sort_domains main "domain list&!!" unset |
13605 | .cindex "sorting remote deliveries" | |
13606 | .cindex "delivery" "sorting remote" | |
168e428f PH |
13607 | When there are a number of remote deliveries for a message, they are sorted by |
13608 | domain into the order given by this list. For example, | |
9b371988 PH |
13609 | .code |
13610 | remote_sort_domains = *.cam.ac.uk:*.uk | |
13611 | .endd | |
13612 | would attempt to deliver to all addresses in the &'cam.ac.uk'& domain first, | |
13613 | then to those in the &%uk%& domain, then to any others. | |
168e428f | 13614 | |
168e428f | 13615 | |
9b371988 PH |
13616 | .option retry_data_expire main time 7d |
13617 | .cindex "hints database" "data expiry" | |
13618 | This option sets a &"use before"& time on retry information in Exim's hints | |
168e428f PH |
13619 | database. Any older retry data is ignored. This means that, for example, once a |
13620 | host has not been tried for 7 days, Exim behaves as if it has no knowledge of | |
13621 | past failures. | |
13622 | ||
13623 | ||
9b371988 PH |
13624 | .option retry_interval_max main time 24h |
13625 | .cindex "retry" "limit on interval" | |
13626 | .cindex "limit" "on retry interval" | |
13627 | Chapter &<<CHAPretry>>& describes Exim's mechanisms for controlling the | |
13628 | intervals between delivery attempts for messages that cannot be delivered | |
13629 | straight away. This option sets an overall limit to the length of time between | |
13630 | retries. | |
168e428f PH |
13631 | |
13632 | ||
9b371988 PH |
13633 | .option return_path_remove main boolean true |
13634 | .cindex "&'Return-path:'& header line" "removing" | |
13635 | RFC 2821, section 4.4, states that an SMTP server must insert a | |
13636 | &'Return-path:'& header line into a message when it makes a &"final delivery"&. | |
13637 | The &'Return-path:'& header preserves the sender address as received in the | |
13638 | MAIL command. This description implies that this header should not be present | |
13639 | in an incoming message. If &%return_path_remove%& is true, any existing | |
13640 | &'Return-path:'& headers are removed from messages at the time they are | |
13641 | received. Exim's transports have options for adding &'Return-path:'& headers at | |
13642 | the time of delivery. They are normally used only for final local deliveries. | |
168e428f | 13643 | |
168e428f | 13644 | |
9b371988 PH |
13645 | .option return_size_limit main integer 100K |
13646 | This option is an obsolete synonym for &%bounce_return_size_limit%&. | |
168e428f | 13647 | |
168e428f | 13648 | |
9b371988 PH |
13649 | .option rfc1413_hosts main "host list&!!" * |
13650 | .cindex "RFC 1413" | |
13651 | .cindex "host" "for RFC 1413 calls" | |
168e428f PH |
13652 | RFC 1413 identification calls are made to any client host which matches an item |
13653 | in the list. | |
13654 | ||
13655 | ||
9b371988 PH |
13656 | .option rfc1413_query_timeout main time 30s |
13657 | .cindex "RFC 1413" "query timeout" | |
13658 | .cindex "timeout" "for RFC 1413 call" | |
168e428f PH |
13659 | This sets the timeout on RFC 1413 identification calls. If it is set to zero, |
13660 | no RFC 1413 calls are ever made. | |
13661 | ||
13662 | ||
9b371988 PH |
13663 | .option sender_unqualified_hosts main "host list&!!" unset |
13664 | .cindex "unqualified addresses" | |
13665 | .cindex "host" "unqualified addresses from" | |
168e428f PH |
13666 | This option lists those hosts from which Exim is prepared to accept unqualified |
13667 | sender addresses. The addresses are made fully qualified by the addition of | |
9b371988 PH |
13668 | &%qualify_domain%&. This option also affects message header lines. Exim does |
13669 | not reject unqualified addresses in headers that contain sender addresses, but | |
13670 | it qualifies them only if the message came from a host that matches | |
13671 | &%sender_unqualified_hosts%&, or if the message was submitted locally (not | |
13672 | using TCP/IP), and the &%-bnq%& option was not set. | |
168e428f PH |
13673 | |
13674 | ||
9b371988 PH |
13675 | .option smtp_accept_keepalive main boolean true |
13676 | .cindex "keepalive" "on incoming connection" | |
168e428f PH |
13677 | This option controls the setting of the SO_KEEPALIVE option on incoming |
13678 | TCP/IP socket connections. When set, it causes the kernel to probe idle | |
9b371988 | 13679 | connections periodically, by sending packets with &"old"& sequence numbers. The |
168e428f PH |
13680 | other end of the connection should send an acknowledgement if the connection is |
13681 | still okay or a reset if the connection has been aborted. The reason for doing | |
13682 | this is that it has the beneficial effect of freeing up certain types of | |
13683 | connection that can get stuck when the remote host is disconnected without | |
13684 | tidying up the TCP/IP call properly. The keepalive mechanism takes several | |
13685 | hours to detect unreachable hosts. | |
13686 | ||
13687 | ||
13688 | ||
9b371988 PH |
13689 | .option smtp_accept_max main integer 20 |
13690 | .cindex "limit" "incoming SMTP connections" | |
13691 | .cindex "SMTP" "incoming connection count" | |
13692 | .cindex "inetd" | |
168e428f PH |
13693 | This option specifies the maximum number of simultaneous incoming SMTP calls |
13694 | that Exim will accept. It applies only to the listening daemon; there is no | |
9b371988 PH |
13695 | control (in Exim) when incoming SMTP is being handled by &'inetd'&. If the |
13696 | value is set to zero, no limit is applied. However, it is required to be | |
13697 | non-zero if either &%smtp_accept_max_per_host%& or &%smtp_accept_queue%& is | |
13698 | set. See also &%smtp_accept_reserve%&. | |
168e428f PH |
13699 | |
13700 | ||
168e428f | 13701 | |
9b371988 PH |
13702 | .option smtp_accept_max_nonmail main integer 10 |
13703 | .cindex "limit" "non-mail SMTP commands" | |
13704 | .cindex "SMTP" "limiting non-mail commands" | |
13705 | Exim counts the number of &"non-mail"& commands in an SMTP session, and drops | |
13706 | the connection if there are too many. This option defines &"too many"&. The | |
13707 | check catches some denial-of-service attacks, repeated failing AUTHs, or a mad | |
168e428f | 13708 | client looping sending EHLO, for example. The check is applied only if the |
9b371988 | 13709 | client host matches &%smtp_accept_max_nonmail_hosts%&. |
168e428f PH |
13710 | |
13711 | When a new message is expected, one occurrence of RSET is not counted. This | |
13712 | allows a client to send one RSET between messages (this is not necessary, | |
13713 | but some clients do it). Exim also allows one uncounted occurence of HELO | |
13714 | or EHLO, and one occurrence of STARTTLS between messages. After | |
13715 | starting up a TLS session, another EHLO is expected, and so it too is not | |
13716 | counted. The first occurrence of AUTH in a connection, or immediately | |
13717 | following STARTTLS is not counted. Otherwise, all commands other than | |
13718 | MAIL, RCPT, DATA, and QUIT are counted. | |
13719 | ||
13720 | ||
9b371988 PH |
13721 | .option smtp_accept_max_nonmail_hosts main "host list&!!" * |
13722 | You can control which hosts are subject to the &%smtp_accept_max_nonmail%& | |
168e428f PH |
13723 | check by setting this option. The default value makes it apply to all hosts. By |
13724 | changing the value, you can exclude any badly-behaved hosts that you have to | |
13725 | live with. | |
13726 | ||
13727 | ||
13728 | ||
9b371988 PH |
13729 | .option smtp_accept_max_per_connection main integer 1000 |
13730 | .cindex "SMTP incoming message count" "limiting" | |
13731 | .cindex "limit" "messages per SMTP connection" | |
168e428f PH |
13732 | The value of this option limits the number of MAIL commands that Exim is |
13733 | prepared to accept over a single SMTP connection, whether or not each command | |
13734 | results in the transfer of a message. After the limit is reached, a 421 | |
13735 | response is given to subsequent MAIL commands. This limit is a safety | |
13736 | precaution against a client that goes mad (incidents of this type have been | |
13737 | seen). | |
13738 | ||
13739 | ||
9b371988 PH |
13740 | .option smtp_accept_max_per_host main string&!! unset |
13741 | .cindex "limit" "SMTP connections from one host" | |
13742 | .cindex "host" "limiting SMTP connections from" | |
168e428f PH |
13743 | This option restricts the number of simultaneous IP connections from a single |
13744 | host (strictly, from a single IP address) to the Exim daemon. The option is | |
13745 | expanded, to enable different limits to be applied to different hosts by | |
9b371988 | 13746 | reference to &$sender_host_address$&. Once the limit is reached, additional |
168e428f PH |
13747 | connection attempts from the same host are rejected with error code 421. The |
13748 | default value of zero imposes no limit. If this option is set, it is required | |
9b371988 | 13749 | that &%smtp_accept_max%& be non-zero. |
168e428f | 13750 | |
9b371988 | 13751 | &*Warning*&: When setting this option you should not use any expansion |
168e428f PH |
13752 | constructions that take an appreciable amount of time. The expansion and test |
13753 | happen in the main daemon loop, in order to reject additional connections | |
13754 | without forking additional processes (otherwise a denial-of-service attack | |
13755 | could cause a vast number or processes to be created). While the daemon is | |
13756 | doing this processing, it cannot accept any other incoming connections. | |
13757 | ||
13758 | ||
13759 | ||
9b371988 PH |
13760 | .option smtp_accept_queue main integer 0 |
13761 | .cindex "SMTP" "incoming connection count" | |
13762 | .cindex "queueing incoming messages" | |
13763 | .cindex "message" "queueing by SMTP connection count" | |
168e428f PH |
13764 | If the number of simultaneous incoming SMTP calls handled via the listening |
13765 | daemon exceeds this value, messages received by SMTP are just placed on the | |
13766 | queue; no delivery processes are started automatically. A value of zero implies | |
13767 | no limit, and clearly any non-zero value is useful only if it is less than the | |
9b371988 PH |
13768 | &%smtp_accept_max%& value (unless that is zero). See also &%queue_only%&, |
13769 | &%queue_only_load%&, &%queue_smtp_domains%&, and the various &%-od%&&'x'& | |
13770 | command line options. | |
168e428f | 13771 | |
168e428f | 13772 | |
9b371988 PH |
13773 | .option smtp_accept_queue_per_connection main integer 10 |
13774 | .cindex "queueing incoming messages" | |
13775 | .cindex "message" "queueing by message count" | |
168e428f PH |
13776 | This option limits the number of delivery processes that Exim starts |
13777 | automatically when receiving messages via SMTP, whether via the daemon or by | |
9b371988 | 13778 | the use of &%-bs%& or &%-bS%&. If the value of the option is greater than zero, |
168e428f PH |
13779 | and the number of messages received in a single SMTP session exceeds this |
13780 | number, subsequent messages are placed on the queue, but no delivery processes | |
13781 | are started. This helps to limit the number of Exim processes when a server | |
13782 | restarts after downtime and there is a lot of mail waiting for it on other | |
13783 | systems. On large systems, the default should probably be increased, and on | |
13784 | dial-in client systems it should probably be set to zero (that is, disabled). | |
13785 | ||
13786 | ||
9b371988 PH |
13787 | .option smtp_accept_reserve main integer 0 |
13788 | .cindex "SMTP" "incoming call count" | |
13789 | .cindex "host" "reserved" | |
13790 | When &%smtp_accept_max%& is set greater than zero, this option specifies a | |
168e428f | 13791 | number of SMTP connections that are reserved for connections from the hosts |
9b371988 PH |
13792 | that are specified in &%smtp_reserve_hosts%&. The value set in |
13793 | &%smtp_accept_max%& includes this reserve pool. The specified hosts are not | |
168e428f PH |
13794 | restricted to this number of connections; the option specifies a minimum number |
13795 | of connection slots for them, not a maximum. It is a guarantee that that group | |
9b371988 | 13796 | of hosts can always get at least &%smtp_accept_reserve%& connections. |
168e428f | 13797 | |
9b371988 | 13798 | For example, if &%smtp_accept_max%& is set to 50 and &%smtp_accept_reserve%& is |
168e428f | 13799 | set to 5, once there are 45 active connections (from any hosts), new |
9b371988 PH |
13800 | connections are accepted only from hosts listed in &%smtp_reserve_hosts%&. |
13801 | See also &%smtp_accept_max_per_host%&. | |
168e428f PH |
13802 | |
13803 | ||
9b371988 PH |
13804 | .option smtp_active_hostname main string&!! unset |
13805 | .cindex "host" "name in SMTP responses" | |
13806 | .cindex "SMTP" "host name in responses" | |
13807 | .cindex "&$primary_hostname$&" | |
168e428f PH |
13808 | This option is provided for multi-homed servers that want to masquerade as |
13809 | several different hosts. At the start of an SMTP connection, its value is | |
9b371988 | 13810 | expanded and used instead of the value of &$primary_hostname$& in SMTP |
168e428f PH |
13811 | responses. For example, it is used as domain name in the response to an |
13812 | incoming HELO or EHLO command. | |
13813 | ||
9b371988 | 13814 | .cindex "&$smtp_active_hostname$&" |
068aaea8 | 13815 | It is also used in HELO commands for callout verification. The active hostname |
9b371988 | 13816 | is placed in the &$smtp_active_hostname$& variable, which is saved with any |
068aaea8 PH |
13817 | messages that are received. It is therefore available for use in routers and |
13818 | transports when the message is later delivered. | |
168e428f PH |
13819 | |
13820 | If this option is unset, or if its expansion is forced to fail, or if the | |
9b371988 | 13821 | expansion results in an empty string, the value of &$primary_hostname$& is |
168e428f PH |
13822 | used. Other expansion failures cause a message to be written to the main and |
13823 | panic logs, and the SMTP command receives a temporary error. Typically, the | |
9b371988 | 13824 | value of &%smtp_active_hostname%& depends on the incoming interface address. |
168e428f | 13825 | For example: |
9b371988 | 13826 | .code |
168e428f PH |
13827 | smtp_active_hostname = ${if eq{$interface_address}{10.0.0.1}\ |
13828 | {cox.mydomain}{box.mydomain}} | |
9b371988 | 13829 | .endd |
168e428f | 13830 | |
9b371988 PH |
13831 | .option smtp_banner main string&!! "see below" |
13832 | .cindex "SMTP" "welcome banner" | |
13833 | .cindex "banner for SMTP" | |
13834 | .cindex "welcome banner for SMTP" | |
13835 | .cindex "customizing" "SMTP banner" | |
168e428f PH |
13836 | This string, which is expanded every time it is used, is output as the initial |
13837 | positive response to an SMTP connection. The default setting is: | |
9b371988 | 13838 | .code |
168e428f PH |
13839 | smtp_banner = $smtp_active_hostname ESMTP Exim \ |
13840 | $version_number $tod_full | |
9b371988 | 13841 | .endd |
168e428f | 13842 | Failure to expand the string causes a panic error. If you want to create a |
9b371988 | 13843 | multiline response to the initial SMTP connection, use &"\n"& in the string at |
168e428f PH |
13844 | appropriate points, but not at the end. Note that the 220 code is not included |
13845 | in this string. Exim adds it automatically (several times in the case of a | |
13846 | multiline response). | |
13847 | ||
13848 | ||
9b371988 PH |
13849 | .option smtp_check_spool_space main boolean true |
13850 | .cindex "checking disk space" | |
13851 | .cindex "disk space" "checking" | |
13852 | .cindex "spool directory" "checking space" | |
168e428f PH |
13853 | When this option is set, if an incoming SMTP session encounters the SIZE |
13854 | option on a MAIL command, it checks that there is enough space in the | |
13855 | spool directory's partition to accept a message of that size, while still | |
9b371988 | 13856 | leaving free the amount specified by &%check_spool_space%& (even if that value |
168e428f PH |
13857 | is zero). If there isn't enough space, a temporary error code is returned. |
13858 | ||
13859 | ||
9b371988 PH |
13860 | .option smtp_connect_backlog main integer 20 |
13861 | .cindex "connection backlog" | |
13862 | .cindex "SMTP" "connection backlog" | |
13863 | .cindex "backlog of connections" | |
168e428f PH |
13864 | This option specifies a maximum number of waiting SMTP connections. Exim passes |
13865 | this value to the TCP/IP system when it sets up its listener. Once this number | |
13866 | of connections are waiting for the daemon's attention, subsequent connection | |
13867 | attempts are refused at the TCP/IP level. At least, that is what the manuals | |
13868 | say; in some circumstances such connection attempts have been observed to time | |
13869 | out instead. For large systems it is probably a good idea to increase the | |
13870 | value (to 50, say). It also gives some protection against denial-of-service | |
13871 | attacks by SYN flooding. | |
13872 | ||
13873 | ||
9b371988 PH |
13874 | .option smtp_enforce_sync main boolean true |
13875 | .cindex "SMTP" "synchronization checking" | |
13876 | .cindex "synchronization checking in SMTP" | |
168e428f PH |
13877 | The SMTP protocol specification requires the client to wait for a response from |
13878 | the server at certain points in the dialogue. Without PIPELINING these | |
13879 | synchronization points are after every command; with PIPELINING they are | |
13880 | fewer, but they still exist. | |
13881 | ||
13882 | Some spamming sites send out a complete set of SMTP commands without waiting | |
13883 | for any response. Exim protects against this by rejecting a message if the | |
9b371988 PH |
13884 | client has sent further input when it should not have. The error response &"554 |
13885 | SMTP synchronization error"& is sent, and the connection is dropped. Testing | |
13886 | for this error cannot be perfect because of transmission delays (unexpected | |
13887 | input may be on its way but not yet received when Exim checks). However, it | |
13888 | does detect many instances. | |
168e428f | 13889 | |
9b371988 | 13890 | The check can be globally disabled by setting &%smtp_enforce_sync%& false. |
168e428f | 13891 | If you want to disable the check selectively (for example, only for certain |
9b371988 PH |
13892 | hosts), you can do so by an appropriate use of a &%control%& modifier in an ACL |
13893 | (see section &<<SECTcontrols>>&). See also &%pipelining_advertise_hosts%&. | |
168e428f PH |
13894 | |
13895 | ||
13896 | ||
9b371988 PH |
13897 | .option smtp_etrn_command main string&!! unset |
13898 | .cindex "ETRN" "command to be run" | |
13899 | .cindex "&$domain$&" | |
168e428f PH |
13900 | If this option is set, the given command is run whenever an SMTP ETRN |
13901 | command is received from a host that is permitted to issue such commands (see | |
9b371988 PH |
13902 | chapter &<<CHAPACL>>&). The string is split up into separate arguments which |
13903 | are independently expanded. The expansion variable &$domain$& is set to the | |
168e428f PH |
13904 | argument of the ETRN command, and no syntax checking is done on it. For |
13905 | example: | |
9b371988 PH |
13906 | .code |
13907 | smtp_etrn_command = /etc/etrn_command $domain \ | |
13908 | $sender_host_address | |
13909 | .endd | |
168e428f PH |
13910 | A new process is created to run the command, but Exim does not wait for it to |
13911 | complete. Consequently, its status cannot be checked. If the command cannot be | |
13912 | run, a line is written to the panic log, but the ETRN caller still receives | |
13913 | a 250 success response. Exim is normally running under its own uid when | |
13914 | receiving SMTP, so it is not possible for it to change the uid before running | |
13915 | the command. | |
13916 | ||
13917 | ||
9b371988 PH |
13918 | .option smtp_etrn_serialize main boolean true |
13919 | .cindex "ETRN" "serializing" | |
168e428f PH |
13920 | When this option is set, it prevents the simultaneous execution of more than |
13921 | one identical command as a result of ETRN in an SMTP connection. See | |
9b371988 | 13922 | section &<<SECTETRN>>& for details. |
168e428f | 13923 | |
168e428f | 13924 | |
9b371988 PH |
13925 | .option smtp_load_reserve main fixed-point unset |
13926 | .cindex "load average" | |
168e428f | 13927 | If the system load average ever gets higher than this, incoming SMTP calls are |
9b371988 PH |
13928 | accepted only from those hosts that match an entry in &%smtp_reserve_hosts%&. |
13929 | If &%smtp_reserve_hosts%& is not set, no incoming SMTP calls are accepted when | |
168e428f PH |
13930 | the load is over the limit. The option has no effect on ancient operating |
13931 | systems on which Exim cannot determine the load average. See also | |
9b371988 | 13932 | &%deliver_queue_load_max%& and &%queue_only_load%&. |
168e428f PH |
13933 | |
13934 | ||
13935 | ||
9b371988 PH |
13936 | .option smtp_max_synprot_errors main integer 3 |
13937 | .cindex "SMTP" "limiting syntax and protocol errors" | |
13938 | .cindex "limit" "SMTP syntax and protocol errors" | |
168e428f PH |
13939 | Exim rejects SMTP commands that contain syntax or protocol errors. In |
13940 | particular, a syntactically invalid email address, as in this command: | |
9b371988 PH |
13941 | .code |
13942 | RCPT TO:<abc xyz@a.b.c> | |
13943 | .endd | |
168e428f PH |
13944 | causes immediate rejection of the command, before any other tests are done. |
13945 | (The ACL cannot be run if there is no valid address to set up for it.) An | |
13946 | example of a protocol error is receiving RCPT before MAIL. If there are | |
13947 | too many syntax or protocol errors in one SMTP session, the connection is | |
13948 | dropped. The limit is set by this option. | |
13949 | ||
9b371988 | 13950 | .cindex "PIPELINING" "expected errors" |
168e428f | 13951 | When the PIPELINING extension to SMTP is in use, some protocol errors are |
9b371988 | 13952 | &"expected"&, for instance, a RCPT command after a rejected MAIL command. |
168e428f | 13953 | Exim assumes that PIPELINING will be used if it advertises it (see |
9b371988 | 13954 | &%pipelining_advertise_hosts%&), and in this situation, &"expected"& errors do |
168e428f PH |
13955 | not count towards the limit. |
13956 | ||
13957 | ||
13958 | ||
9b371988 PH |
13959 | .option smtp_max_unknown_commands main integer 3 |
13960 | .cindex "SMTP" "limiting unknown commands" | |
13961 | .cindex "limit" "unknown SMTP commands" | |
168e428f PH |
13962 | If there are too many unrecognized commands in an incoming SMTP session, an |
13963 | Exim server drops the connection. This is a defence against some kinds of abuse | |
13964 | that subvert web | |
13965 | clients | |
13966 | into making connections to SMTP ports; in these circumstances, a number of | |
13967 | non-SMTP command lines are sent first. | |
13968 | ||
13969 | ||
13970 | ||
9b371988 PH |
13971 | .option smtp_ratelimit_hosts main "host list&!!" unset |
13972 | .cindex "SMTP" "rate limiting" | |
13973 | .cindex "limit" "rate of message arrival" | |
13974 | .cindex "RCPT" "rate limiting" | |
168e428f PH |
13975 | Some sites find it helpful to be able to limit the rate at which certain hosts |
13976 | can send them messages, and the rate at which an individual message can specify | |
9b371988 PH |
13977 | recipients. |
13978 | ||
13979 | .new | |
13980 | Exim has two rate-limiting facilities. This section describes the older | |
13981 | facility, which can limit rates within a single connection. The newer | |
13982 | &%ratelimit%& ACL condition can limit rates across all connections. See section | |
13983 | &<<SECTratelimiting>>& for details of the newer facility. | |
13984 | .wen | |
13985 | ||
13986 | When a host matches &%smtp_ratelimit_hosts%&, the values of | |
13987 | &%smtp_ratelimit_mail%& and &%smtp_ratelimit_rcpt%& are used to control the | |
168e428f PH |
13988 | rate of acceptance of MAIL and RCPT commands in a single SMTP session, |
13989 | respectively. Each option, if set, must contain a set of four comma-separated | |
13990 | values: | |
13991 | ||
9b371988 PH |
13992 | .ilist |
13993 | A threshold, before which there is no rate limiting. | |
13994 | .next | |
13995 | An initial time delay. Unlike other times in Exim, numbers with decimal | |
168e428f | 13996 | fractional parts are allowed here. |
9b371988 PH |
13997 | .next |
13998 | A factor by which to increase the delay each time. | |
13999 | .next | |
14000 | A maximum value for the delay. This should normally be less than 5 minutes, | |
168e428f | 14001 | because after that time, the client is liable to timeout the SMTP command. |
9b371988 | 14002 | .endlist |
168e428f PH |
14003 | |
14004 | For example, these settings have been used successfully at the site which | |
14005 | first suggested this feature, for controlling mail from their customers: | |
9b371988 PH |
14006 | .code |
14007 | smtp_ratelimit_mail = 2,0.5s,1.05,4m | |
14008 | smtp_ratelimit_rcpt = 4,0.25s,1.015,4m | |
14009 | .endd | |
168e428f PH |
14010 | The first setting specifies delays that are applied to MAIL commands after |
14011 | two have been received over a single connection. The initial delay is 0.5 | |
14012 | seconds, increasing by a factor of 1.05 each time. The second setting applies | |
14013 | delays to RCPT commands when more than four occur in a single message. | |
14014 | ||
168e428f | 14015 | |
9b371988 PH |
14016 | .option smtp_ratelimit_mail main string unset |
14017 | See &%smtp_ratelimit_hosts%& above. | |
168e428f PH |
14018 | |
14019 | ||
9b371988 PH |
14020 | .option smtp_ratelimit_rcpt main string unset |
14021 | See &%smtp_ratelimit_hosts%& above. | |
168e428f | 14022 | |
168e428f | 14023 | |
9b371988 PH |
14024 | .option smtp_receive_timeout main time 5m |
14025 | .cindex "timeout" "for SMTP input" | |
14026 | .cindex "SMTP timeout" "input" | |
168e428f PH |
14027 | This sets a timeout value for SMTP reception. It applies to all forms of SMTP |
14028 | input, including batch SMTP. If a line of input (either an SMTP command or a | |
14029 | data line) is not received within this time, the SMTP connection is dropped and | |
14030 | the message is abandoned. | |
14031 | A line is written to the log containing one of the following messages: | |
9b371988 PH |
14032 | .code |
14033 | SMTP command timeout on connection from... | |
14034 | SMTP data timeout on connection from... | |
14035 | .endd | |
168e428f PH |
14036 | The former means that Exim was expecting to read an SMTP command; the latter |
14037 | means that it was in the DATA phase, reading the contents of a message. | |
14038 | ||
14039 | ||
9b371988 | 14040 | .cindex "&%-os%& option" |
168e428f | 14041 | The value set by this option can be overridden by the |
9b371988 | 14042 | &%-os%& command-line option. A setting of zero time disables the timeout, but |
168e428f | 14043 | this should never be used for SMTP over TCP/IP. (It can be useful in some cases |
9b371988 PH |
14044 | of local input using &%-bs%& or &%-bS%&.) For non-SMTP input, the reception |
14045 | timeout is controlled by &%receive_timeout%& and &%-or%&. | |
168e428f | 14046 | |
168e428f | 14047 | |
9b371988 | 14048 | .option smtp_reserve_hosts main "host list&!!" unset |
168e428f | 14049 | This option defines hosts for which SMTP connections are reserved; see |
9b371988 | 14050 | &%smtp_accept_reserve%& and &%smtp_load_reserve%& above. |
168e428f PH |
14051 | |
14052 | ||
9b371988 PH |
14053 | .option smtp_return_error_details main boolean false |
14054 | .cindex "SMTP" "details policy failures" | |
14055 | .cindex "policy control rejection" "returning details" | |
168e428f | 14056 | In the default state, Exim uses bland messages such as |
9b371988 | 14057 | &"Administrative prohibition"& when it rejects SMTP commands for policy |
168e428f PH |
14058 | reasons. Many sysadmins like this because it gives away little information |
14059 | to spammers. However, some other syadmins who are applying strict checking | |
14060 | policies want to give out much fuller information about failures. Setting | |
9b371988 PH |
14061 | &%smtp_return_error_details%& true causes Exim to be more forthcoming. For |
14062 | example, instead of &"Administrative prohibition"&, it might give: | |
14063 | .code | |
14064 | 550-Rejected after DATA: '>' missing at end of address: | |
14065 | 550 failing address in "From" header is: <user@dom.ain | |
14066 | .endd | |
14067 | ||
14068 | .option spamd_address main string "see below" | |
168e428f | 14069 | This option is available when Exim is compiled with the content-scanning |
9b371988 PH |
14070 | extension. It specifies how Exim connects to SpamAssassin's &%spamd%& daemon. |
14071 | The default value is | |
14072 | .code | |
14073 | 127.0.0.1 783 | |
14074 | .endd | |
14075 | See section &<<SECTscanspamass>>& for more details. | |
168e428f PH |
14076 | |
14077 | ||
14078 | ||
9b371988 PH |
14079 | .option split_spool_directory main boolean false |
14080 | .cindex "multiple spool directories" | |
14081 | .cindex "spool directory" "split" | |
14082 | .cindex "directories" "multiple" | |
168e428f PH |
14083 | If this option is set, it causes Exim to split its input directory into 62 |
14084 | subdirectories, each with a single alphanumeric character as its name. The | |
14085 | sixth character of the message id is used to allocate messages to | |
14086 | subdirectories; this is the least significant base-62 digit of the time of | |
14087 | arrival of the message. | |
14088 | ||
14089 | Splitting up the spool in this way may provide better performance on systems | |
14090 | where there are long mail queues, by reducing the number of files in any one | |
14091 | directory. The msglog directory is also split up in a similar way to the input | |
9b371988 PH |
14092 | directory; however, if &%preserve_message_logs%& is set, all old msglog files |
14093 | are still placed in the single directory &_msglog.OLD_&. | |
168e428f PH |
14094 | |
14095 | It is not necessary to take any special action for existing messages when | |
9b371988 PH |
14096 | changing &%split_spool_directory%&. Exim notices messages that are in the |
14097 | &"wrong"& place, and continues to process them. If the option is turned off | |
14098 | after a period of being on, the subdirectories will eventually empty and be | |
168e428f PH |
14099 | automatically deleted. |
14100 | ||
9b371988 | 14101 | When &%split_spool_directory%& is set, the behaviour of queue runner processes |
168e428f PH |
14102 | changes. Instead of creating a list of all messages in the queue, and then |
14103 | trying to deliver each one in turn, it constructs a list of those in one | |
14104 | sub-directory and tries to deliver them, before moving on to the next | |
14105 | sub-directory. The sub-directories are processed in a random order. This | |
14106 | spreads out the scanning of the input directories, and uses less memory. It is | |
14107 | particularly beneficial when there are lots of messages on the queue. However, | |
9b371988 | 14108 | if &%queue_run_in_order%& is set, none of this new processing happens. The |
168e428f PH |
14109 | entire queue has to be scanned and sorted before any deliveries can start. |
14110 | ||
14111 | ||
9b371988 PH |
14112 | .option spool_directory main string&!! "set at compile time" |
14113 | .cindex "spool directory" "path to" | |
168e428f PH |
14114 | This defines the directory in which Exim keeps its spool, that is, the messages |
14115 | it is waiting to deliver. The default value is taken from the compile-time | |
14116 | configuration setting, if there is one. If not, this option must be set. The | |
14117 | string is expanded, so it can contain, for example, a reference to | |
9b371988 | 14118 | &$primary_hostname$&. |
168e428f PH |
14119 | |
14120 | If the spool directory name is fixed on your installation, it is recommended | |
14121 | that you set it at build time rather than from this option, particularly if the | |
9b371988 | 14122 | log files are being written to the spool directory (see &%log_file_path%&). |
168e428f PH |
14123 | Otherwise log files cannot be used for errors that are detected early on, such |
14124 | as failures in the configuration file. | |
14125 | ||
14126 | By using this option to override the compiled-in path, it is possible to run | |
14127 | tests of Exim without using the standard spool. | |
14128 | ||
9b371988 PH |
14129 | .new |
14130 | .option sqlite_lock_timeout main time 5s | |
14131 | .cindex "sqlite" "lock timeout" | |
14132 | This option controls the timeout that the &(sqlite)& lookup uses when trying to | |
14133 | access an SQLite database. See section &<<SECTsqlite>>& for more details. | |
14134 | .wen | |
14135 | ||
14136 | .option strip_excess_angle_brackets main boolean false | |
14137 | .cindex "angle brackets" "excess" | |
14138 | If this option is set, redundant pairs of angle brackets round &"route-addr"& | |
14139 | items in addresses are stripped. For example, &'<<xxx@a.b.c.d>>'& is | |
14140 | treated as &'<xxx@a.b.c.d>'&. If this is in the envelope and the message is | |
14141 | passed on to another MTA, the excess angle brackets are not passed on. If this | |
14142 | option is not set, multiple pairs of angle brackets cause a syntax error. | |
14143 | ||
14144 | ||
14145 | .option strip_trailing_dot main boolean false | |
14146 | .cindex "trailing dot on domain" | |
14147 | .cindex "dot" "trailing on domain" | |
168e428f PH |
14148 | If this option is set, a trailing dot at the end of a domain in an address is |
14149 | ignored. If this is in the envelope and the message is passed on to another | |
14150 | MTA, the dot is not passed on. If this option is not set, a dot at the end of a | |
14151 | domain causes a syntax error. | |
14152 | However, addresses in header lines are checked only when an ACL requests header | |
14153 | syntax checking. | |
14154 | ||
14155 | ||
9b371988 PH |
14156 | .option syslog_duplication main boolean true |
14157 | .cindex "syslog" "duplicate log lines; suppressing" | |
168e428f PH |
14158 | When Exim is logging to syslog, it writes the log lines for its three |
14159 | separate logs at different syslog priorities so that they can in principle | |
14160 | be separated on the logging hosts. Some installations do not require this | |
14161 | separation, and in those cases, the duplication of certain log lines is a | |
9b371988 | 14162 | nuisance. If &%syslog_duplication%& is set false, only one copy of any |
168e428f PH |
14163 | particular log line is written to syslog. For lines that normally go to |
14164 | both the main log and the reject log, the reject log version (possibly | |
14165 | containing message header lines) is written, at LOG_NOTICE priority. | |
14166 | Lines that normally go to both the main and the panic log are written at | |
14167 | the LOG_ALERT priority. | |
14168 | ||
14169 | ||
9b371988 PH |
14170 | .option syslog_facility main string unset |
14171 | .cindex "syslog" "facility; setting" | |
14172 | This option sets the syslog &"facility"& name, used when Exim is logging to | |
14173 | syslog. The value must be one of the strings &"mail"&, &"user"&, &"news"&, | |
14174 | &"uucp"&, &"daemon"&, or &"local&'x'&"& where &'x'& is a digit between 0 and 7. | |
14175 | If this option is unset, &"mail"& is used. See chapter &<<CHAPlog>>& for | |
14176 | details of Exim's logging. | |
168e428f | 14177 | |
168e428f | 14178 | |
168e428f | 14179 | |
9b371988 PH |
14180 | .option syslog_processname main string &`exim`& |
14181 | .cindex "syslog" "process name; setting" | |
14182 | This option sets the syslog &"ident"& name, used when Exim is logging to | |
14183 | syslog. The value must be no longer than 32 characters. See chapter | |
14184 | &<<CHAPlog>>& for details of Exim's logging. | |
168e428f PH |
14185 | |
14186 | ||
168e428f | 14187 | |
9b371988 PH |
14188 | .option syslog_timestamp main boolean true |
14189 | .cindex "syslog" "timestamps" | |
14190 | If &%syslog_timestamp%& is set false, the timestamps on Exim's log lines are | |
14191 | omitted when these lines are sent to syslog. See chapter &<<CHAPlog>>& for | |
168e428f PH |
14192 | details of Exim's logging. |
14193 | ||
14194 | ||
9b371988 PH |
14195 | .option system_filter main string&!! unset |
14196 | .cindex "filter" "system filter" | |
14197 | .cindex "system filter" "specifying" | |
14198 | .cindex "Sieve filter" "not available for system filter" | |
168e428f PH |
14199 | This option specifies an Exim filter file that is applied to all messages at |
14200 | the start of each delivery attempt, before any routing is done. System filters | |
14201 | must be Exim filters; they cannot be Sieve filters. If the system filter | |
14202 | generates any deliveries to files or pipes, or any new mail messages, the | |
9b371988 | 14203 | appropriate &%system_filter_..._transport%& option(s) must be set, to define |
168e428f | 14204 | which transports are to be used. Details of this facility are given in chapter |
9b371988 | 14205 | &<<CHAPsystemfilter>>&. |
168e428f | 14206 | |
168e428f | 14207 | |
9b371988 PH |
14208 | .option system_filter_directory_transport main string&!! unset |
14209 | .cindex "&$address_file$&" | |
168e428f | 14210 | This sets the name of the transport driver that is to be used when the |
9b371988 | 14211 | &%save%& command in a system message filter specifies a path ending in &"/"&, |
168e428f | 14212 | implying delivery of each message into a separate file in some directory. |
9b371988 | 14213 | During the delivery, the variable &$address_file$& contains the path name. |
168e428f PH |
14214 | |
14215 | ||
9b371988 PH |
14216 | .option system_filter_file_transport main string&!! unset |
14217 | .cindex "file" "transport for system filter" | |
14218 | This sets the name of the transport driver that is to be used when the &%save%& | |
14219 | command in a system message filter specifies a path not ending in &"/"&. During | |
14220 | the delivery, the variable &$address_file$& contains the path name. | |
168e428f | 14221 | |
9b371988 PH |
14222 | .option system_filter_group main string unset |
14223 | .cindex "gid (group id)" "system filter" | |
14224 | This option is used only when &%system_filter_user%& is also set. It sets the | |
168e428f PH |
14225 | gid under which the system filter is run, overriding any gid that is associated |
14226 | with the user. The value may be numerical or symbolic. | |
14227 | ||
9b371988 PH |
14228 | .option system_filter_pipe_transport main string&!! unset |
14229 | .cindex "&(pipe)& transport" "for system filter" | |
14230 | .cindex "&$address_pipe$&" | |
14231 | This specifies the transport driver that is to be used when a &%pipe%& command | |
14232 | is used in a system filter. During the delivery, the variable &$address_pipe$& | |
168e428f PH |
14233 | contains the pipe command. |
14234 | ||
14235 | ||
9b371988 PH |
14236 | .option system_filter_reply_transport main string&!! unset |
14237 | .cindex "&(autoreply)& transport" "for system filter" | |
14238 | This specifies the transport driver that is to be used when a &%mail%& command | |
14239 | is used in a system filter. | |
168e428f | 14240 | |
9b371988 PH |
14241 | .option system_filter_user main string unset |
14242 | .cindex "uid (user id)" "system filter" | |
168e428f PH |
14243 | If this option is not set, the system filter is run in the main Exim delivery |
14244 | process, as root. When the option is set, the system filter runs in a separate | |
14245 | process, as the given user. Unless the string consists entirely of digits, it | |
14246 | is looked up in the password data. Failure to find the named user causes a | |
14247 | configuration error. The gid is either taken from the password data, or | |
9b371988 PH |
14248 | specified by &%system_filter_group%&. When the uid is specified numerically, |
14249 | &%system_filter_group%& is required to be set. | |
168e428f PH |
14250 | |
14251 | If the system filter generates any pipe, file, or reply deliveries, the uid | |
14252 | under which the filter is run is used when transporting them, unless a | |
9b371988 | 14253 | transport option overrides. Normally you should set &%system_filter_user%& if |
168e428f PH |
14254 | your system filter generates these kinds of delivery. |
14255 | ||
14256 | ||
9b371988 PH |
14257 | .option tcp_nodelay main boolean true |
14258 | .cindex "daemon" "TCP_NODELAY on sockets" | |
14259 | .cindex "Nagle algorithm" | |
14260 | .cindex "TCP_NODELAY on listening sockets" | |
168e428f PH |
14261 | If this option is set false, it stops the Exim daemon setting the |
14262 | TCP_NODELAY option on its listening sockets. Setting TCP_NODELAY | |
9b371988 | 14263 | turns off the &"Nagle algorithm"&, which is a way of improving network |
168e428f PH |
14264 | performance in interactive (character-by-character) situations. Turning it off |
14265 | should improve Exim's performance a bit, so that is what happens by default. | |
14266 | However, it appears that some broken clients cannot cope, and time out. Hence | |
14267 | this option. It affects only those sockets that are set up for listening by the | |
14268 | daemon. Sockets created by the smtp transport for delivering mail always set | |
14269 | TCP_NODELAY. | |
14270 | ||
14271 | ||
9b371988 PH |
14272 | .option timeout_frozen_after main time 0s |
14273 | .cindex "frozen messages" "timing out" | |
14274 | .cindex "timeout" "frozen messages" | |
14275 | If &%timeout_frozen_after%& is set to a time greater than zero, a frozen | |
168e428f PH |
14276 | message of any kind that has been on the queue for longer than the given |
14277 | time is automatically cancelled at the next queue run. If it is a bounce | |
14278 | message, it is just discarded; otherwise, a bounce is sent to the sender, in a | |
9b371988 | 14279 | similar manner to cancellation by the &%-Mg%& command line option. If you want |
168e428f | 14280 | to timeout frozen bounce messages earlier than other kinds of frozen message, |
9b371988 | 14281 | see &%ignore_bounce_errors_after%&. |
168e428f | 14282 | |
168e428f | 14283 | |
9b371988 PH |
14284 | .option timezone main string unset |
14285 | .cindex "timezone" "setting" | |
14286 | The value of &%timezone%& is used to set the environment variable TZ while | |
168e428f PH |
14287 | running Exim (if it is different on entry). This ensures that all timestamps |
14288 | created by Exim are in the required timezone. If you want all your timestamps | |
14289 | to be in UTC (aka GMT) you should set | |
9b371988 PH |
14290 | .code |
14291 | timezone = UTC | |
14292 | .endd | |
14293 | The default value is taken from TIMEZONE_DEFAULT in &_Local/Makefile_&, | |
168e428f | 14294 | or, if that is not set, from the value of the TZ environment variable when Exim |
9b371988 | 14295 | is built. If &%timezone%& is set to the empty string, either at build or run |
168e428f PH |
14296 | time, any existing TZ variable is removed from the environment when Exim |
14297 | runs. This is appropriate behaviour for obtaining wall-clock time on some, but | |
14298 | unfortunately not all, operating systems. | |
14299 | ||
14300 | ||
9b371988 PH |
14301 | .option tls_advertise_hosts main "host list&!!" unset |
14302 | .cindex "TLS" "advertising" | |
14303 | .cindex "encryption" "on SMTP connection" | |
14304 | .cindex "SMTP" "encrypted connection" | |
168e428f PH |
14305 | When Exim is built with support for TLS encrypted connections, the availability |
14306 | of the STARTTLS command to set up an encrypted session is advertised in | |
14307 | response to EHLO only to those client hosts that match this option. See | |
9b371988 | 14308 | chapter &<<CHAPTLS>>& for details of Exim's support for TLS. |
168e428f PH |
14309 | |
14310 | ||
9b371988 PH |
14311 | .option tls_certificate main string&!! unset |
14312 | .cindex "TLS" "server certificate; location of" | |
14313 | .cindex "certificate for server" "location of" | |
168e428f PH |
14314 | The value of this option is expanded, and must then be the absolute path to a |
14315 | file which contains the server's certificates. The server's private key is also | |
9b371988 PH |
14316 | assumed to be in this file if &%tls_privatekey%& is unset. See chapter |
14317 | &<<CHAPTLS>>& for further details. | |
168e428f | 14318 | |
9b371988 | 14319 | &*Note*&: The certificates defined by this option are used only when Exim is |
168e428f | 14320 | receiving incoming messages as a server. If you want to supply certificates for |
9b371988 PH |
14321 | use when sending messages as a client, you must set the &%tls_certificate%& |
14322 | option in the relevant &(smtp)& transport. | |
168e428f | 14323 | |
168e428f | 14324 | |
9b371988 PH |
14325 | .option tls_crl main string&!! unset |
14326 | .cindex "TLS" "server certificate revocation list" | |
14327 | .cindex "certificate" "revocation list for server" | |
168e428f PH |
14328 | This option specifies a certificate revocation list. The expanded value must |
14329 | be the name of a file that contains a CRL in PEM format. | |
14330 | ||
14331 | ||
9b371988 PH |
14332 | .option tls_dhparam main string&!! unset |
14333 | .cindex "TLS" "D-H parameters for server" | |
168e428f PH |
14334 | The value of this option is expanded, and must then be the absolute path to |
14335 | a file which contains the server's DH parameter values. | |
14336 | This is used only for OpenSSL. When Exim is linked with GnuTLS, this option is | |
9b371988 | 14337 | ignored. See section &<<SECTopenvsgnu>>& for further details. |
168e428f PH |
14338 | |
14339 | ||
9b371988 | 14340 | .option tls_on_connect_ports main "string list" unset |
168e428f PH |
14341 | This option specifies a list of incoming SSMTP (aka SMTPS) ports that should |
14342 | operate the obsolete SSMTP (SMTPS) protocol, where a TLS session is immediately | |
14343 | set up without waiting for the client to issue a STARTTLS command. For | |
9b371988 | 14344 | further details, see section &<<SECTsupobssmt>>&. |
168e428f PH |
14345 | |
14346 | ||
168e428f | 14347 | |
9b371988 PH |
14348 | .option tls_privatekey main string&!! unset |
14349 | .cindex "TLS" "server private key; location of" | |
168e428f PH |
14350 | The value of this option is expanded, and must then be the absolute path to a |
14351 | file which contains the server's private key. If this option is unset, the | |
14352 | private key is assumed to be in the same file as the server's certificates. See | |
9b371988 | 14353 | chapter &<<CHAPTLS>>& for further details. |
168e428f | 14354 | |
168e428f | 14355 | |
9b371988 PH |
14356 | .option tls_remember_esmtp main boolean false |
14357 | .cindex "TLS" "esmtp state; remembering" | |
14358 | .cindex "TLS" "broken clients" | |
168e428f | 14359 | If this option is set true, Exim violates the RFCs by remembering that it is in |
9b371988 | 14360 | &"esmtp"& state after successfully negotiating a TLS session. This provides |
168e428f PH |
14361 | support for broken clients that fail to send a new EHLO after starting a |
14362 | TLS session. | |
14363 | ||
14364 | ||
9b371988 PH |
14365 | .option tls_require_ciphers main string&!! unset |
14366 | .cindex "TLS" "requiring specific ciphers" | |
14367 | .cindex "cipher" "requiring specific" | |
168e428f | 14368 | This option controls which ciphers can be used for incoming TLS connections. |
9b371988 | 14369 | The &(smtp)& transport has an option of the same name for controlling outgoing |
168e428f PH |
14370 | connections. This option is expanded for each connection, so can be varied for |
14371 | different clients if required. The value of this option must be a list of | |
14372 | permitted cipher suites. The OpenSSL and GnuTLS libraries handle cipher control | |
9b371988 PH |
14373 | in somewhat different ways. If GnuTLS is being used, the client controls the |
14374 | preference order of the available ciphers. Details are given in sections | |
14375 | &<<SECTreqciphssl>>& and &<<SECTreqciphgnu>>&. | |
168e428f | 14376 | |
168e428f | 14377 | |
9b371988 PH |
14378 | .option tls_try_verify_hosts main "host list&!!" unset |
14379 | .cindex "TLS" "client certificate verification" | |
14380 | .cindex "certificate" "verification of client" | |
14381 | See &%tls_verify_hosts%& below. | |
168e428f | 14382 | |
168e428f | 14383 | |
9b371988 PH |
14384 | .option tls_verify_certificates main string&!! unset |
14385 | .cindex "TLS" "client certificate verification" | |
14386 | .cindex "certificate" "verification of client" | |
168e428f PH |
14387 | The value of this option is expanded, and must then be the absolute path to |
14388 | a file containing permitted certificates for clients that | |
9b371988 PH |
14389 | match &%tls_verify_hosts%& or &%tls_try_verify_hosts%&. Alternatively, if you |
14390 | are using OpenSSL, you can set &%tls_verify_certificates%& to the name of a | |
168e428f PH |
14391 | directory containing certificate files. This does not work with GnuTLS; the |
14392 | option must be set to the name of a single file if you are using GnuTLS. | |
14393 | ||
14394 | ||
9b371988 PH |
14395 | .option tls_verify_hosts main "host list&!!" unset |
14396 | .cindex "TLS" "client certificate verification" | |
14397 | .cindex "certificate" "verification of client" | |
14398 | This option, along with &%tls_try_verify_hosts%&, controls the checking of | |
168e428f | 14399 | certificates from clients. |
9b371988 PH |
14400 | The expected certificates are defined by &%tls_verify_certificates%&, which |
14401 | must be set. A configuration error occurs if either &%tls_verify_hosts%& or | |
14402 | &%tls_try_verify_hosts%& is set and &%tls_verify_certificates%& is not set. | |
168e428f | 14403 | |
9b371988 PH |
14404 | Any client that matches &%tls_verify_hosts%& is constrained by |
14405 | &%tls_verify_certificates%&. The client must present one of the listed | |
168e428f PH |
14406 | certificates. If it does not, the connection is aborted. |
14407 | ||
9b371988 PH |
14408 | A weaker form of checking is provided by &%tls_try_verify_hosts%&. If a client |
14409 | matches this option (but not &%tls_verify_hosts%&), Exim requests a | |
14410 | certificate and checks it against &%tls_verify_certificates%&, but does not | |
168e428f PH |
14411 | abort the connection if there is no certificate or if it does not match. This |
14412 | state can be detected in an ACL, which makes it possible to implement policies | |
9b371988 PH |
14413 | such as &"accept for relay only if a verified certificate has been received, |
14414 | but accept for local delivery if encrypted, even without a verified | |
14415 | certificate"&. | |
168e428f PH |
14416 | |
14417 | Client hosts that match neither of these lists are not asked to present | |
14418 | certificates. | |
14419 | ||
14420 | ||
9b371988 PH |
14421 | .option trusted_groups main "string list&!!" unset |
14422 | .cindex "trusted group" | |
14423 | .cindex "group" "trusted" | |
14424 | .new | |
068aaea8 PH |
14425 | This option is expanded just once, at the start of Exim's processing. If this |
14426 | option is set, any process that is running in one of the listed groups, or | |
14427 | which has one of them as a supplementary group, is trusted. The groups can be | |
9b371988 PH |
14428 | specified numerically or by name. See section &<<SECTtrustedadmin>>& for |
14429 | details of what trusted callers are permitted to do. If neither | |
14430 | &%trusted_groups%& nor &%trusted_users%& is set, only root and the Exim user | |
14431 | are trusted. | |
14432 | .wen | |
14433 | ||
14434 | .option trusted_users main "string list&!!" unset | |
14435 | .cindex "trusted user" | |
14436 | .cindex "user" "trusted" | |
14437 | .new | |
068aaea8 PH |
14438 | This option is expanded just once, at the start of Exim's processing. If this |
14439 | option is set, any process that is running as one of the listed users is | |
14440 | trusted. The users can be specified numerically or by name. See section | |
9b371988 PH |
14441 | &<<SECTtrustedadmin>>& for details of what trusted callers are permitted to do. |
14442 | If neither &%trusted_groups%& nor &%trusted_users%& is set, only root and the | |
14443 | Exim user are trusted. | |
14444 | .wen | |
14445 | ||
14446 | .option unknown_login main string&!! unset | |
14447 | .cindex "uid (user id)" "unknown caller" | |
14448 | .cindex "&$caller_uid$&" | |
168e428f | 14449 | This is a specialized feature for use in unusual configurations. By default, if |
9b371988 PH |
14450 | the uid of the caller of Exim cannot be looked up using &[getpwuid()]&, Exim |
14451 | gives up. The &%unknown_login%& option can be used to set a login name to be | |
14452 | used in this circumstance. It is expanded, so values like &%user$caller_uid%& | |
14453 | can be set. When &%unknown_login%& is used, the value of &%unknown_username%& | |
14454 | is used for the user's real name (gecos field), unless this has been set by the | |
14455 | &%-F%& option. | |
14456 | ||
14457 | .option unknown_username main string unset | |
14458 | See &%unknown_login%&. | |
14459 | ||
14460 | .option untrusted_set_sender main "address list&!!" unset | |
14461 | .cindex "trusted user" | |
14462 | .cindex "sender" "setting by untrusted user" | |
14463 | .cindex "untrusted user" "setting sender" | |
14464 | .cindex "user" "untrusted setting sender" | |
14465 | .cindex "envelope sender" | |
168e428f PH |
14466 | When an untrusted user submits a message to Exim using the standard input, Exim |
14467 | normally creates an envelope sender address from the user's login and the | |
9b371988 PH |
14468 | default qualification domain. Data from the &%-f%& option (for setting envelope |
14469 | senders on non-SMTP messages) or the SMTP MAIL command (if &%-bs%& or &%-bS%& | |
168e428f PH |
14470 | is used) is ignored. |
14471 | ||
14472 | However, untrusted users are permitted to set an empty envelope sender address, | |
14473 | to declare that a message should never generate any bounces. For example: | |
9b371988 PH |
14474 | .code |
14475 | exim -f '<>' user@domain.example | |
14476 | .endd | |
14477 | .cindex "&$sender_ident$&" | |
14478 | The &%untrusted_set_sender%& option allows you to permit untrusted users to set | |
168e428f PH |
14479 | other envelope sender addresses in a controlled way. When it is set, untrusted |
14480 | users are allowed to set envelope sender addresses that match any of the | |
14481 | patterns in the list. Like all address lists, the string is expanded. The | |
9b371988 | 14482 | identity of the user is in &$sender_ident$&, so you can, for example, restrict |
168e428f PH |
14483 | users to setting senders that start with their login ids |
14484 | followed by a hyphen | |
14485 | by a setting like this: | |
9b371988 PH |
14486 | .code |
14487 | untrusted_set_sender = ^$sender_ident- | |
14488 | .endd | |
168e428f PH |
14489 | If you want to allow untrusted users to set envelope sender addresses without |
14490 | restriction, you can use | |
9b371988 PH |
14491 | .code |
14492 | untrusted_set_sender = * | |
14493 | .endd | |
14494 | The &%untrusted_set_sender%& option applies to all forms of local input, but | |
168e428f PH |
14495 | only to the setting of the envelope sender. It does not permit untrusted users |
14496 | to use the other options which trusted user can use to override message | |
14497 | parameters. Furthermore, it does not stop Exim from removing an existing | |
9b371988 PH |
14498 | &'Sender:'& header in the message, or from adding a &'Sender:'& header if |
14499 | necessary. See &%local_sender_retain%& and &%local_from_check%& for ways of | |
14500 | overriding these actions. The handling of the &'Sender:'& header is also | |
14501 | described in section &<<SECTthesenhea>>&. | |
168e428f | 14502 | |
9b371988 PH |
14503 | The log line for a message's arrival shows the envelope sender following |
14504 | &"<="&. For local messages, the user's login always follows, after &"U="&. In | |
14505 | &%-bp%& displays, and in the Exim monitor, if an untrusted user sets an | |
14506 | envelope sender address, the user's login is shown in parentheses after the | |
14507 | sender address. | |
168e428f | 14508 | |
168e428f | 14509 | |
9b371988 PH |
14510 | .option uucp_from_pattern main string "see below" |
14511 | .cindex "&""From""& line" | |
14512 | .cindex "UUCP" "&""From""& line" | |
168e428f | 14513 | Some applications that pass messages to an MTA via a command line interface use |
9b371988 | 14514 | an initial line starting with &"From&~"& to pass the envelope sender. In |
168e428f | 14515 | particular, this is used by UUCP software. Exim recognizes such a line by means |
9b371988 | 14516 | of a regular expression that is set in &%uucp_from_pattern%&. When the pattern |
168e428f | 14517 | matches, the sender address is constructed by expanding the contents of |
9b371988 | 14518 | &%uucp_from_sender%&, provided that the caller of Exim is a trusted user. The |
168e428f | 14519 | default pattern recognizes lines in the following two forms: |
9b371988 PH |
14520 | .code |
14521 | From ph10 Fri Jan 5 12:35 GMT 1996 | |
14522 | From ph10 Fri, 7 Jan 97 14:00:00 GMT | |
14523 | .endd | |
168e428f | 14524 | The pattern can be seen by running |
9b371988 PH |
14525 | .code |
14526 | exim -bP uucp_from_pattern | |
14527 | .endd | |
168e428f | 14528 | It checks only up to the hours and minutes, and allows for a 2-digit or 4-digit |
9b371988 PH |
14529 | year in the second case. The first word after &"From&~"& is matched in the |
14530 | regular expression by a parenthesized subpattern. The default value for | |
14531 | &%uucp_from_sender%& is &"$1"&, which therefore just uses this first word | |
14532 | (&"ph10"& in the example above) as the message's sender. See also | |
14533 | &%ignore_fromline_hosts%&. | |
168e428f PH |
14534 | |
14535 | ||
9b371988 PH |
14536 | .option uucp_from_sender main string&!! &`$1`& |
14537 | See &%uucp_from_pattern%& above. | |
168e428f | 14538 | |
168e428f | 14539 | |
9b371988 PH |
14540 | .option warn_message_file main string unset |
14541 | .cindex "warning of delay" "customizing the message" | |
14542 | .cindex "customizing" "warning message" | |
168e428f PH |
14543 | This option defines a template file containing paragraphs of text to be used |
14544 | for constructing the warning message which is sent by Exim when a message has | |
14545 | been on the queue for a specified amount of time, as specified by | |
9b371988 PH |
14546 | &%delay_warning%&. Details of the file's contents are given in chapter |
14547 | &<<CHAPemsgcust>>&. See also &%bounce_message_file%&. | |
168e428f PH |
14548 | |
14549 | ||
9b371988 PH |
14550 | .option write_rejectlog main boolean true |
14551 | .cindex "reject log" "disabling" | |
168e428f | 14552 | If this option is set false, Exim no longer writes anything to the reject log. |
9b371988 | 14553 | See chapter &<<CHAPlog>>& for details of what Exim writes to its logs. |
168e428f PH |
14554 | |
14555 | ||
14556 | ||
14557 | ||
9b371988 PH |
14558 | . //////////////////////////////////////////////////////////////////////////// |
14559 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 14560 | |
9b371988 PH |
14561 | .chapter "Generic options for routers" "CHAProutergeneric" |
14562 | .cindex "options" "generic; for routers" | |
14563 | .cindex "generic options" "router" | |
168e428f | 14564 | This chapter describes the generic options that apply to all routers. |
9b371988 | 14565 | Those that are preconditions are marked with ‡ in the &"use"& field. |
168e428f PH |
14566 | |
14567 | For a general description of how a router operates, see sections | |
9b371988 | 14568 | &<<SECTrunindrou>>& and &<<SECTrouprecon>>&. The latter specifies the order in |
168e428f | 14569 | which the preconditions are tested. The order of expansion of the options that |
9b371988 PH |
14570 | provide data for a transport is: &%errors_to%&, &%headers_add%&, |
14571 | &%headers_remove%&, &%transport%&. | |
168e428f PH |
14572 | |
14573 | ||
168e428f | 14574 | |
9b371988 PH |
14575 | .option address_data routers string&!! unset |
14576 | .cindex "router" "data attached to address" | |
14577 | .new | |
168e428f PH |
14578 | The string is expanded just before the router is run, that is, after all the |
14579 | precondition tests have succeeded. If the expansion is forced to fail, the | |
9b371988 PH |
14580 | router declines, the value of &%address_data%& remains unchanged, and the |
14581 | &%more%& option controls what happens next. Other expansion failures cause | |
14582 | delivery of the address to be deferred. | |
14583 | .wen | |
168e428f | 14584 | |
9b371988 | 14585 | .cindex "&$address_data$&" |
168e428f | 14586 | When the expansion succeeds, the value is retained with the address, and can be |
9b371988 | 14587 | accessed using the variable &$address_data$& in the current router, subsequent |
168e428f PH |
14588 | routers, and the eventual transport. |
14589 | ||
9b371988 PH |
14590 | &*Warning*&: If the current or any subsequent router is a &(redirect)& router |
14591 | that runs a user's filter file, the contents of &$address_data$& are accessible | |
068aaea8 | 14592 | in the filter. This is not normally a problem, because such data is usually |
9b371988 PH |
14593 | either not confidential or it &"belongs"& to the current user, but if you do |
14594 | put confidential data into &$address_data$& you need to remember this point. | |
168e428f | 14595 | |
9b371988 PH |
14596 | Even if the router declines or passes, the value of &$address_data$& remains |
14597 | with the address, though it can be changed by another &%address_data%& setting | |
168e428f | 14598 | on a subsequent router. If a router generates child addresses, the value of |
9b371988 PH |
14599 | &$address_data$& propagates to them. This also applies to the special kind of |
14600 | &"child"& that is generated by a router with the &%unseen%& option. | |
14601 | ||
14602 | The idea of &%address_data%& is that you can use it to look up a lot of data | |
14603 | for the address once, and then pick out parts of the data later. For example, | |
14604 | you could use a single LDAP lookup to return a string of the form | |
14605 | .code | |
14606 | uid=1234 gid=5678 mailbox=/mail/xyz forward=/home/xyz/.forward | |
14607 | .endd | |
168e428f | 14608 | In the transport you could pick out the mailbox by a setting such as |
9b371988 PH |
14609 | .code |
14610 | file = ${extract{mailbox}{$address_data}} | |
14611 | .endd | |
168e428f PH |
14612 | This makes the configuration file less messy, and also reduces the number of |
14613 | lookups (though Exim does cache lookups). | |
14614 | ||
9b371988 | 14615 | The &%address_data%& facility is also useful as a means of passing information |
168e428f PH |
14616 | from one router to another, and from a router to a transport. In addition, if |
14617 | ||
9b371988 PH |
14618 | .cindex "&$sender_address_data$&" |
14619 | .cindex "&$address_data$&" | |
14620 | When &$address_data$& is set by a router when verifying a recipient address | |
14621 | from an ACL, it remains available for use in the rest of the ACL statement. | |
14622 | After verifying a sender, the value is transferred to &$sender_address_data$&. | |
168e428f PH |
14623 | |
14624 | ||
14625 | ||
168e428f | 14626 | |
9b371988 PH |
14627 | .option address_test routers&!? boolean true |
14628 | .cindex "&%-bt%& option" | |
14629 | .cindex "router" "skipping when address testing" | |
168e428f | 14630 | If this option is set false, the router is skipped when routing is being tested |
9b371988 PH |
14631 | by means of the &%-bt%& command line option. This can be a convenience when |
14632 | your first router sends messages to an external scanner, because it saves you | |
14633 | having to set the &"already scanned"& indicator when testing real address | |
168e428f PH |
14634 | routing. |
14635 | ||
14636 | ||
14637 | ||
9b371988 PH |
14638 | .option cannot_route_message routers string&!! unset |
14639 | .cindex "router" "customizing &""cannot route""& message" | |
14640 | .cindex "customizing" "&""cannot route""& message" | |
168e428f | 14641 | This option specifies a text message that is used when an address cannot be |
9b371988 PH |
14642 | routed because Exim has run out of routers. The default message is |
14643 | &"Unrouteable address"&. This option is useful only on routers that have | |
14644 | &%more%& set false, or on the very last router in a configuration, because the | |
14645 | value that is used is taken from the last router that is considered. &new("This | |
14646 | includes a router that is skipped because its preconditions are not met, as | |
14647 | well as a router that declines.") For example, using the default configuration, | |
14648 | you could put: | |
14649 | .code | |
14650 | cannot_route_message = Remote domain not found in DNS | |
14651 | .endd | |
14652 | on the first router, which is a &(dnslookup)& router with &%more%& set false, | |
14653 | and | |
14654 | .code | |
14655 | cannot_route_message = Unknown local user | |
14656 | .endd | |
14657 | on the final router that checks for local users. If string expansion fails for | |
14658 | this option, the default message is used. Unless the expansion failure was | |
14659 | explicitly forced, a message about the failure is written to the main and panic | |
14660 | logs, in addition to the normal message about the routing failure. | |
14661 | ||
14662 | ||
14663 | .option caseful_local_part routers boolean false | |
14664 | .cindex "case of local parts" | |
14665 | .cindex "router" "case of local parts" | |
168e428f PH |
14666 | By default, routers handle the local parts of addresses in a case-insensitive |
14667 | manner, though the actual case is preserved for transmission with the message. | |
14668 | If you want the case of letters to be significant in a router, you must set | |
14669 | this option true. For individual router options that contain address or local | |
9b371988 PH |
14670 | part lists (for example, &%local_parts%&), case-sensitive matching can be |
14671 | turned on by &"+caseful"& as a list item. See section &<<SECTcasletadd>>& for | |
14672 | more details. | |
14673 | ||
14674 | .cindex "&$local_part$&" | |
14675 | .cindex "&$original_local_part$&" | |
14676 | .cindex "&$parent_local_part$&" | |
14677 | The value of the &$local_part$& variable is forced to lower case while a | |
14678 | router is running unless &%caseful_local_part%& is set. When a router assigns | |
14679 | an address to a transport, the value of &$local_part$& when the transport runs | |
168e428f | 14680 | is the same as it was in the router. Similarly, when a router generates child |
9b371988 PH |
14681 | addresses by aliasing or forwarding, the values of &$original_local_part$& |
14682 | and &$parent_local_part$& are those that were used by the redirecting router. | |
168e428f PH |
14683 | |
14684 | This option applies to the processing of an address by a router. When a | |
9b371988 | 14685 | recipient address is being processed in an ACL, there is a separate &%control%& |
168e428f | 14686 | modifier that can be used to specify case-sensitive processing within the ACL |
9b371988 | 14687 | (see section &<<SECTcontrols>>&). |
168e428f PH |
14688 | |
14689 | ||
14690 | ||
9b371988 PH |
14691 | .option check_local_user routers&!? boolean false |
14692 | .cindex "local user" "checking in router" | |
14693 | .cindex "router" "checking for local user" | |
14694 | .cindex "&_/etc/passwd_&" | |
14695 | .cindex "&$home$&" | |
168e428f PH |
14696 | When this option is true, Exim checks that the local part of the recipient |
14697 | address (with affixes removed if relevant) is the name of an account on the | |
9b371988 PH |
14698 | local system. The check is done by calling the &[getpwnam()]& function rather |
14699 | than trying to read &_/etc/passwd_& directly. This means that other methods of | |
168e428f | 14700 | holding password data (such as NIS) are supported. If the local part is a local |
9b371988 | 14701 | user, &$home$& is set from the password data, and can be tested in other |
168e428f | 14702 | preconditions that are evaluated after this one (the order of evaluation is |
9b371988 PH |
14703 | given in section &<<SECTrouprecon>>&). However, the value of &$home$& can be |
14704 | overridden by &%router_home_directory%&. If the local part is not a local user, | |
168e428f PH |
14705 | the router is skipped. |
14706 | ||
14707 | If you want to check that the local part is either the name of a local user | |
9b371988 PH |
14708 | or matches something else, you cannot combine &%check_local_user%& with a |
14709 | setting of &%local_parts%&, because that specifies the logical &'and'& of the | |
14710 | two conditions. However, you can use a &(passwd)& lookup in a &%local_parts%& | |
168e428f | 14711 | setting to achieve this. For example: |
9b371988 PH |
14712 | .code |
14713 | local_parts = passwd;$local_part : lsearch;/etc/other/users | |
14714 | .endd | |
14715 | Note, however, that the side effects of &%check_local_user%& (such as setting | |
14716 | up a home directory) do not occur when a &(passwd)& lookup is used in a | |
14717 | &%local_parts%& (or any other) precondition. | |
168e428f | 14718 | |
168e428f PH |
14719 | |
14720 | ||
9b371988 PH |
14721 | .option condition routers&!? string&!! unset |
14722 | .cindex "router" "customized precondition" | |
168e428f | 14723 | This option specifies a general precondition test that has to succeed for the |
9b371988 PH |
14724 | router to be called. The &%condition%& option is the last precondition to be |
14725 | evaluated (see section &<<SECTrouprecon>>&). The string is expanded, and if the | |
14726 | result is a forced failure, or an empty string, or one of the strings &"0"& or | |
14727 | &"no"& or &"false"& (checked without regard to the case of the letters), the | |
14728 | router is skipped, and the address is offered to the next one. | |
168e428f PH |
14729 | |
14730 | If the result is any other value, the router is run (as this is the last | |
14731 | precondition to be evaluated, all the other preconditions must be true). | |
14732 | ||
9b371988 | 14733 | The &%condition%& option provides a means of applying custom conditions to the |
168e428f PH |
14734 | running of routers. Note that in the case of a simple conditional expansion, |
14735 | the default expansion values are exactly what is wanted. For example: | |
9b371988 PH |
14736 | .code |
14737 | condition = ${if >{$message_age}{600}} | |
14738 | .endd | |
168e428f | 14739 | Because of the default behaviour of the string expansion, this is equivalent to |
9b371988 PH |
14740 | .code |
14741 | condition = ${if >{$message_age}{600}{true}{}} | |
14742 | .endd | |
168e428f PH |
14743 | If the expansion fails (other than forced failure) delivery is deferred. Some |
14744 | of the other precondition options are common special cases that could in fact | |
9b371988 | 14745 | be specified using &%condition%&. |
168e428f PH |
14746 | |
14747 | ||
168e428f | 14748 | |
9b371988 PH |
14749 | .option debug_print routers string&!! unset |
14750 | .cindex "testing" "variables in drivers" | |
14751 | If this option is set and debugging is enabled (see the &%-d%& command line | |
168e428f PH |
14752 | option), the string is expanded and included in the debugging output. |
14753 | If expansion of the string fails, the error message is written to the debugging | |
14754 | output, and Exim carries on processing. | |
14755 | This option is provided to help with checking out the values of variables and | |
9b371988 PH |
14756 | so on when debugging router configurations. For example, if a &%condition%& |
14757 | option appears not to be working, &%debug_print%& can be used to output the | |
14758 | variables it references. The output happens after checks for &%domains%&, | |
14759 | &%local_parts%&, and &%check_local_user%& but before any other preconditions | |
14760 | are tested. A newline is added to the text if it does not end with one. | |
168e428f PH |
14761 | |
14762 | ||
14763 | ||
9b371988 | 14764 | .option disable_logging routers boolean false |
168e428f PH |
14765 | If this option is set true, nothing is logged for any routing errors |
14766 | or for any deliveries caused by this router. You should not set this option | |
14767 | unless you really, really know what you are doing. See also the generic | |
14768 | transport option of the same name. | |
14769 | ||
14770 | ||
9b371988 PH |
14771 | .option domains routers&!? "domain list&!!" unset |
14772 | .cindex "router" "restricting to specific domains" | |
14773 | .cindex "&$domain_data$&" | |
168e428f PH |
14774 | If this option is set, the router is skipped unless the current domain matches |
14775 | the list. If the match is achieved by means of a file lookup, the data that the | |
9b371988 PH |
14776 | lookup returned for the domain is placed in &$domain_data$& for use in string |
14777 | expansions of the driver's private options. See section &<<SECTrouprecon>>& for | |
14778 | a list of the order in which preconditions are evaluated. | |
168e428f PH |
14779 | |
14780 | ||
14781 | ||
9b371988 | 14782 | .option driver routers string unset |
168e428f PH |
14783 | This option must always be set. It specifies which of the available routers is |
14784 | to be used. | |
14785 | ||
14786 | ||
14787 | ||
9b371988 PH |
14788 | .option errors_to routers string&!! unset |
14789 | .cindex "envelope sender" | |
14790 | .cindex "router" "changing address for errors" | |
168e428f PH |
14791 | If a router successfully handles an address, it may queue the address for |
14792 | delivery or it may generate child addresses. In both cases, if there is a | |
14793 | delivery problem during later processing, the resulting bounce message is sent | |
14794 | to the address that results from expanding this string, provided that the | |
9b371988 PH |
14795 | address verifies successfully. &%errors_to%& is expanded before |
14796 | &%headers_add%&, &%headers_remove%&, and &%transport%&. | |
168e428f PH |
14797 | |
14798 | If the option is unset, or the expansion is forced to fail, or the result of | |
14799 | the expansion fails to verify, the errors address associated with the incoming | |
14800 | address is used. At top level, this is the envelope sender. A non-forced | |
14801 | expansion failure causes delivery to be deferred. | |
14802 | ||
9b371988 PH |
14803 | If an address for which &%errors_to%& has been set ends up being delivered over |
14804 | SMTP, the envelope sender for that delivery is the &%errors_to%& value, so that | |
168e428f | 14805 | any bounces that are generated by other MTAs on the delivery route are also |
9b371988 | 14806 | sent there. The most common use of &%errors_to%& is probably to direct mailing |
168e428f | 14807 | list bounces to the manager of the list, as described in section |
9b371988 | 14808 | &<<SECTmailinglists>>&. |
168e428f | 14809 | |
9b371988 PH |
14810 | The &%errors_to%& setting associated with an address can be overridden if it |
14811 | subsequently passes through other routers that have their own &%errors_to%& | |
168e428f | 14812 | settings, |
9b371988 | 14813 | or if it is delivered by a transport with a &%return_path%& setting. |
168e428f | 14814 | |
9b371988 PH |
14815 | You can set &%errors_to%& to the empty string by either of these settings: |
14816 | .code | |
14817 | errors_to = | |
14818 | errors_to = | |
14819 | .endd | |
168e428f PH |
14820 | An expansion item that yields an empty string has the same effect. If you do |
14821 | this, a locally detected delivery error for addresses processed by this router | |
14822 | no longer gives rise to a bounce message; the error is discarded. If the | |
9b371988 PH |
14823 | address is delivered to a remote host, the return path is set to &`<>`&, unless |
14824 | overridden by the &%return_path%& option on the transport. | |
168e428f | 14825 | |
9b371988 | 14826 | .cindex "&$address_data$&" |
168e428f PH |
14827 | If for some reason you want to discard local errors, but use a non-empty |
14828 | MAIL command for remote delivery, you can preserve the original return | |
9b371988 PH |
14829 | path in &$address_data$& in the router, and reinstate it in the transport by |
14830 | setting &%return_path%&. | |
168e428f PH |
14831 | |
14832 | ||
14833 | ||
9b371988 PH |
14834 | .option expn routers&!? boolean true |
14835 | .cindex "address" "testing" | |
14836 | .cindex "testing" "addresses" | |
14837 | .cindex "EXPN" "router skipping" | |
14838 | .cindex "router" "skipping for EXPN" | |
168e428f PH |
14839 | If this option is turned off, the router is skipped when testing an address |
14840 | as a result of processing an SMTP EXPN command. You might, for example, | |
9b371988 | 14841 | want to turn it off on a router for users' &_.forward_& files, while leaving it |
168e428f | 14842 | on for the system alias file. |
9b371988 | 14843 | See section &<<SECTrouprecon>>& for a list of the order in which preconditions |
168e428f PH |
14844 | are evaluated. |
14845 | ||
14846 | The use of the SMTP EXPN command is controlled by an ACL (see chapter | |
9b371988 PH |
14847 | &<<CHAPACL>>&). When Exim is running an EXPN command, it is similar to testing |
14848 | an address with &%-bt%&. Compare VRFY, whose counterpart is &%-bv%&. | |
168e428f PH |
14849 | |
14850 | ||
168e428f | 14851 | |
9b371988 PH |
14852 | .option fail_verify routers boolean false |
14853 | .cindex "router" "forcing verification failure" | |
14854 | Setting this option has the effect of setting both &%fail_verify_sender%& and | |
14855 | &%fail_verify_recipient%& to the same value. | |
168e428f PH |
14856 | |
14857 | ||
14858 | ||
9b371988 | 14859 | .option fail_verify_recipient routers boolean false |
168e428f PH |
14860 | If this option is true and an address is accepted by this router when |
14861 | verifying a recipient, verification fails. | |
14862 | ||
14863 | ||
14864 | ||
9b371988 | 14865 | .option fail_verify_sender routers boolean false |
168e428f PH |
14866 | If this option is true and an address is accepted by this router when |
14867 | verifying a sender, verification fails. | |
14868 | ||
14869 | ||
14870 | ||
9b371988 PH |
14871 | .option fallback_hosts routers "string list" unset |
14872 | .new | |
14873 | .cindex "router" "fallback hosts" | |
14874 | .cindex "fallback" "hosts specified on router" | |
168e428f | 14875 | String expansion is not applied to this option. The argument must be a |
068aaea8 | 14876 | colon-separated list of host names or IP addresses. The list separator can be |
9b371988 | 14877 | changed (see section &<<SECTlistconstruct>>&), and a port can be specified with |
068aaea8 | 14878 | each name or address. In fact, the format of each item is exactly the same as |
9b371988 PH |
14879 | defined for the list of hosts in a &(manualroute)& router (see section |
14880 | &<<SECTformatonehostitem>>&). | |
14881 | .wen | |
068aaea8 PH |
14882 | |
14883 | If a router queues an address for a remote transport, this host list is | |
14884 | associated with the address, and used instead of the transport's fallback host | |
9b371988 PH |
14885 | list. If &%hosts_randomize%& is set on the transport, the order of the list is |
14886 | randomized for each use. See the &%fallback_hosts%& option of the &(smtp)& | |
068aaea8 | 14887 | transport for further details. |
168e428f PH |
14888 | |
14889 | ||
9b371988 PH |
14890 | .option group routers string&!! "see below" |
14891 | .cindex "gid (group id)" "local delivery" | |
14892 | .cindex "local transports" "uid and gid" | |
14893 | .cindex "transport" "local" | |
14894 | .cindex "router" "setting group" | |
168e428f PH |
14895 | When a router queues an address for a transport, and the transport does not |
14896 | specify a group, the group given here is used when running the delivery | |
14897 | process. | |
14898 | The group may be specified numerically or by name. If expansion fails, the | |
14899 | error is logged and delivery is deferred. | |
9b371988 PH |
14900 | The default is unset, unless &%check_local_user%& is set, when the default |
14901 | is taken from the password information. See also &%initgroups%& and &%user%& | |
14902 | and the discussion in chapter &<<CHAPenvironment>>&. | |
168e428f PH |
14903 | |
14904 | ||
14905 | ||
9b371988 PH |
14906 | .option headers_add routers string&!! unset |
14907 | .new | |
14908 | .cindex "header lines" "adding" | |
14909 | .cindex "router" "adding header lines" | |
168e428f PH |
14910 | This option specifies a string of text that is expanded at routing time, and |
14911 | associated with any addresses that are accepted by the router. However, this | |
14912 | option has no effect when an address is just being verified. The way in which | |
14913 | the text is used to add header lines at transport time is described in section | |
9b371988 | 14914 | &<<SECTheadersaddrem>>&. New header lines are not actually added until the |
d1e83bff PH |
14915 | message is in the process of being transported. This means that references to |
14916 | header lines in string expansions in the transport's configuration do not | |
9b371988 PH |
14917 | &"see"& the added header lines. |
14918 | .wen | |
168e428f | 14919 | |
9b371988 PH |
14920 | The &%headers_add%& option is expanded after &%errors_to%&, but before |
14921 | &%headers_remove%& and &%transport%&. If the expanded string is empty, or if | |
14922 | the expansion is forced to fail, the option has no effect. Other expansion | |
14923 | failures are treated as configuration errors. | |
168e428f | 14924 | |
9b371988 PH |
14925 | &*Warning 1*&: The &%headers_add%& option cannot be used for a &(redirect)& |
14926 | router that has the &%one_time%& option set. | |
068aaea8 | 14927 | |
9b371988 PH |
14928 | .new |
14929 | &*Warning 2*&: If the &%unseen%& option is set on the router, all header | |
14930 | additions are deleted when the address is passed on to subsequent routers. | |
14931 | .wen | |
168e428f PH |
14932 | |
14933 | ||
14934 | ||
9b371988 PH |
14935 | .option headers_remove routers string&!! unset |
14936 | .new | |
14937 | .cindex "header lines" "removing" | |
14938 | .cindex "router" "removing header lines" | |
168e428f PH |
14939 | This option specifies a string of text that is expanded at routing time, and |
14940 | associated with any addresses that are accepted by the router. However, this | |
14941 | option has no effect when an address is just being verified. The way in which | |
14942 | the text is used to remove header lines at transport time is described in | |
9b371988 PH |
14943 | section &<<SECTheadersaddrem>>&. Header lines are not actually removed until |
14944 | the message is in the process of being transported. This means that references | |
14945 | to header lines in string expansions in the transport's configuration still | |
14946 | &"see"& the original header lines. | |
14947 | .wen | |
14948 | ||
14949 | The &%headers_remove%& option is expanded after &%errors_to%& and | |
14950 | &%headers_add%&, but before &%transport%&. If the expansion is forced to fail, | |
14951 | the option has no effect. Other expansion failures are treated as configuration | |
14952 | errors. | |
168e428f | 14953 | |
9b371988 PH |
14954 | &*Warning 1*&: The &%headers_remove%& option cannot be used for a &(redirect)& |
14955 | router that has the &%one_time%& option set. | |
168e428f | 14956 | |
9b371988 PH |
14957 | .new |
14958 | &*Warning 2*&: If the &%unseen%& option is set on the router, all header | |
14959 | removal requests are deleted when the address is passed on to subsequent | |
14960 | routers. | |
14961 | .wen | |
168e428f | 14962 | |
168e428f | 14963 | |
9b371988 PH |
14964 | .option ignore_target_hosts routers "host list&!!" unset |
14965 | .cindex "IP address" "discarding" | |
14966 | .cindex "router" "discarding IP addresses" | |
168e428f PH |
14967 | Although this option is a host list, it should normally contain IP address |
14968 | entries rather than names. If any host that is looked up by the router has an | |
14969 | IP address that matches an item in this list, Exim behaves as if that IP | |
14970 | address did not exist. This option allows you to cope with rogue DNS entries | |
14971 | like | |
9b371988 PH |
14972 | .code |
14973 | remote.domain.example. A 127.0.0.1 | |
14974 | .endd | |
168e428f | 14975 | by setting |
9b371988 PH |
14976 | .code |
14977 | ignore_target_hosts = 127.0.0.1 | |
14978 | .endd | |
14979 | on the relevant router. If all the hosts found by a &(dnslookup)& router are | |
168e428f | 14980 | discarded in this way, the router declines. In a conventional configuration, an |
9b371988 PH |
14981 | attempt to mail to such a domain would normally provoke the &"unrouteable |
14982 | domain"& error, and an attempt to verify an address in the domain would fail. | |
14983 | Similarly, if &%ignore_target_hosts%& is set on an &(ipliteral)& router, the | |
168e428f PH |
14984 | router declines if presented with one of the listed addresses. |
14985 | ||
9b371988 PH |
14986 | .new |
14987 | You can use this option to disable the use of IPv4 or IPv6 for mail delivery by | |
14988 | means of the first or the second of the following settings, respectively: | |
14989 | .code | |
14990 | ignore_target_hosts = 0.0.0.0/0 | |
14991 | ignore_target_hosts = <; 0::0/0 | |
14992 | .endd | |
14993 | The pattern in the first line matches all IPv4 addresses, whereas the pattern | |
14994 | in the second line matches all IPv6 addresses. | |
14995 | .wen | |
14996 | ||
168e428f | 14997 | This option may also be useful for ignoring link-local and site-local IPv6 |
9b371988 | 14998 | addresses. Because, like all host lists, the value of &%ignore_target_hosts%& |
168e428f PH |
14999 | is expanded before use as a list, it is possible to make it dependent on the |
15000 | domain that is being routed. | |
15001 | ||
9b371988 PH |
15002 | .cindex "&$host_address$&" |
15003 | During its expansion, &$host_address$& is set to the IP address that is being | |
168e428f PH |
15004 | checked. |
15005 | ||
9b371988 PH |
15006 | .option initgroups routers boolean false |
15007 | .cindex "additional groups" | |
15008 | .cindex "groups" "additional" | |
15009 | .cindex "local transports" "uid and gid" | |
15010 | .cindex "transport" "local" | |
168e428f PH |
15011 | If the router queues an address for a transport, and this option is true, and |
15012 | the uid supplied by the router is not overridden by the transport, the | |
9b371988 PH |
15013 | &[initgroups()]& function is called when running the transport to ensure that |
15014 | any additional groups associated with the uid are set up. See also &%group%& | |
15015 | and &%user%& and the discussion in chapter &<<CHAPenvironment>>&. | |
168e428f PH |
15016 | |
15017 | ||
168e428f | 15018 | |
9b371988 PH |
15019 | .option local_part_prefix routers&!? "string list" unset |
15020 | .cindex "router" "prefix for local part" | |
15021 | .cindex "prefix" "for local part; used in router" | |
068aaea8 | 15022 | If this option is set, the router is skipped unless the local part starts with |
9b371988 PH |
15023 | one of the given strings, or &%local_part_prefix_optional%& is true. See |
15024 | section &<<SECTrouprecon>>& for a list of the order in which preconditions are | |
15025 | evaluated. | |
168e428f PH |
15026 | |
15027 | The list is scanned from left to right, and the first prefix that matches is | |
15028 | used. A limited form of wildcard is available; if the prefix begins with an | |
15029 | asterisk, it matches the longest possible sequence of arbitrary characters at | |
15030 | the start of the local part. An asterisk should therefore always be followed by | |
15031 | some character that does not occur in normal local parts. | |
9b371988 PH |
15032 | .cindex "multiple mailboxes" |
15033 | .cindex "mailbox" "multiple" | |
168e428f | 15034 | Wildcarding can be used to set up multiple user mailboxes, as described in |
9b371988 | 15035 | section &<<SECTmulbox>>&. |
168e428f | 15036 | |
9b371988 PH |
15037 | .new |
15038 | .cindex "&$local_part$&" | |
15039 | .cindex "&$local_part_prefix$&" | |
15040 | During the testing of the &%local_parts%& option, and while the router is | |
168e428f | 15041 | running, the prefix is removed from the local part, and is available in the |
9b371988 | 15042 | expansion variable &$local_part_prefix$&. When a message is being delivered, if |
068aaea8 PH |
15043 | the router accepts the address, this remains true during subsequent delivery by |
15044 | a transport. In particular, the local part that is transmitted in the RCPT | |
15045 | command for LMTP, SMTP, and BSMTP deliveries has the prefix removed by default. | |
9b371988 PH |
15046 | This behaviour can be overridden by setting &%rcpt_include_affixes%& true on |
15047 | the relevant transport. | |
168e428f | 15048 | |
9b371988 | 15049 | When an address is being verified, &%local_part_prefix%& affects only the |
068aaea8 PH |
15050 | behaviour of the router. If the callout feature of verification is in use, this |
15051 | means that the full address, including the prefix, will be used during the | |
15052 | callout. | |
9b371988 | 15053 | .wen |
068aaea8 | 15054 | |
168e428f | 15055 | The prefix facility is commonly used to handle local parts of the form |
9b371988 PH |
15056 | &%owner-something%&. Another common use is to support local parts of the form |
15057 | &%real-username%& to bypass a user's &_.forward_& file &-- helpful when trying | |
15058 | to tell a user their forwarding is broken &-- by placing a router like this one | |
15059 | immediately before the router that handles &_.forward_& files: | |
15060 | .code | |
15061 | real_localuser: | |
15062 | driver = accept | |
15063 | local_part_prefix = real- | |
15064 | check_local_user | |
15065 | transport = local_delivery | |
15066 | .endd | |
15067 | If both &%local_part_prefix%& and &%local_part_suffix%& are set for a router, | |
168e428f PH |
15068 | both conditions must be met if not optional. Care must be taken if wildcards |
15069 | are used in both a prefix and a suffix on the same router. Different | |
15070 | separator characters must be used to avoid ambiguity. | |
15071 | ||
15072 | ||
9b371988 PH |
15073 | .option local_part_prefix_optional routers boolean false |
15074 | See &%local_part_prefix%& above. | |
168e428f PH |
15075 | |
15076 | ||
168e428f | 15077 | |
9b371988 PH |
15078 | .option local_part_suffix routers&!? "string list" unset |
15079 | .cindex "router" "suffix for local part" | |
15080 | .cindex "suffix for local part" "used in router" | |
15081 | This option operates in the same way as &%local_part_prefix%&, except that the | |
168e428f | 15082 | local part must end (rather than start) with the given string, the |
9b371988 PH |
15083 | &%local_part_suffix_optional%& option determines whether the suffix is |
15084 | mandatory, and the wildcard * character, if present, must be the last | |
168e428f | 15085 | character of the suffix. This option facility is commonly used to handle local |
9b371988 PH |
15086 | parts of the form &%something-request%& and multiple user mailboxes of the form |
15087 | &%username-foo%&. | |
168e428f PH |
15088 | |
15089 | ||
9b371988 PH |
15090 | .option local_part_suffix_optional routers boolean false |
15091 | See &%local_part_suffix%& above. | |
168e428f | 15092 | |
168e428f PH |
15093 | |
15094 | ||
9b371988 PH |
15095 | .option local_parts routers&!? "local part list&!!" unset |
15096 | .cindex "router" "restricting to specific local parts" | |
15097 | .cindex "local part" "checking in router" | |
168e428f | 15098 | The router is run only if the local part of the address matches the list. |
9b371988 | 15099 | See section &<<SECTrouprecon>>& for a list of the order in which preconditions |
168e428f | 15100 | are evaluated, and |
9b371988 | 15101 | section &<<SECTlocparlis>>& for a discussion of local part lists. Because the |
168e428f PH |
15102 | string is expanded, it is possible to make it depend on the domain, for |
15103 | example: | |
9b371988 PH |
15104 | .code |
15105 | local_parts = dbm;/usr/local/specials/$domain | |
15106 | .endd | |
15107 | .cindex "&$local_part_data$&" | |
168e428f | 15108 | If the match is achieved by a lookup, the data that the lookup returned |
9b371988 | 15109 | for the local part is placed in the variable &$local_part_data$& for use in |
168e428f PH |
15110 | expansions of the router's private options. You might use this option, for |
15111 | example, if you have a large number of local virtual domains, and you want to | |
15112 | send all postmaster mail to the same place without having to set up an alias in | |
15113 | each virtual domain: | |
9b371988 PH |
15114 | .code |
15115 | postmaster: | |
15116 | driver = redirect | |
15117 | local_parts = postmaster | |
15118 | data = postmaster@real.domain.example | |
15119 | .endd | |
168e428f | 15120 | |
168e428f | 15121 | |
9b371988 PH |
15122 | .option log_as_local routers boolean "see below" |
15123 | .cindex "log" "delivery line" | |
15124 | .cindex "delivery" "log line format" | |
168e428f | 15125 | Exim has two logging styles for delivery, the idea being to make local |
9b371988 | 15126 | deliveries stand out more visibly from remote ones. In the &"local"& style, the |
168e428f | 15127 | recipient address is given just as the local part, without a domain. The use of |
9b371988 PH |
15128 | this style is controlled by this option. It defaults to true for the &(accept)& |
15129 | router, and false for all the others. &new("This option applies only when a | |
15130 | router assigns an address to a transport. It has no effect on routers that | |
15131 | redirect addresses.") | |
168e428f PH |
15132 | |
15133 | ||
168e428f | 15134 | |
9b371988 | 15135 | .option more routers boolean&!! true |
168e428f | 15136 | The result of string expansion for this option must be a valid boolean value, |
9b371988 | 15137 | that is, one of the strings &"yes"&, &"no"&, &"true"&, or &"false"&. Any other |
168e428f PH |
15138 | result causes an error, and delivery is deferred. If the expansion is forced to |
15139 | fail, the default value for the option (true) is used. Other failures cause | |
15140 | delivery to be deferred. | |
15141 | ||
068aaea8 PH |
15142 | If this option is set false, and the router declines to handle the address, no |
15143 | further routers are tried, routing fails, and the address is bounced. | |
9b371988 PH |
15144 | .cindex "&%self%& option" |
15145 | However, if the router explicitly passes an address to the following router by | |
15146 | means of the setting | |
15147 | .code | |
15148 | self = pass | |
15149 | .endd | |
15150 | or otherwise, the setting of &%more%& is ignored. Also, the setting of &%more%& | |
168e428f PH |
15151 | does not affect the behaviour if one of the precondition tests fails. In that |
15152 | case, the address is always passed to the next router. | |
15153 | ||
9b371988 PH |
15154 | .new |
15155 | Note that &%address_data%& is not considered to be a precondition. If its | |
15156 | expansion is forced to fail, the router declines, and the value of &%more%& | |
068aaea8 | 15157 | controls what happens next. |
9b371988 | 15158 | .wen |
068aaea8 | 15159 | |
168e428f | 15160 | |
9b371988 PH |
15161 | .option pass_on_timeout routers boolean false |
15162 | .cindex "timeout" "of router" | |
15163 | .cindex "router" "timeout" | |
168e428f | 15164 | If a router times out during a host lookup, it normally causes deferral of the |
9b371988 PH |
15165 | address. If &%pass_on_timeout%& is set, the address is passed on to the next |
15166 | router, overriding &%no_more%&. This may be helpful for systems that are | |
168e428f PH |
15167 | intermittently connected to the Internet, or those that want to pass to a smart |
15168 | host any messages that cannot immediately be delivered. | |
15169 | ||
15170 | There are occasional other temporary errors that can occur while doing DNS | |
15171 | lookups. They are treated in the same way as a timeout, and this option | |
15172 | applies to all of them. | |
15173 | ||
15174 | ||
15175 | ||
9b371988 PH |
15176 | .option pass_router routers string unset |
15177 | .cindex "router" "go to after &""pass""&" | |
15178 | When a router returns &"pass"&, the address is normally handed on to the next | |
15179 | router in sequence. This can be changed by setting &%pass_router%& to the name | |
15180 | of another router. However (unlike &%redirect_router%&) the named router must | |
15181 | be below the current router, to avoid loops. Note that this option applies only | |
15182 | to the special case of &"pass"&. It does not apply when a router returns | |
15183 | &"decline"&. | |
168e428f PH |
15184 | |
15185 | ||
168e428f | 15186 | |
9b371988 PH |
15187 | .option redirect_router routers string unset |
15188 | .cindex "router" "start at after redirection" | |
168e428f PH |
15189 | Sometimes an administrator knows that it is pointless to reprocess addresses |
15190 | generated from alias or forward files with the same router again. For | |
15191 | example, if an alias file translates real names into login ids there is no | |
15192 | point searching the alias file a second time, especially if it is a large file. | |
15193 | ||
9b371988 PH |
15194 | The &%redirect_router%& option can be set to the name of any router instance. |
15195 | It causes the routing of any generated addresses to start at the named router | |
168e428f PH |
15196 | instead of at the first router. This option has no effect if the router in |
15197 | which it is set does not generate new addresses. | |
15198 | ||
15199 | ||
15200 | ||
9b371988 PH |
15201 | .option require_files routers&!? "string list&!!" unset |
15202 | .cindex "file" "requiring for router" | |
15203 | .cindex "router" "requiring file existence" | |
168e428f PH |
15204 | This option provides a general mechanism for predicating the running of a |
15205 | router on the existence or non-existence of certain files or directories. | |
15206 | Before running a router, as one of its precondition tests, Exim works its way | |
9b371988 | 15207 | through the &%require_files%& list, expanding each item separately. |
168e428f PH |
15208 | |
15209 | Because the list is split before expansion, any colons in expansion items must | |
15210 | be doubled, or the facility for using a different list separator must be used. | |
15211 | If any expansion is forced to fail, the item is ignored. Other expansion | |
15212 | failures cause routing of the address to be deferred. | |
15213 | ||
15214 | If any expanded string is empty, it is ignored. Otherwise, except as described | |
15215 | below, each string must be a fully qualified file path, optionally preceded by | |
9b371988 PH |
15216 | &"!"&. The paths are passed to the &[stat()]& function to test for the |
15217 | existence of the files or directories. The router is skipped if any paths not | |
15218 | preceded by &"!"& do not exist, or if any paths preceded by &"!"& do exist. | |
168e428f | 15219 | |
9b371988 PH |
15220 | .cindex "NFS" |
15221 | If &[stat()]& cannot determine whether a file exists or not, delivery of | |
168e428f PH |
15222 | the message is deferred. This can happen when NFS-mounted filesystems are |
15223 | unavailable. | |
15224 | ||
9b371988 | 15225 | This option is checked after the &%domains%&, &%local_parts%&, and &%senders%& |
168e428f | 15226 | options, so you cannot use it to check for the existence of a file in which to |
9b371988 | 15227 | look up a domain, local part, or sender. (See section &<<SECTrouprecon>>& for a |
168e428f | 15228 | full list of the order in which preconditions are evaluated.) However, as |
9b371988 PH |
15229 | these options are all expanded, you can use the &%exists%& expansion condition |
15230 | to make such tests. The &%require_files%& option is intended for checking files | |
168e428f | 15231 | that the router may be going to use internally, or which are needed by a |
9b371988 | 15232 | transport (for example &_.procmailrc_&). |
168e428f | 15233 | |
9b371988 | 15234 | During delivery, the &[stat()]& function is run as root, but there is a |
168e428f | 15235 | facility for some checking of the accessibility of a file by another user. |
9b371988 | 15236 | This is not a proper permissions check, but just a &"rough"& check that |
168e428f PH |
15237 | operates as follows: |
15238 | ||
9b371988 | 15239 | If an item in a &%require_files%& list does not contain any forward slash |
168e428f PH |
15240 | characters, it is taken to be the user (and optional group, separated by a |
15241 | comma) to be checked for subsequent files in the list. If no group is specified | |
15242 | but the user is specified symbolically, the gid associated with the uid is | |
15243 | used. For example: | |
9b371988 PH |
15244 | .code |
15245 | require_files = mail:/some/file | |
15246 | require_files = $local_part:$home/.procmailrc | |
15247 | .endd | |
15248 | If a user or group name in a &%require_files%& list does not exist, the | |
15249 | &%require_files%& condition fails. | |
168e428f PH |
15250 | |
15251 | Exim performs the check by scanning along the components of the file path, and | |
9b371988 PH |
15252 | checking the access for the given uid and gid. It checks for &"x"& access on |
15253 | directories, and &"r"& access on the final file. Note that this means that file | |
168e428f PH |
15254 | access control lists, if the operating system has them, are ignored. |
15255 | ||
9b371988 | 15256 | &*Warning 1*&: When the router is being run to verify addresses for an |
168e428f | 15257 | incoming SMTP message, Exim is not running as root, but under its own uid. This |
9b371988 PH |
15258 | may affect the result of a &%require_files%& check. In particular, &[stat()]& |
15259 | may yield the error EACCES (&"Permission denied"&). This means that the Exim | |
168e428f PH |
15260 | user is not permitted to read one of the directories on the file's path. |
15261 | ||
9b371988 PH |
15262 | &*Warning 2*&: Even when Exim is running as root while delivering a message, |
15263 | &[stat()]& can yield EACCES for a file in an NFS directory that is mounted | |
15264 | without root access. In this case, if a check for access by a particular user | |
15265 | is requested, Exim creates a subprocess that runs as that user, and tries the | |
15266 | check again in that process. | |
168e428f PH |
15267 | |
15268 | The default action for handling an unresolved EACCES is to consider it to | |
9b371988 PH |
15269 | be caused by a configuration error, and routing is deferred because the |
15270 | existence or non-existence of the file cannot be determined. However, in some | |
15271 | circumstances it may be desirable to treat this condition as if the file did | |
15272 | not exist. If the file name (or the exclamation mark that precedes the file | |
15273 | name for non-existence) is preceded by a plus sign, the EACCES error is treated | |
15274 | as if the file did not exist. For example: | |
15275 | .code | |
15276 | require_files = +/some/file | |
15277 | .endd | |
168e428f | 15278 | If the router is not an essential part of verification (for example, it |
9b371988 | 15279 | handles users' &_.forward_& files), another solution is to set the &%verify%& |
168e428f PH |
15280 | option false so that the router is skipped when verifying. |
15281 | ||
15282 | ||
15283 | ||
9b371988 PH |
15284 | .option retry_use_local_part routers boolean "see below" |
15285 | .cindex "hints database" "retry keys" | |
15286 | .cindex "local part" "in retry keys" | |
168e428f PH |
15287 | When a delivery suffers a temporary routing failure, a retry record is created |
15288 | in Exim's hints database. For addresses whose routing depends only on the | |
15289 | domain, the key for the retry record should not involve the local part, but for | |
15290 | other addresses, both the domain and the local part should be included. | |
15291 | Usually, remote routing is of the former kind, and local routing is of the | |
15292 | latter kind. | |
15293 | ||
15294 | This option controls whether the local part is used to form the key for retry | |
15295 | hints for addresses that suffer temporary errors while being handled by this | |
9b371988 | 15296 | router. The default value is true for any router that has &%check_local_user%& |
168e428f PH |
15297 | set, and false otherwise. Note that this option does not apply to hints keys |
15298 | for transport delays; they are controlled by a generic transport option of the | |
15299 | same name. | |
15300 | ||
9b371988 | 15301 | The setting of &%retry_use_local_part%& applies only to the router on which it |
168e428f PH |
15302 | appears. If the router generates child addresses, they are routed |
15303 | independently; this setting does not become attached to them. | |
15304 | ||
15305 | ||
15306 | ||
9b371988 PH |
15307 | .option router_home_directory routers string&!! unset |
15308 | .cindex "router" "home directory for" | |
15309 | .cindex "home directory" "for router" | |
15310 | .cindex "&$home$&" | |
168e428f | 15311 | This option sets a home directory for use while the router is running. (Compare |
9b371988 PH |
15312 | &%transport_home_directory%&, which sets a home directory for later |
15313 | transporting.) In particular, if used on a &(redirect)& router, this option | |
15314 | sets a value for &$home$& while a filter is running. The value is expanded; | |
15315 | forced expansion failure causes the option to be ignored &-- other failures | |
168e428f PH |
15316 | cause the router to defer. |
15317 | ||
9b371988 PH |
15318 | Expansion of &%router_home_directory%& happens immediately after the |
15319 | &%check_local_user%& test (if configured), before any further expansions take | |
168e428f | 15320 | place. |
9b371988 | 15321 | (See section &<<SECTrouprecon>>& for a list of the order in which preconditions |
168e428f | 15322 | are evaluated.) |
9b371988 PH |
15323 | While the router is running, &%router_home_directory%& overrides the value of |
15324 | &$home$& that came from &%check_local_user%&. | |
168e428f PH |
15325 | |
15326 | When a router accepts an address and routes it to a transport (including the | |
15327 | cases when a redirect router generates a pipe, file, or autoreply delivery), | |
15328 | the home directory setting for the transport is taken from the first of these | |
15329 | values that is set: | |
15330 | ||
9b371988 PH |
15331 | .ilist |
15332 | The &%home_directory%& option on the transport; | |
15333 | .next | |
15334 | The &%transport_home_directory%& option on the router; | |
15335 | .next | |
15336 | The password data if &%check_local_user%& is set on the router; | |
15337 | .next | |
15338 | The &%router_home_directory%& option on the router. | |
15339 | .endlist | |
15340 | ||
15341 | In other words, &%router_home_directory%& overrides the password data for the | |
168e428f PH |
15342 | router, but not for the transport. |
15343 | ||
15344 | ||
15345 | ||
9b371988 PH |
15346 | .option self routers string freeze |
15347 | .cindex "MX record" "pointing to local host" | |
15348 | .cindex "local host" "MX pointing to" | |
168e428f | 15349 | This option applies to those routers that use a recipient address to find a |
9b371988 PH |
15350 | list of remote hosts. Currently, these are the &(dnslookup)&, &(ipliteral)&, |
15351 | and &(manualroute)& routers. | |
15352 | Certain configurations of the &(queryprogram)& router can also specify a list | |
168e428f PH |
15353 | of remote hosts. |
15354 | Usually such routers are configured to send the message to a remote host via an | |
9b371988 | 15355 | &(smtp)& transport. The &%self%& option specifies what happens when the first |
168e428f PH |
15356 | host on the list turns out to be the local host. |
15357 | The way in which Exim checks for the local host is described in section | |
9b371988 | 15358 | &<<SECTreclocipadd>>&. |
168e428f PH |
15359 | |
15360 | Normally this situation indicates either an error in Exim's configuration (for | |
15361 | example, the router should be configured not to process this domain), or an | |
15362 | error in the DNS (for example, the MX should not point to this host). For this | |
15363 | reason, the default action is to log the incident, defer the address, and | |
15364 | freeze the message. The following alternatives are provided for use in special | |
15365 | cases: | |
15366 | ||
9b371988 PH |
15367 | .vlist |
15368 | .vitem &%defer%& | |
168e428f PH |
15369 | Delivery of the message is tried again later, but the message is not frozen. |
15370 | ||
9b371988 | 15371 | .vitem "&%reroute%&: <&'domain'&>" |
168e428f PH |
15372 | The domain is changed to the given domain, and the address is passed back to |
15373 | be reprocessed by the routers. No rewriting of headers takes place. This | |
15374 | behaviour is essentially a redirection. | |
15375 | ||
9b371988 | 15376 | .vitem "&%reroute: rewrite:%& <&'domain'&>" |
168e428f PH |
15377 | The domain is changed to the given domain, and the address is passed back to be |
15378 | reprocessed by the routers. Any headers that contain the original domain are | |
15379 | rewritten. | |
15380 | ||
9b371988 PH |
15381 | .vitem &%pass%& |
15382 | .cindex "&%more%& option" | |
15383 | .cindex "&$self_hostname$&" | |
168e428f | 15384 | The router passes the address to the next router, or to the router named in the |
9b371988 PH |
15385 | &%pass_router%& option if it is set. This overrides &%no_more%&. During |
15386 | subsequent routing and delivery, the variable &$self_hostname$& contains the | |
15387 | name of the local host that the router encountered. This can be used to | |
168e428f PH |
15388 | distinguish between different cases for hosts with multiple names. The |
15389 | combination | |
9b371988 PH |
15390 | .code |
15391 | self = pass | |
15392 | no_more | |
15393 | .endd | |
168e428f | 15394 | ensures that only those addresses that routed to the local host are passed on. |
9b371988 | 15395 | Without &%no_more%&, addresses that were declined for other reasons would also |
168e428f PH |
15396 | be passed to the next router. |
15397 | ||
9b371988 | 15398 | .vitem &%fail%& |
168e428f PH |
15399 | Delivery fails and an error report is generated. |
15400 | ||
9b371988 PH |
15401 | .vitem &%send%& |
15402 | .cindex "local host" "sending to" | |
168e428f | 15403 | The anomaly is ignored and the address is queued for the transport. This |
9b371988 PH |
15404 | setting should be used with extreme caution. For an &(smtp)& transport, it |
15405 | makes sense only in cases where the program that is listening on the SMTP port | |
15406 | is not this version of Exim. That is, it must be some other MTA, or Exim with a | |
168e428f | 15407 | different configuration file that handles the domain in another way. |
9b371988 | 15408 | .endlist |
168e428f PH |
15409 | |
15410 | ||
15411 | ||
9b371988 PH |
15412 | .option senders routers&!? "address list&!!" unset |
15413 | .cindex "router" "checking senders" | |
168e428f PH |
15414 | If this option is set, the router is skipped unless the message's sender |
15415 | address matches something on the list. | |
9b371988 | 15416 | See section &<<SECTrouprecon>>& for a list of the order in which preconditions |
168e428f PH |
15417 | are evaluated. |
15418 | ||
15419 | There are issues concerning verification when the running of routers is | |
9b371988 PH |
15420 | dependent on the sender. When Exim is verifying the address in an &%errors_to%& |
15421 | setting, it sets the sender to the null string. When using the &%-bt%& option | |
15422 | to check a configuration file, it is necessary also to use the &%-f%& option to | |
15423 | set an appropriate sender. For incoming mail, the sender is unset when | |
15424 | verifying the sender, but is available when verifying any recipients. If the | |
15425 | SMTP VRFY command is enabled, it must be used after MAIL if the sender address | |
15426 | matters. | |
15427 | ||
15428 | ||
15429 | .option translate_ip_address routers string&!! unset | |
15430 | .cindex "IP address" "translating" | |
15431 | .cindex "packet radio" | |
15432 | .cindex "router" "IP address translation" | |
168e428f PH |
15433 | There exist some rare networking situations (for example, packet radio) where |
15434 | it is helpful to be able to translate IP addresses generated by normal routing | |
15435 | mechanisms into other IP addresses, thus performing a kind of manual IP | |
15436 | routing. This should be done only if the normal IP routing of the TCP/IP stack | |
15437 | is inadequate or broken. Because this is an extremely uncommon requirement, the | |
15438 | code to support this option is not included in the Exim binary unless | |
9b371988 | 15439 | SUPPORT_TRANSLATE_IP_ADDRESS=yes is set in &_Local/Makefile_&. |
168e428f | 15440 | |
9b371988 PH |
15441 | .cindex "&$host_address$&" |
15442 | The &%translate_ip_address%& string is expanded for every IP address generated | |
15443 | by the router, with the generated address set in &$host_address$&. If the | |
168e428f PH |
15444 | expansion is forced to fail, no action is taken. |
15445 | For any other expansion error, delivery of the message is deferred. | |
15446 | If the result of the expansion is an IP address, that replaces the original | |
9b371988 PH |
15447 | address; otherwise the result is assumed to be a host name &-- this is looked |
15448 | up using &[gethostbyname()]& (or &[getipnodebyname()]& when available) to | |
15449 | produce one or more replacement IP addresses. For example, to subvert all IP | |
15450 | addresses in some specific networks, this could be added to a router: | |
15451 | .code | |
168e428f | 15452 | translate_ip_address = \ |
9b371988 PH |
15453 | ${lookup{${mask:$host_address/26}}lsearch{/some/file}\ |
15454 | {$value}fail}} | |
15455 | .endd | |
168e428f | 15456 | The file would contain lines like |
9b371988 PH |
15457 | .code |
15458 | 10.2.3.128/26 some.host | |
15459 | 10.8.4.34/26 10.44.8.15 | |
15460 | .endd | |
168e428f PH |
15461 | You should not make use of this facility unless you really understand what you |
15462 | are doing. | |
15463 | ||
15464 | ||
15465 | ||
9b371988 | 15466 | .option transport routers string&!! unset |
168e428f PH |
15467 | This option specifies the transport to be used when a router accepts an address |
15468 | and sets it up for delivery. A transport is never needed if a router is used | |
15469 | only for verification. The value of the option is expanded at routing time, | |
9b371988 PH |
15470 | after the expansion of &%errors_to%&, &%headers_add%&, and &%headers_remove%&, |
15471 | and result must be the name of one of the configured transports. If it is not, | |
168e428f PH |
15472 | delivery is deferred. |
15473 | ||
9b371988 PH |
15474 | The &%transport%& option is not used by the &(redirect)& router, but it does |
15475 | have some private options that set up transports for pipe and file deliveries | |
15476 | (see chapter &<<CHAPredirect>>&). | |
168e428f PH |
15477 | |
15478 | ||
15479 | ||
9b371988 PH |
15480 | .option transport_current_directory routers string&!! unset |
15481 | .cindex "current directory for local transport" | |
168e428f PH |
15482 | This option associates a current directory with any address that is routed |
15483 | to a local transport. This can happen either because a transport is | |
15484 | explicitly configured for the router, or because it generates a delivery to a | |
15485 | file or a pipe. During the delivery process (that is, at transport time), this | |
15486 | option string is expanded and is set as the current directory, unless | |
15487 | overridden by a setting on the transport. | |
15488 | If the expansion fails for any reason, including forced failure, an error is | |
15489 | logged, and delivery is deferred. | |
9b371988 PH |
15490 | See chapter &<<CHAPenvironment>>& for details of the local delivery |
15491 | environment. | |
168e428f PH |
15492 | |
15493 | ||
15494 | ||
168e428f | 15495 | |
9b371988 PH |
15496 | .option transport_home_directory routers string&!! "see below" |
15497 | .cindex "home directory" "for local transport" | |
168e428f PH |
15498 | This option associates a home directory with any address that is routed to a |
15499 | local transport. This can happen either because a transport is explicitly | |
15500 | configured for the router, or because it generates a delivery to a file or a | |
15501 | pipe. During the delivery process (that is, at transport time), the option | |
15502 | string is expanded and is set as the home directory, unless overridden by a | |
9b371988 | 15503 | setting of &%home_directory%& on the transport. |
168e428f PH |
15504 | If the expansion fails for any reason, including forced failure, an error is |
15505 | logged, and delivery is deferred. | |
15506 | ||
15507 | If the transport does not specify a home directory, and | |
9b371988 PH |
15508 | &%transport_home_directory%& is not set for the router, the home directory for |
15509 | the tranport is taken from the password data if &%check_local_user%& is set for | |
15510 | the router. Otherwise it is taken from &%router_home_directory%& if that option | |
168e428f PH |
15511 | is set; if not, no home directory is set for the transport. |
15512 | ||
9b371988 | 15513 | See chapter &<<CHAPenvironment>>& for further details of the local delivery |
168e428f PH |
15514 | environment. |
15515 | ||
15516 | ||
15517 | ||
15518 | ||
9b371988 PH |
15519 | .option unseen routers boolean&!! false |
15520 | .cindex "router" "carrying on after success" | |
168e428f | 15521 | The result of string expansion for this option must be a valid boolean value, |
9b371988 | 15522 | that is, one of the strings &"yes"&, &"no"&, &"true"&, or &"false"&. Any other |
068aaea8 PH |
15523 | result causes an error, and delivery is deferred. If the expansion is forced to |
15524 | fail, the default value for the option (false) is used. Other failures cause | |
15525 | delivery to be deferred. | |
15526 | ||
168e428f PH |
15527 | When this option is set true, routing does not cease if the router accepts the |
15528 | address. Instead, a copy of the incoming address is passed to the next router, | |
9b371988 PH |
15529 | overriding a false setting of &%more%&. There is little point in setting |
15530 | &%more%& false if &%unseen%& is always true, but it may be useful in cases when | |
15531 | the value of &%unseen%& contains expansion items (and therefore, presumably, is | |
15532 | sometimes true and sometimes false). | |
15533 | ||
15534 | .new | |
15535 | .cindex "copy of message (&%unseen%& option)" | |
15536 | The &%unseen%& option can be used to cause copies of messages to be delivered | |
15537 | to some other destination, while also carrying out a normal delivery. In | |
15538 | effect, the current address is made into a &"parent"& that has two children &-- | |
15539 | one that is delivered as specified by this router, and a clone that goes on to | |
15540 | be routed further. For this reason, &%unseen%& may not be combined with the | |
15541 | &%one_time%& option in a &(redirect)& router. | |
15542 | .wen | |
15543 | ||
15544 | &*Warning*&: Header lines added to the address (or specified for removal) by | |
15545 | this router or by previous routers affect the &"unseen"& copy of the message | |
15546 | only. The clone that continues to be processed by further routers starts with | |
15547 | no added headers and none specified for removal. However, any data that was set | |
15548 | by the &%address_data%& option in the current or previous routers is passed on. | |
15549 | Setting the &%unseen%& option has a similar effect to the &%unseen%& command | |
068aaea8 | 15550 | qualifier in filter files. |
168e428f PH |
15551 | |
15552 | ||
15553 | ||
9b371988 PH |
15554 | .option user routers string&!! "see below" |
15555 | .cindex "uid (user id)" "local delivery" | |
15556 | .cindex "local transports" "uid and gid" | |
15557 | .cindex "transport" "local" | |
15558 | .cindex "router" "user for filter processing" | |
15559 | .cindex "filter" "user for processing" | |
168e428f PH |
15560 | When a router queues an address for a transport, and the transport does not |
15561 | specify a user, the user given here is used when running the delivery process. | |
15562 | The user may be specified numerically or by name. If expansion fails, the | |
15563 | error is logged and delivery is deferred. | |
9b371988 PH |
15564 | This user is also used by the &(redirect)& router when running a filter file. |
15565 | The default is unset, except when &%check_local_user%& is set. In this case, | |
168e428f | 15566 | the default is taken from the password information. If the user is specified as |
9b371988 PH |
15567 | a name, and &%group%& is not set, the group associated with the user is used. |
15568 | See also &%initgroups%& and &%group%& and the discussion in chapter | |
15569 | &<<CHAPenvironment>>&. | |
168e428f PH |
15570 | |
15571 | ||
168e428f | 15572 | |
9b371988 PH |
15573 | .option verify routers&!? boolean true |
15574 | Setting this option has the effect of setting &%verify_sender%& and | |
15575 | &%verify_recipient%& to the same value. | |
168e428f PH |
15576 | |
15577 | ||
9b371988 PH |
15578 | .option verify_only routers&!? boolean false |
15579 | .cindex "EXPN" "with &%verify_only%&" | |
15580 | .cindex "&%-bv%& option" | |
15581 | .cindex "router" "used only when verifying" | |
168e428f | 15582 | If this option is set, the router is used only when verifying an address or |
9b371988 PH |
15583 | testing with the &%-bv%& option, not when actually doing a delivery, testing |
15584 | with the &%-bt%& option, or running the SMTP EXPN command. It can be further | |
15585 | restricted to verifying only senders or recipients by means of | |
15586 | &%verify_sender%& and &%verify_recipient%&. | |
168e428f | 15587 | |
9b371988 | 15588 | &*Warning*&: When the router is being run to verify addresses for an incoming |
168e428f PH |
15589 | SMTP message, Exim is not running as root, but under its own uid. If the router |
15590 | accesses any files, you need to make sure that they are accessible to the Exim | |
15591 | user or group. | |
15592 | ||
15593 | ||
9b371988 | 15594 | .option verify_recipient routers&!? boolean true |
168e428f PH |
15595 | If this option is false, the router is skipped when verifying recipient |
15596 | addresses | |
9b371988 PH |
15597 | or testing recipient verification using &%-bv%&. |
15598 | See section &<<SECTrouprecon>>& for a list of the order in which preconditions | |
168e428f PH |
15599 | are evaluated. |
15600 | ||
15601 | ||
9b371988 | 15602 | .option verify_sender routers&!? boolean true |
168e428f | 15603 | If this option is false, the router is skipped when verifying sender addresses |
9b371988 PH |
15604 | or testing sender verification using &%-bvs%&. |
15605 | See section &<<SECTrouprecon>>& for a list of the order in which preconditions | |
168e428f PH |
15606 | are evaluated. |
15607 | ||
15608 | ||
15609 | ||
15610 | ||
15611 | ||
15612 | ||
9b371988 PH |
15613 | . //////////////////////////////////////////////////////////////////////////// |
15614 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 15615 | |
9b371988 PH |
15616 | .chapter "The accept router" |
15617 | .cindex "&(accept)& router" | |
15618 | .cindex "routers" "&(accept)&" | |
15619 | The &(accept)& router has no private options of its own. Unless it is being | |
15620 | used purely for verification (see &%verify_only%&) a transport is required to | |
15621 | be defined by the generic &%transport%& option. If the preconditions that are | |
168e428f PH |
15622 | specified by generic options are met, the router accepts the address and queues |
15623 | it for the given transport. The most common use of this router is for setting | |
15624 | up deliveries to local mailboxes. For example: | |
9b371988 PH |
15625 | .code |
15626 | localusers: | |
15627 | driver = accept | |
15628 | domains = mydomain.example | |
15629 | check_local_user | |
15630 | transport = local_delivery | |
15631 | .endd | |
15632 | The &%domains%& condition in this example checks the domain of the address, and | |
15633 | &%check_local_user%& checks that the local part is the login of a local user. | |
15634 | When both preconditions are met, the &(accept)& router runs, and queues the | |
15635 | address for the &(local_delivery)& transport. | |
168e428f PH |
15636 | |
15637 | ||
15638 | ||
15639 | ||
15640 | ||
15641 | ||
9b371988 PH |
15642 | . //////////////////////////////////////////////////////////////////////////// |
15643 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 15644 | |
9b371988 PH |
15645 | .chapter "The dnslookup router" "CHAPdnslookup" |
15646 | .cindex "&(dnslookup)& router" | |
15647 | .cindex "routers" "&(dnslookup)&" | |
15648 | The &(dnslookup)& router looks up the hosts that handle mail for the | |
168e428f | 15649 | recipient's domain in the DNS. A transport must always be set for this router, |
9b371988 | 15650 | unless &%verify_only%& is set. |
168e428f | 15651 | |
9b371988 | 15652 | If SRV support is configured (see &%check_srv%& below), Exim first searches for |
168e428f PH |
15653 | SRV records. If none are found, or if SRV support is not configured, |
15654 | MX records are looked up. If no MX records exist, address records are sought. | |
9b371988 PH |
15655 | However, &%mx_domains%& can be set to disable the direct use of address |
15656 | records. | |
168e428f PH |
15657 | |
15658 | MX records of equal priority are sorted by Exim into a random order. Exim then | |
15659 | looks for address records for the host names obtained from MX or SRV records. | |
15660 | When a host has more than one IP address, they are sorted into a random order, | |
15661 | except that IPv6 addresses are always sorted before IPv4 addresses. If all the | |
9b371988 | 15662 | IP addresses found are discarded by a setting of the &%ignore_target_hosts%& |
168e428f PH |
15663 | generic option, the router declines. |
15664 | ||
15665 | Unless they have the highest priority (lowest MX value), MX records that point | |
9b371988 | 15666 | to the local host, or to any host name that matches &%hosts_treat_as_local%&, |
168e428f PH |
15667 | are discarded, together with any other MX records of equal or lower priority. |
15668 | ||
9b371988 PH |
15669 | .cindex "MX record" "pointing to local host" |
15670 | .cindex "local host" "MX pointing to" | |
15671 | .cindex "&%self%& option" "in &(dnslookup)& router" | |
168e428f | 15672 | If the host pointed to by the highest priority MX record, or looked up as an |
9b371988 PH |
15673 | address record, is the local host, or matches &%hosts_treat_as_local%&, what |
15674 | happens is controlled by the generic &%self%& option. | |
168e428f PH |
15675 | |
15676 | ||
9b371988 | 15677 | .section "Problems with DNS lookups" "SECTprowitdnsloo" |
168e428f PH |
15678 | There have been problems with DNS servers when SRV records are looked up. |
15679 | Some mis-behaving servers return a DNS error or timeout when a non-existent | |
15680 | SRV record is sought. Similar problems have in the past been reported for | |
9b371988 | 15681 | MX records. The global &%dns_again_means_nonexist%& option can help with this |
168e428f PH |
15682 | problem, but it is heavy-handed because it is a global option. |
15683 | ||
9b371988 PH |
15684 | For this reason, there are two options, &%srv_fail_domains%& and |
15685 | &%mx_fail_domains%&, that control what happens when a DNS lookup in a | |
15686 | &(dnslookup)& router results in a DNS failure or a &"try again"& response. If | |
15687 | an attempt to look up an SRV or MX record causes one of these results, and the | |
15688 | domain matches the relevant list, Exim behaves as if the DNS had responded &"no | |
15689 | such record"&. In the case of an SRV lookup, this means that the router | |
15690 | proceeds to look for MX records; in the case of an MX lookup, it proceeds to | |
15691 | look for A or AAAA records, unless the domain matches &%mx_domains%&, in which | |
15692 | case routing fails. | |
168e428f PH |
15693 | |
15694 | ||
15695 | ||
168e428f | 15696 | |
9b371988 PH |
15697 | .section "Private options for dnslookup" |
15698 | .cindex "options" "&(dnslookup)& router" | |
15699 | The private options for the &(dnslookup)& router are as follows: | |
168e428f | 15700 | |
9b371988 PH |
15701 | .option check_secondary_mx dnslookup boolean false |
15702 | .cindex "MX record" "checking for secondary" | |
168e428f PH |
15703 | If this option is set, the router declines unless the local host is found in |
15704 | (and removed from) the list of hosts obtained by MX lookup. This can be used to | |
15705 | process domains for which the local host is a secondary mail exchanger | |
15706 | differently to other domains. The way in which Exim decides whether a host is | |
9b371988 | 15707 | the local host is described in section &<<SECTreclocipadd>>&. |
168e428f PH |
15708 | |
15709 | ||
9b371988 PH |
15710 | .option check_srv dnslookup string&!! unset |
15711 | .cindex "SRV record" "enabling use of" | |
15712 | The &(dnslookup)& router supports the use of SRV records (see RFC 2782) in | |
168e428f | 15713 | addition to MX and address records. The support is disabled by default. To |
9b371988 | 15714 | enable SRV support, set the &%check_srv%& option to the name of the service |
168e428f | 15715 | required. For example, |
9b371988 PH |
15716 | .code |
15717 | check_srv = smtp | |
15718 | .endd | |
168e428f PH |
15719 | looks for SRV records that refer to the normal smtp service. The option is |
15720 | expanded, so the service name can vary from message to message or address | |
15721 | to address. This might be helpful if SRV records are being used for a | |
9b371988 | 15722 | submission service. If the expansion is forced to fail, the &%check_srv%& |
168e428f PH |
15723 | option is ignored, and the router proceeds to look for MX records in the |
15724 | normal way. | |
15725 | ||
15726 | When the expansion succeeds, the router searches first for SRV records for | |
15727 | the given service (it assumes TCP protocol). A single SRV record with a | |
9b371988 PH |
15728 | host name that consists of just a single dot indicates &"no such service for |
15729 | this domain"&; if this is encountered, the router declines. If other kinds of | |
168e428f PH |
15730 | SRV record are found, they are used to construct a host list for delivery |
15731 | according to the rules of RFC 2782. MX records are not sought in this case. | |
15732 | ||
15733 | When no SRV records are found, MX records (and address records) are sought in | |
15734 | the traditional way. In other words, SRV records take precedence over MX | |
15735 | records, just as MX records take precedence over address records. Note that | |
15736 | this behaviour is not sanctioned by RFC 2782, though a previous draft RFC | |
15737 | defined it. It is apparently believed that MX records are sufficient for email | |
15738 | and that SRV records should not be used for this purpose. However, SRV records | |
9b371988 | 15739 | have an additional &"weight"& feature which some people might find useful when |
168e428f PH |
15740 | trying to split an SMTP load between hosts of different power. |
15741 | ||
9b371988 PH |
15742 | See section &<<SECTprowitdnsloo>>& above for a discussion of Exim's behaviour |
15743 | when there is a DNS lookup error. | |
168e428f PH |
15744 | |
15745 | ||
168e428f | 15746 | |
9b371988 PH |
15747 | .option mx_domains dnslookup "domain list&!!" unset |
15748 | .cindex "MX record" "required to exist" | |
15749 | .cindex "SRV record" "required to exist" | |
15750 | A domain that matches &%mx_domains%& is required to have either an MX or an SRV | |
168e428f | 15751 | record in order to be recognised. (The name of this option could be improved.) |
9b371988 PH |
15752 | For example, if all the mail hosts in &'fict.example'& are known to have MX |
15753 | records, except for those in &'discworld.fict.example'&, you could use this | |
168e428f | 15754 | setting: |
9b371988 PH |
15755 | .code |
15756 | mx_domains = ! *.discworld.fict.example : *.fict.example | |
15757 | .endd | |
168e428f PH |
15758 | This specifies that messages addressed to a domain that matches the list but |
15759 | has no MX record should be bounced immediately instead of being routed using | |
15760 | the address record. | |
15761 | ||
15762 | ||
9b371988 | 15763 | .option mx_fail_domains dnslookup "domain list&!!" unset |
168e428f PH |
15764 | If the DNS lookup for MX records for one of the domains in this list causes a |
15765 | DNS lookup error, Exim behaves as if no MX records were found. See section | |
9b371988 | 15766 | &<<SECTprowitdnsloo>>& for more discussion. |
168e428f PH |
15767 | |
15768 | ||
15769 | ||
168e428f | 15770 | |
9b371988 PH |
15771 | .option qualify_single dnslookup boolean true |
15772 | .cindex "DNS" "resolver options" | |
15773 | .cindex "DNS" "qualifying single-component names" | |
168e428f PH |
15774 | When this option is true, the resolver option RES_DEFNAMES is set for DNS |
15775 | lookups. Typically, but not standardly, this causes the resolver to qualify | |
15776 | single-component names with the default domain. For example, on a machine | |
9b371988 PH |
15777 | called &'dictionary.ref.example'&, the domain &'thesaurus'& would be changed to |
15778 | &'thesaurus.ref.example'& inside the resolver. For details of what your | |
15779 | resolver actually does, consult your man pages for &'resolver'& and | |
15780 | &'resolv.conf'&. | |
168e428f PH |
15781 | |
15782 | ||
15783 | ||
9b371988 PH |
15784 | .option rewrite_headers dnslookup boolean true |
15785 | .cindex "rewriting" "header lines" | |
15786 | .cindex "header lines" "rewriting" | |
168e428f PH |
15787 | If the domain name in the address that is being processed is not fully |
15788 | qualified, it may be expanded to its full form by a DNS lookup. For example, if | |
9b371988 PH |
15789 | an address is specified as &'dormouse@teaparty'&, the domain might be |
15790 | expanded to &'teaparty.wonderland.fict.example'&. Domain expansion can also | |
15791 | occur as a result of setting the &%widen_domains%& option. If | |
15792 | &%rewrite_headers%& is true, all occurrences of the abbreviated domain name in | |
15793 | any &'Bcc:'&, &'Cc:'&, &'From:'&, &'Reply-to:'&, &'Sender:'&, and &'To:'& | |
15794 | header lines of the message are rewritten with the full domain name. | |
168e428f PH |
15795 | |
15796 | This option should be turned off only when it is known that no message is | |
15797 | ever going to be sent outside an environment where the abbreviation makes | |
15798 | sense. | |
15799 | ||
15800 | When an MX record is looked up in the DNS and matches a wildcard record, name | |
15801 | servers normally return a record containing the name that has been looked up, | |
15802 | making it impossible to detect whether a wildcard was present or not. However, | |
15803 | some name servers have recently been seen to return the wildcard entry. If the | |
15804 | name returned by a DNS lookup begins with an asterisk, it is not used for | |
15805 | header rewriting. | |
15806 | ||
15807 | ||
9b371988 PH |
15808 | .option same_domain_copy_routing dnslookup boolean false |
15809 | .cindex "address" "copying routing" | |
15810 | Addresses with the same domain are normally routed by the &(dnslookup)& router | |
168e428f PH |
15811 | to the same list of hosts. However, this cannot be presumed, because the router |
15812 | options and preconditions may refer to the local part of the address. By | |
15813 | default, therefore, Exim routes each address in a message independently. DNS | |
15814 | servers run caches, so repeated DNS lookups are not normally expensive, and in | |
15815 | any case, personal messages rarely have more than a few recipients. | |
15816 | ||
15817 | If you are running mailing lists with large numbers of subscribers at the same | |
9b371988 PH |
15818 | domain, and you are using a &(dnslookup)& router which is independent of the |
15819 | local part, you can set &%same_domain_copy_routing%& to bypass repeated DNS | |
15820 | lookups for identical domains in one message. In this case, when &(dnslookup)& | |
168e428f PH |
15821 | routes an address to a remote transport, any other unrouted addresses in the |
15822 | message that have the same domain are automatically given the same routing | |
15823 | without processing them independently, | |
15824 | provided the following conditions are met: | |
15825 | ||
9b371988 PH |
15826 | .ilist |
15827 | No router that processed the address specified &%headers_add%& or | |
15828 | &%headers_remove%&. | |
15829 | .next | |
15830 | The router did not change the address in any way, for example, by &"widening"& | |
168e428f | 15831 | the domain. |
9b371988 | 15832 | .endlist |
168e428f PH |
15833 | |
15834 | ||
15835 | ||
15836 | ||
9b371988 PH |
15837 | .option search_parents dnslookup boolean false |
15838 | .cindex "DNS" "resolver options" | |
168e428f | 15839 | When this option is true, the resolver option RES_DNSRCH is set for DNS |
9b371988 PH |
15840 | lookups. This is different from the &%qualify_single%& option in that it |
15841 | applies to domains containing dots. Typically, but not standardly, it causes | |
15842 | the resolver to search for the name in the current domain and in parent | |
15843 | domains. For example, on a machine in the &'fict.example'& domain, if looking | |
15844 | up &'teaparty.wonderland'& failed, the resolver would try | |
15845 | &'teaparty.wonderland.fict.example'&. For details of what your resolver | |
15846 | actually does, consult your man pages for &'resolver'& and &'resolv.conf'&. | |
168e428f PH |
15847 | |
15848 | Setting this option true can cause problems in domains that have a wildcard MX | |
15849 | record, because any domain that does not have its own MX record matches the | |
15850 | local wildcard. | |
15851 | ||
15852 | ||
15853 | ||
9b371988 | 15854 | .option srv_fail_domains dnslookup "domain list&!!" unset |
168e428f PH |
15855 | If the DNS lookup for SRV records for one of the domains in this list causes a |
15856 | DNS lookup error, Exim behaves as if no SRV records were found. See section | |
9b371988 | 15857 | &<<SECTprowitdnsloo>>& for more discussion. |
168e428f PH |
15858 | |
15859 | ||
15860 | ||
168e428f | 15861 | |
9b371988 PH |
15862 | .option widen_domains dnslookup "string list" unset |
15863 | .cindex "domain" "partial; widening" | |
168e428f PH |
15864 | If a DNS lookup fails and this option is set, each of its strings in turn is |
15865 | added onto the end of the domain, and the lookup is tried again. For example, | |
15866 | if | |
9b371988 PH |
15867 | .code |
15868 | widen_domains = fict.example:ref.example | |
15869 | .endd | |
15870 | is set and a lookup of &'klingon.dictionary'& fails, | |
15871 | &'klingon.dictionary.fict.example'& is looked up, and if this fails, | |
15872 | &'klingon.dictionary.ref.example'& is tried. Note that the &%qualify_single%& | |
15873 | and &%search_parents%& options can cause some widening to be undertaken inside | |
15874 | the DNS resolver. &new("&%widen_domains%& is not applied to sender addresses | |
15875 | when verifying, unless &%rewrite_headers%& is false (not the default).") | |
15876 | ||
15877 | ||
15878 | .section "Effect of qualify_single and search_parents" | |
168e428f | 15879 | When a domain from an envelope recipient is changed by the resolver as a result |
9b371988 PH |
15880 | of the &%qualify_single%& or &%search_parents%& options, Exim rewrites the |
15881 | corresponding address in the message's header lines unless &%rewrite_headers%& | |
168e428f PH |
15882 | is set false. Exim then re-routes the address, using the full domain. |
15883 | ||
15884 | These two options affect only the DNS lookup that takes place inside the router | |
15885 | for the domain of the address that is being routed. They do not affect lookups | |
15886 | such as that implied by | |
9b371988 PH |
15887 | .code |
15888 | domains = @mx_any | |
15889 | .endd | |
168e428f PH |
15890 | that may happen while processing a router precondition before the router is |
15891 | entered. No widening ever takes place for these lookups. | |
15892 | ||
15893 | ||
15894 | ||
15895 | ||
15896 | ||
15897 | ||
15898 | ||
15899 | ||
15900 | ||
9b371988 PH |
15901 | . //////////////////////////////////////////////////////////////////////////// |
15902 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 15903 | |
9b371988 PH |
15904 | .chapter "The ipliteral router" |
15905 | .cindex "&(ipliteral)& router" | |
15906 | .cindex "domain literal" "routing" | |
15907 | .cindex "routers" "&(ipliteral)&" | |
168e428f | 15908 | This router has no private options. Unless it is being used purely for |
9b371988 PH |
15909 | verification (see &%verify_only%&) a transport is required to be defined by the |
15910 | generic &%transport%& option. The router accepts the address if its domain part | |
168e428f | 15911 | takes the form of an RFC 2822 domain literal, that is, an IP address enclosed |
9b371988 PH |
15912 | in square brackets. For example, the &(ipliteral)& router handles the address |
15913 | .code | |
15914 | root@[192.168.1.1] | |
15915 | .endd | |
168e428f PH |
15916 | by setting up delivery to the host with that IP address. |
15917 | ||
9b371988 PH |
15918 | .cindex "&%self%& option" "in &(ipliteral)& router" |
15919 | If the IP address matches something in &%ignore_target_hosts%&, the router | |
168e428f | 15920 | declines. If an IP literal turns out to refer to the local host, the generic |
9b371988 | 15921 | &%self%& option determines what happens. |
168e428f PH |
15922 | |
15923 | The RFCs require support for domain literals; however, their use is | |
15924 | controversial in today's Internet. If you want to use this router, you must | |
9b371988 | 15925 | also set the main configuration option &%allow_domain_literals%&. Otherwise, |
168e428f PH |
15926 | Exim will not recognize the domain literal syntax in addresses. |
15927 | ||
15928 | ||
15929 | ||
9b371988 PH |
15930 | . //////////////////////////////////////////////////////////////////////////// |
15931 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 15932 | |
9b371988 PH |
15933 | .chapter "The iplookup router" |
15934 | .cindex "&(iplookup)& router" | |
15935 | .cindex "routers" "&(iplookup)&" | |
15936 | The &(iplookup)& router was written to fulfil a specific requirement in | |
168e428f PH |
15937 | Cambridge University (which in fact no longer exists). For this reason, it is |
15938 | not included in the binary of Exim by default. If you want to include it, you | |
15939 | must set | |
9b371988 PH |
15940 | .code |
15941 | ROUTER_IPLOOKUP=yes | |
15942 | .endd | |
15943 | in your &_Local/Makefile_& configuration file. | |
168e428f | 15944 | |
9b371988 | 15945 | The &(iplookup)& router routes an address by sending it over a TCP or UDP |
168e428f | 15946 | connection to one or more specific hosts. The host can then return the same or |
9b371988 | 15947 | a different address &-- in effect rewriting the recipient address in the |
168e428f PH |
15948 | message's envelope. The new address is then passed on to subsequent routers. If |
15949 | this process fails, the address can be passed on to other routers, or delivery | |
9b371988 PH |
15950 | can be deferred. Since &(iplookup)& is just a rewriting router, a transport |
15951 | must not be specified for it. | |
168e428f | 15952 | |
9b371988 PH |
15953 | .cindex "options" "&(iplookup)& router" |
15954 | .option hosts iplookup string unset | |
168e428f | 15955 | This option must be supplied. Its value is a colon-separated list of host |
9b371988 PH |
15956 | names. The hosts are looked up using &[gethostbyname()]& |
15957 | (or &[getipnodebyname()]& when available) | |
168e428f | 15958 | and are tried in order until one responds to the query. If none respond, what |
9b371988 | 15959 | happens is controlled by &%optional%&. |
168e428f PH |
15960 | |
15961 | ||
9b371988 PH |
15962 | .option optional iplookup boolean false |
15963 | If &%optional%& is true, if no response is obtained from any host, the address | |
15964 | is passed to the next router, overriding &%no_more%&. If &%optional%& is false, | |
168e428f PH |
15965 | delivery to the address is deferred. |
15966 | ||
15967 | ||
9b371988 PH |
15968 | .option port iplookup integer 0 |
15969 | .cindex "port" "&(iplookup)& router" | |
168e428f PH |
15970 | This option must be supplied. It specifies the port number for the TCP or UDP |
15971 | call. | |
15972 | ||
15973 | ||
9b371988 PH |
15974 | .option protocol iplookup string udp |
15975 | This option can be set to &"udp"& or &"tcp"& to specify which of the two | |
15976 | protocols is to be used. | |
168e428f | 15977 | |
168e428f | 15978 | |
9b371988 | 15979 | .option query iplookup string&!! "&`$local_part@$domain $local_part@$domain`&" |
168e428f PH |
15980 | This defines the content of the query that is sent to the remote hosts. The |
15981 | repetition serves as a way of checking that a response is to the correct query | |
9b371988 | 15982 | in the default case (see &%response_pattern%& below). |
168e428f PH |
15983 | |
15984 | ||
9b371988 | 15985 | .option reroute iplookup string&!! unset |
168e428f PH |
15986 | If this option is not set, the rerouted address is precisely the byte string |
15987 | returned by the remote host, up to the first white space, if any. If set, the | |
15988 | string is expanded to form the rerouted address. It can include parts matched | |
9b371988 PH |
15989 | in the response by &%response_pattern%& by means of numeric variables such as |
15990 | &$1$&, &$2$&, etc. The variable &$0$& refers to the entire input string, | |
168e428f | 15991 | whether or not a pattern is in use. In all cases, the rerouted address must end |
9b371988 | 15992 | up in the form &'local_part@domain'&. |
168e428f | 15993 | |
168e428f | 15994 | |
9b371988 | 15995 | .option response_pattern iplookup string unset |
168e428f PH |
15996 | This option can be set to a regular expression that is applied to the string |
15997 | returned from the remote host. If the pattern does not match the response, the | |
9b371988 PH |
15998 | router declines. If &%response_pattern%& is not set, no checking of the |
15999 | response is done, unless the query was defaulted, in which case there is a | |
16000 | check that the text returned after the first white space is the original | |
16001 | address. This checks that the answer that has been received is in response to | |
16002 | the correct question. For example, if the response is just a new domain, the | |
16003 | following could be used: | |
16004 | .code | |
16005 | response_pattern = ^([^@]+)$ | |
16006 | reroute = $local_part@$1 | |
16007 | .endd | |
16008 | ||
16009 | .option timeout iplookup time 5s | |
168e428f | 16010 | This specifies the amount of time to wait for a response from the remote |
9b371988 | 16011 | machine. The same timeout is used for the &[connect()]& function for a TCP |
168e428f PH |
16012 | call. It does not apply to UDP. |
16013 | ||
16014 | ||
16015 | ||
16016 | ||
9b371988 PH |
16017 | . //////////////////////////////////////////////////////////////////////////// |
16018 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 16019 | |
9b371988 PH |
16020 | .chapter "The manualroute router" |
16021 | .cindex "&(manualroute)& router" | |
16022 | .cindex "routers" "&(manualroute)&" | |
16023 | .cindex "domain" "manually routing" | |
16024 | The &(manualroute)& router is so-called because it provides a way of manually | |
168e428f PH |
16025 | routing an address according to its domain. It is mainly used when you want to |
16026 | route addresses to remote hosts according to your own rules, bypassing the | |
9b371988 | 16027 | normal DNS routing that looks up MX records. However, &(manualroute)& can also |
168e428f PH |
16028 | route to local transports, a facility that may be useful if you want to save |
16029 | messages for dial-in hosts in local files. | |
16030 | ||
9b371988 PH |
16031 | The &(manualroute)& router compares a list of domain patterns with the domain |
16032 | it is trying to route. If there is no match, the router declines. Each pattern | |
16033 | has associated with it a list of hosts and some other optional data, which may | |
168e428f | 16034 | include a transport. The combination of a pattern and its data is called a |
9b371988 PH |
16035 | &"routing rule"&. For patterns that do not have an associated transport, the |
16036 | generic &%transport%& option must specify a transport, unless the router is | |
16037 | being used purely for verification (see &%verify_only%&). | |
168e428f | 16038 | |
9b371988 | 16039 | .cindex "&$host$&" |
168e428f PH |
16040 | In the case of verification, matching the domain pattern is sufficient for the |
16041 | router to accept the address. When actually routing an address for delivery, | |
16042 | an address that matches a domain pattern is queued for the associated | |
16043 | transport. If the transport is not a local one, a host list must be associated | |
16044 | with the pattern; IP addresses are looked up for the hosts, and these are | |
16045 | passed to the transport along with the mail address. For local transports, a | |
9b371988 | 16046 | host list is optional. If it is present, it is passed in &$host$& as a single |
168e428f PH |
16047 | text string. |
16048 | ||
9b371988 PH |
16049 | The list of routing rules can be provided as an inline string in |
16050 | &%route_list%&, or the data can be obtained by looking up the domain in a file | |
16051 | or database by setting &%route_data%&. Only one of these settings may appear in | |
16052 | any one instance of &(manualroute)&. The format of routing rules is described | |
16053 | below, following the list of private options. | |
168e428f | 16054 | |
168e428f | 16055 | |
9b371988 | 16056 | .section "Private options for manualroute" "SECTprioptman" |
168e428f | 16057 | |
9b371988 PH |
16058 | .cindex "options" "&(manualroute)& router" |
16059 | The private options for the &(manualroute)& router are as follows: | |
168e428f | 16060 | |
168e428f | 16061 | |
9b371988 PH |
16062 | .option host_find_failed manualroute string freeze |
16063 | This option controls what happens when &(manualroute)& tries to find an IP | |
168e428f PH |
16064 | address for a host, and the host does not exist. The option can be set to one |
16065 | of | |
9b371988 PH |
16066 | .code |
16067 | decline | |
16068 | defer | |
16069 | fail | |
16070 | freeze | |
16071 | pass | |
16072 | .endd | |
168e428f | 16073 | The default assumes that this state is a serious configuration error. The |
9b371988 PH |
16074 | difference between &"pass"& and &"decline"& is that the former forces the |
16075 | address to be passed to the next router (or the router defined by | |
16076 | &%pass_router%&), | |
16077 | .cindex "&%more%& option" | |
16078 | overriding &%no_more%&, whereas the latter passes the address to the next | |
16079 | router only if &%more%& is true. | |
168e428f | 16080 | |
9b371988 PH |
16081 | This option applies only to a definite &"does not exist"& state; if a host |
16082 | lookup gets a temporary error, delivery is deferred unless the generic | |
16083 | &%pass_on_timeout%& option is set. | |
168e428f | 16084 | |
168e428f | 16085 | |
9b371988 PH |
16086 | .option hosts_randomize manualroute boolean false |
16087 | .cindex "randomized host list" | |
16088 | .cindex "host" "list of; randomized" | |
168e428f PH |
16089 | If this option is set, the order of the items in a host list in a routing rule |
16090 | is randomized each time the list is used, unless an option in the routing rule | |
16091 | overrides (see below). Randomizing the order of a host list can be used to do | |
16092 | crude load sharing. However, if more than one mail address is routed by the | |
16093 | same router to the same host list, the host lists are considered to be the same | |
16094 | (even though they may be randomized into different orders) for the purpose of | |
16095 | deciding whether to batch the deliveries into a single SMTP transaction. | |
16096 | ||
9b371988 | 16097 | When &%hosts_randomize%& is true, a host list may be split |
168e428f PH |
16098 | into groups whose order is separately randomized. This makes it possible to |
16099 | set up MX-like behaviour. The boundaries between groups are indicated by an | |
9b371988 PH |
16100 | item that is just &`+`& in the host list. For example: |
16101 | .code | |
16102 | route_list = * host1:host2:host3:+:host4:host5 | |
16103 | .endd | |
168e428f PH |
16104 | The order of the first three hosts and the order of the last two hosts is |
16105 | randomized for each use, but the first three always end up before the last two. | |
9b371988 PH |
16106 | If &%hosts_randomize%& is not set, a &`+`& item in the list is ignored. If a |
16107 | randomized host list is passed to an &(smtp)& transport that also has | |
16108 | &%hosts_randomize set%&, the list is not re-randomized. | |
168e428f PH |
16109 | |
16110 | ||
9b371988 | 16111 | .option route_data manualroute string&!! unset |
168e428f PH |
16112 | If this option is set, it must expand to yield the data part of a routing rule. |
16113 | Typically, the expansion string includes a lookup based on the domain. For | |
16114 | example: | |
9b371988 PH |
16115 | .code |
16116 | route_data = ${lookup{$domain}dbm{/etc/routes}} | |
16117 | .endd | |
168e428f PH |
16118 | If the expansion is forced to fail, or the result is an empty string, the |
16119 | router declines. Other kinds of expansion failure cause delivery to be | |
16120 | deferred. | |
16121 | ||
16122 | ||
9b371988 | 16123 | .option route_list manualroute " "string list" " semicolon-separated"" |
168e428f PH |
16124 | This string is a list of routing rules, in the form defined below. Note that, |
16125 | unlike most string lists, the items are separated by semicolons. This is so | |
16126 | that they may contain colon-separated host lists. | |
16127 | ||
16128 | ||
9b371988 PH |
16129 | .option same_domain_copy_routing manualroute boolean false |
16130 | .cindex "address" "copying routing" | |
16131 | Addresses with the same domain are normally routed by the &(manualroute)& | |
16132 | router to the same list of hosts. However, this cannot be presumed, because the | |
16133 | router options and preconditions may refer to the local part of the address. By | |
168e428f PH |
16134 | default, therefore, Exim routes each address in a message independently. DNS |
16135 | servers run caches, so repeated DNS lookups are not normally expensive, and in | |
16136 | any case, personal messages rarely have more than a few recipients. | |
16137 | ||
16138 | If you are running mailing lists with large numbers of subscribers at the same | |
9b371988 PH |
16139 | domain, and you are using a &(manualroute)& router which is independent of the |
16140 | local part, you can set &%same_domain_copy_routing%& to bypass repeated DNS | |
16141 | lookups for identical domains in one message. In this case, when | |
16142 | &(manualroute)& routes an address to a remote transport, any other unrouted | |
16143 | addresses in the message that have the same domain are automatically given the | |
16144 | same routing without processing them independently. However, this is only done | |
16145 | if &%headers_add%& and &%headers_remove%& are unset. | |
168e428f PH |
16146 | |
16147 | ||
16148 | ||
16149 | ||
9b371988 PH |
16150 | .section "Routing rules in route_list" |
16151 | The value of &%route_list%& is a string consisting of a sequence of routing | |
168e428f | 16152 | rules, separated by semicolons. If a semicolon is needed in a rule, it can be |
068aaea8 | 16153 | entered as two semicolons. Alternatively, the list separator can be changed as |
9b371988 | 16154 | described (for colon-separated lists) in section &<<SECTlistconstruct>>&. |
068aaea8 | 16155 | Empty rules are ignored. The format of each rule is |
9b371988 PH |
16156 | .display |
16157 | <&'domain pattern'&> <&'list of hosts'&> <&'options'&> | |
16158 | .endd | |
168e428f PH |
16159 | The following example contains two rules, each with a simple domain pattern and |
16160 | no options: | |
9b371988 | 16161 | .code |
168e428f PH |
16162 | route_list = \ |
16163 | dict.ref.example mail-1.ref.example:mail-2.ref.example ; \ | |
16164 | thes.ref.example mail-3.ref.example:mail-4.ref.example | |
9b371988 | 16165 | .endd |
168e428f PH |
16166 | The three parts of a rule are separated by white space. The pattern and the |
16167 | list of hosts can be enclosed in quotes if necessary, and if they are, the | |
9b371988 | 16168 | usual quoting rules apply. Each rule in a &%route_list%& must start with a |
168e428f PH |
16169 | single domain pattern, which is the only mandatory item in the rule. The |
16170 | pattern is in the same format as one item in a domain list (see section | |
9b371988 | 16171 | &<<SECTdomainlist>>&), |
168e428f PH |
16172 | except that it may not be the name of an interpolated file. |
16173 | That is, it may be wildcarded, or a regular expression, or a file or database | |
16174 | lookup (with semicolons doubled, because of the use of semicolon as a separator | |
9b371988 | 16175 | in a &%route_list%&). |
168e428f | 16176 | |
9b371988 | 16177 | The rules in &%route_list%& are searched in order until one of the patterns |
168e428f PH |
16178 | matches the domain that is being routed. The list of hosts and then options are |
16179 | then used as described below. If there is no match, the router declines. When | |
9b371988 | 16180 | &%route_list%& is set, &%route_data%& must not be set. |
168e428f PH |
16181 | |
16182 | ||
16183 | ||
9b371988 PH |
16184 | .section "Routing rules in route_data" |
16185 | The use of &%route_list%& is convenient when there are only a small number of | |
168e428f | 16186 | routing rules. For larger numbers, it is easier to use a file or database to |
9b371988 PH |
16187 | hold the routing information, and use the &%route_data%& option instead. |
16188 | The value of &%route_data%& is a list of hosts, followed by (optional) options. | |
16189 | Most commonly, &%route_data%& is set as a string that contains an | |
168e428f PH |
16190 | expansion lookup. For example, suppose we place two routing rules in a file |
16191 | like this: | |
9b371988 PH |
16192 | .code |
16193 | dict.ref.example: mail-1.ref.example:mail-2.ref.example | |
16194 | thes.ref.example: mail-3.ref.example:mail-4.ref.example | |
16195 | .endd | |
168e428f | 16196 | This data can be accessed by setting |
9b371988 PH |
16197 | .code |
16198 | route_data = ${lookup{$domain}lsearch{/the/file/name}} | |
16199 | .endd | |
168e428f | 16200 | Failure of the lookup results in an empty string, causing the router to |
9b371988 | 16201 | decline. However, you do not have to use a lookup in &%route_data%&. The only |
168e428f PH |
16202 | requirement is that the result of expanding the string is a list of hosts, |
16203 | possibly followed by options, separated by white space. The list of hosts must | |
16204 | be enclosed in quotes if it contains white space. | |
16205 | ||
16206 | ||
16207 | ||
16208 | ||
9b371988 PH |
16209 | .section "Format of the list of hosts" |
16210 | .new | |
16211 | A list of hosts, whether obtained via &%route_data%& or &%route_list%&, is | |
16212 | always separately expanded before use. If the expansion fails, the router | |
16213 | declines. The result of the expansion must be a colon-separated list of names | |
16214 | and/or IP addresses, optionally also including ports. The format of each item | |
16215 | in the list is described in the next section. The list separator can be changed | |
16216 | as described in section &<<SECTlistconstruct>>&. | |
16217 | .wen | |
168e428f | 16218 | |
9b371988 | 16219 | If the list of hosts was obtained from a &%route_list%& item, the following |
168e428f PH |
16220 | variables are set during its expansion: |
16221 | ||
9b371988 PH |
16222 | .ilist |
16223 | .cindex "numerical variables (&$1$& &$2$& etc)" "in &(manualroute)& router" | |
168e428f | 16224 | If the domain was matched against a regular expression, the numeric variables |
9b371988 PH |
16225 | &$1$&, &$2$&, etc. may be set. For example: |
16226 | .code | |
16227 | route_list = ^domain(\d+) host-$1.text.example | |
16228 | .endd | |
16229 | .next | |
16230 | &$0$& is always set to the entire domain. | |
16231 | .next | |
16232 | &$1$& is also set when partial matching is done in a file lookup. | |
16233 | ||
16234 | .next | |
16235 | .cindex "&$value$&" | |
168e428f | 16236 | If the pattern that matched the domain was a lookup item, the data that was |
9b371988 PH |
16237 | looked up is available in the expansion variable &$value$&. For example: |
16238 | .code | |
16239 | route_list = lsearch;;/some/file.routes $value | |
16240 | .endd | |
16241 | .endlist | |
068aaea8 PH |
16242 | |
16243 | Note the doubling of the semicolon in the pattern that is necessary because | |
16244 | semicolon is the default route list separator. | |
16245 | ||
16246 | ||
16247 | ||
9b371988 PH |
16248 | .section "Format of one host item" "SECTformatonehostitem" |
16249 | .new | |
068aaea8 PH |
16250 | Each item in the list of hosts is either a host name or an IP address, |
16251 | optionally with an attached port number. When no port is given, an IP address | |
16252 | is not enclosed in brackets. When a port is specified, it overrides the port | |
16253 | specification on the transport. The port is separated from the name or address | |
16254 | by a colon. This leads to some complications: | |
168e428f | 16255 | |
9b371988 PH |
16256 | .ilist |
16257 | Because colon is the default separator for the list of hosts, either | |
068aaea8 PH |
16258 | the colon that specifies a port must be doubled, or the list separator must |
16259 | be changed. The following two examples have the same effect: | |
9b371988 PH |
16260 | .code |
16261 | route_list = * "host1.tld::1225 : host2.tld::1226" | |
16262 | route_list = * "<+ host1.tld:1225 + host2.tld:1226" | |
16263 | .endd | |
16264 | .next | |
16265 | When IPv6 addresses are involved, it gets worse, because they contain | |
068aaea8 PH |
16266 | colons of their own. To make this case easier, it is permitted to |
16267 | enclose an IP address (either v4 or v6) in square brackets if a port | |
16268 | number follows. For example: | |
9b371988 PH |
16269 | .code |
16270 | route_list = * "</ [10.1.1.1]:1225 / [::1]:1226" | |
16271 | .endd | |
16272 | .endlist | |
16273 | .wen | |
16274 | ||
16275 | .section "How the list of hosts is used" "SECThostshowused" | |
16276 | When an address is routed to an &(smtp)& transport by &(manualroute)&, each of | |
168e428f | 16277 | the hosts is tried, in the order specified, when carrying out the SMTP |
9b371988 PH |
16278 | delivery. However, the order can be changed by setting the &%hosts_randomize%& |
16279 | option, either on the router (see section &<<SECTprioptman>>& above), or on the | |
168e428f PH |
16280 | transport. |
16281 | ||
16282 | Hosts may be listed by name or by IP address. An unadorned name in the list of | |
9b371988 | 16283 | hosts is interpreted as a host name. A name that is followed by &`/MX`& is |
168e428f PH |
16284 | interpreted as an indirection to a sublist of hosts obtained by looking up MX |
16285 | records in the DNS. For example: | |
9b371988 PH |
16286 | .code |
16287 | route_list = * x.y.z:p.q.r/MX:e.f.g | |
16288 | .endd | |
16289 | .new | |
068aaea8 PH |
16290 | If this feature is used with a port specifier, the port must come last. For |
16291 | example: | |
9b371988 PH |
16292 | .code |
16293 | route_list = * dom1.tld/mx::1225 | |
16294 | .endd | |
16295 | .wen | |
16296 | If the &%hosts_randomize%& option is set, the order of the items in the list is | |
168e428f | 16297 | randomized before any lookups are done. Exim then scans the list; for any name |
9b371988 | 16298 | that is not followed by &`/MX`& it looks up an IP address. If this turns out to |
168e428f PH |
16299 | be an interface on the local host and the item is not the first in the list, |
16300 | Exim discards it and any subsequent items. If it is the first item, what | |
16301 | happens is controlled by the | |
9b371988 PH |
16302 | .cindex "&%self%& option" "in &(manualroute)& router" |
16303 | &%self%& option of the router. | |
168e428f | 16304 | |
9b371988 | 16305 | A name on the list that is followed by &`/MX`& is replaced with the list of |
168e428f | 16306 | hosts obtained by looking up MX records for the name. This is always a DNS |
9b371988 PH |
16307 | lookup; the &%bydns%& and &%byname%& options (see section &<<SECThowoptused>>& |
16308 | below) are not relevant here. The order of these hosts is determined by the | |
16309 | preference values in the MX records, according to the usual rules. Because | |
16310 | randomizing happens before the MX lookup, it does not affect the order that is | |
16311 | defined by MX preferences. | |
168e428f PH |
16312 | |
16313 | If the local host is present in the sublist obtained from MX records, but is | |
16314 | not the most preferred host in that list, it and any equally or less | |
16315 | preferred hosts are removed before the sublist is inserted into the main list. | |
16316 | ||
16317 | If the local host is the most preferred host in the MX list, what happens | |
9b371988 | 16318 | depends on where in the original list of hosts the &`/MX`& item appears. If it |
168e428f PH |
16319 | is not the first item (that is, there are previous hosts in the main list), |
16320 | Exim discards this name and any subsequent items in the main list. | |
16321 | ||
16322 | If the MX item is first in the list of hosts, and the local host is the | |
9b371988 | 16323 | most preferred host, what happens is controlled by the &%self%& option of the |
168e428f PH |
16324 | router. |
16325 | ||
16326 | DNS failures when lookup up the MX records are treated in the same way as DNS | |
9b371988 PH |
16327 | failures when looking up IP addresses: &%pass_on_timeout%& and |
16328 | &%host_find_failed%& are used when relevant. | |
168e428f | 16329 | |
9b371988 | 16330 | The generic &%ignore_target_hosts%& option applies to all hosts in the list, |
168e428f PH |
16331 | whether obtained from an MX lookup or not. |
16332 | ||
16333 | ||
16334 | ||
9b371988 | 16335 | .section "How the options are used" "SECThowoptused" |
168e428f PH |
16336 | The options are a sequence of words; in practice no more than three are ever |
16337 | present. One of the words can be the name of a transport; this overrides the | |
9b371988 | 16338 | &%transport%& option on the router for this particular routing rule only. The |
168e428f PH |
16339 | other words (if present) control randomization of the list of hosts on a |
16340 | per-rule basis, and how the IP addresses of the hosts are to be found when | |
16341 | routing to a remote transport. These options are as follows: | |
16342 | ||
9b371988 PH |
16343 | .ilist |
16344 | &%randomize%&: randomize the order of the hosts in this list, overriding the | |
16345 | setting of &%hosts_randomize%& for this routing rule only. | |
16346 | .next | |
16347 | &%no_randomize%&: do not randomize the order of the hosts in this list, | |
16348 | overriding the setting of &%hosts_randomize%& for this routing rule only. | |
16349 | .next | |
16350 | &%byname%&: use &[getipnodebyname()]& (&[gethostbyname()]& on older systems) to | |
168e428f | 16351 | find IP addresses. This function may ultimately cause a DNS lookup, but it may |
9b371988 PH |
16352 | also look in &_/etc/hosts_& or other sources of information. |
16353 | .next | |
16354 | &%bydns%&: look up address records for the hosts directly in the DNS; fail if | |
168e428f PH |
16355 | no address records are found. If there is a temporary DNS error (such as a |
16356 | timeout), delivery is deferred. | |
9b371988 | 16357 | .endlist |
168e428f PH |
16358 | |
16359 | For example: | |
9b371988 | 16360 | .code |
168e428f PH |
16361 | route_list = domain1 host1:host2:host3 randomize bydns;\ |
16362 | domain2 host4:host5 | |
9b371988 PH |
16363 | .endd |
16364 | If neither &%byname%& nor &%bydns%& is given, Exim behaves as follows: First, a | |
16365 | DNS lookup is done. If this yields anything other than HOST_NOT_FOUND, that | |
16366 | result is used. Otherwise, Exim goes on to try a call to &[getipnodebyname()]& | |
16367 | or &[gethostbyname()]&, and the result of the lookup is the result of that | |
168e428f PH |
16368 | call. |
16369 | ||
9b371988 PH |
16370 | &*Warning*&: It has been discovered that on some systems, if a DNS lookup |
16371 | called via &[getipnodebyname()]& times out, HOST_NOT_FOUND is returned | |
168e428f | 16372 | instead of TRY_AGAIN. That is why the default action is to try a DNS |
9b371988 | 16373 | lookup first. Only if that gives a definite &"no such host"& is the local |
168e428f PH |
16374 | function called. |
16375 | ||
16376 | ||
16377 | ||
16378 | If no IP address for a host can be found, what happens is controlled by the | |
9b371988 | 16379 | &%host_find_failed%& option. |
168e428f | 16380 | |
9b371988 | 16381 | .cindex "&$host$&" |
168e428f | 16382 | When an address is routed to a local transport, IP addresses are not looked up. |
9b371988 | 16383 | The host list is passed to the transport in the &$host$& variable. |
168e428f PH |
16384 | |
16385 | ||
16386 | ||
9b371988 PH |
16387 | .section "Manualroute examples" |
16388 | In some of the examples that follow, the presence of the &%remote_smtp%& | |
168e428f PH |
16389 | transport, as defined in the default configuration file, is assumed: |
16390 | ||
9b371988 PH |
16391 | .ilist |
16392 | .cindex "smart host" "example router" | |
16393 | The &(manualroute)& router can be used to forward all external mail to a | |
16394 | &'smart host'&. If you have set up, in the main part of the configuration, a | |
16395 | named domain list that contains your local domains, for example: | |
16396 | .code | |
16397 | domainlist local_domains = my.domain.example | |
16398 | .endd | |
16399 | You can arrange for all other domains to be routed to a smart host by making | |
168e428f | 16400 | your first router something like this: |
9b371988 PH |
16401 | .code |
16402 | smart_route: | |
16403 | driver = manualroute | |
16404 | domains = !+local_domains | |
16405 | transport = remote_smtp | |
16406 | route_list = * smarthost.ref.example | |
16407 | .endd | |
168e428f | 16408 | This causes all non-local addresses to be sent to the single host |
9b371988 | 16409 | &'smarthost.ref.example'&. If a colon-separated list of smart hosts is given, |
168e428f | 16410 | they are tried in order |
9b371988 | 16411 | (but you can use &%hosts_randomize%& to vary the order each time). |
168e428f | 16412 | Another way of configuring the same thing is this: |
9b371988 PH |
16413 | .code |
16414 | smart_route: | |
16415 | driver = manualroute | |
16416 | transport = remote_smtp | |
16417 | route_list = !+local_domains smarthost.ref.example | |
16418 | .endd | |
168e428f | 16419 | There is no difference in behaviour between these two routers as they stand. |
9b371988 PH |
16420 | However, they behave differently if &%no_more%& is added to them. In the first |
16421 | example, the router is skipped if the domain does not match the &%domains%& | |
168e428f | 16422 | precondition; the following router is always tried. If the router runs, it |
9b371988 PH |
16423 | always matches the domain and so can never decline. Therefore, &%no_more%& |
16424 | would have no effect. In the second case, the router is never skipped; it | |
16425 | always runs. However, if it doesn't match the domain, it declines. In this case | |
16426 | &%no_more%& would prevent subsequent routers from running. | |
16427 | ||
16428 | .next | |
16429 | .cindex "mail hub example" | |
16430 | A &'mail hub'& is a host which receives mail for a number of domains via MX | |
168e428f PH |
16431 | records in the DNS and delivers it via its own private routing mechanism. Often |
16432 | the final destinations are behind a firewall, with the mail hub being the one | |
16433 | machine that can connect to machines both inside and outside the firewall. The | |
9b371988 | 16434 | &(manualroute)& router is usually used on a mail hub to route incoming messages |
168e428f | 16435 | to the correct hosts. For a small number of domains, the routing can be inline, |
9b371988 | 16436 | using the &%route_list%& option, but for a larger number a file or database |
168e428f | 16437 | lookup is easier to manage. |
9b371988 | 16438 | |
168e428f PH |
16439 | If the domain names are in fact the names of the machines to which the mail is |
16440 | to be sent by the mail hub, the configuration can be quite simple. For | |
9b371988 PH |
16441 | example: |
16442 | .code | |
16443 | hub_route: | |
16444 | driver = manualroute | |
16445 | transport = remote_smtp | |
16446 | route_list = *.rhodes.tvs.example $domain | |
16447 | .endd | |
16448 | This configuration routes domains that match &`*.rhodes.tvs.example`& to hosts | |
168e428f PH |
16449 | whose names are the same as the mail domains. A similar approach can be taken |
16450 | if the host name can be obtained from the domain name by a string manipulation | |
16451 | that the expansion facilities can handle. Otherwise, a lookup based on the | |
16452 | domain can be used to find the host: | |
9b371988 PH |
16453 | .code |
16454 | through_firewall: | |
16455 | driver = manualroute | |
16456 | transport = remote_smtp | |
16457 | route_data = ${lookup {$domain} cdb {/internal/host/routes}} | |
16458 | .endd | |
168e428f PH |
16459 | The result of the lookup must be the name or IP address of the host (or |
16460 | hosts) to which the address is to be routed. If the lookup fails, the route | |
16461 | data is empty, causing the router to decline. The address then passes to the | |
16462 | next router. | |
16463 | ||
9b371988 PH |
16464 | .next |
16465 | .cindex "batched SMTP output example" | |
16466 | .cindex "SMTP" "batched outgoing; example" | |
16467 | You can use &(manualroute)& to deliver messages to pipes or files in batched | |
168e428f PH |
16468 | SMTP format for onward transportation by some other means. This is one way of |
16469 | storing mail for a dial-up host when it is not connected. The route list entry | |
16470 | can be as simple as a single domain name in a configuration like this: | |
9b371988 PH |
16471 | .code |
16472 | save_in_file: | |
16473 | driver = manualroute | |
16474 | transport = batchsmtp_appendfile | |
16475 | route_list = saved.domain.example | |
16476 | .endd | |
168e428f PH |
16477 | though often a pattern is used to pick up more than one domain. If there are |
16478 | several domains or groups of domains with different transport requirements, | |
16479 | different transports can be listed in the routing information: | |
9b371988 | 16480 | .code |
168e428f PH |
16481 | save_in_file: |
16482 | driver = manualroute | |
16483 | route_list = \ | |
16484 | *.saved.domain1.example $domain batch_appendfile; \ | |
16485 | *.saved.domain2.example \ | |
16486 | ${lookup{$domain}dbm{/domain2/hosts}{$value}fail} \ | |
16487 | batch_pipe | |
9b371988 PH |
16488 | .endd |
16489 | .cindex "&$domain$&" | |
16490 | .cindex "&$host$&" | |
16491 | The first of these just passes the domain in the &$host$& variable, which | |
16492 | doesn't achieve much (since it is also in &$domain$&), but the second does a | |
168e428f PH |
16493 | file lookup to find a value to pass, causing the router to decline to handle |
16494 | the address if the lookup fails. | |
16495 | ||
9b371988 PH |
16496 | .next |
16497 | .cindex "UUCP" "example of router for" | |
168e428f | 16498 | Routing mail directly to UUCP software is a specific case of the use of |
9b371988 | 16499 | &(manualroute)& in a gateway to another mail environment. This is an example of |
168e428f | 16500 | one way it can be done: |
9b371988 | 16501 | .code |
168e428f PH |
16502 | # Transport |
16503 | uucp: | |
16504 | driver = pipe | |
16505 | user = nobody | |
16506 | command = /usr/local/bin/uux -r - \ | |
16507 | ${substr_-5:$host}!rmail ${local_part} | |
16508 | return_fail_output = true | |
16509 | ||
16510 | # Router | |
16511 | uucphost: | |
16512 | transport = uucp | |
16513 | driver = manualroute | |
16514 | route_data = \ | |
16515 | ${lookup{$domain}lsearch{/usr/local/exim/uucphosts}} | |
9b371988 PH |
16516 | .endd |
16517 | The file &_/usr/local/exim/uucphosts_& contains entries like | |
16518 | .code | |
16519 | darksite.ethereal.example: darksite.UUCP | |
16520 | .endd | |
16521 | It can be set up more simply without adding and removing &".UUCP"& but this way | |
168e428f | 16522 | makes clear the distinction between the domain name |
9b371988 PH |
16523 | &'darksite.ethereal.example'& and the UUCP host name &'darksite'&. |
16524 | .endlist | |
168e428f PH |
16525 | |
16526 | ||
16527 | ||
16528 | ||
16529 | ||
16530 | ||
16531 | ||
16532 | ||
9b371988 PH |
16533 | . //////////////////////////////////////////////////////////////////////////// |
16534 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 16535 | |
9b371988 PH |
16536 | .chapter "The queryprogram router" "CHAPdriverlast" |
16537 | .cindex "&(queryprogram)& router" | |
16538 | .cindex "routers" "&(queryprogram)&" | |
16539 | .cindex "routing" "by external program" | |
16540 | The &(queryprogram)& router routes an address by running an external command | |
16541 | and acting on its output. This is an expensive way to route, and is intended | |
16542 | mainly for use in lightly-loaded systems, or for performing experiments. | |
16543 | However, if it is possible to use the precondition options (&%domains%&, | |
16544 | &%local_parts%&, etc) to skip this router for most addresses, it could sensibly | |
16545 | be used in special cases, even on a busy host. There are the following private | |
16546 | options: | |
16547 | .cindex "options" "&(queryprogram)& router" | |
168e428f | 16548 | |
9b371988 | 16549 | .option command queryprogram string&!! unset |
168e428f PH |
16550 | This option must be set. It specifies the command that is to be run. The |
16551 | command is split up into a command name and arguments, and then each is | |
9b371988 PH |
16552 | expanded separately (exactly as for a &(pipe)& transport, described in chapter |
16553 | &<<CHAPpipetransport>>&). | |
168e428f | 16554 | |
168e428f | 16555 | |
9b371988 PH |
16556 | .option command_group queryprogram string unset |
16557 | .cindex "gid (group id)" "in &(queryprogram)& router" | |
168e428f | 16558 | This option specifies a gid to be set when running the command. It must be set |
9b371988 | 16559 | if &%command_user%& specifies a numerical uid. If it begins with a digit, it is |
168e428f | 16560 | interpreted as the numerical value of the gid. Otherwise it is looked up using |
9b371988 | 16561 | &[getgrnam()]&. |
168e428f PH |
16562 | |
16563 | ||
9b371988 PH |
16564 | .option command_user queryprogram string unset |
16565 | .cindex "uid (user id)" "for &(queryprogram)&" | |
168e428f PH |
16566 | This option must be set. It specifies the uid which is set when running the |
16567 | command. If it begins with a digit it is interpreted as the numerical value of | |
9b371988 PH |
16568 | the uid. Otherwise, it is looked up using &[getpwnam()]& to obtain a value for |
16569 | the uid and, if &%command_group%& is not set, a value for the gid also. | |
168e428f | 16570 | |
168e428f | 16571 | |
9b371988 | 16572 | .option current_directory queryprogram string / |
168e428f PH |
16573 | This option specifies an absolute path which is made the current directory |
16574 | before running the command. | |
16575 | ||
16576 | ||
9b371988 | 16577 | .option timeout queryprogram time 1h |
168e428f PH |
16578 | If the command does not complete within the timeout period, its process group |
16579 | is killed and the message is frozen. A value of zero time specifies no | |
16580 | timeout. | |
16581 | ||
16582 | ||
16583 | The standard output of the command is connected to a pipe, which is read when | |
16584 | the command terminates. It should consist of a single line of output, | |
16585 | containing up to five fields, separated by white space. The maximum length of | |
16586 | the line is 1023 characters. Longer lines are silently truncated. The first | |
16587 | field is one of the following words (case-insensitive): | |
16588 | ||
9b371988 PH |
16589 | .ilist |
16590 | &'Accept'&: routing succeeded; the remaining fields specify what to do (see | |
168e428f | 16591 | below). |
9b371988 PH |
16592 | .next |
16593 | &'Decline'&: the router declines; pass the address to the next router, unless | |
16594 | &%no_more%& is set. | |
16595 | .next | |
16596 | &'Fail'&: routing failed; do not pass the address to any more routers. Any | |
168e428f PH |
16597 | subsequent text on the line is an error message. If the router is run as part |
16598 | of address verification during an incoming SMTP message, the message is | |
16599 | included in the SMTP response. | |
9b371988 PH |
16600 | .next |
16601 | &'Defer'&: routing could not be completed at this time; try again later. Any | |
168e428f PH |
16602 | subsequent text on the line is an error message which is logged. It is not |
16603 | included in any SMTP response. | |
9b371988 PH |
16604 | .next |
16605 | &'Freeze'&: the same as &'defer'&, except that the message is frozen. | |
16606 | .next | |
16607 | &'Pass'&: pass the address to the next router (or the router specified by | |
16608 | &%pass_router%&), overriding &%no_more%&. | |
16609 | .next | |
16610 | &'Redirect'&: the message is redirected. The remainder of the line is a list of | |
168e428f | 16611 | new addresses, which are routed independently, starting with the first router, |
9b371988 PH |
16612 | or the router specified by &%redirect_router%&, if set. |
16613 | .endlist | |
168e428f | 16614 | |
9b371988 | 16615 | When the first word is &'accept'&, the remainder of the line consists of a |
168e428f PH |
16616 | number of keyed data values, as follows (split into two lines here, to fit on |
16617 | the page): | |
9b371988 PH |
16618 | .code |
16619 | ACCEPT TRANSPORT=<transport> HOSTS=<list of hosts> | |
16620 | LOOKUP=byname|bydns DATA=<text> | |
16621 | .endd | |
168e428f | 16622 | The data items can be given in any order, and all are optional. If no transport |
9b371988 PH |
16623 | is included, the transport specified by the generic &%transport%& option is |
16624 | used. The list of hosts and the lookup type are needed only if the transport is | |
16625 | an &(smtp)& transport that does not itself supply a list of hosts. | |
168e428f | 16626 | |
9b371988 | 16627 | The format of the list of hosts is the same as for the &(manualroute)& router. |
068aaea8 | 16628 | As well as host names and IP addresses with optional port numbers, as described |
9b371988 PH |
16629 | in section &<<SECTformatonehostitem>>&, it may contain names followed by |
16630 | &`/MX`& to specify sublists of hosts that are obtained by looking up MX records | |
16631 | (see section &<<SECThostshowused>>&). | |
168e428f PH |
16632 | |
16633 | If the lookup type is not specified, Exim behaves as follows when trying to | |
16634 | find an IP address for each host: First, a DNS lookup is done. If this yields | |
16635 | anything other than HOST_NOT_FOUND, that result is used. Otherwise, Exim | |
9b371988 | 16636 | goes on to try a call to &[getipnodebyname()]& or &[gethostbyname()]&, and the |
168e428f PH |
16637 | result of the lookup is the result of that call. |
16638 | ||
9b371988 PH |
16639 | .cindex "&$address_data$&" |
16640 | If the DATA field is set, its value is placed in the &$address_data$& | |
168e428f | 16641 | variable. For example, this return line |
9b371988 PH |
16642 | .code |
16643 | accept hosts=x1.y.example:x2.y.example data="rule1" | |
16644 | .endd | |
168e428f | 16645 | routes the address to the default transport, passing a list of two hosts. When |
9b371988 | 16646 | the transport runs, the string &"rule1"& is in &$address_data$&. |
168e428f PH |
16647 | |
16648 | ||
16649 | ||
16650 | ||
9b371988 PH |
16651 | . //////////////////////////////////////////////////////////////////////////// |
16652 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 16653 | |
9b371988 PH |
16654 | .chapter "The redirect router" "CHAPredirect" |
16655 | .cindex "&(redirect)& router" | |
16656 | .cindex "routers" "&(redirect)&" | |
16657 | .cindex "alias file" "in a &(redirect)& router" | |
16658 | .cindex "address redirection" "&(redirect)& router" | |
16659 | The &(redirect)& router handles several kinds of address redirection. Its most | |
168e428f | 16660 | common uses are for resolving local part aliases from a central alias file |
9b371988 | 16661 | (usually called &_/etc/aliases_&) and for handling users' personal &_.forward_& |
168e428f PH |
16662 | files, but it has many other potential uses. The incoming address can be |
16663 | redirected in several different ways: | |
16664 | ||
9b371988 PH |
16665 | .ilist |
16666 | It can be replaced by one or more new addresses which are themselves routed | |
168e428f | 16667 | independently. |
9b371988 PH |
16668 | .next |
16669 | It can be routed to be delivered to a given file or directory. | |
16670 | .next | |
16671 | It can be routed to be delivered to a specified pipe command. | |
16672 | .next | |
16673 | It can cause an automatic reply to be generated. | |
16674 | .next | |
16675 | It can be forced to fail, with a custom error message. | |
16676 | .next | |
16677 | It can be temporarily deferred. | |
16678 | .next | |
16679 | It can be discarded. | |
16680 | .endlist | |
16681 | ||
16682 | The generic &%transport%& option must not be set for &(redirect)& routers. | |
168e428f | 16683 | However, there are some private options which define transports for delivery to |
9b371988 PH |
16684 | files and pipes, and for generating autoreplies. See the &%file_transport%&, |
16685 | &%pipe_transport%& and &%reply_transport%& descriptions below. | |
168e428f PH |
16686 | |
16687 | ||
16688 | ||
9b371988 | 16689 | .section "Redirection data" |
168e428f | 16690 | The router operates by interpreting a text string which it obtains either by |
9b371988 PH |
16691 | expanding the contents of the &%data%& option, or by reading the entire |
16692 | contents of a file whose name is given in the &%file%& option. These two | |
16693 | options are mutually exclusive. The first is commonly used for handling system | |
16694 | aliases, in a configuration like this: | |
16695 | .code | |
16696 | system_aliases: | |
16697 | driver = redirect | |
16698 | data = ${lookup{$local_part}lsearch{/etc/aliases}} | |
16699 | .endd | |
168e428f | 16700 | If the lookup fails, the expanded string in this example is empty. When the |
9b371988 | 16701 | expansion of &%data%& results in an empty string, the router declines. A forced |
168e428f PH |
16702 | expansion failure also causes the router to decline; other expansion failures |
16703 | cause delivery to be deferred. | |
16704 | ||
9b371988 PH |
16705 | A configuration using &%file%& is commonly used for handling users' |
16706 | &_.forward_& files, like this: | |
16707 | .code | |
16708 | userforward: | |
16709 | driver = redirect | |
16710 | check_local_user | |
16711 | file = $home/.forward | |
16712 | no_verify | |
16713 | .endd | |
168e428f | 16714 | If the file does not exist, or causes no action to be taken (for example, it is |
9b371988 | 16715 | empty or consists only of comments), the router declines. &*Warning*&: This |
168e428f PH |
16716 | is not the case when the file contains syntactically valid items that happen to |
16717 | yield empty addresses, for example, items containing only RFC 2822 address | |
16718 | comments. | |
16719 | ||
16720 | ||
16721 | ||
9b371988 PH |
16722 | .section "Forward files and address verification" |
16723 | .cindex "address redirection" "while verifying" | |
16724 | It is usual to set &%no_verify%& on &(redirect)& routers which handle users' | |
16725 | &_.forward_& files, as in the example above. There are two reasons for this: | |
168e428f | 16726 | |
9b371988 PH |
16727 | .ilist |
16728 | When Exim is receiving an incoming SMTP message from a remote host, it is | |
168e428f PH |
16729 | running under the Exim uid, not as root. |
16730 | No additional groups are set up, even if the Exim uid is a member of other | |
9b371988 | 16731 | groups (that is, the &[initgroups()]& function is not run). |
168e428f PH |
16732 | Exim is unable to change uid to read the file as the user, and it may not be |
16733 | able to read it as the Exim user. So in practice the router may not be able to | |
16734 | operate. | |
9b371988 PH |
16735 | .next |
16736 | However, even when the router can operate, the existence of a &_.forward_& file | |
168e428f PH |
16737 | is unimportant when verifying an address. What should be checked is whether the |
16738 | local part is a valid user name or not. Cutting out the redirection processing | |
16739 | saves some resources. | |
9b371988 | 16740 | .endlist |
168e428f PH |
16741 | |
16742 | ||
16743 | ||
16744 | ||
16745 | ||
16746 | ||
9b371988 PH |
16747 | .section "Interpreting redirection data" |
16748 | .cindex "Sieve filter" "specifying in redirection data" | |
16749 | .cindex "filter" "specifying in redirection data" | |
16750 | The contents of the data string, whether obtained from &%data%& or &%file%&, | |
16751 | can be interpreted in two different ways: | |
168e428f | 16752 | |
9b371988 PH |
16753 | .ilist |
16754 | If the &%allow_filter%& option is set true, and the data begins with the text | |
16755 | &"#Exim filter"& or &"#Sieve filter"&, it is interpreted as a list of | |
16756 | &'filtering'& instructions in the form of an Exim or Sieve filter file, | |
168e428f | 16757 | respectively. Details of the syntax and semantics of filter files are described |
9b371988 | 16758 | in a separate document entitled &'Exim's interfaces to mail filtering'&; this |
168e428f | 16759 | document is intended for use by end users. |
9b371988 PH |
16760 | .next |
16761 | Otherwise, the data must be a comma-separated list of redirection items, as | |
168e428f | 16762 | described in the next section. |
9b371988 | 16763 | .endlist |
168e428f | 16764 | |
9b371988 | 16765 | When a message is redirected to a file (a &"mail folder"&), the file name given |
168e428f | 16766 | in a non-filter redirection list must always be an absolute path. A filter may |
9b371988 PH |
16767 | generate a relative path &-- how this is handled depends on the transport's |
16768 | configuration. See section &<<SECTfildiropt>>& for a discussion of this issue | |
16769 | for the &(appendfile)& transport. | |
168e428f PH |
16770 | |
16771 | ||
16772 | ||
9b371988 PH |
16773 | .section "Items in a non-filter redirection list" "SECTitenonfilred" |
16774 | .cindex "address redirection" "non-filter list items" | |
168e428f PH |
16775 | When the redirection data is not an Exim or Sieve filter, for example, if it |
16776 | comes from a conventional alias or forward file, it consists of a list of | |
16777 | addresses, file names, pipe commands, or certain special items (see section | |
9b371988 PH |
16778 | &<<SECTspecitredli>>& below). The special items can be individually enabled or |
16779 | disabled by means of options whose names begin with &%allow_%& or &%forbid_%&, | |
168e428f PH |
16780 | depending on their default values. The items in the list are separated by |
16781 | commas or newlines. | |
16782 | If a comma is required in an item, the entire item must be enclosed in double | |
16783 | quotes. | |
16784 | ||
16785 | Lines starting with a # character are comments, and are ignored, and # may | |
16786 | also appear following a comma, in which case everything between the # and the | |
16787 | next newline character is ignored. | |
16788 | ||
16789 | If an item is entirely enclosed in double quotes, these are removed. Otherwise | |
16790 | double quotes are retained because some forms of mail address require their use | |
068aaea8 | 16791 | (but never to enclose the entire address). In the following description, |
9b371988 | 16792 | &"item"& refers to what remains after any surrounding double quotes have been |
068aaea8 | 16793 | removed. |
168e428f | 16794 | |
9b371988 PH |
16795 | .cindex "&$local_part$&" |
16796 | &*Warning*&: If you use an Exim expansion to construct a redirection address, | |
16797 | and the expansion contains a reference to &$local_part$&, you should make use | |
16798 | of the &%quote_local_part%& expansion operator, in case the local part contains | |
068aaea8 | 16799 | special characters. For example, to redirect all mail for the domain |
9b371988 | 16800 | &'obsolete.example'&, retaining the existing local part, you could use this |
168e428f | 16801 | setting: |
9b371988 PH |
16802 | .code |
16803 | data = ${quote_local_part:$local_part}@newdomain.example | |
16804 | .endd | |
168e428f PH |
16805 | |
16806 | ||
9b371988 PH |
16807 | .section "Redirecting to a local mailbox" "SECTredlocmai" |
16808 | .cindex "routing" "loops in" | |
16809 | .cindex "loop while routing" "avoidance of" | |
16810 | .cindex "address redirection" "to local mailbox" | |
168e428f PH |
16811 | A redirection item may safely be the same as the address currently under |
16812 | consideration. This does not cause a routing loop, because a router is | |
16813 | automatically skipped if any ancestor of the address that is being processed | |
16814 | is the same as the current address and was processed by the current router. | |
16815 | Such an address is therefore passed to the following routers, so it is handled | |
16816 | as if there were no redirection. When making this loop-avoidance test, the | |
16817 | complete local part, including any prefix or suffix, is used. | |
16818 | ||
9b371988 | 16819 | .cindex "address redirection" "local part without domain" |
168e428f PH |
16820 | Specifying the same local part without a domain is a common usage in personal |
16821 | filter files when the user wants to have messages delivered to the local | |
16822 | mailbox and also forwarded elsewhere. For example, the user whose login is | |
9b371988 PH |
16823 | &'cleo'& might have a &_.forward_& file containing this: |
16824 | .code | |
16825 | cleo, cleopatra@egypt.example | |
16826 | .endd | |
16827 | .cindex "backslash in alias file" | |
16828 | .cindex "alias file" "backslash in" | |
168e428f | 16829 | For compatibility with other MTAs, such unqualified local parts may be |
9b371988 | 16830 | preceeded by &"\"&, but this is not a requirement for loop prevention. However, |
168e428f PH |
16831 | it does make a difference if more than one domain is being handled |
16832 | synonymously. | |
16833 | ||
9b371988 PH |
16834 | If an item begins with &"\"& and the rest of the item parses as a valid RFC |
16835 | 2822 address that does not include a domain, the item is qualified using the | |
16836 | domain of the incoming address. In the absence of a leading &"\"&, unqualified | |
16837 | addresses are qualified using the value in &%qualify_recipient%&, but you can | |
16838 | force the incoming domain to be used by setting &%qualify_preserve_domain%&. | |
168e428f PH |
16839 | |
16840 | Care must be taken if there are alias names for local users. | |
16841 | Consider an MTA handling a single local domain where the system alias file | |
16842 | contains: | |
9b371988 PH |
16843 | .code |
16844 | Sam.Reman: spqr | |
16845 | .endd | |
16846 | Now suppose that Sam (whose login id is &'spqr'&) wants to save copies of | |
168e428f PH |
16847 | messages in the local mailbox, and also forward copies elsewhere. He creates |
16848 | this forward file: | |
9b371988 PH |
16849 | .code |
16850 | Sam.Reman, spqr@reme.elsewhere.example | |
16851 | .endd | |
16852 | With these settings, an incoming message addressed to &'Sam.Reman'& fails. The | |
16853 | &(redirect)& router for system aliases does not process &'Sam.Reman'& the | |
168e428f PH |
16854 | second time round, because it has previously routed it, |
16855 | and the following routers presumably cannot handle the alias. The forward file | |
16856 | should really contain | |
9b371988 PH |
16857 | .code |
16858 | spqr, spqr@reme.elsewhere.example | |
16859 | .endd | |
16860 | but because this is such a common error, the &%check_ancestor%& option (see | |
168e428f | 16861 | below) exists to provide a way to get round it. This is normally set on a |
9b371988 | 16862 | &(redirect)& router that is handling users' &_.forward_& files. |
168e428f PH |
16863 | |
16864 | ||
16865 | ||
9b371988 | 16866 | .section "Special items in redirection lists" "SECTspecitredli" |
168e428f PH |
16867 | In addition to addresses, the following types of item may appear in redirection |
16868 | lists (that is, in non-filter redirection data): | |
16869 | ||
9b371988 PH |
16870 | .ilist |
16871 | .cindex "pipe" "in redirection list" | |
16872 | .cindex "address redirection" "to pipe" | |
16873 | An item is treated as a pipe command if it begins with &"|"& and does not parse | |
168e428f | 16874 | as a valid RFC 2822 address that includes a domain. A transport for running the |
9b371988 | 16875 | command must be specified by the &%pipe_transport%& option. |
168e428f PH |
16876 | Normally, either the router or the transport specifies a user and a group under |
16877 | which to run the delivery. The default is to use the Exim user and group. | |
9b371988 | 16878 | |
168e428f PH |
16879 | Single or double quotes can be used for enclosing the individual arguments of |
16880 | the pipe command; no interpretation of escapes is done for single quotes. If | |
16881 | the command contains a comma character, it is necessary to put the whole item | |
16882 | in double quotes, for example: | |
9b371988 PH |
16883 | .code |
16884 | "|/some/command ready,steady,go" | |
16885 | .endd | |
168e428f PH |
16886 | since items in redirection lists are terminated by commas. Do not, however, |
16887 | quote just the command. An item such as | |
9b371988 PH |
16888 | .code |
16889 | |"/some/command ready,steady,go" | |
16890 | .endd | |
168e428f PH |
16891 | is interpreted as a pipe with a rather strange command name, and no arguments. |
16892 | ||
9b371988 PH |
16893 | .next |
16894 | .cindex "file" "in redirection list" | |
16895 | .cindex "address redirection" "to file" | |
16896 | An item is interpreted as a path name if it begins with &"/"& and does not | |
16897 | parse as a valid RFC 2822 address that includes a domain. For example, | |
16898 | .code | |
16899 | /home/world/minbari | |
16900 | .endd | |
168e428f | 16901 | is treated as a file name, but |
9b371988 PH |
16902 | .code |
16903 | /s=molari/o=babylon/@x400gate.way | |
16904 | .endd | |
168e428f | 16905 | is treated as an address. For a file name, a transport must be specified using |
9b371988 | 16906 | the &%file_transport%& option. However, if the generated path name ends with a |
168e428f | 16907 | forward slash character, it is interpreted as a directory name rather than a |
9b371988 PH |
16908 | file name, and &%directory_transport%& is used instead. |
16909 | ||
168e428f PH |
16910 | Normally, either the router or the transport specifies a user and a group under |
16911 | which to run the delivery. The default is to use the Exim user and group. | |
9b371988 PH |
16912 | |
16913 | .cindex "&_/dev/null_&" | |
16914 | However, if a redirection item is the path &_/dev/null_&, delivery to it is | |
16915 | bypassed at a high level, and the log entry shows &"**bypassed**"& | |
168e428f PH |
16916 | instead of a transport name. In this case the user and group are not used. |
16917 | ||
9b371988 PH |
16918 | .next |
16919 | .cindex "included address list" | |
16920 | .cindex "address redirection" "included external list" | |
168e428f | 16921 | If an item is of the form |
9b371988 PH |
16922 | .code |
16923 | :include:<path name> | |
16924 | .endd | |
168e428f | 16925 | a list of further items is taken from the given file and included at that |
9b371988 PH |
16926 | point. &*Note*&: Such a file can not be a filter file; it is just an |
16927 | out-of-line addition to the list. The items in the included list are separated | |
16928 | by commas or newlines and are not subject to expansion. If this is the first | |
16929 | item in an alias list in an &(lsearch)& file, a colon must be used to terminate | |
16930 | the alias name. This example is incorrect: | |
16931 | .code | |
16932 | list1 :include:/opt/lists/list1 | |
16933 | .endd | |
168e428f | 16934 | It must be given as |
9b371988 PH |
16935 | .code |
16936 | list1: :include:/opt/lists/list1 | |
16937 | .endd | |
16938 | .next | |
16939 | .cindex "address redirection" "to black hole" | |
168e428f | 16940 | Sometimes you want to throw away mail to a particular local part. Making the |
9b371988 PH |
16941 | &%data%& option expand to an empty string does not work, because that causes |
16942 | the router to decline. Instead, the alias item | |
16943 | .cindex "black hole" | |
16944 | .cindex "abandoning mail" | |
16945 | .code | |
16946 | :blackhole: | |
16947 | .endd | |
168e428f | 16948 | can be used. It does what its name implies. No delivery is done, and no error |
9b371988 | 16949 | message is generated. This has the same effect as specifing &_/dev/null_&, but |
168e428f | 16950 | can be independently disabled. |
9b371988 PH |
16951 | |
16952 | &*Warning*&: If &`:blackhole:`& appears anywhere in a redirection list, no | |
168e428f PH |
16953 | delivery is done for the original local part, even if other redirection items |
16954 | are present. If you are generating a multi-item list (for example, by reading a | |
16955 | database) and need the ability to provide a no-op item, you must use | |
9b371988 PH |
16956 | &_/dev/null_&. |
16957 | ||
16958 | .next | |
16959 | .cindex "delivery" "forcing failure" | |
16960 | .cindex "delivery" "forcing deferral" | |
16961 | .cindex "failing delivery" "forcing" | |
16962 | .cindex "deferred delivery" "forcing" | |
16963 | .cindex "customizing" "failure message" | |
168e428f PH |
16964 | An attempt to deliver a particular address can be deferred or forced to fail by |
16965 | redirection items of the form | |
9b371988 PH |
16966 | .code |
16967 | :defer: | |
16968 | :fail: | |
16969 | .endd | |
168e428f | 16970 | respectively. When a redirection list contains such an item, it applies to the |
9b371988 PH |
16971 | entire redirection; any other items in the list are ignored (&':blackhole:'& is |
16972 | different). Any text following &':fail:'& or &':defer:'& is placed in the error | |
168e428f | 16973 | text associated with the failure. For example, an alias file might contain: |
9b371988 PH |
16974 | .code |
16975 | X.Employee: :fail: Gone away, no forwarding address | |
16976 | .endd | |
168e428f PH |
16977 | In the case of an address that is being verified from an ACL or as the subject |
16978 | of a | |
9b371988 | 16979 | .cindex "VRFY error text" "display of" |
168e428f PH |
16980 | VRFY command, the text is included in the SMTP error response by |
16981 | default. | |
9b371988 | 16982 | .cindex "EXPN error text" "display of" |
168e428f | 16983 | The text is not included in the response to an EXPN command. |
9b371988 PH |
16984 | |
16985 | .cindex "&$acl_verify_message$&" | |
168e428f | 16986 | In an ACL, an explicitly provided message overrides the default, but the |
9b371988 | 16987 | default message is available in the variable &$acl_verify_message$& and can |
168e428f | 16988 | therefore be included in a custom message if this is desired. Exim sends a 451 |
9b371988 | 16989 | SMTP code for a &':defer:'&, and 550 for &':fail:'&. In non-SMTP cases the text |
168e428f | 16990 | is included in the error message that Exim generates. |
9b371988 PH |
16991 | |
16992 | Normally the error text is the rest of the redirection list &-- a comma does | |
16993 | not terminate it &-- but a newline does act as a terminator. Newlines are not | |
16994 | normally present in alias expansions. In &(lsearch)& lookups they are removed | |
16995 | as part of the continuation process, but they may exist in other kinds of | |
16996 | lookup and in &':include:'& files. | |
16997 | ||
168e428f | 16998 | During routing for message delivery (as opposed to verification), a redirection |
9b371988 PH |
16999 | containing &':fail:'& causes an immediate failure of the incoming address, |
17000 | whereas &':defer:'& causes the message to remain on the queue so that a | |
168e428f PH |
17001 | subsequent delivery attempt can happen at a later time. If an address is |
17002 | deferred for too long, it will ultimately fail, because the normal retry | |
17003 | rules still apply. | |
17004 | ||
9b371988 PH |
17005 | .next |
17006 | .cindex "alias file" "exception to default" | |
168e428f | 17007 | Sometimes it is useful to use a single-key search type with a default (see |
9b371988 PH |
17008 | chapter &<<CHAPfdlookup>>&) to look up aliases. However, there may be a need |
17009 | for exceptions to the default. These can be handled by aliasing them to | |
17010 | .code | |
17011 | :unknown: | |
17012 | .endd | |
17013 | This differs from &':fail:'& in that it causes the &(redirect)& router to | |
17014 | decline, whereas &':fail:'& forces routing to fail. A lookup which results in | |
17015 | an empty redirection list has the same effect. | |
17016 | .endlist | |
17017 | ||
17018 | ||
17019 | .section "Duplicate addresses" | |
17020 | .cindex "duplicate addresses" | |
17021 | .cindex "address duplicate" "discarding" | |
17022 | .cindex "pipe" "duplicated" | |
168e428f PH |
17023 | Exim removes duplicate addresses from the list to which it is delivering, so as |
17024 | to deliver just one copy to each address. This does not apply to deliveries | |
17025 | routed to pipes by different immediate parent addresses, but an indirect | |
17026 | aliasing scheme of the type | |
9b371988 PH |
17027 | .code |
17028 | pipe: |/some/command $local_part | |
17029 | localpart1: pipe | |
17030 | localpart2: pipe | |
17031 | .endd | |
168e428f | 17032 | does not work with a message that is addressed to both local parts, because |
9b371988 | 17033 | when the second is aliased to the intermediate local part &"pipe"& it gets |
168e428f PH |
17034 | discarded as being the same as a previously handled address. However, a scheme |
17035 | such as | |
9b371988 PH |
17036 | .code |
17037 | localpart1: |/some/command $local_part | |
17038 | localpart2: |/some/command $local_part | |
17039 | .endd | |
168e428f PH |
17040 | does result in two different pipe deliveries, because the immediate parents of |
17041 | the pipes are distinct. | |
17042 | ||
17043 | ||
17044 | ||
9b371988 PH |
17045 | .section "Repeated redirection expansion" |
17046 | .cindex "repeated redirection expansion" | |
17047 | .cindex "address redirection" "repeated for each delivery attempt" | |
168e428f PH |
17048 | When a message cannot be delivered to all of its recipients immediately, |
17049 | leading to two or more delivery attempts, redirection expansion is carried out | |
17050 | afresh each time for those addresses whose children were not all previously | |
17051 | delivered. If redirection is being used as a mailing list, this can lead to new | |
9b371988 | 17052 | members of the list receiving copies of old messages. The &%one_time%& option |
168e428f PH |
17053 | can be used to avoid this. |
17054 | ||
17055 | ||
9b371988 PH |
17056 | .section "Errors in redirection lists" |
17057 | .cindex "address redirection" "errors" | |
17058 | If &%skip_syntax_errors%& is set, a malformed address that causes a parsing | |
168e428f PH |
17059 | error is skipped, and an entry is written to the main log. This may be useful |
17060 | for mailing lists that are automatically managed. Otherwise, if an error is | |
17061 | detected while generating the list of new addresses, the original address is | |
9b371988 | 17062 | deferred. See also &%syntax_errors_to%&. |
168e428f | 17063 | |
168e428f | 17064 | |
168e428f | 17065 | |
9b371988 | 17066 | .section "Private options for the redirect router" |
168e428f | 17067 | |
9b371988 PH |
17068 | .cindex "options" "&(redirect)& router" |
17069 | The private options for the &(redirect)& router are as follows: | |
168e428f | 17070 | |
168e428f | 17071 | |
9b371988 PH |
17072 | .option allow_defer redirect boolean false |
17073 | Setting this option allows the use of &':defer:'& in non-filter redirection | |
17074 | data, or the &%defer%& command in an Exim filter file. | |
168e428f | 17075 | |
168e428f | 17076 | |
9b371988 PH |
17077 | .option allow_fail redirect boolean false |
17078 | .cindex "failing delivery" "from filter" | |
17079 | If this option is true, the &':fail:'& item can be used in a redirection list, | |
17080 | and the &%fail%& command may be used in an Exim filter file. | |
168e428f PH |
17081 | |
17082 | ||
9b371988 PH |
17083 | .option allow_filter redirect boolean false |
17084 | .cindex "filter" "enabling use of" | |
17085 | .cindex "Sieve filter" "enabling use of" | |
168e428f | 17086 | Setting this option allows Exim to interpret redirection data that starts with |
9b371988 | 17087 | &"#Exim filter"& or &"#Sieve filter"& as a set of filtering instructions. There |
168e428f | 17088 | are some features of Exim filter files that some administrators may wish to |
9b371988 | 17089 | lock out; see the &%forbid_filter_%&&'xxx'& options below. |
168e428f PH |
17090 | |
17091 | It is also possible to lock out Exim filters or Sieve filters while allowing | |
9b371988 | 17092 | the other type; see &%forbid_exim_filter%& and &%forbid_sieve_filter%&. |
168e428f | 17093 | |
168e428f | 17094 | |
9b371988 PH |
17095 | The filter is run using the uid and gid set by the generic &%user%& and |
17096 | &%group%& options. These take their defaults from the password data if | |
17097 | &%check_local_user%& is set, so in the normal case of users' personal filter | |
17098 | files, the filter is run as the relevant user. When &%allow_filter%& is set | |
17099 | true, Exim insists that either &%check_local_user%& or &%user%& is set. | |
168e428f PH |
17100 | |
17101 | ||
168e428f | 17102 | |
9b371988 PH |
17103 | .option allow_freeze redirect boolean false |
17104 | .cindex "freezing messages" "allowing in filter" | |
17105 | Setting this option allows the use of the &%freeze%& command in an Exim filter. | |
168e428f PH |
17106 | This command is more normally encountered in system filters, and is disabled by |
17107 | default for redirection filters because it isn't something you usually want to | |
17108 | let ordinary users do. | |
17109 | ||
17110 | ||
17111 | ||
9b371988 | 17112 | .option check_ancestor redirect boolean false |
168e428f PH |
17113 | This option is concerned with handling generated addresses that are the same |
17114 | as some address in the list of redirection ancestors of the current address. | |
17115 | Although it is turned off by default in the code, it is set in the default | |
9b371988 PH |
17116 | configuration file for handling users' &_.forward_& files. It is recommended |
17117 | for this use of the &(redirect)& router. | |
168e428f | 17118 | |
9b371988 PH |
17119 | When &%check_ancestor%& is set, if a generated address (including the domain) |
17120 | is the same as any ancestor of the current address, it is replaced by a copy of | |
168e428f | 17121 | the current address. This helps in the case where local part A is aliased to B, |
9b371988 PH |
17122 | and B has a &_.forward_& file pointing back to A. For example, within a single |
17123 | domain, the local part &"Joe.Bloggs"& is aliased to &"jb"& and | |
17124 | &_&~jb/.forward_& contains: | |
17125 | .code | |
17126 | \Joe.Bloggs, <other item(s)> | |
17127 | .endd | |
17128 | Without the &%check_ancestor%& setting, either local part (&"jb"& or | |
17129 | &"joe.bloggs"&) gets processed once by each router and so ends up as it was | |
17130 | originally. If &"jb"& is the real mailbox name, mail to &"jb"& gets delivered | |
17131 | (having been turned into &"joe.bloggs"& by the &_.forward_& file and back to | |
17132 | &"jb"& by the alias), but mail to &"joe.bloggs"& fails. Setting | |
17133 | &%check_ancestor%& on the &(redirect)& router that handles the &_.forward_& | |
17134 | file prevents it from turning &"jb"& back into &"joe.bloggs"& when that was the | |
17135 | original address. See also the &%repeat_use%& option below. | |
17136 | ||
17137 | ||
17138 | .option check_group redirect boolean "see below" | |
17139 | When the &%file%& option is used, the group owner of the file is checked only | |
168e428f | 17140 | when this option is set. The permitted groups are those listed in the |
9b371988 PH |
17141 | &%owngroups%& option, together with the user's default group if |
17142 | &%check_local_user%& is set. If the file has the wrong group, routing is | |
17143 | deferred. The default setting for this option is true if &%check_local_user%& | |
17144 | is set and the &%modemask%& option permits the group write bit, or if the | |
17145 | &%owngroups%& option is set. Otherwise it is false, and no group check occurs. | |
168e428f PH |
17146 | |
17147 | ||
168e428f | 17148 | |
9b371988 PH |
17149 | .option check_owner redirect boolean "see below" |
17150 | When the &%file%& option is used, the owner of the file is checked only when | |
17151 | this option is set. If &%check_local_user%& is set, the local user is | |
17152 | permitted; otherwise the owner must be one of those listed in the &%owners%& | |
17153 | option. The default value for this option is true if &%check_local_user%& or | |
17154 | &%owners%& is set. Otherwise the default is false, and no owner check occurs. | |
168e428f PH |
17155 | |
17156 | ||
9b371988 PH |
17157 | .option data redirect string&!! unset |
17158 | This option is mutually exclusive with &%file%&. One or other of them must be | |
17159 | set, but not both. The contents of &%data%& are expanded, and then used as the | |
168e428f PH |
17160 | list of forwarding items, or as a set of filtering instructions. If the |
17161 | expansion is forced to fail, or the result is an empty string or a string that | |
17162 | has no effect (consists entirely of comments), the router declines. | |
17163 | ||
9b371988 PH |
17164 | When filtering instructions are used, the string must begin with &"#Exim |
17165 | filter"&, and all comments in the string, including this initial one, must be | |
168e428f | 17166 | terminated with newline characters. For example: |
9b371988 | 17167 | .code |
168e428f PH |
17168 | data = #Exim filter\n\ |
17169 | if $h_to: contains Exim then save $home/mail/exim endif | |
9b371988 | 17170 | .endd |
168e428f | 17171 | If you are reading the data from a database where newlines cannot be included, |
9b371988 | 17172 | you can use the &${sg}$& expansion item to turn the escape string of your |
168e428f PH |
17173 | choice into a newline. |
17174 | ||
17175 | ||
9b371988 PH |
17176 | .option directory_transport redirect string&!! unset |
17177 | A &(redirect)& router sets up a direct delivery to a directory when a path name | |
17178 | ending with a slash is specified as a new &"address"&. The transport used is | |
168e428f | 17179 | specified by this option, which, after expansion, must be the name of a |
9b371988 | 17180 | configured transport. This should normally be an &(appendfile)& transport. |
168e428f PH |
17181 | |
17182 | ||
9b371988 | 17183 | .option file redirect string&!! unset |
168e428f | 17184 | This option specifies the name of a file that contains the redirection data. It |
9b371988 | 17185 | is mutually exclusive with the &%data%& option. The string is expanded before |
168e428f PH |
17186 | use; if the expansion is forced to fail, the router declines. Other expansion |
17187 | failures cause delivery to be deferred. The result of a successful expansion | |
17188 | must be an absolute path. The entire file is read and used as the redirection | |
17189 | data. If the data is an empty string or a string that has no effect (consists | |
17190 | entirely of comments), the router declines. | |
17191 | ||
9b371988 PH |
17192 | .cindex "NFS" "checking for file existence" |
17193 | If the attempt to open the file fails with a &"does not exist"& error, Exim | |
168e428f | 17194 | runs a check on the containing directory, |
9b371988 | 17195 | unless &%ignore_enotdir%& is true (see below). |
168e428f | 17196 | If the directory does not appear to exist, delivery is deferred. This can |
9b371988 | 17197 | happen when users' &_.forward_& files are in NFS-mounted directories, and there |
168e428f PH |
17198 | is a mount problem. If the containing directory does exist, but the file does |
17199 | not, the router declines. | |
17200 | ||
17201 | ||
9b371988 PH |
17202 | .option file_transport redirect string&!! unset |
17203 | .cindex "&$address_file$&" | |
17204 | A &(redirect)& router sets up a direct delivery to a file when a path name not | |
17205 | ending in a slash is specified as a new &"address"&. The transport used is | |
168e428f | 17206 | specified by this option, which, after expansion, must be the name of a |
9b371988 PH |
17207 | configured transport. This should normally be an &(appendfile)& transport. When |
17208 | it is running, the file name is in &$address_file$&. | |
168e428f PH |
17209 | |
17210 | ||
9b371988 PH |
17211 | .option forbid_blackhole redirect boolean false |
17212 | If this option is true, the &':blackhole:'& item may not appear in a | |
17213 | redirection list. | |
168e428f PH |
17214 | |
17215 | ||
9b371988 | 17216 | .option forbid_exim_filter redirect boolean false |
168e428f | 17217 | If this option is set true, only Sieve filters are permitted when |
9b371988 | 17218 | &%allow_filter%& is true. |
168e428f PH |
17219 | |
17220 | ||
17221 | ||
168e428f | 17222 | |
9b371988 PH |
17223 | .option forbid_file redirect boolean false |
17224 | .cindex "delivery" "to file; forbidding" | |
17225 | .cindex "Sieve filter" "forbidding delivery to a file" | |
17226 | .cindex "Sieve filter" "&""keep""& facility; disabling" | |
168e428f PH |
17227 | If this option is true, this router may not generate a new address that |
17228 | specifies delivery to a local file or directory, either from a filter or from a | |
9b371988 | 17229 | conventional forward file. This option is forced to be true if &%one_time%& is |
168e428f | 17230 | set. It applies to Sieve filters as well as to Exim filters, but if true, it |
9b371988 | 17231 | locks out the Sieve's &"keep"& facility. |
168e428f PH |
17232 | |
17233 | ||
9b371988 PH |
17234 | .new |
17235 | .option forbid_filter_dlfunc redirect boolean false | |
17236 | .cindex "filter" "locking out certain features" | |
068aaea8 | 17237 | If this option is true, string expansions in Exim filters are not allowed to |
9b371988 | 17238 | make use of the &%dlfunc%& expansion facility to run dynamically loaded |
068aaea8 | 17239 | functions. |
9b371988 | 17240 | .wen |
068aaea8 | 17241 | |
9b371988 PH |
17242 | .option forbid_filter_existstest redirect boolean false |
17243 | .new | |
17244 | .cindex "expansion" "statting a file" | |
168e428f | 17245 | If this option is true, string expansions in Exim filters are not allowed to |
9b371988 PH |
17246 | make use of the &%exists%& condition or the &%stat%& expansion item. |
17247 | .wen | |
168e428f | 17248 | |
9b371988 | 17249 | .option forbid_filter_logwrite redirect boolean false |
168e428f PH |
17250 | If this option is true, use of the logging facility in Exim filters is not |
17251 | permitted. Logging is in any case available only if the filter is being run | |
17252 | under some unprivileged uid (which is normally the case for ordinary users' | |
9b371988 | 17253 | &_.forward_& files). |
168e428f | 17254 | |
168e428f | 17255 | |
9b371988 | 17256 | .option forbid_filter_lookup redirect boolean false |
168e428f | 17257 | If this option is true, string expansions in Exim filter files are not allowed |
9b371988 | 17258 | to make use of &%lookup%& items. |
168e428f PH |
17259 | |
17260 | ||
9b371988 | 17261 | .option forbid_filter_perl redirect boolean false |
068aaea8 | 17262 | This option has an effect only if Exim is built with embedded Perl support. If |
168e428f PH |
17263 | it is true, string expansions in Exim filter files are not allowed to make use |
17264 | of the embedded Perl support. | |
17265 | ||
17266 | ||
9b371988 | 17267 | .option forbid_filter_readfile redirect boolean false |
168e428f | 17268 | If this option is true, string expansions in Exim filter files are not allowed |
9b371988 | 17269 | to make use of &%readfile%& items. |
168e428f PH |
17270 | |
17271 | ||
9b371988 | 17272 | .option forbid_filter_readsocket redirect boolean false |
168e428f | 17273 | If this option is true, string expansions in Exim filter files are not allowed |
9b371988 | 17274 | to make use of &%readsocket%& items. |
168e428f | 17275 | |
168e428f | 17276 | |
9b371988 | 17277 | .option forbid_filter_reply redirect boolean false |
168e428f | 17278 | If this option is true, this router may not generate an automatic reply |
9b371988 PH |
17279 | message. Automatic replies can be generated only from Exim or Sieve filter |
17280 | files, not from traditional forward files. This option is forced to be true if | |
17281 | &%one_time%& is set. | |
168e428f PH |
17282 | |
17283 | ||
9b371988 | 17284 | .option forbid_filter_run redirect boolean false |
168e428f | 17285 | If this option is true, string expansions in Exim filter files are not allowed |
9b371988 | 17286 | to make use of &%run%& items. |
168e428f | 17287 | |
168e428f | 17288 | |
9b371988 | 17289 | .option forbid_include redirect boolean false |
168e428f | 17290 | If this option is true, items of the form |
9b371988 PH |
17291 | .code |
17292 | :include:<path name> | |
17293 | .endd | |
168e428f PH |
17294 | are not permitted in non-filter redirection lists. |
17295 | ||
17296 | ||
9b371988 PH |
17297 | .option forbid_pipe redirect boolean false |
17298 | .cindex "delivery" "to pipe; forbidding" | |
168e428f PH |
17299 | If this option is true, this router may not generate a new address which |
17300 | specifies delivery to a pipe, either from an Exim filter or from a conventional | |
9b371988 | 17301 | forward file. This option is forced to be true if &%one_time%& is set. |
168e428f | 17302 | |
168e428f | 17303 | |
9b371988 | 17304 | .option forbid_sieve_filter redirect boolean false |
168e428f | 17305 | If this option is set true, only Exim filters are permitted when |
9b371988 | 17306 | &%allow_filter%& is true. |
168e428f PH |
17307 | |
17308 | ||
17309 | ||
17310 | ||
9b371988 PH |
17311 | .option hide_child_in_errmsg redirect boolean false |
17312 | .cindex "bounce message" "redirection details; suppressing" | |
168e428f | 17313 | If this option is true, it prevents Exim from quoting a child address if it |
9b371988 PH |
17314 | generates a bounce or delay message for it. Instead it says &"an address |
17315 | generated from <&'the top level address'&>"&. Of course, this applies only to | |
17316 | bounces generated locally. If a message is forwarded to another host, &'its'& | |
168e428f PH |
17317 | bounce may well quote the generated address. |
17318 | ||
17319 | ||
9b371988 PH |
17320 | .option ignore_eacces redirect boolean false |
17321 | .cindex "EACCES" | |
168e428f | 17322 | If this option is set and an attempt to open a redirection file yields the |
9b371988 | 17323 | EACCES error (permission denied), the &(redirect)& router behaves as if the |
168e428f PH |
17324 | file did not exist. |
17325 | ||
17326 | ||
9b371988 PH |
17327 | .option ignore_enotdir redirect boolean false |
17328 | .cindex "ENOTDIR" | |
168e428f | 17329 | If this option is set and an attempt to open a redirection file yields the |
9b371988 | 17330 | ENOTDIR error (something on the path is not a directory), the &(redirect)& |
168e428f PH |
17331 | router behaves as if the file did not exist. |
17332 | ||
9b371988 PH |
17333 | Setting &%ignore_enotdir%& has another effect as well: When a &(redirect)& |
17334 | router that has the &%file%& option set discovers that the file does not exist | |
17335 | (the ENOENT error), it tries to &[stat()]& the parent directory, as a check | |
168e428f | 17336 | against unmounted NFS directories. If the parent can not be statted, delivery |
9b371988 PH |
17337 | is deferred. However, it seems wrong to do this check when &%ignore_enotdir%& |
17338 | is set, because that option tells Exim to ignore &"something on the path is not | |
17339 | a directory"& (the ENOTDIR error). This is a confusing area, because it seems | |
168e428f PH |
17340 | that some operating systems give ENOENT where others give ENOTDIR. |
17341 | ||
17342 | ||
17343 | ||
9b371988 PH |
17344 | .option include_directory redirect string unset |
17345 | If this option is set, the path names of any &':include:'& items in a | |
17346 | redirection list must start with this directory. | |
168e428f PH |
17347 | |
17348 | ||
9b371988 | 17349 | .option modemask redirect "octal integer" 022 |
168e428f | 17350 | This specifies mode bits which must not be set for a file specified by the |
9b371988 | 17351 | &%file%& option. If any of the forbidden bits are set, delivery is deferred. |
168e428f | 17352 | |
168e428f | 17353 | |
9b371988 PH |
17354 | .option one_time redirect boolean false |
17355 | .cindex "one-time aliasing/forwarding expansion" | |
17356 | .cindex "alias file" "one-time expansion" | |
17357 | .cindex "forward file" "one-time expansion" | |
17358 | .cindex "mailing lists" "one-time expansion" | |
17359 | .cindex "address redirection" "one-time expansion" | |
168e428f | 17360 | Sometimes the fact that Exim re-evaluates aliases and reprocesses redirection |
068aaea8 PH |
17361 | files each time it tries to deliver a message causes a problem when one or more |
17362 | of the generated addresses fails be delivered at the first attempt. The problem | |
9b371988 PH |
17363 | is not one of duplicate delivery &-- Exim is clever enough to handle that &-- |
17364 | but of what happens when the redirection list changes during the time that the | |
068aaea8 PH |
17365 | message is on Exim's queue. This is particularly true in the case of mailing |
17366 | lists, where new subscribers might receive copies of messages that were posted | |
17367 | before they subscribed. | |
17368 | ||
9b371988 PH |
17369 | If &%one_time%& is set and any addresses generated by the router fail to |
17370 | deliver at the first attempt, the failing addresses are added to the message as | |
17371 | &"top level"& addresses, and the parent address that generated them is marked | |
17372 | &"delivered"&. Thus, redirection does not happen again at the next delivery | |
068aaea8 | 17373 | attempt. |
168e428f | 17374 | |
9b371988 | 17375 | &*Warning 1*&: Any header line addition or removal that is specified by this |
068aaea8 | 17376 | router would be lost if delivery did not succeed at the first attempt. For this |
9b371988 PH |
17377 | reason, the &%headers_add%& and &%headers_remove%& generic options are not |
17378 | permitted when &%one_time%& is set. | |
168e428f | 17379 | |
9b371988 PH |
17380 | &*Warning 2*&: To ensure that the router generates only addresses (as opposed |
17381 | to pipe or file deliveries or auto-replies) &%forbid_file%&, &%forbid_pipe%&, | |
17382 | and &%forbid_filter_reply%& are forced to be true when &%one_time%& is set. | |
168e428f | 17383 | |
9b371988 PH |
17384 | .new |
17385 | &*Warning 3*&: The &%unseen%& generic router option may not be set with | |
17386 | &%one_time%&. | |
17387 | .wen | |
068aaea8 | 17388 | |
168e428f PH |
17389 | The original top-level address is remembered with each of the generated |
17390 | addresses, and is output in any log messages. However, any intermediate parent | |
17391 | addresses are not recorded. This makes a difference to the log only if | |
9b371988 | 17392 | &%all_parents%& log selector is set. It is expected that &%one_time%& will |
168e428f PH |
17393 | typically be used for mailing lists, where there is normally just one level of |
17394 | expansion. | |
17395 | ||
17396 | ||
9b371988 PH |
17397 | .option owners redirect "string list" unset |
17398 | .cindex "ownership" "alias file" | |
17399 | .cindex "ownership" "forward file" | |
17400 | .cindex "alias file" "ownership" | |
17401 | .cindex "forward file" "ownership" | |
17402 | This specifies a list of permitted owners for the file specified by &%file%&. | |
17403 | This list is in addition to the local user when &%check_local_user%& is set. | |
17404 | See &%check_owner%& above. | |
168e428f PH |
17405 | |
17406 | ||
9b371988 PH |
17407 | .option owngroups redirect "string list" unset |
17408 | This specifies a list of permitted groups for the file specified by &%file%&. | |
17409 | The list is in addition to the local user's primary group when | |
17410 | &%check_local_user%& is set. See &%check_group%& above. | |
168e428f | 17411 | |
168e428f | 17412 | |
9b371988 PH |
17413 | .option pipe_transport redirect string&!! unset |
17414 | .cindex "&$address_pipe$&" | |
17415 | A &(redirect)& router sets up a direct delivery to a pipe when a string | |
17416 | starting with a vertical bar character is specified as a new &"address"&. The | |
17417 | transport used is specified by this option, which, after expansion, must be the | |
17418 | name of a configured transport. This should normally be a &(pipe)& transport. | |
17419 | When the transport is run, the pipe command is in &$address_pipe$&. | |
168e428f | 17420 | |
168e428f | 17421 | |
9b371988 PH |
17422 | .option qualify_domain redirect string&!! unset |
17423 | .cindex "&$qualify_recipient$&" | |
168e428f PH |
17424 | If this option is set and an unqualified address (one without a domain) is |
17425 | generated, it is qualified with the domain specified by expanding this string, | |
9b371988 | 17426 | instead of the global setting in &%qualify_recipient%&. If the expansion fails, |
168e428f | 17427 | the router declines. If you want to revert to the default, you can have the |
9b371988 | 17428 | expansion generate &$qualify_recipient$&. |
168e428f PH |
17429 | |
17430 | ||
9b371988 PH |
17431 | .option qualify_preserve_domain redirect boolean false |
17432 | .cindex "domain" "in redirection; preserving" | |
17433 | .cindex "preserving domain in redirection" | |
17434 | .cindex "address redirection" "domain; preserving" | |
168e428f PH |
17435 | If this is set and an unqualified address (one without a domain) is generated, |
17436 | it is qualified with the domain of the | |
17437 | parent address (the immediately preceding ancestor) instead of the local | |
9b371988 | 17438 | &%qualify_domain%& or global &%qualify_recipient%& value. |
168e428f | 17439 | |
168e428f | 17440 | |
9b371988 | 17441 | .option repeat_use redirect boolean true |
168e428f PH |
17442 | If this option is set false, the router is skipped for a child address that has |
17443 | any ancestor that was routed by this router. This test happens before any of | |
17444 | the other preconditions are tested. Exim's default anti-looping rules skip | |
17445 | only when the ancestor is the same as the current address. See also | |
9b371988 | 17446 | &%check_ancestor%& above and the generic &%redirect_router%& option. |
168e428f | 17447 | |
168e428f | 17448 | |
9b371988 PH |
17449 | .option reply_transport redirect string&!! unset |
17450 | A &(redirect)& router sets up an automatic reply when a &%mail%& or | |
17451 | &%vacation%& command is used in a filter file. The transport used is specified | |
17452 | by this option, which, after expansion, must be the name of a configured | |
17453 | transport. This should normally be an &(autoreply)& transport. Other transports | |
17454 | are unlikely to do anything sensible or useful. | |
168e428f | 17455 | |
168e428f | 17456 | |
9b371988 PH |
17457 | .option rewrite redirect boolean true |
17458 | .cindex "address redirection" "disabling rewriting" | |
168e428f PH |
17459 | If this option is set false, addresses generated by the router are not |
17460 | subject to address rewriting. Otherwise, they are treated like new addresses | |
17461 | and are rewritten according to the global rewriting rules. | |
17462 | ||
17463 | ||
9b371988 PH |
17464 | .new |
17465 | .option sieve_subaddress redirect string&!! unset | |
068aaea8 PH |
17466 | The value of this option is passed to a Sieve filter to specify the |
17467 | :subaddress part of an address. | |
17468 | ||
9b371988 | 17469 | .option sieve_useraddress redirect string&!! unset |
068aaea8 PH |
17470 | The value of this option is passed to a Sieve filter to specify the :user part |
17471 | of an address. However, if it is unset, the entire original local part | |
17472 | (including any prefix or suffix) is used for :user. | |
9b371988 | 17473 | .wen |
068aaea8 PH |
17474 | |
17475 | ||
9b371988 PH |
17476 | .option sieve_vacation_directory redirect string&!! unset |
17477 | .new | |
17478 | .cindex "Sieve filter" "vacation directory" | |
17479 | To enable the &"vacation"& extension for Sieve filters, you must set | |
17480 | &%sieve_vacation_directory%& to the directory where vacation databases are held | |
168e428f | 17481 | (do not put anything else in that directory), and ensure that the |
9b371988 PH |
17482 | &%reply_transport%& option refers to an &(autoreply)& transport. Each user |
17483 | needs their own directory; Exim will create it if necessary. | |
17484 | .wen | |
168e428f PH |
17485 | |
17486 | ||
17487 | ||
9b371988 PH |
17488 | .option skip_syntax_errors redirect boolean false |
17489 | .cindex "forward file" "broken" | |
17490 | .cindex "address redirection" "broken files" | |
17491 | .cindex "alias file" "broken" | |
17492 | .cindex "broken alias or forward files" | |
17493 | .cindex "ignoring faulty addresses" | |
17494 | .cindex "skipping faulty addresses" | |
17495 | .cindex "error" "skipping bad syntax" | |
17496 | If &%skip_syntax_errors%& is set, syntactically malformed addresses in | |
168e428f | 17497 | non-filter redirection data are skipped, and each failing address is logged. If |
9b371988 PH |
17498 | &%syntax_errors_to%& is set, a message is sent to the address it defines, |
17499 | giving details of the failures. If &%syntax_errors_text%& is set, its contents | |
168e428f | 17500 | are expanded and placed at the head of the error message generated by |
9b371988 PH |
17501 | &%syntax_errors_to%&. Usually it is appropriate to set &%syntax_errors_to%& to |
17502 | be the same address as the generic &%errors_to%& option. The | |
17503 | &%skip_syntax_errors%& option is often used when handling mailing lists. | |
168e428f PH |
17504 | |
17505 | If all the addresses in a redirection list are skipped because of syntax | |
17506 | errors, the router declines to handle the original address, and it is passed to | |
17507 | the following routers. | |
17508 | ||
9b371988 | 17509 | If &%skip_syntax_errors%& is set when an Exim filter is interpreted, any syntax |
168e428f PH |
17510 | error in the filter causes filtering to be abandoned without any action being |
17511 | taken. The incident is logged, and the router declines to handle the address, | |
17512 | so it is passed to the following routers. | |
17513 | ||
9b371988 PH |
17514 | .cindex "Sieve filter" "syntax errors in" |
17515 | Syntax errors in a Sieve filter file cause the &"keep"& action to occur. This | |
17516 | action is specified by RFC 3028. The values of &%skip_syntax_errors%&, | |
17517 | &%syntax_errors_to%&, and &%syntax_errors_text%& are not used. | |
168e428f | 17518 | |
9b371988 PH |
17519 | &%skip_syntax_errors%& can be used to specify that errors in users' forward |
17520 | lists or filter files should not prevent delivery. The &%syntax_errors_to%& | |
168e428f PH |
17521 | option, used with an address that does not get redirected, can be used to |
17522 | notify users of these errors, by means of a router like this: | |
9b371988 | 17523 | .code |
168e428f PH |
17524 | userforward: |
17525 | driver = redirect | |
17526 | allow_filter | |
17527 | check_local_user | |
17528 | file = $home/.forward | |
17529 | file_transport = address_file | |
17530 | pipe_transport = address_pipe | |
17531 | reply_transport = address_reply | |
17532 | no_verify | |
17533 | skip_syntax_errors | |
9b371988 | 17534 | syntax_errors_to = real-$local_part@$domain |
168e428f | 17535 | syntax_errors_text = \ |
9b371988 PH |
17536 | This is an automatically generated message. An error has\n\ |
17537 | been found in your .forward file. Details of the error are\n\ | |
17538 | reported below. While this error persists, you will receive\n\ | |
17539 | a copy of this message for every message that is addressed\n\ | |
17540 | to you. If your .forward file is a filter file, or if it is\n\ | |
17541 | a non-filter file containing no valid forwarding addresses,\n\ | |
17542 | a copy of each incoming message will be put in your normal\n\ | |
17543 | mailbox. If a non-filter file contains at least one valid\n\ | |
17544 | forwarding address, forwarding to the valid addresses will\n\ | |
17545 | happen, and those will be the only deliveries that occur. | |
17546 | .endd | |
168e428f | 17547 | You also need a router to ensure that local addresses that are prefixed by |
9b371988 PH |
17548 | &`real-`& are recognized, but not forwarded or filtered. For example, you could |
17549 | put this immediately before the &(userforward)& router: | |
17550 | .code | |
17551 | real_localuser: | |
17552 | driver = accept | |
17553 | check_local_user | |
17554 | local_part_prefix = real- | |
17555 | transport = local_delivery | |
17556 | .endd | |
168e428f | 17557 | |
9b371988 PH |
17558 | .option syntax_errors_text redirect string&!! unset |
17559 | See &%skip_syntax_errors%& above. | |
168e428f | 17560 | |
168e428f | 17561 | |
9b371988 PH |
17562 | .option syntax_errors_to redirect string unset |
17563 | See &%skip_syntax_errors%& above. | |
168e428f PH |
17564 | |
17565 | ||
17566 | ||
17567 | ||
17568 | ||
17569 | ||
9b371988 PH |
17570 | . //////////////////////////////////////////////////////////////////////////// |
17571 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 17572 | |
9b371988 PH |
17573 | .chapter "Environment for running local transports" "CHAPenvironment" &&& |
17574 | "Environment for local transports" | |
17575 | .cindex "local transports" "environment for" | |
17576 | .cindex "environment for local transports" | |
17577 | .cindex "transport" "local; environment for" | |
17578 | Local transports handle deliveries to files and pipes. (The &(autoreply)& | |
168e428f PH |
17579 | transport can be thought of as similar to a pipe.) Exim always runs transports |
17580 | in subprocesses, under specified uids and gids. Typical deliveries to local | |
17581 | mailboxes run under the uid and gid of the local user. | |
17582 | ||
17583 | Exim also sets a specific current directory while running the transport; for | |
9b371988 | 17584 | some transports a home directory setting is also relevant. The &(pipe)& |
168e428f | 17585 | transport is the only one that sets up environment variables; see section |
9b371988 | 17586 | &<<SECTpipeenv>>& for details. |
168e428f PH |
17587 | |
17588 | The values used for the uid, gid, and the directories may come from several | |
17589 | different places. In many cases, the router that handles the address associates | |
9b371988 PH |
17590 | settings with that address as a result of its &%check_local_user%&, &%group%&, |
17591 | or &%user%& options. However, values may also be given in the transport's own | |
168e428f PH |
17592 | configuration, and these override anything that comes from the router. |
17593 | ||
17594 | ||
17595 | ||
9b371988 PH |
17596 | .section "Concurrent deliveries" |
17597 | .cindex "concurrent deliveries" | |
17598 | .cindex "simultaneous deliveries" | |
168e428f PH |
17599 | If two different messages for the same local recpient arrive more or less |
17600 | simultaneously, the two delivery processes are likely to run concurrently. When | |
9b371988 | 17601 | the &(appendfile)& transport is used to write to a file, Exim applies locking |
168e428f PH |
17602 | rules to stop concurrent processes from writing to the same file at the same |
17603 | time. | |
17604 | ||
9b371988 | 17605 | However, when you use a &(pipe)& transport, it is up to you to arrange any |
168e428f | 17606 | locking that is needed. Here is a silly example: |
9b371988 PH |
17607 | .code |
17608 | my_transport: | |
17609 | driver = pipe | |
17610 | command = /bin/sh -c 'cat >>/some/file' | |
17611 | .endd | |
168e428f PH |
17612 | This is supposed to write the message at the end of the file. However, if two |
17613 | messages arrive at the same time, the file will be scrambled. You can use the | |
9b371988 PH |
17614 | &%exim_lock%& utility program (see section &<<SECTmailboxmaint>>&) to lock a |
17615 | file using the same algorithm that Exim itself uses. | |
168e428f PH |
17616 | |
17617 | ||
17618 | ||
17619 | ||
9b371988 PH |
17620 | .section "Uids and gids" "SECTenvuidgid" |
17621 | .cindex "local transports" "uid and gid" | |
17622 | .cindex "transport" "local; uid and gid" | |
17623 | All transports have the options &%group%& and &%user%&. If &%group%& is set, it | |
17624 | overrides any group that the router set in the address, even if &%user%& is not | |
168e428f PH |
17625 | set for the transport. This makes it possible, for example, to run local mail |
17626 | delivery under the uid of the recipient (set by the router), but in a special | |
17627 | group (set by the transport). For example: | |
9b371988 PH |
17628 | .code |
17629 | # Routers ... | |
17630 | # User/group are set by check_local_user in this router | |
17631 | local_users: | |
17632 | driver = accept | |
17633 | check_local_user | |
17634 | transport = group_delivery | |
168e428f | 17635 | |
9b371988 PH |
17636 | # Transports ... |
17637 | # This transport overrides the group | |
17638 | group_delivery: | |
17639 | driver = appendfile | |
17640 | file = /var/spool/mail/$local_part | |
17641 | group = mail | |
17642 | .endd | |
17643 | If &%user%& is set for a transport, its value overrides what is set in the | |
17644 | address by the router. If &%user%& is non-numeric and &%group%& is not set, the | |
17645 | gid associated with the user is used. If &%user%& is numeric, &%group%& must be | |
17646 | set. | |
168e428f | 17647 | |
9b371988 PH |
17648 | .cindex "&%initgroups%& option" |
17649 | When the uid is taken from the transport's configuration, the &[initgroups()]& | |
17650 | function is called for the groups associated with that uid if the | |
17651 | &%initgroups%& option is set for the transport. When the uid is not specified | |
17652 | by the transport, but is associated with the address by a router, the option | |
17653 | for calling &[initgroups()]& is taken from the router configuration. | |
17654 | ||
17655 | .cindex "&(pipe)& transport" "uid for" | |
17656 | The &(pipe)& transport contains the special option &%pipe_as_creator%&. If this | |
17657 | is set and &%user%& is not set, the uid of the process that called Exim to | |
17658 | receive the message is used, and if &%group%& is not set, the corresponding | |
17659 | original gid is also used. | |
168e428f | 17660 | |
9b371988 PH |
17661 | .new |
17662 | This is the detailed preference order for obtaining a gid; the first of the | |
17663 | following that is set is used: | |
17664 | ||
17665 | .ilist | |
17666 | A &%group%& setting of the transport; | |
17667 | .next | |
17668 | A &%group%& setting of the router; | |
17669 | .next | |
17670 | A gid associated with a user setting of the router, either as a result of | |
17671 | &%check_local_user%& or an explicit non-numeric &%user%& setting; | |
17672 | .next | |
17673 | The group associated with a non-numeric &%user%& setting of the transport; | |
17674 | .next | |
17675 | In a &(pipe)& transport, the creator's gid if &%deliver_as_creator%& is set and | |
17676 | the uid is the creator's uid; | |
17677 | .next | |
17678 | The Exim gid if the Exim uid is being used as a default. | |
17679 | .endlist | |
17680 | ||
17681 | If, for example, the user is specified numerically on the router and there are | |
17682 | no group settings, no gid is available. In this situation, an error occurs. | |
17683 | This is different for the uid, for which there always is an ultimate default. | |
17684 | The first of the following that is set is used: | |
17685 | ||
17686 | .ilist | |
17687 | A &%user%& setting of the transport; | |
17688 | .next | |
17689 | In a &(pipe)& transport, the creator's uid if &%deliver_as_creator%& is set; | |
17690 | .next | |
17691 | A &%user%& setting of the router; | |
17692 | .next | |
17693 | A &%check_local_user%& setting of the router; | |
17694 | .next | |
17695 | The Exim uid. | |
17696 | .endlist | |
17697 | ||
17698 | Of course, an error will still occur if the uid that is chosen is on the | |
17699 | &%never_users%& list. | |
17700 | .wen | |
17701 | ||
17702 | ||
17703 | ||
17704 | ||
17705 | ||
17706 | .section "Current and home directories" | |
17707 | .cindex "current directory for local transport" | |
17708 | .cindex "home directory" "for local transport" | |
17709 | .cindex "transport" "local; home directory for" | |
17710 | .cindex "transport" "local; current directory for" | |
168e428f | 17711 | Routers may set current and home directories for local transports by means of |
9b371988 PH |
17712 | the &%transport_current_directory%& and &%transport_home_directory%& options. |
17713 | However, if the transport's &%current_directory%& or &%home_directory%& options | |
168e428f PH |
17714 | are set, they override the router's values. In detail, the home directory |
17715 | for a local transport is taken from the first of these values that is set: | |
17716 | ||
9b371988 PH |
17717 | .ilist |
17718 | The &%home_directory%& option on the transport; | |
17719 | .next | |
17720 | The &%transport_home_directory%& option on the router; | |
17721 | .next | |
17722 | The password data if &%check_local_user%& is set on the router; | |
17723 | .next | |
17724 | The &%router_home_directory%& option on the router. | |
17725 | .endlist | |
168e428f PH |
17726 | |
17727 | The current directory is taken from the first of these values that is set: | |
17728 | ||
9b371988 PH |
17729 | .ilist |
17730 | The &%current_directory%& option on the transport; | |
17731 | .next | |
17732 | The &%transport_current_directory%& option on the router. | |
17733 | .endlist | |
168e428f PH |
17734 | |
17735 | ||
17736 | If neither the router nor the transport sets a current directory, Exim uses the | |
17737 | value of the home directory, if it is set. Otherwise it sets the current | |
9b371988 | 17738 | directory to &_/_& before running a local transport. |
168e428f PH |
17739 | |
17740 | ||
17741 | ||
9b371988 PH |
17742 | .section "Expansion variables derived from the address" |
17743 | .cindex "&$domain$&" | |
17744 | .cindex "&$local_part$&" | |
17745 | .cindex "&$original_domain$&" | |
168e428f | 17746 | Normally a local delivery is handling a single address, and in that case the |
9b371988 PH |
17747 | variables such as &$domain$& and &$local_part$& are set during local |
17748 | deliveries. However, in some circumstances more than one address may be handled | |
17749 | at once (for example, while writing batch SMTP for onward transmission by some | |
17750 | other means). In this case, the variables associated with the local part are | |
17751 | never set, &$domain$& is set only if all the addresses have the same domain, | |
17752 | and &$original_domain$& is never set. | |
168e428f PH |
17753 | |
17754 | ||
17755 | ||
17756 | ||
17757 | ||
17758 | ||
17759 | ||
9b371988 PH |
17760 | . //////////////////////////////////////////////////////////////////////////// |
17761 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 17762 | |
9b371988 | 17763 | .chapter "Generic options for transports" "CHAPtransportgeneric" |
168e428f | 17764 | |
9b371988 PH |
17765 | .cindex "generic options" "transport" |
17766 | .cindex "options" "generic; for transports" | |
17767 | .cindex "transport" "generic options for" | |
168e428f PH |
17768 | The following generic options apply to all transports: |
17769 | ||
17770 | ||
9b371988 PH |
17771 | .option body_only transports boolean false |
17772 | .cindex "transport" "body only" | |
17773 | .cindex "message" "transporting body only" | |
17774 | .cindex "body of message" "transporting" | |
168e428f | 17775 | If this option is set, the message's headers are not transported. It is |
9b371988 PH |
17776 | mutually exclusive with &%headers_only%&. If it is used with the &(appendfile)& |
17777 | or &(pipe)& transports, the settings of &%message_prefix%& and | |
17778 | &%message_suffix%& should be checked, because this option does not | |
17779 | automatically suppress them. | |
168e428f PH |
17780 | |
17781 | ||
9b371988 PH |
17782 | .option current_directory transports string&!! unset |
17783 | .cindex "transport" "current directory for" | |
168e428f PH |
17784 | This specifies the current directory that is to be set while running the |
17785 | transport, overriding any value that may have been set by the router. | |
17786 | If the expansion fails for any reason, including forced failure, an error is | |
17787 | logged, and delivery is deferred. | |
17788 | ||
17789 | ||
9b371988 | 17790 | .option disable_logging transports boolean false |
168e428f PH |
17791 | If this option is set true, nothing is logged for any |
17792 | deliveries by the transport or for any | |
17793 | transport errors. You should not set this option unless you really, really know | |
17794 | what you are doing. | |
17795 | ||
17796 | ||
9b371988 PH |
17797 | .option debug_print transports string&!! unset |
17798 | .cindex "testing" "variables in drivers" | |
17799 | If this option is set and debugging is enabled (see the &%-d%& command line | |
168e428f PH |
17800 | option), the string is expanded and included in the debugging output when the |
17801 | transport is run. | |
17802 | If expansion of the string fails, the error message is written to the debugging | |
17803 | output, and Exim carries on processing. | |
17804 | This facility is provided to help with checking out the values of variables and | |
9b371988 PH |
17805 | so on when debugging driver configurations. For example, if a &%headers_add%& |
17806 | option is not working properly, &%debug_print%& could be used to output the | |
168e428f PH |
17807 | variables it references. A newline is added to the text if it does not end with |
17808 | one. | |
17809 | ||
17810 | ||
9b371988 PH |
17811 | .option delivery_date_add transports boolean false |
17812 | .cindex "&'Delivery-date:'& header line" | |
17813 | If this option is true, a &'Delivery-date:'& header is added to the message. | |
17814 | This gives the actual time the delivery was made. As this is not a standard | |
17815 | header, Exim has a configuration option (&%delivery_date_remove%&) which | |
17816 | requests its removal from incoming messages, so that delivered messages can | |
17817 | safely be resent to other recipients. | |
168e428f PH |
17818 | |
17819 | ||
9b371988 | 17820 | .option driver transports string unset |
168e428f PH |
17821 | This specifies which of the available transport drivers is to be used. |
17822 | There is no default, and this option must be set for every transport. | |
17823 | ||
17824 | ||
9b371988 PH |
17825 | .option envelope_to_add transports boolean false |
17826 | .cindex "&'Envelope-to:'& header line" | |
17827 | If this option is true, an &'Envelope-to:'& header is added to the message. | |
17828 | This gives the original address(es) in the incoming envelope that caused this | |
168e428f PH |
17829 | delivery to happen. More than one address may be present if the transport is |
17830 | configured to handle several addresses at once, or if more than one original | |
17831 | address was redirected to the same final address. As this is not a standard | |
9b371988 | 17832 | header, Exim has a configuration option (&%envelope_to_remove%&) which requests |
168e428f PH |
17833 | its removal from incoming messages, so that delivered messages can safely be |
17834 | resent to other recipients. | |
17835 | ||
17836 | ||
9b371988 PH |
17837 | .option group transports string&!! "Exim group" |
17838 | .cindex "transport" "group; specifying" | |
168e428f PH |
17839 | This option specifies a gid for running the transport process, overriding any |
17840 | value that the router supplies, and also overriding any value associated with | |
9b371988 | 17841 | &%user%& (see below). |
168e428f | 17842 | |
168e428f | 17843 | |
9b371988 PH |
17844 | .option headers_add transports string&!! unset |
17845 | .cindex "header lines" "adding in transport" | |
17846 | .cindex "transport" "header lines; adding" | |
168e428f PH |
17847 | This option specifies a string of text that is expanded and added to the header |
17848 | portion of a message as it is transported, as described in section | |
9b371988 PH |
17849 | &<<SECTheadersaddrem>>&. Additional header lines can also be specified by |
17850 | routers. If the result of the expansion is an empty string, or if the expansion | |
17851 | is forced to fail, no action is taken. Other expansion failures are treated as | |
168e428f PH |
17852 | errors and cause the delivery to be deferred. |
17853 | ||
17854 | ||
17855 | ||
9b371988 PH |
17856 | .option headers_only transports boolean false |
17857 | .cindex "transport" "header lines only" | |
17858 | .cindex "message" "transporting headers only" | |
17859 | .cindex "header lines" "transporting" | |
168e428f | 17860 | If this option is set, the message's body is not transported. It is mutually |
9b371988 PH |
17861 | exclusive with &%body_only%&. If it is used with the &(appendfile)& or &(pipe)& |
17862 | transports, the settings of &%message_prefix%& and &%message_suffix%& should be | |
168e428f PH |
17863 | checked, since this option does not automatically suppress them. |
17864 | ||
17865 | ||
9b371988 PH |
17866 | .option headers_remove transports string&!! unset |
17867 | .cindex "header lines" "removing" | |
17868 | .cindex "transport" "header lines; removing" | |
168e428f PH |
17869 | This option specifies a string that is expanded into a list of header names; |
17870 | these headers are omitted from the message as it is transported, as described | |
9b371988 | 17871 | in section &<<SECTheadersaddrem>>&. Header removal can also be specified by |
168e428f PH |
17872 | routers. If the result of the expansion is an empty string, or if the expansion |
17873 | is forced to fail, no action is taken. Other expansion failures are treated as | |
17874 | errors and cause the delivery to be deferred. | |
17875 | ||
17876 | ||
17877 | ||
9b371988 PH |
17878 | .option headers_rewrite transports string unset |
17879 | .cindex "transport" "header lines; rewriting" | |
17880 | .cindex "rewriting" "at transport time" | |
168e428f PH |
17881 | This option allows addresses in header lines to be rewritten at transport time, |
17882 | that is, as the message is being copied to its destination. The contents of the | |
17883 | option are a colon-separated list of rewriting rules. Each rule is in exactly | |
17884 | the same form as one of the general rewriting rules that are applied when a | |
9b371988 PH |
17885 | message is received. These are described in chapter &<<CHAPrewrite>>&. For |
17886 | example, | |
17887 | .code | |
168e428f PH |
17888 | headers_rewrite = a@b c@d f : \ |
17889 | x@y w@z | |
9b371988 PH |
17890 | .endd |
17891 | changes &'a@b'& into &'c@d'& in &'From:'& header lines, and &'x@y'& into | |
17892 | &'w@z'& in all address-bearing header lines. The rules are applied to the | |
17893 | header lines just before they are written out at transport time, so they affect | |
17894 | only those copies of the message that pass through the transport. However, only | |
17895 | the message's original header lines, and any that were added by a system | |
17896 | filter, are rewritten. If a router or transport adds header lines, they are not | |
17897 | affected by this option. These rewriting rules are &'not'& applied to the | |
17898 | envelope. You can change the return path using &%return_path%&, but you cannot | |
168e428f PH |
17899 | change envelope recipients at this time. |
17900 | ||
17901 | ||
9b371988 PH |
17902 | .option home_directory transports string&!! unset |
17903 | .cindex "transport" "home directory for" | |
17904 | .cindex "&$home$&" | |
168e428f PH |
17905 | This option specifies a home directory setting for the transport, overriding |
17906 | any value that may be set by the router. The home directory is placed in | |
9b371988 | 17907 | &$home$& while expanding the transport's private options. It is also used as |
168e428f | 17908 | the current directory if no current directory is set by the |
9b371988 PH |
17909 | &%current_directory%& option on the transport or the |
17910 | &%transport_current_directory%& option on the router. | |
168e428f PH |
17911 | If the expansion fails for any reason, including forced failure, an error is |
17912 | logged, and delivery is deferred. | |
17913 | ||
17914 | ||
9b371988 PH |
17915 | .option initgroups transports boolean false |
17916 | .cindex "additional groups" | |
17917 | .cindex "groups" "additional" | |
17918 | .cindex "transport" "group; additional" | |
168e428f | 17919 | If this option is true and the uid for the delivery process is provided by the |
9b371988 | 17920 | transport, the &[initgroups()]& function is called when running the transport |
168e428f PH |
17921 | to ensure that any additional groups associated with the uid are set up. |
17922 | ||
17923 | ||
9b371988 PH |
17924 | .option message_size_limit transports string&!! 0 |
17925 | .cindex "limit" "message size per transport" | |
17926 | .cindex "size of message" "limit" | |
17927 | .cindex "transport" "message size; limiting" | |
168e428f PH |
17928 | This option controls the size of messages passed through the transport. It is |
17929 | expanded before use; the result of the expansion must be a sequence of digits, | |
17930 | optionally followed by K or M. | |
17931 | If the expansion fails for any reason, including forced failure, or if the | |
17932 | result is not of the required form, delivery is deferred. | |
17933 | If the value is greater than zero and the size of a message exceeds this | |
17934 | limit, the address is failed. If there is any chance that the resulting bounce | |
17935 | message could be routed to the same transport, you should ensure that | |
9b371988 | 17936 | &%return_size_limit%& is less than the transport's &%message_size_limit%&, as |
168e428f PH |
17937 | otherwise the bounce message will fail to get delivered. |
17938 | ||
17939 | ||
17940 | ||
9b371988 PH |
17941 | .option rcpt_include_affixes transports boolean false |
17942 | .cindex "prefix" "for local part; including in envelope" | |
17943 | .cindex "suffix" "for local part; including in envelope" | |
17944 | .cindex "local part" "prefix" | |
17945 | .cindex "local part" "suffix" | |
168e428f PH |
17946 | When this option is false (the default), and an address that has had any |
17947 | affixes (prefixes or suffixes) removed from the local part is delivered by any | |
17948 | form of SMTP or LMTP, the affixes are not included. For example, if a router | |
17949 | that contains | |
9b371988 PH |
17950 | .code |
17951 | local_part_prefix = *- | |
17952 | .endd | |
17953 | routes the address &'abc-xyz@some.domain'& to an SMTP transport, the envelope | |
168e428f | 17954 | is delivered with |
9b371988 PH |
17955 | .code |
17956 | RCPT TO:<xyz@some.domain> | |
17957 | .endd | |
17958 | &new("This is also the case when an ACL-time callout is being used to verify a | |
17959 | recipient address.") However, if &%rcpt_include_affixes%& is set true, the | |
17960 | whole local part is included in the RCPT command. This option applies to BSMTP | |
17961 | deliveries by the &(appendfile)& and &(pipe)& transports as well as to the | |
17962 | &(lmtp)& and &(smtp)& transports. | |
17963 | ||
17964 | ||
17965 | .option retry_use_local_part transports boolean "see below" | |
17966 | .cindex "hints database" "retry keys" | |
168e428f PH |
17967 | When a delivery suffers a temporary failure, a retry record is created |
17968 | in Exim's hints database. For remote deliveries, the key for the retry record | |
17969 | is based on the name and/or IP address of the failing remote host. For local | |
17970 | deliveries, the key is normally the entire address, including both the local | |
17971 | part and the domain. This is suitable for most common cases of local delivery | |
9b371988 | 17972 | temporary failure &-- for example, exceeding a mailbox quota should delay only |
168e428f PH |
17973 | deliveries to that mailbox, not to the whole domain. |
17974 | ||
17975 | However, in some special cases you may want to treat a temporary local delivery | |
17976 | as a failure associated with the domain, and not with a particular local part. | |
17977 | (For example, if you are storing all mail for some domain in files.) You can do | |
9b371988 | 17978 | this by setting &%retry_use_local_part%& false. |
168e428f PH |
17979 | |
17980 | For all the local transports, its default value is true. For remote transports, | |
17981 | the default value is false for tidiness, but changing the value has no effect | |
17982 | on a remote transport in the current implementation. | |
17983 | ||
17984 | ||
9b371988 PH |
17985 | .option return_path transports string&!! unset |
17986 | .cindex "envelope sender" | |
17987 | .cindex "transport" "return path; changing" | |
17988 | .cindex "return path" "changing in transport" | |
168e428f PH |
17989 | If this option is set, the string is expanded at transport time and replaces |
17990 | the existing return path (envelope sender) value in the copy of the message | |
17991 | that is being delivered. An empty return path is permitted. This feature is | |
17992 | designed for remote deliveries, where the value of this option is used in the | |
9b371988 PH |
17993 | SMTP MAIL command. If you set &%return_path%& for a local transport, the |
17994 | only effect is to change the address that is placed in the &'Return-path:'& | |
168e428f PH |
17995 | header line, if one is added to the message (see the next option). |
17996 | ||
9b371988 PH |
17997 | .cindex "&$return_path$&" |
17998 | The expansion can refer to the existing value via &$return_path$&. This is | |
168e428f | 17999 | either the message's envelope sender, or an address set by the |
9b371988 | 18000 | &%errors_to%& option on a router. If the expansion is forced to fail, no |
168e428f | 18001 | replacement occurs; if it fails for another reason, delivery is deferred. This |
9b371988 PH |
18002 | option can be used to support VERP (Variable Envelope Return Paths) &-- see |
18003 | chapter &<<CHAPSMTP>>&. | |
168e428f | 18004 | |
9b371988 | 18005 | &*Note*&: If a delivery error is detected locally, |
168e428f PH |
18006 | including the case when a remote server rejects a message at SMTP time, |
18007 | the bounce message is not sent to the value of this option, but to the | |
18008 | previously set errors address (which defaults to the incoming sender address). | |
18009 | ||
18010 | ||
18011 | ||
9b371988 PH |
18012 | .option return_path_add transports boolean false |
18013 | .cindex "&'Return-path:'& header line" | |
18014 | If this option is true, a &'Return-path:'& header is added to the message. | |
168e428f PH |
18015 | Although the return path is normally available in the prefix line of BSD |
18016 | mailboxes, this is commonly not displayed by MUAs, and so the user does not | |
18017 | have easy access to it. | |
18018 | ||
9b371988 PH |
18019 | RFC 2821 states that the &'Return-path:'& header is added to a message &"when |
18020 | the delivery SMTP server makes the final delivery"&. This implies that this | |
18021 | header should not be present in incoming messages. Exim has a configuration | |
18022 | option, &%return_path_remove%&, which requests removal of this header from | |
18023 | incoming messages, so that delivered messages can safely be resent to other | |
18024 | recipients. | |
168e428f | 18025 | |
168e428f | 18026 | |
9b371988 PH |
18027 | .option shadow_condition transports string&!! unset |
18028 | See &%shadow_transport%& below. | |
168e428f PH |
18029 | |
18030 | ||
9b371988 PH |
18031 | .option shadow_transport transports string unset |
18032 | .cindex "shadow transport" | |
18033 | .cindex "transport" "shadow" | |
18034 | A local transport may set the &%shadow_transport%& option to the name of | |
18035 | another local transport. Shadow remote transports are not supported. | |
168e428f PH |
18036 | |
18037 | Whenever a delivery to the main transport succeeds, and either | |
9b371988 PH |
18038 | &%shadow_condition%& is unset, or its expansion does not result in the empty |
18039 | string or one of the strings &"0"& or &"no"& or &"false"&, the message is also | |
18040 | passed to the shadow transport, with the same delivery address or addresses. If | |
18041 | expansion fails, no action is taken except that non-forced expansion failures | |
18042 | cause a log line to be written. | |
168e428f PH |
18043 | |
18044 | The result of the shadow transport is discarded and does not affect the | |
18045 | subsequent processing of the message. Only a single level of shadowing is | |
9b371988 PH |
18046 | provided; the &%shadow_transport%& option is ignored on any transport when it |
18047 | is running as a shadow. Options concerned with output from pipes are also | |
18048 | ignored. The log line for the successful delivery has an item added on the end, | |
18049 | of the form | |
18050 | .code | |
18051 | ST=<shadow transport name> | |
18052 | .endd | |
168e428f | 18053 | If the shadow transport did not succeed, the error message is put in |
9b371988 PH |
18054 | parentheses afterwards. Shadow transports can be used for a number of different |
18055 | purposes, including keeping more detailed log information than Exim normally | |
18056 | provides, and implementing automatic acknowledgement policies based on message | |
18057 | headers that some sites insist on. | |
168e428f PH |
18058 | |
18059 | ||
9b371988 PH |
18060 | .option transport_filter transports string&!! unset |
18061 | .cindex "transport" "filter" | |
18062 | .cindex "filter" "transport filter" | |
168e428f PH |
18063 | This option sets up a filtering (in the Unix shell sense) process for messages |
18064 | at transport time. It should not be confused with mail filtering as set up by | |
18065 | individual users or via a system filter. | |
18066 | ||
18067 | When the message is about to be written out, the command specified by | |
9b371988 PH |
18068 | &%transport_filter%& is started up in a separate, &new(parallel) process, and |
18069 | the entire message, including the header lines, is passed to it on its standard | |
18070 | input (this in fact is done from a third process, to avoid deadlock). The | |
18071 | command must be specified as an absolute path. | |
168e428f PH |
18072 | |
18073 | The lines of the message that are written to the transport filter are | |
9b371988 PH |
18074 | terminated by newline (&"\n"&). The message is passed to the filter before any |
18075 | SMTP-specific processing, such as turning &"\n"& into &"\r\n"& and escaping | |
068aaea8 | 18076 | lines beginning with a dot, and also before any processing implied by the |
9b371988 PH |
18077 | settings of &%check_string%& and &%escape_string%& in the &(appendfile)& or |
18078 | &(pipe)& transports. | |
168e428f PH |
18079 | |
18080 | The standard error for the filter process is set to the same destination as its | |
18081 | standard output; this is read and written to the message's ultimate | |
9b371988 PH |
18082 | destination. &new("The process that writes the message to the filter, the |
18083 | filter itself, and the original process that reads the result and delivers it | |
18084 | are all run in parallel, like a shell pipeline.") | |
18085 | ||
18086 | The filter can perform any transformations it likes, but of course should take | |
18087 | care not to break RFC 2822 syntax. A demonstration Perl script is provided in | |
18088 | &_util/transport-filter.pl_&; this makes a few arbitrary modifications just to | |
18089 | show the possibilities. Exim does not check the result, except to test for a | |
18090 | final newline when SMTP is in use. All messages transmitted over SMTP must end | |
18091 | with a newline, so Exim supplies one if it is missing. | |
18092 | ||
18093 | .new | |
18094 | .cindex "content scanning" "per user" | |
068aaea8 PH |
18095 | A transport filter can be used to provide content-scanning on a per-user basis |
18096 | at delivery time if the only required effect of the scan is to modify the | |
18097 | message. For example, a content scan could insert a new header line containing | |
18098 | a spam score. This could be interpreted by a filter in the user's MUA. It is | |
18099 | not possible to discard a message at this stage. | |
9b371988 | 18100 | .wen |
168e428f | 18101 | |
9b371988 | 18102 | .cindex "SMTP" "SIZE" |
168e428f PH |
18103 | A problem might arise if the filter increases the size of a message that is |
18104 | being sent down an SMTP connection. If the receiving SMTP server has indicated | |
18105 | support for the SIZE parameter, Exim will have sent the size of the message | |
18106 | at the start of the SMTP session. If what is actually sent is substantially | |
18107 | more, the server might reject the message. This can be worked round by setting | |
9b371988 | 18108 | the &%size_addition%& option on the &(smtp)& transport, either to allow for |
168e428f PH |
18109 | additions to the message, or to disable the use of SIZE altogether. |
18110 | ||
9b371988 PH |
18111 | .cindex "&$pipe_addresses$&" |
18112 | The value of the &%transport_filter%& option is the command string for starting | |
168e428f | 18113 | the filter, which is run directly from Exim, not under a shell. The string is |
9b371988 PH |
18114 | parsed by Exim in the same way as a command string for the &(pipe)& transport: |
18115 | Exim breaks it up into arguments and then expands each argument separately. | |
18116 | &new("Any kind of expansion failure causes delivery to be deferred.") The | |
18117 | special argument &$pipe_addresses$& is replaced by a number of arguments, one | |
168e428f | 18118 | for each address that applies to this delivery. (This isn't an ideal name for |
9b371988 | 18119 | this feature here, but as it was already implemented for the &(pipe)& |
168e428f PH |
18120 | transport, it seemed sensible not to change it.) |
18121 | ||
9b371988 PH |
18122 | .cindex "&$host$&" |
18123 | .cindex "&$host_address$&" | |
18124 | The expansion variables &$host$& and &$host_address$& are available when the | |
168e428f PH |
18125 | transport is a remote one. They contain the name and IP address of the host to |
18126 | which the message is being sent. For example: | |
9b371988 | 18127 | .code |
168e428f PH |
18128 | transport_filter = /some/directory/transport-filter.pl \ |
18129 | $host $host_address $sender_address $pipe_addresses | |
9b371988 | 18130 | .endd |
168e428f PH |
18131 | The filter process is run under the same uid and gid as the normal delivery. |
18132 | For remote deliveries this is the Exim uid/gid by default. | |
18133 | ||
9b371988 PH |
18134 | .new |
18135 | The command should normally yield a zero return code. Transport filters are not | |
18136 | supposed to fail. A non-zero code is taken to mean that the transport filter | |
18137 | encountered some serious problem. Delivery of the message is deferred; the | |
18138 | message remains on the queue and is tried again later. It is not possible to | |
18139 | cause a message to be bounced from a transport filter. | |
18140 | .wen | |
168e428f PH |
18141 | |
18142 | If a transport filter is set on an autoreply transport, the original message is | |
18143 | passed through the filter as it is being copied into the newly generated | |
9b371988 | 18144 | message, which happens if the &%return_message%& option is set. |
168e428f PH |
18145 | |
18146 | ||
9b371988 PH |
18147 | .option transport_filter_timeout transports time 5m |
18148 | .new | |
18149 | .cindex "transport filter" "timeout" | |
168e428f | 18150 | When Exim is reading the output of a transport filter, it a applies a timeout |
068aaea8 PH |
18151 | that can be set by this option. Exceeding the timeout is normally treated as a |
18152 | temporary delivery failure. However, if a transport filter is used with a | |
9b371988 PH |
18153 | &(pipe)& transport, a timeout in the transport filter is treated in the same |
18154 | way as a timeout in the pipe command itself. By default, a timeout is a hard | |
18155 | error, but if the &(pipe)& transport's &%timeout_defer%& option is set true, it | |
18156 | becomes a temporary error. | |
18157 | .wen | |
168e428f PH |
18158 | |
18159 | ||
9b371988 PH |
18160 | .option user transports string&!! "Exim user" |
18161 | .cindex "uid (user id)" "local delivery" | |
18162 | .cindex "transport user" "specifying" | |
168e428f PH |
18163 | This option specifies the user under whose uid the delivery process is to be |
18164 | run, overriding any uid that may have been set by the router. If the user is | |
18165 | given as a name, the uid is looked up from the password data, and the | |
9b371988 | 18166 | associated group is taken as the value of the gid to be used if the &%group%& |
168e428f PH |
18167 | option is not set. |
18168 | ||
18169 | For deliveries that use local transports, a user and group are normally | |
18170 | specified explicitly or implicitly (for example, as a result of | |
9b371988 | 18171 | &%check_local_user%&) by the router or transport. |
168e428f | 18172 | |
9b371988 | 18173 | .cindex "hints database" "access by remote transport" |
168e428f PH |
18174 | For remote transports, you should leave this option unset unless you really are |
18175 | sure you know what you are doing. When a remote transport is running, it needs | |
18176 | to be able to access Exim's hints databases, because each host may have its own | |
18177 | retry data. | |
18178 | ||
18179 | ||
18180 | ||
18181 | ||
18182 | ||
18183 | ||
9b371988 PH |
18184 | . //////////////////////////////////////////////////////////////////////////// |
18185 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 18186 | |
9b371988 PH |
18187 | .chapter "Address batching in local transports" "CHAPbatching" &&& |
18188 | "Address batching" | |
18189 | .cindex "transport" "local; address batching in" | |
18190 | The only remote transport (&(smtp)&) is normally configured to handle more than | |
168e428f PH |
18191 | one address at a time, so that when several addresses are routed to the same |
18192 | remote host, just one copy of the message is sent. Local transports, however, | |
18193 | normally handle one address at a time. That is, a separate instance of the | |
18194 | transport is run for each address that is routed to the transport. A separate | |
18195 | copy of the message is delivered each time. | |
18196 | ||
9b371988 PH |
18197 | .cindex "batched local delivery" |
18198 | .cindex "&%batch_max%&" | |
18199 | .cindex "&%batch_id%&" | |
168e428f PH |
18200 | In special cases, it may be desirable to handle several addresses at once in a |
18201 | local transport, for example: | |
18202 | ||
9b371988 PH |
18203 | .ilist |
18204 | In an &(appendfile)& transport, when storing messages in files for later | |
168e428f PH |
18205 | delivery by some other means, a single copy of the message with multiple |
18206 | recipients saves space. | |
9b371988 PH |
18207 | .next |
18208 | In an &(lmtp)& transport, when delivering over &"local SMTP"& to some process, | |
168e428f | 18209 | a single copy saves time, and is the normal way LMTP is expected to work. |
9b371988 PH |
18210 | .next |
18211 | In a &(pipe)& transport, when passing the message | |
168e428f PH |
18212 | to a scanner program or |
18213 | to some other delivery mechanism such as UUCP, multiple recipients may be | |
18214 | acceptable. | |
9b371988 | 18215 | .endlist |
168e428f | 18216 | |
9b371988 PH |
18217 | The three local transports (&(appendfile)&, &(lmtp)&, and &(pipe)&) all have |
18218 | the same options for controlling multiple (&"batched"&) deliveries, namely | |
18219 | &%batch_max%& and &%batch_id%&. To save repeating the information for each | |
168e428f PH |
18220 | transport, these options are described here. |
18221 | ||
9b371988 | 18222 | The &%batch_max%& option specifies the maximum number of addresses that can be |
168e428f | 18223 | delivered together in a single run of the transport. Its default value is one. |
9b371988 | 18224 | When more than one address is routed to a transport that has a &%batch_max%& |
168e428f PH |
18225 | value greater than one, the addresses are delivered in a batch (that is, in a |
18226 | single run of the transport), subject to certain conditions: | |
18227 | ||
9b371988 PH |
18228 | .ilist |
18229 | .cindex "&$local_part$&" | |
18230 | If any of the transport's options contain a reference to &$local_part$&, no | |
168e428f | 18231 | batching is possible. |
9b371988 PH |
18232 | .next |
18233 | .cindex "&$domain$&" | |
18234 | If any of the transport's options contain a reference to &$domain$&, only | |
168e428f | 18235 | addresses with the same domain are batched. |
9b371988 PH |
18236 | .next |
18237 | .cindex "customizing" "batching condition" | |
18238 | If &%batch_id%& is set, it is expanded for each address, and only those | |
168e428f PH |
18239 | addresses with the same expanded value are batched. This allows you to specify |
18240 | customized batching conditions. | |
18241 | Failure of the expansion for any reason, including forced failure, disables | |
18242 | batching, but it does not stop the delivery from taking place. | |
9b371988 PH |
18243 | .next |
18244 | Batched addresses must also have the same errors address (where to send | |
168e428f PH |
18245 | delivery errors), the same header additions and removals, the same user and |
18246 | group for the transport, and if a host list is present, the first host must | |
18247 | be the same. | |
9b371988 | 18248 | .endlist |
168e428f | 18249 | |
9b371988 PH |
18250 | .cindex "&'Envelope-to:'& header line" |
18251 | If the generic &%envelope_to_add%& option is set for the transport, the | |
18252 | &'Envelope-to:'& header that is added to the message contains all the addresses | |
168e428f PH |
18253 | that are batched together. |
18254 | ||
9b371988 PH |
18255 | The &(appendfile)& and &(pipe)& transports have an option called &%use_bsmtp%&, |
18256 | which causes them to deliver the message in &"batched SMTP"& format, with the | |
18257 | envelope represented as SMTP commands. The &%check_string%& and | |
18258 | &%escape_string%& options are forced to the values | |
18259 | .code | |
18260 | check_string = "." | |
18261 | escape_string = ".." | |
18262 | .endd | |
168e428f | 18263 | when batched SMTP is in use. A full description of the batch SMTP mechanism is |
9b371988 PH |
18264 | given in section &<<SECTbatchSMTP>>&. The &(lmtp)& transport does not have a |
18265 | &%use_bsmtp%& option, because it always delivers using the SMTP protocol. | |
168e428f | 18266 | |
9b371988 PH |
18267 | .cindex "&(pipe)& transport" "with multiple addresses" |
18268 | .cindex "&$pipe_addresses$&" | |
18269 | If you are not using BSMTP, but are using a &(pipe)& transport, you can include | |
18270 | &$pipe_addresses$& as part of the command. This is not a true variable; it is | |
168e428f PH |
18271 | a bit of magic that causes each of the recipient addresses to be inserted into |
18272 | the command as a separate argument. This provides a way of accessing all the | |
18273 | addresses that are being delivered in the batch. | |
18274 | ||
9b371988 PH |
18275 | If you are using a batching &(appendfile)& transport without &%use_bsmtp%&, the |
18276 | only way to preserve the recipient addresses is to set the &%envelope_to_add%& | |
18277 | option. This causes an &'Envelope-to:'& header line to be added to the message, | |
168e428f PH |
18278 | containing all the recipients. |
18279 | ||
18280 | ||
18281 | ||
9b371988 PH |
18282 | . //////////////////////////////////////////////////////////////////////////// |
18283 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 18284 | |
9b371988 PH |
18285 | .chapter "The appendfile transport" "CHAPappendfile" |
18286 | .cindex "&(appendfile)& transport" | |
18287 | .cindex "transports" "&(appendfile)&" | |
18288 | .cindex "directory creation" | |
18289 | .cindex "creating directories" | |
18290 | The &(appendfile)& transport delivers a message by appending it to an existing | |
168e428f PH |
18291 | file, or by creating an entirely new file in a specified directory. Single |
18292 | files to which messages are appended can be in the traditional Unix mailbox | |
18293 | format, or optionally in the MBX format supported by the Pine MUA and | |
9b371988 PH |
18294 | University of Washington IMAP daemon, &'inter alia'&. When each message is |
18295 | being delivered as a separate file, &"maildir"& format can optionally be used | |
18296 | to give added protection against failures that happen part-way through the | |
18297 | delivery. A third form of separate-file delivery known as &"mailstore"& is also | |
168e428f | 18298 | supported. For all file formats, Exim attempts to create as many levels of |
9b371988 | 18299 | directory as necessary, provided that &%create_directory%& is set. |
168e428f PH |
18300 | |
18301 | The code for the optional formats is not included in the Exim binary by | |
18302 | default. It is necessary to set SUPPORT_MBX, SUPPORT_MAILDIR and/or | |
9b371988 | 18303 | SUPPORT_MAILSTORE in &_Local/Makefile_& to have the appropriate code |
168e428f PH |
18304 | included. |
18305 | ||
9b371988 | 18306 | .cindex "quota" "system" |
168e428f PH |
18307 | Exim recognises system quota errors, and generates an appropriate message. Exim |
18308 | also supports its own quota control within the transport, for use when the | |
18309 | system facility is unavailable or cannot be used for some reason. | |
18310 | ||
18311 | If there is an error while appending to a file (for example, quota exceeded or | |
18312 | partition filled), Exim attempts to reset the file's length and last | |
18313 | modification time back to what they were before. If there is an error while | |
18314 | creating an entirely new file, the new file is removed. | |
18315 | ||
18316 | Before appending to a file, a number of security checks are made, and the | |
18317 | file is locked. A detailed description is given below, after the list of | |
18318 | private options. | |
18319 | ||
9b371988 PH |
18320 | The &(appendfile)& transport is most commonly used for local deliveries to |
18321 | users' mailboxes. However, it can also be used as a pseudo-remote transport for | |
18322 | putting messages into files for remote delivery by some means other than Exim. | |
18323 | &"Batch SMTP"& format is often used in this case (see the &%use_bsmtp%& | |
18324 | option). | |
168e428f PH |
18325 | |
18326 | ||
18327 | ||
9b371988 PH |
18328 | .section "The file and directory options" "SECTfildiropt" |
18329 | The &%file%& option specifies a single file, to which the message is appended; | |
18330 | the &%directory%& option specifies a directory, in which a new file containing | |
168e428f | 18331 | the message is created. Only one of these two options can be set, and for |
9b371988 | 18332 | normal deliveries to mailboxes, one of them &'must'& be set. |
168e428f | 18333 | |
9b371988 PH |
18334 | .cindex "&$address_file$&" |
18335 | .cindex "&$local_part$&" | |
18336 | However, &(appendfile)& is also used for delivering messages to files or | |
168e428f | 18337 | directories whose names (or parts of names) are obtained from alias, |
9b371988 PH |
18338 | forwarding, or filtering operations (for example, a &%save%& command in a |
18339 | user's Exim filter). When such a transport is running, &$local_part$& contains | |
18340 | the local part that was aliased or forwarded, and &$address_file$& contains the | |
168e428f PH |
18341 | name (or partial name) of the file or directory generated by the redirection |
18342 | operation. There are two cases: | |
18343 | ||
9b371988 PH |
18344 | .ilist |
18345 | If neither &%file%& nor &%directory%& is set, the redirection operation | |
18346 | must specify an absolute path (one that begins with &`/`&). This is the most | |
168e428f | 18347 | common case when users with local accounts use filtering to sort mail into |
9b371988 | 18348 | different folders. See for example, the &(address_file)& transport in the |
168e428f PH |
18349 | default configuration. If the path ends with a slash, it is assumed to be the |
18350 | name of a directory. A delivery to a directory can also be forced by setting | |
9b371988 PH |
18351 | &%maildir_format%& or &%mailstore_format%&. |
18352 | .next | |
18353 | If &%file%& or &%directory%& is set for a delivery from a redirection, it is | |
18354 | used to determine the file or directory name for the delivery. Normally, the | |
18355 | contents of &$address_file$& are used in some way in the string expansion. | |
18356 | .endlist | |
168e428f PH |
18357 | |
18358 | ||
9b371988 PH |
18359 | .cindex "Sieve filter" "configuring &(appendfile)&" |
18360 | .cindex "Sieve filter" "relative mailbox path handling" | |
168e428f PH |
18361 | As an example of the second case, consider an environment where users do not |
18362 | have home directories. They may be permitted to use Exim filter commands of the | |
18363 | form: | |
9b371988 PH |
18364 | .code |
18365 | save folder23 | |
18366 | .endd | |
168e428f | 18367 | or Sieve filter commands of the form: |
9b371988 PH |
18368 | .code |
18369 | require "fileinto"; | |
18370 | fileinto "folder23"; | |
18371 | .endd | |
18372 | In this situation, the expansion of &%file%& or &%directory%& in the transport | |
18373 | must transform the relative path into an appropriate absolute file name. In the | |
18374 | case of Sieve filters, the name &'inbox'& must be handled. It is the name that | |
18375 | is used as a result of a &"keep"& action in the filter. This example shows one | |
18376 | way of handling this requirement: | |
18377 | .code | |
168e428f PH |
18378 | file = ${if eq{$address_file}{inbox} \ |
18379 | {/var/mail/$local_part} \ | |
18380 | {${if eq{${substr_0_1:$address_file}}{/} \ | |
18381 | {$address_file} \ | |
18382 | {$home/mail/$address_file} \ | |
18383 | }} \ | |
18384 | } | |
9b371988 PH |
18385 | .endd |
18386 | With this setting of &%file%&, &'inbox'& refers to the standard mailbox | |
18387 | location, absolute paths are used without change, and other folders are in the | |
18388 | &_mail_& directory within the home directory. | |
18389 | ||
18390 | &*Note 1*&: While processing an Exim filter, a relative path such as | |
18391 | &_folder23_& is turned into an absolute path if a home directory is known to | |
18392 | the router. In particular, this is the case if &%check_local_user%& is set. If | |
168e428f | 18393 | you want to prevent this happening at routing time, you can set |
9b371988 | 18394 | &%router_home_directory%& empty. This forces the router to pass the relative |
168e428f PH |
18395 | path to the transport. |
18396 | ||
9b371988 PH |
18397 | &*Note 2*&: An absolute path in &$address_file$& is not treated specially; |
18398 | the &%file%& or &%directory%& option is still used if it is set. | |
168e428f PH |
18399 | |
18400 | ||
18401 | ||
168e428f | 18402 | |
9b371988 PH |
18403 | .section "Private options for appendfile" |
18404 | .cindex "options" "&(appendfile)& transport" | |
168e428f PH |
18405 | |
18406 | ||
168e428f | 18407 | |
9b371988 PH |
18408 | .option allow_fifo appendfile boolean false |
18409 | .cindex "fifo (named pipe)" | |
18410 | .cindex "named pipe (fifo)" | |
18411 | .cindex "pipe" "named (fifo)" | |
168e428f PH |
18412 | Setting this option permits delivery to named pipes (FIFOs) as well as to |
18413 | regular files. If no process is reading the named pipe at delivery time, the | |
18414 | delivery is deferred. | |
18415 | ||
18416 | ||
9b371988 PH |
18417 | .option allow_symlink appendfile boolean false |
18418 | .cindex "symbolic link" "to mailbox" | |
18419 | .cindex "mailbox" "symbolic link" | |
18420 | By default, &(appendfile)& will not deliver if the path name for the file is | |
168e428f PH |
18421 | that of a symbolic link. Setting this option relaxes that constraint, but there |
18422 | are security issues involved in the use of symbolic links. Be sure you know | |
18423 | what you are doing if you set this. Details of exactly what this option affects | |
18424 | are included in the discussion which follows this list of options. | |
18425 | ||
18426 | ||
9b371988 PH |
18427 | .option batch_id appendfile string&!! unset |
18428 | See the description of local delivery batching in chapter &<<CHAPbatching>>&. | |
18429 | However, batching is automatically disabled for &(appendfile)& deliveries that | |
168e428f PH |
18430 | happen as a result of forwarding or aliasing or other redirection directly to a |
18431 | file. | |
18432 | ||
18433 | ||
9b371988 PH |
18434 | .option batch_max appendfile integer 1 |
18435 | See the description of local delivery batching in chapter &<<CHAPbatching>>&. | |
168e428f | 18436 | |
168e428f | 18437 | |
9b371988 PH |
18438 | .option check_group appendfile boolean false |
18439 | When this option is set, the group owner of the file defined by the &%file%& | |
168e428f PH |
18440 | option is checked to see that it is the same as the group under which the |
18441 | delivery process is running. The default setting is false because the default | |
18442 | file mode is 0600, which means that the group is irrelevant. | |
18443 | ||
18444 | ||
9b371988 PH |
18445 | .option check_owner appendfile boolean true |
18446 | When this option is set, the owner of the file defined by the &%file%& option | |
18447 | is checked to ensure that it is the same as the user under which the delivery | |
168e428f PH |
18448 | process is running. |
18449 | ||
18450 | ||
9b371988 PH |
18451 | .option check_string appendfile string "see below" |
18452 | .cindex "&""From""& line" | |
18453 | As &(appendfile)& writes the message, the start of each line is tested for | |
18454 | matching &%check_string%&, and if it does, the initial matching characters are | |
18455 | replaced by the contents of &%escape_string%&. The value of &%check_string%& is | |
18456 | a literal string, not a regular expression, and the case of any letters it | |
168e428f PH |
18457 | contains is significant. |
18458 | ||
9b371988 PH |
18459 | If &%use_bsmtp%& is set the values of &%check_string%& and &%escape_string%& |
18460 | are forced to &"."& and &".."& respectively, and any settings in the | |
18461 | configuration are ignored. Otherwise, they default to &"From&~"& and | |
18462 | &">From&~"& when the &%file%& option is set, and unset when any of the | |
18463 | &%directory%&, &%maildir%&, or &%mailstore%& options are set. | |
18464 | ||
18465 | The default settings, along with &%message_prefix%& and &%message_suffix%&, are | |
18466 | suitable for traditional &"BSD"& mailboxes, where a line beginning with | |
18467 | &"From&~"& indicates the start of a new message. All four options need changing | |
18468 | if another format is used. For example, to deliver to mailboxes in MMDF format: | |
18469 | .cindex "MMDF format mailbox" | |
18470 | .cindex "mailbox" "MMDF format" | |
18471 | .code | |
18472 | check_string = "\1\1\1\1\n" | |
18473 | escape_string = "\1\1\1\1 \n" | |
18474 | message_prefix = "\1\1\1\1\n" | |
18475 | message_suffix = "\1\1\1\1\n" | |
18476 | .endd | |
18477 | .option create_directory appendfile boolean true | |
18478 | .cindex "directory creation" | |
168e428f PH |
18479 | When this option is true, Exim attempts to create any missing superior |
18480 | directories for the file that it is about to write. A created directory's mode | |
9b371988 | 18481 | is given by the &%directory_mode%& option. |
168e428f PH |
18482 | |
18483 | The group ownership of a newly created directory is highly dependent on the | |
18484 | operating system (and possibly the file system) that is being used. For | |
18485 | example, in Solaris, if the parent directory has the setgid bit set, its group | |
18486 | is propagated to the child; if not, the currently set group is used. However, | |
18487 | in FreeBSD, the parent's group is always used. | |
18488 | ||
18489 | ||
18490 | ||
9b371988 | 18491 | .option create_file appendfile string anywhere |
168e428f | 18492 | This option constrains the location of files and directories that are created |
9b371988 PH |
18493 | by this transport. It applies to files defined by the &%file%& option and |
18494 | directories defined by the &%directory%& option. In the case of maildir | |
18495 | delivery, it applies to the top level directory, not the maildir directories | |
18496 | beneath. | |
18497 | ||
18498 | The option must be set to one of the words &"anywhere"&, &"inhome"&, or | |
18499 | &"belowhome"&. In the second and third cases, a home directory must have been | |
18500 | set for the transport. This option is not useful when an explicit file name is | |
168e428f | 18501 | given for normal mailbox deliveries. It is intended for the case when file |
9b371988 PH |
18502 | names are generated from users' &_.forward_& files. These are usually handled |
18503 | by an &(appendfile)& transport called &%address_file%&. See also | |
18504 | &%file_must_exist%&. | |
168e428f PH |
18505 | |
18506 | ||
9b371988 PH |
18507 | .option directory appendfile string&!! unset |
18508 | This option is mutually exclusive with the &%file%& option, but one of &%file%& | |
18509 | or &%directory%& must be set, unless the delivery is the direct result of a | |
18510 | redirection (see section &<<SECTfildiropt>>&). | |
168e428f | 18511 | |
9b371988 | 18512 | When &%directory%& is set, the string is expanded, and the message is delivered |
168e428f PH |
18513 | into a new file or files in or below the given directory, instead of being |
18514 | appended to a single mailbox file. A number of different formats are provided | |
9b371988 PH |
18515 | (see &%maildir_format%& and &%mailstore_format%&), and see section |
18516 | &<<SECTopdir>>& for further details of this form of delivery. | |
168e428f PH |
18517 | |
18518 | ||
9b371988 PH |
18519 | .option directory_file appendfile string&!! &`q${base62:$tod_epoch}-$inode`& |
18520 | .cindex "base62" | |
18521 | .cindex "&$inode$&" | |
18522 | When &%directory%& is set, but neither &%maildir_format%& nor | |
18523 | &%mailstore_format%& is set, &(appendfile)& delivers each message into a file | |
18524 | whose name is obtained by expanding this string. The default value generates a | |
18525 | unique name from the current time, in base 62 form, and the inode of the file. | |
18526 | The variable &$inode$& is available only when expanding this option. | |
168e428f | 18527 | |
168e428f | 18528 | |
9b371988 PH |
18529 | .option directory_mode appendfile "octal integer" 0700 |
18530 | If &(appendfile)& creates any directories as a result of the | |
18531 | &%create_directory%& option, their mode is specified by this option. | |
168e428f | 18532 | |
168e428f | 18533 | |
9b371988 PH |
18534 | .option escape_string appendfile string "see description" |
18535 | See &%check_string%& above. | |
168e428f PH |
18536 | |
18537 | ||
9b371988 PH |
18538 | .option file appendfile string&!! unset |
18539 | This option is mutually exclusive with the &%directory%& option, but one of | |
18540 | &%file%& or &%directory%& must be set, unless the delivery is the direct result | |
18541 | of a redirection (see section &<<SECTfildiropt>>&). The &%file%& option | |
18542 | specifies a single file, to which the message is appended. One or more of | |
18543 | &%use_fcntl_lock%&, &%use_flock_lock%&, or &%use_lockfile%& must be set with | |
18544 | &%file%&. | |
168e428f | 18545 | |
9b371988 PH |
18546 | .cindex "NFS" "lock file" |
18547 | .cindex "locking files" | |
18548 | .cindex "lock files" | |
168e428f PH |
18549 | If you are using more than one host to deliver over NFS into the same |
18550 | mailboxes, you should always use lock files. | |
18551 | ||
18552 | The string value is expanded for each delivery, and must yield an absolute | |
18553 | path. The most common settings of this option are variations on one of these | |
18554 | examples: | |
9b371988 PH |
18555 | .code |
18556 | file = /var/spool/mail/$local_part | |
18557 | file = /home/$local_part/inbox | |
18558 | file = $home/inbox | |
18559 | .endd | |
18560 | .cindex "&""sticky""& bit" | |
168e428f | 18561 | In the first example, all deliveries are done into the same directory. If Exim |
9b371988 PH |
18562 | is configured to use lock files (see &%use_lockfile%& below) it must be able to |
18563 | create a file in the directory, so the &"sticky"& bit must be turned on for | |
18564 | deliveries to be possible, or alternatively the &%group%& option can be used to | |
168e428f PH |
18565 | run the delivery under a group id which has write access to the directory. |
18566 | ||
18567 | ||
18568 | ||
9b371988 PH |
18569 | .option file_format appendfile string unset |
18570 | .cindex "file" "mailbox; checking existing format" | |
168e428f PH |
18571 | This option requests the transport to check the format of an existing file |
18572 | before adding to it. The check consists of matching a specific string at the | |
18573 | start of the file. The value of the option consists of an even number of | |
18574 | colon-separated strings. The first of each pair is the test string, and the | |
18575 | second is the name of a transport. If the transport associated with a matched | |
18576 | string is not the current transport, control is passed over to the other | |
9b371988 | 18577 | transport. For example, suppose the standard &(local_delivery)& transport has |
168e428f | 18578 | this added to it: |
9b371988 | 18579 | .code |
168e428f PH |
18580 | file_format = "From : local_delivery :\ |
18581 | \1\1\1\1\n : local_mmdf_delivery" | |
9b371988 PH |
18582 | .endd |
18583 | Mailboxes that begin with &"From"& are still handled by this transport, but if | |
18584 | a mailbox begins with four binary ones followed by a newline, control is passed | |
18585 | to a transport called &%local_mmdf_delivery%&, which presumably is configured | |
168e428f PH |
18586 | to do the delivery in MMDF format. If a mailbox does not exist or is empty, it |
18587 | is assumed to match the current transport. If the start of a mailbox doesn't | |
18588 | match any string, or if the transport named for a given string is not defined, | |
18589 | delivery is deferred. | |
18590 | ||
18591 | ||
9b371988 PH |
18592 | .option file_must_exist appendfile boolean false |
18593 | If this option is true, the file specified by the &%file%& option must exist, | |
18594 | and an error occurs if it does not. Otherwise, it is created if it does not | |
18595 | exist. | |
168e428f PH |
18596 | |
18597 | ||
9b371988 PH |
18598 | .option lock_fcntl_timeout appendfile time 0s |
18599 | .cindex "timeout" "mailbox locking" | |
18600 | .cindex "mailbox locking" "blocking and non-blocking" | |
18601 | .cindex "locking files" | |
18602 | By default, the &(appendfile)& transport uses non-blocking calls to &[fcntl()]& | |
168e428f | 18603 | when locking an open mailbox file. If the call fails, the delivery process |
9b371988 | 18604 | sleeps for &%lock_interval%& and tries again, up to &%lock_retries%& times. |
168e428f PH |
18605 | Non-blocking calls are used so that the file is not kept open during the wait |
18606 | for the lock; the reason for this is to make it as safe as possible for | |
18607 | deliveries over NFS in the case when processes might be accessing an NFS | |
18608 | mailbox without using a lock file. This should not be done, but | |
18609 | misunderstandings and hence misconfigurations are not unknown. | |
18610 | ||
18611 | On a busy system, however, the performance of a non-blocking lock approach is | |
18612 | not as good as using a blocking lock with a timeout. In this case, the waiting | |
18613 | is done inside the system call, and Exim's delivery process acquires the lock | |
18614 | and can proceed as soon as the previous lock holder releases it. | |
18615 | ||
9b371988 | 18616 | If &%lock_fcntl_timeout%& is set to a non-zero time, blocking locks, with that |
168e428f PH |
18617 | timeout, are used. There may still be some retrying: the maximum number of |
18618 | retries is | |
9b371988 PH |
18619 | .code |
18620 | (lock_retries * lock_interval) / lock_fcntl_timeout | |
18621 | .endd | |
168e428f | 18622 | rounded up to the next whole number. In other words, the total time during |
9b371988 PH |
18623 | which &(appendfile)& is trying to get a lock is roughly the same, unless |
18624 | &%lock_fcntl_timeout%& is set very large. | |
168e428f PH |
18625 | |
18626 | You should consider setting this option if you are getting a lot of delayed | |
18627 | local deliveries because of errors of the form | |
9b371988 PH |
18628 | .code |
18629 | failed to lock mailbox /some/file (fcntl) | |
18630 | .endd | |
168e428f | 18631 | |
9b371988 PH |
18632 | .option lock_flock_timeout appendfile time 0s |
18633 | This timeout applies to file locking when using &[flock()]& (see | |
18634 | &%use_flock%&); the timeout operates in a similar manner to | |
18635 | &%lock_fcntl_timeout%&. | |
168e428f PH |
18636 | |
18637 | ||
9b371988 | 18638 | .option lock_interval appendfile time 3s |
168e428f PH |
18639 | This specifies the time to wait between attempts to lock the file. See below |
18640 | for details of locking. | |
18641 | ||
18642 | ||
9b371988 | 18643 | .option lock_retries appendfile integer 10 |
168e428f PH |
18644 | This specifies the maximum number of attempts to lock the file. A value of zero |
18645 | is treated as 1. See below for details of locking. | |
18646 | ||
18647 | ||
9b371988 | 18648 | .option lockfile_mode appendfile "octal integer" 0600 |
168e428f | 18649 | This specifies the mode of the created lock file, when a lock file is being |
9b371988 | 18650 | used (see &%use_lockfile%&). |
168e428f PH |
18651 | |
18652 | ||
9b371988 PH |
18653 | .option lockfile_timeout appendfile time 30m |
18654 | .cindex "timeout" "mailbox locking" | |
18655 | When a lock file is being used (see &%use_lockfile%&), if a lock file already | |
168e428f PH |
18656 | exists and is older than this value, it is assumed to have been left behind by |
18657 | accident, and Exim attempts to remove it. | |
18658 | ||
18659 | ||
9b371988 PH |
18660 | .option mailbox_filecount appendfile string&!! unset |
18661 | .cindex "mailbox" "specifying size of" | |
18662 | .cindex "size" "of mailbox" | |
168e428f PH |
18663 | If this option is set, it is expanded, and the result is taken as the current |
18664 | number of files in the mailbox. It must be a decimal number, optionally | |
18665 | followed by K or M. This provides a way of obtaining this information from an | |
18666 | external source that maintains the data. | |
18667 | ||
18668 | ||
9b371988 PH |
18669 | .option mailbox_size appendfile string&!! unset |
18670 | .cindex "mailbox" "specifying size of" | |
18671 | .cindex "size" "of mailbox" | |
168e428f PH |
18672 | If this option is set, it is expanded, and the result is taken as the current |
18673 | size the mailbox. It must be a decimal number, optionally followed by K or M. | |
18674 | This provides a way of obtaining this information from an external source that | |
18675 | maintains the data. This is likely to be helpful for maildir deliveries where | |
18676 | it is computationally expensive to compute the size of a mailbox. | |
18677 | ||
18678 | ||
18679 | ||
9b371988 PH |
18680 | .option maildir_format appendfile boolean false |
18681 | .cindex "maildir format" "specifying" | |
18682 | If this option is set with the &%directory%& option, the delivery is into a new | |
18683 | file, in the &"maildir"& format that is used by other mail software. When the | |
18684 | transport is activated directly from a &(redirect)& router (for example, the | |
18685 | &(address_file)& transport in the default configuration), setting | |
18686 | &%maildir_format%& causes the path received from the router to be treated as a | |
18687 | directory, whether or not it ends with &`/`&. This option is available only if | |
18688 | SUPPORT_MAILDIR is present in &_Local/Makefile_&. See section | |
18689 | &<<SECTmaildirdelivery>>& below for further details. | |
168e428f PH |
18690 | |
18691 | ||
9b371988 PH |
18692 | .option maildir_quota_directory_regex appendfile string "See below" |
18693 | .cindex "maildir format" "quota; directories included in" | |
18694 | .cindex "quota" "maildir; directories included in" | |
18695 | This option is relevant only when &%maildir_use_size_file%& is set. It defines | |
168e428f PH |
18696 | a regular expression for specifying directories that should be included in the |
18697 | quota calculation. The default value is | |
9b371988 PH |
18698 | .code |
18699 | maildir_quota_directory_regex = ^(?:cur|new|\..*)$ | |
18700 | .endd | |
18701 | which includes the &_cur_& and &_new_& directories, and any maildir++ folders | |
168e428f | 18702 | (directories whose names begin with a dot). If you want to exclude the |
9b371988 | 18703 | &_Trash_& |
168e428f | 18704 | folder from the count (as some sites do), you need to change this setting to |
9b371988 PH |
18705 | .code |
18706 | maildir_quota_directory_regex = ^(?:cur|new|\.(?!Trash).*)$ | |
18707 | .endd | |
168e428f | 18708 | This uses a negative lookahead in the regular expression to exclude the |
9b371988 | 18709 | directory whose name is &_.Trash_&. |
168e428f | 18710 | |
168e428f | 18711 | |
9b371988 | 18712 | .option maildir_retries appendfile integer 10 |
168e428f | 18713 | This option specifies the number of times to retry when writing a file in |
9b371988 | 18714 | &"maildir"& format. See section &<<SECTmaildirdelivery>>& below. |
168e428f PH |
18715 | |
18716 | ||
9b371988 | 18717 | .option maildir_tag appendfile string&!! unset |
168e428f | 18718 | This option applies only to deliveries in maildir format, and is described in |
9b371988 | 18719 | section &<<SECTmaildirdelivery>>& below. |
168e428f PH |
18720 | |
18721 | ||
9b371988 PH |
18722 | .option maildir_use_size_file appendfile boolean false |
18723 | .cindex "maildir format" "&_maildirsize_& file" | |
18724 | Setting this option true enables support for &_maildirsize_& files. Exim | |
18725 | creates a &_maildirsize_& file in a maildir if one does not exist, taking the | |
18726 | quota from the &%quota%& option of the transport. If &%quota%& is unset, the | |
18727 | value is zero. See section &<<SECTmaildirdelivery>>& below for further details. | |
168e428f | 18728 | |
168e428f | 18729 | |
9b371988 PH |
18730 | .option mailstore_format appendfile boolean false |
18731 | .cindex "mailstore format" "specifying" | |
18732 | If this option is set with the &%directory%& option, the delivery is into two | |
18733 | new files in &"mailstore"& format. The option is available only if | |
18734 | SUPPORT_MAILSTORE is present in &_Local/Makefile_&. See section &<<SECTopdir>>& | |
18735 | below for further details. | |
168e428f | 18736 | |
168e428f | 18737 | |
9b371988 | 18738 | .option mailstore_prefix appendfile string&!! unset |
168e428f | 18739 | This option applies only to deliveries in mailstore format, and is described in |
9b371988 | 18740 | section &<<SECTopdir>>& below. |
168e428f PH |
18741 | |
18742 | ||
9b371988 | 18743 | .option mailstore_suffix appendfile string&!! unset |
168e428f | 18744 | This option applies only to deliveries in mailstore format, and is described in |
9b371988 | 18745 | section &<<SECTopdir>>& below. |
168e428f | 18746 | |
168e428f | 18747 | |
9b371988 PH |
18748 | .option mbx_format appendfile boolean false |
18749 | .cindex "locking files" | |
18750 | .cindex "file" "locking" | |
18751 | .cindex "file" "MBX format" | |
18752 | .cindex "MBX format" "specifying" | |
168e428f | 18753 | This option is available only if Exim has been compiled with SUPPORT_MBX |
9b371988 | 18754 | set in &_Local/Makefile_&. If &%mbx_format%& is set with the &%file%& option, |
168e428f PH |
18755 | the message is appended to the mailbox file in MBX format instead of |
18756 | traditional Unix format. This format is supported by Pine4 and its associated | |
9b371988 | 18757 | IMAP and POP daemons, by means of the &'c-client'& library that they all use. |
168e428f | 18758 | |
9b371988 PH |
18759 | &*Note*&: The &%message_prefix%& and &%message_suffix%& options are not |
18760 | automatically changed by the use of &%mbx_format%&. They should normally be set | |
168e428f PH |
18761 | empty when using MBX format, so this option almost always appears in this |
18762 | combination: | |
9b371988 PH |
18763 | .code |
18764 | mbx_format = true | |
18765 | message_prefix = | |
18766 | message_suffix = | |
18767 | .endd | |
168e428f | 18768 | If none of the locking options are mentioned in the configuration, |
9b371988 PH |
18769 | &%use_mbx_lock%& is assumed and the other locking options default to false. It |
18770 | is possible to specify the other kinds of locking with &%mbx_format%&, but | |
18771 | &%use_fcntl_lock%& and &%use_mbx_lock%& are mutually exclusive. MBX locking | |
18772 | interworks with &'c-client'&, providing for shared access to the mailbox. It | |
168e428f PH |
18773 | should not be used if any program that does not use this form of locking is |
18774 | going to access the mailbox, nor should it be used if the mailbox file is NFS | |
18775 | mounted, because it works only when the mailbox is accessed from a single host. | |
18776 | ||
9b371988 PH |
18777 | If you set &%use_fcntl_lock%& with an MBX-format mailbox, you cannot use |
18778 | the standard version of &'c-client'&, because as long as it has a mailbox open | |
168e428f PH |
18779 | (this means for the whole of a Pine or IMAP session), Exim will not be able to |
18780 | append messages to it. | |
18781 | ||
18782 | ||
9b371988 PH |
18783 | .option message_prefix appendfile string&!! "see below" |
18784 | .cindex "&""From""& line" | |
168e428f | 18785 | The string specified here is expanded and output at the start of every message. |
9b371988 PH |
18786 | The default is unset unless &%file%& is specified and &%use_bsmtp%& is not set, |
18787 | in which case it is: | |
18788 | .code | |
168e428f PH |
18789 | message_prefix = "From ${if def:return_path{$return_path}\ |
18790 | {MAILER-DAEMON}} $tod_bsdinbox\n" | |
9b371988 | 18791 | .endd |
168e428f PH |
18792 | |
18793 | ||
9b371988 | 18794 | .option message_suffix appendfile string&!! "see below" |
168e428f | 18795 | The string specified here is expanded and output at the end of every message. |
9b371988 PH |
18796 | The default is unset unless &%file%& is specified and &%use_bsmtp%& is not set, |
18797 | in which case it is a single newline character. The suffix can be suppressed by | |
168e428f | 18798 | setting |
9b371988 PH |
18799 | .code |
18800 | message_suffix = | |
18801 | .endd | |
168e428f | 18802 | |
9b371988 | 18803 | .option mode appendfile "octal integer" 0600 |
168e428f PH |
18804 | If the output file is created, it is given this mode. If it already exists and |
18805 | has wider permissions, they are reduced to this mode. If it has narrower | |
9b371988 PH |
18806 | permissions, an error occurs unless &%mode_fail_narrower%& is false. However, |
18807 | if the delivery is the result of a &%save%& command in a filter file specifing | |
18808 | a particular mode, the mode of the output file is always forced to take that | |
168e428f PH |
18809 | value, and this option is ignored. |
18810 | ||
18811 | ||
9b371988 | 18812 | .option mode_fail_narrower appendfile boolean true |
168e428f | 18813 | This option applies in the case when an existing mailbox file has a narrower |
9b371988 PH |
18814 | mode than that specified by the &%mode%& option. If &%mode_fail_narrower%& is |
18815 | true, the delivery is deferred (&"mailbox has the wrong mode"&); otherwise Exim | |
18816 | continues with the delivery attempt, using the existing mode of the file. | |
168e428f | 18817 | |
168e428f | 18818 | |
9b371988 PH |
18819 | .option notify_comsat appendfile boolean false |
18820 | If this option is true, the &'comsat'& daemon is notified after every | |
18821 | successful delivery to a user mailbox. This is the daemon that notifies logged | |
18822 | on users about incoming mail. | |
168e428f | 18823 | |
168e428f | 18824 | |
9b371988 PH |
18825 | .option quota appendfile string&!! unset |
18826 | .cindex "quota" "imposed by Exim" | |
168e428f | 18827 | This option imposes a limit on the size of the file to which Exim is appending, |
9b371988 PH |
18828 | or to the total space used in the directory tree when the &%directory%& option |
18829 | is set. In the latter case, computation of the space used is expensive, because | |
168e428f | 18830 | all the files in the directory (and any sub-directories) have to be |
9b371988 PH |
18831 | individually inspected and their sizes summed. (See &%quota_size_regex%& and |
18832 | &%maildir_use_size_file%& for ways to avoid this in environments where users | |
18833 | have no shell access to their mailboxes). | |
168e428f PH |
18834 | |
18835 | As there is no interlock against two simultaneous deliveries into a | |
18836 | multi-file mailbox, it is possible for the quota to be overrun in this case. | |
18837 | For single-file mailboxes, of course, an interlock is a necessity. | |
18838 | ||
9b371988 | 18839 | A file's size is taken as its &'used'& value. Because of blocking effects, this |
168e428f PH |
18840 | may be a lot less than the actual amount of disk space allocated to the file. |
18841 | If the sizes of a number of files are being added up, the rounding effect can | |
18842 | become quite noticeable, especially on systems that have large block sizes. | |
9b371988 | 18843 | Nevertheless, it seems best to stick to the &'used'& figure, because this is |
168e428f PH |
18844 | the obvious value which users understand most easily. |
18845 | ||
9b371988 | 18846 | .new |
168e428f | 18847 | The value of the option is expanded, and must then be a numerical value |
068aaea8 PH |
18848 | (decimal point allowed), optionally followed by one of the letters K, M, or G, |
18849 | for kilobytes, megabytes, or gigabytes. If Exim is running on a system with | |
18850 | large file support (Linux and FreeBSD have this), mailboxes larger than 2G can | |
18851 | be handled. | |
9b371988 | 18852 | .wen |
168e428f | 18853 | |
9b371988 | 18854 | &*Note*&: A value of zero is interpreted as &"no quota"&. |
168e428f | 18855 | |
068aaea8 PH |
18856 | The expansion happens while Exim is running as root, before it changes uid for |
18857 | the delivery. This means that files that are inaccessible to the end user can | |
18858 | be used to hold quota values that are looked up in the expansion. When delivery | |
18859 | fails because this quota is exceeded, the handling of the error is as for | |
18860 | system quota failures. | |
18861 | ||
168e428f PH |
18862 | By default, Exim's quota checking mimics system quotas, and restricts the |
18863 | mailbox to the specified maximum size, though the value is not accurate to the | |
18864 | last byte, owing to separator lines and additional headers that may get added | |
18865 | during message delivery. When a mailbox is nearly full, large messages may get | |
18866 | refused even though small ones are accepted, because the size of the current | |
18867 | message is added to the quota when the check is made. This behaviour can be | |
9b371988 | 18868 | changed by setting &%quota_is_inclusive%& false. When this is done, the check |
168e428f PH |
18869 | for exceeding the quota does not include the current message. Thus, deliveries |
18870 | continue until the quota has been exceeded; thereafter, no further messages are | |
9b371988 | 18871 | delivered. See also &%quota_warn_threshold%&. |
168e428f | 18872 | |
168e428f | 18873 | |
9b371988 | 18874 | .option quota_directory appendfile string&!! unset |
168e428f PH |
18875 | This option defines the directory to check for quota purposes when delivering |
18876 | into individual files. The default is the delivery directory, or, if a file | |
9b371988 | 18877 | called &_maildirfolder_& exists in a maildir directory, the parent of the |
168e428f PH |
18878 | delivery directory. |
18879 | ||
18880 | ||
9b371988 PH |
18881 | .option quota_filecount appendfile string&!! 0 |
18882 | This option applies when the &%directory%& option is set. It limits the total | |
168e428f | 18883 | number of files in the directory (compare the inode limit in system quotas). It |
9b371988 | 18884 | can only be used if &%quota%& is also set. The value is expanded; an expansion |
168e428f PH |
18885 | failure causes delivery to be deferred. |
18886 | ||
18887 | ||
9b371988 PH |
18888 | .option quota_is_inclusive appendfile boolean true |
18889 | See &%quota%& above. | |
168e428f PH |
18890 | |
18891 | ||
9b371988 | 18892 | .option quota_size_regex appendfile string unset |
168e428f PH |
18893 | This option applies when one of the delivery modes that writes a separate file |
18894 | for each message is being used. When Exim wants to find the size of one of | |
9b371988 | 18895 | these files in order to test the quota, it first checks &%quota_size_regex%&. |
168e428f PH |
18896 | If this is set to a regular expression that matches the file name, and it |
18897 | captures one string, that string is interpreted as a representation of the | |
9b371988 | 18898 | file's size. The value of &%quota_size_regex%& is not expanded. |
168e428f PH |
18899 | |
18900 | This feature is useful only when users have no shell access to their mailboxes | |
9b371988 PH |
18901 | &-- otherwise they could defeat the quota simply by renaming the files. This |
18902 | facility can be used with maildir deliveries, by setting &%maildir_tag%& to add | |
168e428f | 18903 | the file length to the file name. For example: |
9b371988 PH |
18904 | .code |
18905 | maildir_tag = ,S=$message_size | |
18906 | quota_size_regex = ,S=(\d+) | |
18907 | .endd | |
18908 | .new | |
18909 | An alternative to &$message_size$& is &$message_linecount$&, which contains the | |
068aaea8 | 18910 | number of lines in the message. |
9b371988 | 18911 | .wen |
068aaea8 | 18912 | |
168e428f | 18913 | The regular expression should not assume that the length is at the end of the |
9b371988 | 18914 | file name (even though &%maildir_tag%& puts it there) because maildir MUAs |
168e428f PH |
18915 | sometimes add other information onto the ends of message file names. |
18916 | ||
18917 | ||
068aaea8 | 18918 | |
9b371988 | 18919 | .option quota_warn_message appendfile string&!! "see below" |
168e428f | 18920 | See below for the use of this option. If it is not set when |
9b371988 PH |
18921 | &%quota_warn_threshold%& is set, it defaults to |
18922 | .code | |
168e428f PH |
18923 | quota_warn_message = "\ |
18924 | To: $local_part@$domain\n\ | |
18925 | Subject: Your mailbox\n\n\ | |
18926 | This message is automatically created \ | |
18927 | by mail delivery software.\n\n\ | |
18928 | The size of your mailbox has exceeded \ | |
18929 | a warning threshold that is\n\ | |
18930 | set by the system administrator.\n" | |
9b371988 | 18931 | .endd |
168e428f PH |
18932 | |
18933 | ||
9b371988 PH |
18934 | .option quota_warn_threshold appendfile string&!! 0 |
18935 | .cindex "quota" "warning threshold" | |
18936 | .cindex "mailbox" "size warning" | |
18937 | .cindex "size" "of mailbox" | |
18938 | This option is expanded in the same way as &%quota%& (see above). If the | |
168e428f PH |
18939 | resulting value is greater than zero, and delivery of the message causes the |
18940 | size of the file or total space in the directory tree to cross the given | |
9b371988 PH |
18941 | threshold, a warning message is sent. If &%quota%& is also set, the threshold |
18942 | may be specified as a percentage of it by following the value with a percent | |
18943 | sign. For example: | |
18944 | .code | |
18945 | quota = 10M | |
18946 | quota_warn_threshold = 75% | |
18947 | .endd | |
18948 | If &%quota%& is not set, a setting of &%quota_warn_threshold%& that ends with a | |
168e428f PH |
18949 | percent sign is ignored. |
18950 | ||
9b371988 PH |
18951 | .new |
18952 | The warning message itself is specified by the &%quota_warn_message%& option, | |
18953 | and it must start with a &'To:'& header line containing the recipient(s) of the | |
068aaea8 | 18954 | warning message. These do not necessarily have to include the recipient(s) of |
9b371988 | 18955 | the original message. A &'Subject:'& line should also normally be supplied. You |
068aaea8 | 18956 | can include any other header lines that you want. |
9b371988 | 18957 | .wen |
068aaea8 | 18958 | |
9b371988 | 18959 | The &%quota%& option does not have to be set in order to use this option; they |
068aaea8 PH |
18960 | are independent of one another except when the threshold is specified as a |
18961 | percentage. | |
168e428f PH |
18962 | |
18963 | ||
9b371988 PH |
18964 | .option use_bsmtp appendfile boolean false |
18965 | .cindex "envelope sender" | |
18966 | If this option is set true, &(appendfile)& writes messages in &"batch SMTP"& | |
168e428f PH |
18967 | format, with the envelope sender and recipient(s) included as SMTP commands. If |
18968 | you want to include a leading HELO command with such messages, you can do | |
9b371988 PH |
18969 | so by setting the &%message_prefix%& option. See section &<<SECTbatchSMTP>>& |
18970 | for details of batch SMTP. | |
168e428f | 18971 | |
168e428f | 18972 | |
9b371988 PH |
18973 | .option use_crlf appendfile boolean false |
18974 | .cindex "carriage return" | |
18975 | .cindex "linefeed" | |
168e428f PH |
18976 | This option causes lines to be terminated with the two-character CRLF sequence |
18977 | (carriage return, linefeed) instead of just a linefeed character. In the case | |
18978 | of batched SMTP, the byte sequence written to the file is then an exact image | |
18979 | of what would be sent down a real SMTP connection. | |
18980 | ||
9b371988 PH |
18981 | The contents of the &%message_prefix%& and &%message_suffix%& options are |
18982 | written verbatim, so must contain their own carriage return characters if these | |
18983 | are needed. In cases where these options have non-empty defaults, the values | |
18984 | end with a single linefeed, so they must be changed to end with &`\r\n`& if | |
18985 | &%use_crlf%& is set. | |
168e428f PH |
18986 | |
18987 | ||
9b371988 PH |
18988 | .option use_fcntl_lock appendfile boolean "see below" |
18989 | This option controls the use of the &[fcntl()]& function to lock a file for | |
168e428f | 18990 | exclusive use when a message is being appended. It is set by default unless |
9b371988 PH |
18991 | &%use_flock_lock%& is set. Otherwise, it should be turned off only if you know |
18992 | that all your MUAs use lock file locking. When both &%use_fcntl_lock%& and | |
18993 | &%use_flock_lock%& are unset, &%use_lockfile%& must be set. | |
168e428f | 18994 | |
168e428f | 18995 | |
9b371988 PH |
18996 | .option use_flock_lock appendfile boolean false |
18997 | This option is provided to support the use of &[flock()]& for file locking, for | |
168e428f | 18998 | the few situations where it is needed. Most modern operating systems support |
9b371988 PH |
18999 | &[fcntl()]& and &[lockf()]& locking, and these two functions interwork with |
19000 | each other. Exim uses &[fcntl()]& locking by default. | |
168e428f PH |
19001 | |
19002 | This option is required only if you are using an operating system where | |
9b371988 PH |
19003 | &[flock()]& is used by programs that access mailboxes (typically MUAs), and |
19004 | where &[flock()]& does not correctly interwork with &[fcntl()]&. You can use | |
19005 | both &[fcntl()]& and &[flock()]& locking simultaneously if you want. | |
168e428f | 19006 | |
9b371988 PH |
19007 | .cindex "Solaris" "&[flock()]& support" |
19008 | Not all operating systems provide &[flock()]&. Some versions of Solaris do not | |
168e428f | 19009 | have it (and some, I think, provide a not quite right version built on top of |
9b371988 | 19010 | &[lockf()]&). If the OS does not have &[flock()]&, Exim will be built without |
168e428f PH |
19011 | the ability to use it, and any attempt to do so will cause a configuration |
19012 | error. | |
19013 | ||
9b371988 PH |
19014 | &*Warning*&: &[flock()]& locks do not work on NFS files (unless &[flock()]& |
19015 | is just being mapped onto &[fcntl()]& by the OS). | |
168e428f PH |
19016 | |
19017 | ||
9b371988 | 19018 | .option use_lockfile appendfile boolean "see below" |
168e428f PH |
19019 | If this option is turned off, Exim does not attempt to create a lock file when |
19020 | appending to a mailbox file. In this situation, the only locking is by | |
9b371988 | 19021 | &[fcntl()]&. You should only turn &%use_lockfile%& off if you are absolutely |
168e428f | 19022 | sure that every MUA that is ever going to look at your users' mailboxes uses |
9b371988 | 19023 | &[fcntl()]& rather than a lock file, and even then only when you are not |
168e428f PH |
19024 | delivering over NFS from more than one host. |
19025 | ||
9b371988 | 19026 | .cindex "NFS" "lock file" |
168e428f | 19027 | In order to append to an NFS file safely from more than one host, it is |
9b371988 PH |
19028 | necessary to take out a lock &'before'& opening the file, and the lock file |
19029 | achieves this. Otherwise, even with &[fcntl()]& locking, there is a risk of | |
168e428f PH |
19030 | file corruption. |
19031 | ||
9b371988 PH |
19032 | The &%use_lockfile%& option is set by default unless &%use_mbx_lock%& is set. |
19033 | It is not possible to turn both &%use_lockfile%& and &%use_fcntl_lock%& off, | |
19034 | except when &%mbx_format%& is set. | |
168e428f | 19035 | |
168e428f | 19036 | |
9b371988 | 19037 | .option use_mbx_lock appendfile boolean "see below" |
168e428f | 19038 | This option is available only if Exim has been compiled with SUPPORT_MBX |
9b371988 PH |
19039 | set in &_Local/Makefile_&. Setting the option specifies that special MBX |
19040 | locking rules be used. It is set by default if &%mbx_format%& is set and none | |
19041 | of the locking options are mentioned in the configuration. The locking rules | |
19042 | are the same as are used by the &'c-client'& library that underlies Pine and | |
19043 | the IMAP4 and POP daemons that come with it (see the discussion below). The | |
19044 | rules allow for shared access to the mailbox. However, this kind of locking | |
19045 | does not work when the mailbox is NFS mounted. | |
168e428f | 19046 | |
9b371988 PH |
19047 | You can set &%use_mbx_lock%& with either (or both) of &%use_fcntl_lock%& and |
19048 | &%use_flock_lock%& to control what kind of locking is used in implementing the | |
19049 | MBX locking rules. The default is to use &[fcntl()]& if &%use_mbx_lock%& is set | |
19050 | without &%use_fcntl_lock%& or &%use_flock_lock%&. | |
168e428f PH |
19051 | |
19052 | ||
19053 | ||
19054 | ||
9b371988 PH |
19055 | .section "Operational details for appending" "SECTopappend" |
19056 | .cindex "appending to a file" | |
19057 | .cindex "file" "appending" | |
168e428f PH |
19058 | Before appending to a file, the following preparations are made: |
19059 | ||
9b371988 PH |
19060 | .ilist |
19061 | If the name of the file is &_/dev/null_&, no action is taken, and a success | |
168e428f PH |
19062 | return is given. |
19063 | ||
9b371988 PH |
19064 | .next |
19065 | .cindex "directory creation" | |
168e428f | 19066 | If any directories on the file's path are missing, Exim creates them if the |
9b371988 PH |
19067 | &%create_directory%& option is set. A created directory's mode is given by the |
19068 | &%directory_mode%& option. | |
168e428f | 19069 | |
9b371988 PH |
19070 | .next |
19071 | If &%file_format%& is set, the format of an existing file is checked. If this | |
168e428f PH |
19072 | indicates that a different transport should be used, control is passed to that |
19073 | transport. | |
19074 | ||
9b371988 PH |
19075 | .next |
19076 | .cindex "file" "locking" | |
19077 | .cindex "locking files" | |
19078 | .cindex "NFS" "lock file" | |
19079 | If &%use_lockfile%& is set, a lock file is built in a way that will work | |
168e428f | 19080 | reliably over NFS, as follows: |
9b371988 PH |
19081 | |
19082 | .olist | |
19083 | Create a &"hitching post"& file whose name is that of the lock file with the | |
168e428f PH |
19084 | current time, primary host name, and process id added, by opening for writing |
19085 | as a new file. If this fails with an access error, delivery is deferred. | |
9b371988 PH |
19086 | .next |
19087 | Close the hitching post file, and hard link it to the lock file name. | |
19088 | .next | |
19089 | If the call to &[link()]& succeeds, creation of the lock file has succeeded. | |
168e428f | 19090 | Unlink the hitching post name. |
9b371988 PH |
19091 | .next |
19092 | Otherwise, use &[stat()]& to get information about the hitching post file, and | |
168e428f PH |
19093 | then unlink hitching post name. If the number of links is exactly two, creation |
19094 | of the lock file succeeded but something (for example, an NFS server crash and | |
9b371988 PH |
19095 | restart) caused this fact not to be communicated to the &[link()]& call. |
19096 | .next | |
19097 | If creation of the lock file failed, wait for &%lock_interval%& and try again, | |
19098 | up to &%lock_retries%& times. However, since any program that writes to a | |
168e428f PH |
19099 | mailbox should complete its task very quickly, it is reasonable to time out old |
19100 | lock files that are normally the result of user agent and system crashes. If an | |
9b371988 PH |
19101 | existing lock file is older than &%lockfile_timeout%& Exim attempts to unlink |
19102 | it before trying again. | |
19103 | .endlist olist | |
19104 | ||
19105 | .next | |
19106 | A call is made to &[lstat()]& to discover whether the main file exists, and if | |
19107 | so, what its characteristics are. If &[lstat()]& fails for any reason other | |
168e428f PH |
19108 | than non-existence, delivery is deferred. |
19109 | ||
9b371988 PH |
19110 | .next |
19111 | .cindex "symbolic link" "to mailbox" | |
19112 | .cindex "mailbox" "symbolic link" | |
168e428f | 19113 | If the file does exist and is a symbolic link, delivery is deferred, unless the |
9b371988 PH |
19114 | &%allow_symlink%& option is set, in which case the ownership of the link is |
19115 | checked, and then &[stat()]& is called to find out about the real file, which | |
168e428f PH |
19116 | is then subjected to the checks below. The check on the top-level link |
19117 | ownership prevents one user creating a link for another's mailbox in a sticky | |
19118 | directory, though allowing symbolic links in this case is definitely not a good | |
19119 | idea. If there is a chain of symbolic links, the intermediate ones are not | |
19120 | checked. | |
19121 | ||
9b371988 PH |
19122 | .next |
19123 | If the file already exists but is not a regular file, or if the file's owner | |
19124 | and group (if the group is being checked &-- see &%check_group%& above) are | |
168e428f PH |
19125 | different from the user and group under which the delivery is running, |
19126 | delivery is deferred. | |
19127 | ||
9b371988 PH |
19128 | .next |
19129 | If the file's permissions are more generous than specified, they are reduced. | |
19130 | If they are insufficient, delivery is deferred, unless &%mode_fail_narrower%& | |
168e428f PH |
19131 | is set false, in which case the delivery is tried using the existing |
19132 | permissions. | |
19133 | ||
9b371988 PH |
19134 | .next |
19135 | The file's inode number is saved, and the file is then opened for appending. | |
19136 | If this fails because the file has vanished, &(appendfile)& behaves as if it | |
168e428f PH |
19137 | hadn't existed (see below). For any other failures, delivery is deferred. |
19138 | ||
9b371988 PH |
19139 | .next |
19140 | If the file is opened successfully, check that the inode number hasn't | |
168e428f PH |
19141 | changed, that it is still a regular file, and that the owner and permissions |
19142 | have not changed. If anything is wrong, defer delivery and freeze the message. | |
19143 | ||
9b371988 PH |
19144 | .next |
19145 | If the file did not exist originally, defer delivery if the &%file_must_exist%& | |
168e428f | 19146 | option is set. Otherwise, check that the file is being created in a permitted |
9b371988 | 19147 | directory if the &%create_file%& option is set (deferring on failure), and then |
168e428f | 19148 | open for writing as a new file, with the O_EXCL and O_CREAT options, |
9b371988 | 19149 | except when dealing with a symbolic link (the &%allow_symlink%& option must be |
168e428f PH |
19150 | set). In this case, which can happen if the link points to a non-existent file, |
19151 | the file is opened for writing using O_CREAT but not O_EXCL, because | |
19152 | that prevents link following. | |
19153 | ||
9b371988 PH |
19154 | .next |
19155 | .cindex "loop" "while file testing" | |
168e428f PH |
19156 | If opening fails because the file exists, obey the tests given above for |
19157 | existing files. However, to avoid looping in a situation where the file is | |
19158 | being continuously created and destroyed, the exists/not-exists loop is broken | |
19159 | after 10 repetitions, and the message is then frozen. | |
19160 | ||
9b371988 PH |
19161 | .next |
19162 | If opening fails with any other error, defer delivery. | |
19163 | ||
19164 | .next | |
19165 | .cindex "file" "locking" | |
19166 | .cindex "locking files" | |
19167 | Once the file is open, unless both &%use_fcntl_lock%& and &%use_flock_lock%& | |
19168 | are false, it is locked using &[fcntl()]& or &[flock()]& or both. If | |
19169 | &%use_mbx_lock%& is false, an exclusive lock is requested in each case. | |
19170 | However, if &%use_mbx_lock%& is true, Exim takes out a shared lock on the open | |
19171 | file, and an exclusive lock on the file whose name is | |
19172 | .code | |
19173 | /tmp/.<device-number>.<inode-number> | |
19174 | .endd | |
168e428f PH |
19175 | using the device and inode numbers of the open mailbox file, in accordance with |
19176 | the MBX locking rules. | |
9b371988 | 19177 | |
168e428f PH |
19178 | If Exim fails to lock the file, there are two possible courses of action, |
19179 | depending on the value of the locking timeout. This is obtained from | |
9b371988 PH |
19180 | &%lock_fcntl_timeout%& or &%lock_flock_timeout%&, as appropriate. |
19181 | ||
168e428f | 19182 | If the timeout value is zero, the file is closed, Exim waits for |
9b371988 PH |
19183 | &%lock_interval%&, and then goes back and re-opens the file as above and tries |
19184 | to lock it again. This happens up to &%lock_retries%& times, after which the | |
168e428f | 19185 | delivery is deferred. |
9b371988 PH |
19186 | |
19187 | If the timeout has a value greater than zero, blocking calls to &[fcntl()]& or | |
19188 | &[flock()]& are used (with the given timeout), so there has already been some | |
168e428f PH |
19189 | waiting involved by the time locking fails. Nevertheless, Exim does not give up |
19190 | immediately. It retries up to | |
9b371988 PH |
19191 | .code |
19192 | (lock_retries * lock_interval) / <timeout> | |
19193 | .endd | |
168e428f | 19194 | times (rounded up). |
9b371988 | 19195 | .endlist |
168e428f | 19196 | |
9b371988 PH |
19197 | At the end of delivery, Exim closes the file (which releases the &[fcntl()]& |
19198 | and/or &[flock()]& locks) and then deletes the lock file if one was created. | |
168e428f | 19199 | |
168e428f | 19200 | |
9b371988 PH |
19201 | .section "Operational details for delivery to a new file" "SECTopdir" |
19202 | .cindex "delivery" "to single file" | |
19203 | .cindex "&""From""& line" | |
19204 | When the &%directory%& option is set instead of &%file%&, each message is | |
19205 | delivered into a newly-created file or set of files. When &(appendfile)& is | |
19206 | activated directly from a &(redirect)& router, neither &%file%& nor | |
19207 | &%directory%& is normally set, because the path for delivery is supplied by the | |
19208 | router. (See for example, the &(address_file)& transport in the default | |
19209 | configuration.) In this case, delivery is to a new file if either the path name | |
19210 | ends in &`/`&, or the &%maildir_format%& or &%mailstore_format%& option is set. | |
168e428f PH |
19211 | |
19212 | No locking is required while writing the message to a new file, so the various | |
9b371988 | 19213 | locking options of the transport are ignored. The &"From"& line that by default |
168e428f | 19214 | separates messages in a single file is not normally needed, nor is the escaping |
9b371988 | 19215 | of message lines that start with &"From"&, and there is no need to ensure a |
168e428f | 19216 | newline at the end of each message. Consequently, the default values for |
9b371988 PH |
19217 | &%check_string%&, &%message_prefix%&, and &%message_suffix%& are all unset when |
19218 | any of &%directory%&, &%maildir_format%&, or &%mailstore_format%& is set. | |
168e428f | 19219 | |
9b371988 PH |
19220 | If Exim is required to check a &%quota%& setting, it adds up the sizes of all |
19221 | the files in the delivery directory by default. However, you can specify a | |
19222 | different directory by setting &%quota_directory%&. Also, for maildir | |
19223 | deliveries (see below) the &_maildirfolder_& convention is honoured. | |
168e428f PH |
19224 | |
19225 | ||
9b371988 PH |
19226 | .cindex "maildir format" |
19227 | .cindex "mailstore format" | |
168e428f | 19228 | There are three different ways in which delivery to individual files can be |
9b371988 PH |
19229 | done, controlled by the settings of the &%maildir_format%& and |
19230 | &%mailstore_format%& options. Note that code to support maildir or mailstore | |
168e428f | 19231 | formats is not included in the binary unless SUPPORT_MAILDIR or |
9b371988 | 19232 | SUPPORT_MAILSTORE, respectively, is set in &_Local/Makefile_&. |
168e428f | 19233 | |
9b371988 | 19234 | .cindex "directory creation" |
168e428f | 19235 | In all three cases an attempt is made to create the directory and any necessary |
9b371988 | 19236 | sub-directories if they do not exist, provided that the &%create_directory%& |
168e428f | 19237 | option is set (the default). The location of a created directory can be |
9b371988 PH |
19238 | constrained by setting &%create_file%&. A created directory's mode is given by |
19239 | the &%directory_mode%& option. If creation fails, or if the | |
19240 | &%create_directory%& option is not set when creation is required, delivery is | |
19241 | deferred. | |
168e428f PH |
19242 | |
19243 | ||
19244 | ||
9b371988 PH |
19245 | .section "Maildir delivery" "SECTmaildirdelivery" |
19246 | .cindex "maildir format" "description of" | |
19247 | If the &%maildir_format%& option is true, Exim delivers each message by writing | |
19248 | it to a file whose name is &_tmp/<stime>.H<mtime>P<pid>.<host>_& in the | |
168e428f | 19249 | given directory. If the delivery is successful, the file is renamed into the |
9b371988 | 19250 | &_new_& subdirectory. |
168e428f | 19251 | |
9b371988 PH |
19252 | In the file name, <&'stime'&> is the current time of day in seconds, and |
19253 | <&'mtime'&> is the microsecond fraction of the time. After a maildir delivery, | |
168e428f PH |
19254 | Exim checks that the time-of-day clock has moved on by at least one microsecond |
19255 | before terminating the delivery process. This guarantees uniqueness for the | |
9b371988 | 19256 | file name. However, as a precaution, Exim calls &[stat()]& for the file before |
168e428f | 19257 | opening it. If any response other than ENOENT (does not exist) is given, |
9b371988 | 19258 | Exim waits 2 seconds and tries again, up to &%maildir_retries%& times. |
168e428f | 19259 | |
9b371988 PH |
19260 | .cindex "quota" "in maildir delivery" |
19261 | .cindex "maildir++" | |
19262 | If Exim is required to check a &%quota%& setting before a maildir delivery, and | |
19263 | &%quota_directory%& is not set, it looks for a file called &_maildirfolder_& in | |
19264 | the maildir directory (alongside &_new_&, &_cur_&, &_tmp_&). If this exists, | |
168e428f PH |
19265 | Exim assumes the directory is a maildir++ folder directory, which is one level |
19266 | down from the user's top level mailbox directory. This causes it to start at | |
19267 | the parent directory instead of the current directory when calculating the | |
19268 | amount of space used. | |
19269 | ||
19270 | One problem with delivering into a multi-file mailbox is that it is | |
19271 | computationally expensive to compute the size of the mailbox for quota | |
19272 | checking. Various approaches have been taken to reduce the amount of work | |
19273 | needed. The next two sections describe two of them. A third alternative is to | |
19274 | use some external process for maintaining the size data, and use the expansion | |
9b371988 | 19275 | of the &%mailbox_size%& option as a way of importing it into Exim. |
168e428f PH |
19276 | |
19277 | ||
19278 | ||
19279 | ||
9b371988 PH |
19280 | .section "Using tags to record message sizes" |
19281 | If &%maildir_tag%& is set, the string is expanded for each delivery. | |
19282 | When the maildir file is renamed into the &_new_& sub-directory, the | |
168e428f | 19283 | tag is added to its name. However, if adding the tag takes the length of the |
9b371988 | 19284 | name to the point where the test &[stat()]& call fails with ENAMETOOLONG, |
168e428f PH |
19285 | the tag is dropped and the maildir file is created with no tag. |
19286 | ||
9b371988 | 19287 | .cindex "&$message_size$&" |
168e428f | 19288 | Tags can be used to encode the size of files in their names; see |
9b371988 PH |
19289 | &%quota_size_regex%& above for an example. The expansion of &%maildir_tag%& |
19290 | happens after the message has been written. The value of the &$message_size$& | |
19291 | variable is set to the number of bytes actually written. If the expansion is | |
19292 | forced to fail, the tag is ignored, but a non-forced failure causes delivery to | |
19293 | be deferred. The expanded tag may contain any printing characters except &"/"&. | |
168e428f PH |
19294 | Non-printing characters in the string are ignored; if the resulting string is |
19295 | empty, it is ignored. If it starts with an alphanumeric character, a leading | |
19296 | colon is inserted. | |
19297 | ||
19298 | ||
19299 | ||
9b371988 PH |
19300 | .section "Using a maildirsize file" |
19301 | .cindex "quota" "in maildir delivery" | |
19302 | .cindex "maildir format" "&_maildirsize_& file" | |
19303 | If &%maildir_use_size_file%& is true, Exim implements the maildir++ rules for | |
19304 | storing quota and message size information in a file called &_maildirsize_& | |
168e428f | 19305 | within the maildir directory. If this file does not exist, Exim creates it, |
9b371988 | 19306 | setting the quota from the &%quota%& option of the transport. If the maildir |
168e428f | 19307 | directory itself does not exist, it is created before any attempt to write a |
9b371988 | 19308 | &_maildirsize_& file. |
168e428f | 19309 | |
9b371988 | 19310 | The &_maildirsize_& file is used to hold information about the sizes of |
168e428f PH |
19311 | messages in the maildir, thus speeding up quota calculations. The quota value |
19312 | in the file is just a cache; if the quota is changed in the transport, the new | |
19313 | value overrides the cached value when the next message is delivered. The cache | |
19314 | is maintained for the benefit of other programs that access the maildir and | |
19315 | need to know the quota. | |
19316 | ||
9b371988 | 19317 | If the &%quota%& option in the transport is unset or zero, the &_maildirsize_& |
168e428f PH |
19318 | file is maintained (with a zero quota setting), but no quota is imposed. |
19319 | ||
19320 | A regular expression is available for controlling which directories in the | |
19321 | maildir participate in quota calculations. See the description of the | |
9b371988 | 19322 | &%maildir_quota_directory_regex%& option above for details. |
168e428f PH |
19323 | |
19324 | ||
19325 | ||
9b371988 PH |
19326 | .section "Mailstore delivery" |
19327 | .cindex "mailstore format" "description of" | |
19328 | If the &%mailstore_format%& option is true, each message is written as two | |
19329 | files in the given directory. A unique base name is constructed from the | |
19330 | message id and the current delivery process, and the files that are written use | |
19331 | this base name plus the suffixes &_.env_& and &_.msg_&. The &_.env_& file | |
19332 | contains the message's envelope, and the &_.msg_& file contains the message | |
19333 | itself. The base name is placed in the variable &$mailstore_basename$&. | |
168e428f PH |
19334 | |
19335 | During delivery, the envelope is first written to a file with the suffix | |
9b371988 PH |
19336 | &_.tmp_&. The &_.msg_& file is then written, and when it is complete, the |
19337 | &_.tmp_& file is renamed as the &_.env_& file. Programs that access messages in | |
19338 | mailstore format should wait for the presence of both a &_.msg_& and a &_.env_& | |
168e428f | 19339 | file before accessing either of them. An alternative approach is to wait for |
9b371988 | 19340 | the absence of a &_.tmp_& file. |
168e428f | 19341 | |
9b371988 | 19342 | The envelope file starts with any text defined by the &%mailstore_prefix%& |
168e428f PH |
19343 | option, expanded and terminated by a newline if there isn't one. Then follows |
19344 | the sender address on one line, then all the recipient addresses, one per line. | |
9b371988 PH |
19345 | There can be more than one recipient only if the &%batch_max%& option is set |
19346 | greater than one. Finally, &%mailstore_suffix%& is expanded and the result | |
168e428f PH |
19347 | appended to the file, followed by a newline if it does not end with one. |
19348 | ||
9b371988 PH |
19349 | .new |
19350 | If expansion of &%mailstore_prefix%& or &%mailstore_suffix%& ends with a forced | |
168e428f | 19351 | failure, it is ignored. Other expansion errors are treated as serious |
068aaea8 | 19352 | configuration errors, and delivery is deferred. The variable |
9b371988 PH |
19353 | &$mailstore_basename$& is available for use during these expansions. |
19354 | .wen | |
168e428f PH |
19355 | |
19356 | ||
9b371988 PH |
19357 | .section "Non-special new file delivery" |
19358 | If neither &%maildir_format%& nor &%mailstore_format%& is set, a single new | |
19359 | file is created directly in the named directory. For example, when delivering | |
168e428f | 19360 | messages into files in batched SMTP format for later delivery to some host (see |
9b371988 PH |
19361 | section &<<SECTbatchSMTP>>&), a setting such as |
19362 | .code | |
19363 | directory = /var/bsmtp/$host | |
19364 | .endd | |
168e428f PH |
19365 | might be used. A message is written to a file with a temporary name, which is |
19366 | then renamed when the delivery is complete. The final name is obtained by | |
9b371988 | 19367 | expanding the contents of the &%directory_file%& option. |
168e428f PH |
19368 | |
19369 | ||
19370 | ||
19371 | ||
19372 | ||
19373 | ||
9b371988 PH |
19374 | . //////////////////////////////////////////////////////////////////////////// |
19375 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 19376 | |
9b371988 PH |
19377 | .chapter "The autoreply transport" |
19378 | .cindex "transports" "&(autoreply)&" | |
19379 | .cindex "&(autoreply)& transport" | |
19380 | The &(autoreply)& transport is not a true transport in that it does not cause | |
168e428f PH |
19381 | the message to be transmitted. Instead, it generates a new mail message. |
19382 | ||
19383 | If the router that passes the message to this transport does not have the | |
9b371988 PH |
19384 | &%unseen%& option set, the original message (for the current recipient) is not |
19385 | delivered anywhere. However, when the &%unseen%& option is set on the router | |
19386 | that passes the message to this transport, routing of the address continues, so | |
168e428f PH |
19387 | another router can set up a normal message delivery. |
19388 | ||
19389 | ||
9b371988 PH |
19390 | The &(autoreply)& transport is usually run as the result of mail filtering, a |
19391 | &"vacation"& message being the standard example. However, it can also be run | |
168e428f | 19392 | directly from a router like any other transport. To reduce the possibility of |
9b371988 | 19393 | message cascades, messages created by the &(autoreply)& transport always have |
168e428f PH |
19394 | empty envelope sender addresses, like bounce messages. |
19395 | ||
19396 | The parameters of the message to be sent can be specified in the configuration | |
19397 | by options described below. However, these are used only when the address | |
19398 | passed to the transport does not contain its own reply information. When the | |
19399 | transport is run as a consequence of a | |
9b371988 PH |
19400 | &%mail%& |
19401 | or &%vacation%& command in a filter file, the parameters of the message are | |
168e428f PH |
19402 | supplied by the filter, and passed with the address. The transport's options |
19403 | that define the message are then ignored (so they are not usually set in this | |
19404 | case). The message is specified entirely by the filter or by the transport; it | |
9b371988 PH |
19405 | is never built from a mixture of options. However, the &%file_optional%&, |
19406 | &%mode%&, and &%return_message%& options apply in all cases. | |
168e428f | 19407 | |
9b371988 PH |
19408 | &(Autoreply)& is implemented as a local transport. When used as a result of a |
19409 | command in a user's filter file, &(autoreply)& normally runs under the uid and | |
168e428f | 19410 | gid of the user, and with appropriate current and home directories (see chapter |
9b371988 | 19411 | &<<CHAPenvironment>>&). |
168e428f | 19412 | |
9b371988 | 19413 | There is a subtle difference between routing a message to a &(pipe)& transport |
168e428f | 19414 | that generates some text to be returned to the sender, and routing it to an |
9b371988 | 19415 | &(autoreply)& transport. This difference is noticeable only if more than one |
168e428f PH |
19416 | address from the same message is so handled. In the case of a pipe, the |
19417 | separate outputs from the different addresses are gathered up and returned to | |
9b371988 | 19418 | the sender in a single message, whereas if &(autoreply)& is used, a separate |
168e428f PH |
19419 | message is generated for each address that is passed to it. |
19420 | ||
19421 | Non-printing characters are not permitted in the header lines generated for the | |
9b371988 | 19422 | message that &(autoreply)& creates, with the exception of newlines that are |
068aaea8 | 19423 | immediately followed by white space. If any non-printing characters are found, |
168e428f PH |
19424 | the transport defers. |
19425 | Whether characters with the top bit set count as printing characters or not is | |
9b371988 | 19426 | controlled by the &%print_topbitchars%& global option. |
168e428f PH |
19427 | |
19428 | If any of the generic options for manipulating headers (for example, | |
9b371988 PH |
19429 | &%headers_add%&) are set on an &(autoreply)& transport, they apply to the copy |
19430 | of the original message that is included in the generated message when | |
19431 | &%return_message%& is set. They do not apply to the generated message itself. | |
168e428f | 19432 | |
9b371988 PH |
19433 | .cindex "&$sender_address$&" |
19434 | If the &(autoreply)& transport receives return code 2 from Exim when it submits | |
168e428f | 19435 | the message, indicating that there were no recipients, it does not treat this |
9b371988 | 19436 | as an error. This means that autoreplies sent to &$sender_address$& when this |
168e428f PH |
19437 | is empty (because the incoming message is a bounce message) do not cause |
19438 | problems. They are just discarded. | |
19439 | ||
19440 | ||
19441 | ||
9b371988 PH |
19442 | .section "Private options for autoreply" |
19443 | .cindex "options" "&(autoreply)& transport" | |
168e428f | 19444 | |
9b371988 PH |
19445 | .option bcc autoreply string&!! unset |
19446 | This specifies the addresses that are to receive &"blind carbon copies"& of the | |
168e428f PH |
19447 | message when the message is specified by the transport. |
19448 | ||
19449 | ||
9b371988 PH |
19450 | .option cc autoreply string&!! unset |
19451 | This specifies recipients of the message and the contents of the &'Cc:'& header | |
168e428f PH |
19452 | when the message is specified by the transport. |
19453 | ||
19454 | ||
9b371988 | 19455 | .option file autoreply string&!! unset |
168e428f | 19456 | The contents of the file are sent as the body of the message when the message |
9b371988 | 19457 | is specified by the transport. If both &%file%& and &%text%& are set, the text |
168e428f PH |
19458 | string comes first. |
19459 | ||
19460 | ||
9b371988 PH |
19461 | .option file_expand autoreply boolean false |
19462 | If this is set, the contents of the file named by the &%file%& option are | |
168e428f PH |
19463 | subjected to string expansion as they are added to the message. |
19464 | ||
19465 | ||
9b371988 PH |
19466 | .option file_optional autoreply boolean false |
19467 | If this option is true, no error is generated if the file named by the &%file%& | |
168e428f PH |
19468 | option or passed with the address does not exist or cannot be read. |
19469 | ||
19470 | ||
9b371988 PH |
19471 | .option from autoreply string&!! unset |
19472 | This specifies the contents of the &'From:'& header when the message is | |
19473 | specified by the transport. | |
168e428f | 19474 | |
168e428f | 19475 | |
9b371988 PH |
19476 | .option headers autoreply string&!! unset |
19477 | This specifies additional RFC 2822 headers that are to be added to the message | |
19478 | when the message is specified by the transport. Several can be given by using | |
19479 | &"\n"& to separate them. There is no check on the format. | |
168e428f | 19480 | |
168e428f | 19481 | |
9b371988 | 19482 | .option log autoreply string&!! unset |
168e428f PH |
19483 | This option names a file in which a record of every message sent is logged when |
19484 | the message is specified by the transport. | |
19485 | ||
19486 | ||
9b371988 PH |
19487 | .option mode autoreply "octal integer" 0600 |
19488 | If either the log file or the &"once"& file has to be created, this mode is | |
d1e83bff | 19489 | used. |
168e428f PH |
19490 | |
19491 | ||
9b371988 | 19492 | .option never_mail autoreply "address list&!!" unset |
168e428f PH |
19493 | If any run of the transport creates a message with a recipient that matches any |
19494 | item in the list, that recipient is quietly discarded. If all recipients are | |
19495 | discarded, no message is created. | |
19496 | ||
19497 | ||
19498 | ||
9b371988 PH |
19499 | .option once autoreply string&!! unset |
19500 | This option names a file or DBM database in which a record of each &'To:'& | |
19501 | recipient is kept when the message is specified by the transport. &*Note*&: | |
19502 | This does not apply to &'Cc:'& or &'Bcc:'& recipients. | |
d1e83bff | 19503 | |
9b371988 PH |
19504 | If &%once%& is unset, or is set to an empty string, the message is always sent. |
19505 | By default, if &%once%& is set to a non-empty file name, the message | |
d1e83bff | 19506 | is not sent if a potential recipient is already listed in the database. |
9b371988 | 19507 | However, if the &%once_repeat%& option specifies a time greater than zero, the |
d1e83bff | 19508 | message is sent if that much time has elapsed since a message was last sent to |
9b371988 PH |
19509 | this recipient. A setting of zero time for &%once_repeat%& (the default) |
19510 | prevents a message from being sent a second time &-- in this case, zero means | |
19511 | infinity. | |
d1e83bff | 19512 | |
9b371988 PH |
19513 | If &%once_file_size%& is zero, a DBM database is used to remember recipients, |
19514 | and it is allowed to grow as large as necessary. If &%once_file_size%& is set | |
19515 | greater than zero, it changes the way Exim implements the &%once%& option. | |
19516 | Instead of using a DBM file to record every recipient it sends to, it uses a | |
19517 | regular file, whose size will never get larger than the given value. | |
d1e83bff PH |
19518 | |
19519 | In the file, Exim keeps a linear list of recipient addresses and the times at | |
19520 | which they were sent messages. If the file is full when a new address needs to | |
9b371988 | 19521 | be added, the oldest address is dropped. If &%once_repeat%& is not set, this |
d1e83bff PH |
19522 | means that a given recipient may receive multiple messages, but at |
19523 | unpredictable intervals that depend on the rate of turnover of addresses in the | |
9b371988 | 19524 | file. If &%once_repeat%& is set, it specifies a maximum time between repeats. |
168e428f | 19525 | |
168e428f | 19526 | |
9b371988 PH |
19527 | .option once_file_size autoreply integer 0 |
19528 | See &%once%& above. | |
168e428f | 19529 | |
168e428f | 19530 | |
9b371988 PH |
19531 | .option once_repeat autoreply time&!! 0s |
19532 | See &%once%& above. | |
168e428f PH |
19533 | After expansion, the value of this option must be a valid time value. |
19534 | ||
19535 | ||
9b371988 PH |
19536 | .option reply_to autoreply string&!! unset |
19537 | This specifies the contents of the &'Reply-To:'& header when the message is | |
168e428f PH |
19538 | specified by the transport. |
19539 | ||
19540 | ||
9b371988 | 19541 | .option return_message autoreply boolean false |
168e428f | 19542 | If this is set, a copy of the original message is returned with the new |
9b371988 | 19543 | message, subject to the maximum size set in the &%return_size_limit%& global |
168e428f PH |
19544 | configuration option. |
19545 | ||
19546 | ||
9b371988 PH |
19547 | .option subject autoreply string&!! unset |
19548 | This specifies the contents of the &'Subject:'& header when the message is | |
19549 | specified by the transport. It is tempting to quote the original subject in | |
19550 | automatic responses. For example: | |
19551 | .code | |
19552 | subject = Re: $h_subject: | |
19553 | .endd | |
168e428f PH |
19554 | There is a danger in doing this, however. It may allow a third party to |
19555 | subscribe your users to an opt-in mailing list, provided that the list accepts | |
19556 | bounce messages as subscription confirmations. Well-managed lists require a | |
19557 | non-bounce message to confirm a subscription, so the danger is relatively | |
19558 | small. | |
19559 | ||
19560 | ||
19561 | ||
9b371988 | 19562 | .option text autoreply string&!! unset |
168e428f | 19563 | This specifies a single string to be used as the body of the message when the |
9b371988 PH |
19564 | message is specified by the transport. If both &%text%& and &%file%& are set, |
19565 | the text comes first. | |
168e428f | 19566 | |
168e428f | 19567 | |
9b371988 PH |
19568 | .option to autoreply string&!! unset |
19569 | This specifies recipients of the message and the contents of the &'To:'& header | |
168e428f PH |
19570 | when the message is specified by the transport. |
19571 | ||
19572 | ||
19573 | ||
19574 | ||
9b371988 PH |
19575 | . //////////////////////////////////////////////////////////////////////////// |
19576 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 19577 | |
9b371988 PH |
19578 | .chapter "The lmtp transport" "CHAPLMTP" |
19579 | .cindex "transports" "&(lmtp)&" | |
19580 | .cindex "&(lmtp)& transport" | |
19581 | .cindex "LMTP" "over a pipe" | |
19582 | .cindex "LMTP" "over a socket" | |
19583 | The &(lmtp)& transport runs the LMTP protocol (RFC 2033) over a pipe to a | |
168e428f PH |
19584 | specified command |
19585 | or by interacting with a Unix domain socket. | |
9b371988 | 19586 | This transport is something of a cross between the &(pipe)& and &(smtp)& |
168e428f | 19587 | transports. Exim also has support for using LMTP over TCP/IP; this is |
9b371988 PH |
19588 | implemented as an option for the &(smtp)& transport. Because LMTP is expected |
19589 | to be of minority interest, the default build-time configure in &_src/EDITME_& | |
168e428f | 19590 | has it commented out. You need to ensure that |
9b371988 PH |
19591 | .code |
19592 | TRANSPORT_LMTP=yes | |
19593 | .endd | |
19594 | .cindex "options" "&(lmtp)& transport" | |
19595 | is present in your &_Local/Makefile_& in order to have the &(lmtp)& transport | |
19596 | included in the Exim binary. The private options of the &(lmtp)& transport are | |
19597 | as follows: | |
168e428f | 19598 | |
9b371988 PH |
19599 | .option batch_id lmtp string&!! unset |
19600 | See the description of local delivery batching in chapter &<<CHAPbatching>>&. | |
168e428f | 19601 | |
168e428f | 19602 | |
9b371988 | 19603 | .option batch_max lmtp integer 1 |
168e428f PH |
19604 | This limits the number of addresses that can be handled in a single delivery. |
19605 | Most LMTP servers can handle several addresses at once, so it is normally a | |
19606 | good idea to increase this value. See the description of local delivery | |
9b371988 | 19607 | batching in chapter &<<CHAPbatching>>&. |
168e428f PH |
19608 | |
19609 | ||
9b371988 PH |
19610 | .option command lmtp string&!! unset |
19611 | This option must be set if &%socket%& is not set. The string is a command which | |
068aaea8 PH |
19612 | is run in a separate process. It is split up into a command name and list of |
19613 | arguments, each of which is separately expanded (so expansion cannot change the | |
19614 | number of arguments). The command is run directly, not via a shell. The message | |
19615 | is passed to the new process using the standard input and output to operate the | |
19616 | LMTP protocol. | |
19617 | ||
9b371988 PH |
19618 | .new |
19619 | .option ignore_quota lmtp boolean false | |
19620 | .cindex "LMTP" "ignoring quota errors" | |
19621 | If this option is set true, the string &`IGNOREQUOTA`& is added to RCPT | |
19622 | commands, provided that the LMTP server has advertised support for IGNOREQUOTA | |
19623 | in its response to the LHLO command. | |
19624 | .wen | |
168e428f | 19625 | |
9b371988 PH |
19626 | .option socket lmtp string&!! unset |
19627 | This option must be set if &%command%& is not set. The result of expansion must | |
168e428f PH |
19628 | be the name of a Unix domain socket. The transport connects to the socket and |
19629 | delivers the message to it using the LMTP protocol. | |
19630 | ||
19631 | ||
9b371988 | 19632 | .option timeout lmtp time 5m |
168e428f PH |
19633 | The transport is aborted if the created process |
19634 | or Unix domain socket | |
19635 | does not respond to LMTP commands or message input within this timeout. | |
19636 | ||
19637 | ||
19638 | Here is an example of a typical LMTP transport: | |
9b371988 PH |
19639 | .code |
19640 | lmtp: | |
19641 | driver = lmtp | |
19642 | command = /some/local/lmtp/delivery/program | |
19643 | batch_max = 20 | |
19644 | user = exim | |
19645 | .endd | |
168e428f | 19646 | This delivers up to 20 addresses at a time, in a mixture of domains if |
9b371988 | 19647 | necessary, running as the user &'exim'&. |
168e428f PH |
19648 | |
19649 | ||
168e428f | 19650 | |
9b371988 PH |
19651 | . //////////////////////////////////////////////////////////////////////////// |
19652 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 19653 | |
9b371988 PH |
19654 | .chapter "The pipe transport" "CHAPpipetransport" |
19655 | .cindex "transports" "&(pipe)&" | |
19656 | .cindex "&(pipe)& transport" | |
19657 | The &(pipe)& transport is used to deliver messages via a pipe to a command | |
19658 | running in another process. One example is the use of &(pipe)& as a | |
19659 | pseudo-remote transport for passing messages to some other delivery mechanism | |
19660 | (such as UUCP). Another is the use by individual users to automatically process | |
19661 | their incoming messages. The &(pipe)& transport can be used in one of the | |
19662 | following ways: | |
168e428f | 19663 | |
9b371988 PH |
19664 | .ilist |
19665 | .cindex "&$local_part$&" | |
068aaea8 | 19666 | A router routes one address to a transport in the normal way, and the |
9b371988 | 19667 | transport is configured as a &(pipe)& transport. In this case, &$local_part$& |
068aaea8 | 19668 | contains the local part of the address (as usual), and the command that is run |
9b371988 PH |
19669 | is specified by the &%command%& option on the transport. |
19670 | .next | |
19671 | .cindex "&$pipe_addresses$&" | |
19672 | If the &%batch_max%& option is set greater than 1 (the default), the transport | |
168e428f | 19673 | can be called upon to handle more than one address in a single run. In this |
9b371988 PH |
19674 | case, &$local_part$& is not set (because it is not unique). However, the |
19675 | pseudo-variable &$pipe_addresses$& (described in section | |
19676 | &<<SECThowcommandrun>>& below) contains all the addresses that are being | |
19677 | handled. | |
19678 | .next | |
19679 | .cindex "&$address_pipe$&" | |
068aaea8 | 19680 | A router redirects an address directly to a pipe command (for example, from an |
9b371988 PH |
19681 | alias or forward file). In this case, &$local_part$& contains the local part |
19682 | that was redirected, and &$address_pipe$& contains the text of the pipe | |
19683 | command itself. The &%command%& option on the transport is ignored. | |
19684 | .endlist | |
168e428f PH |
19685 | |
19686 | ||
9b371988 | 19687 | The &(pipe)& transport is a non-interactive delivery method. Exim can also |
168e428f | 19688 | deliver messages over pipes using the LMTP interactive protocol. This is |
9b371988 | 19689 | implemented by the &(lmtp)& transport. |
168e428f | 19690 | |
9b371988 PH |
19691 | In the case when &(pipe)& is run as a consequence of an entry in a local user's |
19692 | &_.forward_& file, the command runs under the uid and gid of that user. In | |
19693 | other cases, the uid and gid have to be specified explicitly, either on the | |
19694 | transport or on the router that handles the address. Current and &"home"& | |
19695 | directories are also controllable. See chapter &<<CHAPenvironment>>& for | |
19696 | details of the local delivery environment. | |
168e428f PH |
19697 | |
19698 | ||
19699 | ||
9b371988 | 19700 | .section "Concurrent delivery" |
168e428f PH |
19701 | If two messages arrive at almost the same time, and both are routed to a pipe |
19702 | delivery, the two pipe transports may be run concurrently. You must ensure that | |
19703 | any pipe commands you set up are robust against this happening. If the commands | |
9b371988 | 19704 | write to a file, the &%exim_lock%& utility might be of use. |
168e428f PH |
19705 | |
19706 | ||
19707 | ||
19708 | ||
9b371988 PH |
19709 | .section "Returned status and data" |
19710 | .cindex "&(pipe)& transport" "returned data" | |
168e428f | 19711 | If the command exits with a non-zero return code, the delivery is deemed to |
9b371988 | 19712 | have failed, unless either the &%ignore_status%& option is set (in which case |
168e428f | 19713 | the return code is treated as zero), or the return code is one of those listed |
9b371988 PH |
19714 | in the &%temp_errors%& option, which are interpreted as meaning &"try again |
19715 | later"&. In this case, delivery is deferred. Details of a permanent failure are | |
168e428f | 19716 | logged, but are not included in the bounce message, which merely contains |
9b371988 | 19717 | &"local delivery failed"&. |
168e428f PH |
19718 | |
19719 | If the return code is greater than 128 and the command being run is a shell | |
19720 | script, it normally means that the script was terminated by a signal whose | |
19721 | value is the return code minus 128. | |
19722 | ||
9b371988 | 19723 | If Exim is unable to run the command (that is, if &[execve()]& fails), the |
168e428f PH |
19724 | return code is set to 127. This is the value that a shell returns if it is |
19725 | asked to run a non-existent command. The wording for the log line suggests that | |
19726 | a non-existent command may be the problem. | |
19727 | ||
9b371988 | 19728 | The &%return_output%& option can affect the result of a pipe delivery. If it is |
168e428f PH |
19729 | set and the command produces any output on its standard output or standard |
19730 | error streams, the command is considered to have failed, even if it gave a zero | |
9b371988 PH |
19731 | return code or if &%ignore_status%& is set. The output from the command is |
19732 | included as part of the bounce message. The &%return_fail_output%& option is | |
168e428f PH |
19733 | similar, except that output is returned only when the command exits with a |
19734 | failure return code, that is, a value other than zero or a code that matches | |
9b371988 | 19735 | &%temp_errors%&. |
168e428f PH |
19736 | |
19737 | ||
19738 | ||
9b371988 PH |
19739 | .section "How the command is run" "SECThowcommandrun" |
19740 | .cindex "&(pipe)& transport" "path for command" | |
168e428f | 19741 | The command line is (by default) broken down into a command name and arguments |
9b371988 PH |
19742 | by the &(pipe)& transport itself. The &%allow_commands%& and |
19743 | &%restrict_to_path%& options can be used to restrict the commands that may be | |
19744 | run. | |
168e428f | 19745 | |
9b371988 | 19746 | .cindex "quoting" "in pipe command" |
168e428f PH |
19747 | Unquoted arguments are delimited by white space. If an argument appears in |
19748 | double quotes, backslash is interpreted as an escape character in the usual | |
19749 | way. If an argument appears in single quotes, no escaping is done. | |
19750 | ||
19751 | String expansion is applied to the command line except when it comes from a | |
9b371988 | 19752 | traditional &_.forward_& file (commands from a filter file are expanded). The |
168e428f PH |
19753 | expansion is applied to each argument in turn rather than to the whole line. |
19754 | For this reason, any string expansion item that contains white space must be | |
19755 | quoted so as to be contained within a single argument. A setting such as | |
9b371988 PH |
19756 | .code |
19757 | command = /some/path ${if eq{$local_part}{postmaster}{xx}{yy}} | |
19758 | .endd | |
168e428f PH |
19759 | will not work, because the expansion item gets split between several |
19760 | arguments. You have to write | |
9b371988 PH |
19761 | .code |
19762 | command = /some/path "${if eq{$local_part}{postmaster}{xx}{yy}}" | |
19763 | .endd | |
168e428f PH |
19764 | to ensure that it is all in one argument. The expansion is done in this way, |
19765 | argument by argument, so that the number of arguments cannot be changed as a | |
19766 | result of expansion, and quotes or backslashes in inserted variables do not | |
19767 | interact with external quoting. | |
19768 | ||
9b371988 PH |
19769 | .cindex "transport" "filter" |
19770 | .cindex "filter" "transport filter" | |
19771 | .cindex "&$pipe_addresses$&" | |
168e428f | 19772 | Special handling takes place when an argument consists of precisely the text |
9b371988 | 19773 | &`$pipe_addresses`&. This is not a general expansion variable; the only |
168e428f PH |
19774 | place this string is recognized is when it appears as an argument for a pipe or |
19775 | transport filter command. It causes each address that is being handled to be | |
9b371988 | 19776 | inserted in the argument list at that point &'as a separate argument'&. This |
168e428f | 19777 | avoids any problems with spaces or shell metacharacters, and is of use when a |
9b371988 | 19778 | &(pipe)& transport is handling groups of addresses in a batch. |
168e428f PH |
19779 | |
19780 | After splitting up into arguments and expansion, the resulting command is run | |
9b371988 | 19781 | in a subprocess directly from the transport, &'not'& under a shell. The |
168e428f PH |
19782 | message that is being delivered is supplied on the standard input, and the |
19783 | standard output and standard error are both connected to a single pipe that is | |
9b371988 PH |
19784 | read by Exim. The &%max_output%& option controls how much output the command |
19785 | may produce, and the &%return_output%& and &%return_fail_output%& options | |
19786 | control what is done with it. | |
168e428f PH |
19787 | |
19788 | Not running the command under a shell (by default) lessens the security risks | |
19789 | in cases when a command from a user's filter file is built out of data that was | |
19790 | taken from an incoming message. If a shell is required, it can of course be | |
19791 | explicitly specified as the command to be run. However, there are circumstances | |
9b371988 | 19792 | where existing commands (for example, in &_.forward_& files) expect to be run |
168e428f | 19793 | under a shell and cannot easily be modified. To allow for these cases, there is |
9b371988 | 19794 | an option called &%use_shell%&, which changes the way the &(pipe)& transport |
168e428f | 19795 | works. Instead of breaking up the command line as just described, it expands it |
9b371988 PH |
19796 | as a single string and passes the result to &_/bin/sh_&. The |
19797 | &%restrict_to_path%& option and the &$pipe_addresses$& facility cannot be used | |
19798 | with &%use_shell%&, and the whole mechanism is inherently less secure. | |
168e428f PH |
19799 | |
19800 | ||
19801 | ||
9b371988 PH |
19802 | .section "Environment variables" "SECTpipeenv" |
19803 | .cindex "&(pipe)& transport" "environment for command" | |
19804 | .cindex "environment for pipe transport" | |
168e428f PH |
19805 | The environment variables listed below are set up when the command is invoked. |
19806 | This list is a compromise for maximum compatibility with other MTAs. Note that | |
9b371988 | 19807 | the &%environment%& option can be used to add additional variables to this |
168e428f | 19808 | environment. |
9b371988 PH |
19809 | .display |
19810 | &`DOMAIN `& the domain of the address | |
19811 | &`HOME `& the home directory, if set | |
19812 | &`HOST `& the host name when called from a router (see below) | |
19813 | &`LOCAL_PART `& see below | |
19814 | &`LOCAL_PART_PREFIX `& see below | |
19815 | &`LOCAL_PART_SUFFIX `& see below | |
19816 | &`LOGNAME `& see below | |
19817 | &`MESSAGE_ID `& Exim's local ID for the message | |
19818 | &`PATH `& as specified by the &%path%& option below | |
19819 | &`QUALIFY_DOMAIN `& the sender qualification domain | |
19820 | &`RECIPIENT `& the complete recipient address | |
19821 | &`SENDER `& the sender of the message (empty if a bounce) | |
19822 | &`SHELL `& &`/bin/sh`& | |
19823 | &`TZ `& the value of the &%timezone%& option, if set | |
19824 | &`USER `& see below | |
19825 | .endd | |
19826 | When a &(pipe)& transport is called directly from (for example) an &(accept)& | |
168e428f PH |
19827 | router, LOCAL_PART is set to the local part of the address. When it is |
19828 | called as a result of a forward or alias expansion, LOCAL_PART is set to | |
19829 | the local part of the address that was expanded. In both cases, any affixes are | |
19830 | removed from the local part, and made available in LOCAL_PART_PREFIX and | |
19831 | LOCAL_PART_SUFFIX, respectively. LOGNAME and USER are set to the | |
19832 | same value as LOCAL_PART for compatibility with other MTAs. | |
19833 | ||
9b371988 PH |
19834 | .cindex "HOST" |
19835 | HOST is set only when a &(pipe)& transport is called from a router that | |
19836 | associates hosts with an address, typically when using &(pipe)& as a | |
168e428f PH |
19837 | pseudo-remote transport. HOST is set to the first host name specified by |
19838 | the router. | |
19839 | ||
9b371988 PH |
19840 | .cindex "HOME" |
19841 | If the transport's generic &%home_directory%& option is set, its value is used | |
168e428f | 19842 | for the HOME environment variable. Otherwise, a home directory may be set |
9b371988 PH |
19843 | by the router's &%transport_home_directory%& option, which defaults to the |
19844 | user's home directory if &%check_local_user%& is set. | |
168e428f PH |
19845 | |
19846 | ||
9b371988 PH |
19847 | .section "Private options for pipe" |
19848 | .cindex "options" "&(pipe)& transport" | |
168e428f PH |
19849 | |
19850 | ||
19851 | ||
9b371988 PH |
19852 | .option allow_commands pipe "string list&!!" unset |
19853 | .cindex "&(pipe)& transport" "permitted commands" | |
168e428f | 19854 | The string is expanded, and is then interpreted as a colon-separated list of |
9b371988 PH |
19855 | permitted commands. If &%restrict_to_path%& is not set, the only commands |
19856 | permitted are those in the &%allow_commands%& list. They need not be absolute | |
19857 | paths; the &%path%& option is still used for relative paths. If | |
19858 | &%restrict_to_path%& is set with &%allow_commands%&, the command must either be | |
19859 | in the &%allow_commands%& list, or a name without any slashes that is found on | |
19860 | the path. In other words, if neither &%allow_commands%& nor | |
19861 | &%restrict_to_path%& is set, there is no restriction on the command, but | |
19862 | otherwise only commands that are permitted by one or the other are allowed. For | |
19863 | example, if | |
19864 | .code | |
19865 | allow_commands = /usr/bin/vacation | |
19866 | .endd | |
19867 | and &%restrict_to_path%& is not set, the only permitted command is | |
19868 | &_/usr/bin/vacation_&. The &%allow_commands%& option may not be set if | |
19869 | &%use_shell%& is set. | |
168e428f | 19870 | |
168e428f | 19871 | |
9b371988 PH |
19872 | .option batch_id pipe string&!! unset |
19873 | See the description of local delivery batching in chapter &<<CHAPbatching>>&. | |
168e428f | 19874 | |
168e428f | 19875 | |
9b371988 | 19876 | .option batch_max pipe integer 1 |
168e428f | 19877 | This limits the number of addresses that can be handled in a single delivery. |
9b371988 | 19878 | See the description of local delivery batching in chapter &<<CHAPbatching>>&. |
168e428f PH |
19879 | |
19880 | ||
9b371988 PH |
19881 | .option check_string pipe string unset |
19882 | As &(pipe)& writes the message, the start of each line is tested for matching | |
19883 | &%check_string%&, and if it does, the initial matching characters are replaced | |
19884 | by the contents of &%escape_string%&, provided both are set. The value of | |
19885 | &%check_string%& is a literal string, not a regular expression, and the case of | |
19886 | any letters it contains is significant. When &%use_bsmtp%& is set, the contents | |
19887 | of &%check_string%& and &%escape_string%& are forced to values that implement | |
19888 | the SMTP escaping protocol. Any settings made in the configuration file are | |
168e428f PH |
19889 | ignored. |
19890 | ||
19891 | ||
9b371988 PH |
19892 | .option command pipe string&!! unset |
19893 | This option need not be set when &(pipe)& is being used to deliver to pipes | |
168e428f PH |
19894 | obtained directly from address redirections. In other cases, the option must be |
19895 | set, to provide a command to be run. It need not yield an absolute path (see | |
9b371988 | 19896 | the &%path%& option below). The command is split up into separate arguments by |
168e428f | 19897 | Exim, and each argument is separately expanded, as described in section |
9b371988 | 19898 | &<<SECThowcommandrun>>& above. |
168e428f PH |
19899 | |
19900 | ||
9b371988 PH |
19901 | .option environment pipe string&!! unset |
19902 | .cindex "&(pipe)& transport" "environment for command" | |
19903 | .cindex "environment for &(pipe)& transport" | |
168e428f | 19904 | This option is used to add additional variables to the environment in which the |
9b371988 PH |
19905 | command runs (see section &<<SECTpipeenv>>& for the default list). Its value is |
19906 | a string which is expanded, and then interpreted as a colon-separated list of | |
19907 | environment settings of the form <&'name'&>=<&'value'&>. | |
168e428f | 19908 | |
168e428f | 19909 | |
9b371988 PH |
19910 | .option escape_string pipe string unset |
19911 | See &%check_string%& above. | |
168e428f PH |
19912 | |
19913 | ||
9b371988 PH |
19914 | .option freeze_exec_fail pipe boolean false |
19915 | .cindex "exec failure" | |
19916 | .cindex "failure of exec" | |
19917 | .cindex "&(pipe)& transport" "failure of exec" | |
168e428f | 19918 | Failure to exec the command in a pipe transport is by default treated like |
9b371988 | 19919 | any other failure while running the command. However, if &%freeze_exec_fail%& |
168e428f | 19920 | is set, failure to exec is treated specially, and causes the message to be |
9b371988 | 19921 | frozen, whatever the setting of &%ignore_status%&. |
168e428f | 19922 | |
168e428f | 19923 | |
9b371988 | 19924 | .option ignore_status pipe boolean false |
168e428f PH |
19925 | If this option is true, the status returned by the subprocess that is set up to |
19926 | run the command is ignored, and Exim behaves as if zero had been returned. | |
068aaea8 PH |
19927 | Otherwise, a non-zero status or termination by signal causes an error return |
19928 | from the transport unless the status value is one of those listed in | |
9b371988 | 19929 | &%temp_errors%&; these cause the delivery to be deferred and tried again later. |
068aaea8 | 19930 | |
9b371988 PH |
19931 | .new |
19932 | &*Note*&: This option does not apply to timeouts, which do not return a status. | |
19933 | See the &%timeout_defer%& option for how timeouts are handled. | |
19934 | .wen | |
168e428f | 19935 | |
9b371988 PH |
19936 | .option log_defer_output pipe boolean false |
19937 | .cindex "&(pipe)& transport" "logging output" | |
168e428f | 19938 | If this option is set, and the status returned by the command is |
9b371988 | 19939 | one of the codes listed in &%temp_errors%& (that is, delivery was deferred), |
168e428f PH |
19940 | and any output was produced, the first line of it is written to the main log. |
19941 | ||
19942 | ||
9b371988 | 19943 | .option log_fail_output pipe boolean false |
168e428f PH |
19944 | If this option is set, and the command returns any output, and also ends with a |
19945 | return code that is neither zero nor one of the return codes listed in | |
9b371988 PH |
19946 | &%temp_errors%& (that is, the delivery failed), the first line of output is |
19947 | written to the main log. This option and &%log_output%& are mutually exclusive. | |
19948 | Only one of them may be set. | |
168e428f PH |
19949 | |
19950 | ||
168e428f | 19951 | |
9b371988 | 19952 | .option log_output pipe boolean false |
168e428f | 19953 | If this option is set and the command returns any output, the first line of |
9b371988 PH |
19954 | output is written to the main log, whatever the return code. This option and |
19955 | &%log_fail_output%& are mutually exclusive. Only one of them may be set. | |
168e428f PH |
19956 | |
19957 | ||
168e428f | 19958 | |
9b371988 | 19959 | .option max_output pipe integer 20K |
168e428f PH |
19960 | This specifies the maximum amount of output that the command may produce on its |
19961 | standard output and standard error file combined. If the limit is exceeded, the | |
19962 | process running the command is killed. This is intended as a safety measure to | |
19963 | catch runaway processes. The limit is applied independently of the settings of | |
19964 | the options that control what is done with such output (for example, | |
9b371988 | 19965 | &%return_output%&). Because of buffering effects, the amount of output may |
168e428f PH |
19966 | exceed the limit by a small amount before Exim notices. |
19967 | ||
19968 | ||
9b371988 | 19969 | .option message_prefix pipe string&!! "see below" |
168e428f | 19970 | The string specified here is expanded and output at the start of every message. |
9b371988 PH |
19971 | The default is unset if &%use_bsmtp%& is set. Otherwise it is |
19972 | .code | |
168e428f PH |
19973 | message_prefix = \ |
19974 | From ${if def:return_path{$return_path}{MAILER-DAEMON}}\ | |
19975 | ${tod_bsdinbox}\n | |
9b371988 PH |
19976 | .endd |
19977 | .cindex "Cyrus" | |
19978 | .cindex "&%tmail%&" | |
19979 | .cindex "&""From""& line" | |
19980 | This is required by the commonly used &_/usr/bin/vacation_& program. | |
19981 | However, it must &'not'& be present if delivery is to the Cyrus IMAP server, | |
19982 | or to the &%tmail%& local delivery agent. The prefix can be suppressed by | |
19983 | setting | |
19984 | .code | |
19985 | message_prefix = | |
19986 | .endd | |
168e428f | 19987 | |
9b371988 | 19988 | .option message_suffix pipe string&!! "see below" |
168e428f | 19989 | The string specified here is expanded and output at the end of every message. |
9b371988 | 19990 | The default is unset if &%use_bsmtp%& is set. Otherwise it is a single newline. |
168e428f | 19991 | The suffix can be suppressed by setting |
9b371988 PH |
19992 | .code |
19993 | message_suffix = | |
19994 | .endd | |
168e428f | 19995 | |
9b371988 | 19996 | .option path pipe string &`/bin:/usr/bin`& |
168e428f | 19997 | This option specifies the string that is set up in the PATH environment |
9b371988 PH |
19998 | variable of the subprocess. If the &%command%& option does not yield an |
19999 | absolute path name, the command is sought in the PATH directories, in the usual | |
20000 | way. &*Warning*&: This does not apply to a command specified as a transport | |
168e428f PH |
20001 | filter. |
20002 | ||
20003 | ||
9b371988 PH |
20004 | .option pipe_as_creator pipe boolean false |
20005 | .cindex "uid (user id)" "local delivery" | |
20006 | If the generic &%user%& option is not set and this option is true, the delivery | |
168e428f PH |
20007 | process is run under the uid that was in force when Exim was originally called |
20008 | to accept the message. If the group id is not otherwise set (via the generic | |
9b371988 | 20009 | &%group%& option), the gid that was in force when Exim was originally called to |
168e428f PH |
20010 | accept the message is used. |
20011 | ||
20012 | ||
9b371988 PH |
20013 | .option restrict_to_path pipe boolean false |
20014 | When this option is set, any command name not listed in &%allow_commands%& must | |
168e428f | 20015 | contain no slashes. The command is searched for only in the directories listed |
9b371988 PH |
20016 | in the &%path%& option. This option is intended for use in the case when a pipe |
20017 | command has been generated from a user's &_.forward_& file. This is usually | |
20018 | handled by a &(pipe)& transport called &%address_pipe%&. | |
168e428f PH |
20019 | |
20020 | ||
9b371988 | 20021 | .option return_fail_output pipe boolean false |
168e428f | 20022 | If this option is true, and the command produced any output and ended with a |
9b371988 | 20023 | return code other than zero or one of the codes listed in &%temp_errors%& (that |
168e428f PH |
20024 | is, the delivery failed), the output is returned in the bounce message. |
20025 | However, if the message has a null sender (that is, it is itself a bounce | |
9b371988 PH |
20026 | message), output from the command is discarded. This option and |
20027 | &%return_output%& are mutually exclusive. Only one of them may be set. | |
168e428f PH |
20028 | |
20029 | ||
20030 | ||
9b371988 | 20031 | .option return_output pipe boolean false |
168e428f PH |
20032 | If this option is true, and the command produced any output, the delivery is |
20033 | deemed to have failed whatever the return code from the command, and the output | |
20034 | is returned in the bounce message. Otherwise, the output is just discarded. | |
20035 | However, if the message has a null sender (that is, it is a bounce message), | |
20036 | output from the command is always discarded, whatever the setting of this | |
9b371988 PH |
20037 | option. This option and &%return_fail_output%& are mutually exclusive. Only one |
20038 | of them may be set. | |
168e428f | 20039 | |
168e428f PH |
20040 | |
20041 | ||
9b371988 PH |
20042 | .option temp_errors pipe "string list" "see below" |
20043 | .cindex "&(pipe)& transport" "temporary failure" | |
168e428f | 20044 | This option contains either a colon-separated list of numbers, or a single |
9b371988 PH |
20045 | asterisk. If &%ignore_status%& is false |
20046 | and &%return_output%& is not set, | |
168e428f PH |
20047 | and the command exits with a non-zero return code, the failure is treated as |
20048 | temporary and the delivery is deferred if the return code matches one of the | |
20049 | numbers, or if the setting is a single asterisk. Otherwise, non-zero return | |
20050 | codes are treated as permanent errors. The default setting contains the codes | |
9b371988 | 20051 | defined by EX_TEMPFAIL and EX_CANTCREAT in &_sysexits.h_&. If Exim is |
168e428f PH |
20052 | compiled on a system that does not define these macros, it assumes values of 75 |
20053 | and 73, respectively. | |
20054 | ||
20055 | ||
9b371988 | 20056 | .option timeout pipe time 1h |
168e428f | 20057 | If the command fails to complete within this time, it is killed. This normally |
9b371988 | 20058 | causes the delivery to fail (but see &%timeout_defer%&). A zero time interval |
068aaea8 PH |
20059 | specifies no timeout. In order to ensure that any subprocesses created by the |
20060 | command are also killed, Exim makes the initial process a process group leader, | |
20061 | and kills the whole process group on a timeout. However, this can be defeated | |
20062 | if one of the processes starts a new process group. | |
20063 | ||
9b371988 PH |
20064 | .new |
20065 | .option timeout_defer pipe boolean false | |
20066 | A timeout in a &(pipe)& transport, either in the command that the transport | |
20067 | runs, or in a transport filter that is associated with it, is by default | |
20068 | treated as a hard error, and the delivery fails. However, if &%timeout_defer%& | |
20069 | is set true, both kinds of timeout become temporary errors, causing the | |
20070 | delivery to be deferred. | |
20071 | .wen | |
168e428f | 20072 | |
9b371988 | 20073 | .option umask pipe "octal integer" 022 |
168e428f PH |
20074 | This specifies the umask setting for the subprocess that runs the command. |
20075 | ||
20076 | ||
9b371988 PH |
20077 | .option use_bsmtp pipe boolean false |
20078 | .cindex "envelope sender" | |
20079 | If this option is set true, the &(pipe)& transport writes messages in &"batch | |
20080 | SMTP"& format, with the envelope sender and recipient(s) included as SMTP | |
168e428f | 20081 | commands. If you want to include a leading HELO command with such messages, |
9b371988 PH |
20082 | you can do so by setting the &%message_prefix%& option. See section |
20083 | &<<SECTbatchSMTP>>& for details of batch SMTP. | |
168e428f | 20084 | |
168e428f | 20085 | |
9b371988 PH |
20086 | .option use_crlf pipe boolean false |
20087 | .cindex "carriage return" | |
20088 | .cindex "linefeed" | |
168e428f PH |
20089 | This option causes lines to be terminated with the two-character CRLF sequence |
20090 | (carriage return, linefeed) instead of just a linefeed character. In the case | |
20091 | of batched SMTP, the byte sequence written to the pipe is then an exact image | |
20092 | of what would be sent down a real SMTP connection. | |
20093 | ||
9b371988 PH |
20094 | The contents of the &%message_prefix%& and &%message_suffix%& options are |
20095 | written verbatim, so must contain their own carriage return characters if these | |
20096 | are needed. Since the default values for both &%message_prefix%& and | |
20097 | &%message_suffix%& end with a single linefeed, their values must be changed to | |
20098 | end with &`\r\n`& if &%use_crlf%& is set. | |
168e428f PH |
20099 | |
20100 | ||
9b371988 PH |
20101 | .option use_shell pipe boolean false |
20102 | .cindex "&$pipe_addresses$&" | |
20103 | If this option is set, it causes the command to be passed to &_/bin/sh_& | |
168e428f | 20104 | instead of being run directly from the transport, as described in section |
9b371988 | 20105 | &<<SECThowcommandrun>>&. This is less secure, but is needed in some situations |
168e428f | 20106 | where the command is expected to be run under a shell and cannot easily be |
9b371988 PH |
20107 | modified. The &%allow_commands%& and &%restrict_to_path%& options, and the |
20108 | &`$pipe_addresses`& facility are incompatible with &%use_shell%&. The | |
20109 | command is expanded as a single string, and handed to &_/bin/sh_& as data for | |
20110 | its &%-c%& option. | |
20111 | ||
20112 | ||
20113 | ||
20114 | .section "Using an external local delivery agent" | |
20115 | .cindex "local delivery" "using an external agent" | |
20116 | .cindex "&'procmail'&" | |
20117 | .cindex "external local delivery" | |
20118 | .cindex "delivery" "&'procmail'&" | |
20119 | .cindex "delivery" "by external agent" | |
20120 | The &(pipe)& transport can be used to pass all messages that require local | |
20121 | delivery to a separate local delivery agent such as &%procmail%&. When doing | |
168e428f PH |
20122 | this, care must be taken to ensure that the pipe is run under an appropriate |
20123 | uid and gid. In some configurations one wants this to be a uid that is trusted | |
20124 | by the delivery agent to supply the correct sender of the message. It may be | |
20125 | necessary to recompile or reconfigure the delivery agent so that it trusts an | |
20126 | appropriate user. The following is an example transport and router | |
9b371988 PH |
20127 | configuration for &%procmail%&: |
20128 | .code | |
20129 | # transport | |
20130 | procmail_pipe: | |
20131 | driver = pipe | |
20132 | command = /usr/local/bin/procmail -d $local_part | |
20133 | return_path_add | |
20134 | delivery_date_add | |
20135 | envelope_to_add | |
20136 | check_string = "From " | |
20137 | escape_string = ">From " | |
20138 | user = $local_part | |
20139 | group = mail | |
168e428f | 20140 | |
9b371988 PH |
20141 | # router |
20142 | procmail: | |
20143 | driver = accept | |
20144 | check_local_user | |
20145 | transport = procmail_pipe | |
20146 | .endd | |
168e428f | 20147 | In this example, the pipe is run as the local user, but with the group set to |
9b371988 PH |
20148 | &'mail'&. An alternative is to run the pipe as a specific user such as &'mail'& |
20149 | or &'exim'&, but in this case you must arrange for &%procmail%& to trust that | |
20150 | user to supply a correct sender address. If you do not specify either a | |
20151 | &%group%& or a &%user%& option, the pipe command is run as the local user. The | |
20152 | home directory is the user's home directory by default. | |
20153 | ||
20154 | &*Note*&: The command that the pipe transport runs does &'not'& begin with | |
20155 | .code | |
20156 | IFS=" " | |
20157 | .endd | |
20158 | as shown in some &%procmail%& documentation, because Exim does not by default | |
20159 | use a shell to run pipe commands. | |
20160 | ||
20161 | .cindex "Cyrus" | |
168e428f PH |
20162 | The next example shows a transport and a router for a system where local |
20163 | deliveries are handled by the Cyrus IMAP server. | |
9b371988 | 20164 | .code |
168e428f PH |
20165 | # transport |
20166 | local_delivery_cyrus: | |
20167 | driver = pipe | |
20168 | command = /usr/cyrus/bin/deliver \ | |
20169 | -m ${substr_1:$local_part_suffix} -- $local_part | |
20170 | user = cyrus | |
20171 | group = mail | |
20172 | return_output | |
20173 | log_output | |
20174 | message_prefix = | |
20175 | message_suffix = | |
20176 | ||
20177 | # router | |
20178 | local_user_cyrus: | |
20179 | driver = accept | |
20180 | check_local_user | |
20181 | local_part_suffix = .* | |
20182 | transport = local_delivery_cyrus | |
9b371988 PH |
20183 | .endd |
20184 | Note the unsetting of &%message_prefix%& and &%message_suffix%&, and the use of | |
20185 | &%return_output%& to cause any text written by Cyrus to be returned to the | |
168e428f PH |
20186 | sender. |
20187 | ||
20188 | ||
9b371988 PH |
20189 | . //////////////////////////////////////////////////////////////////////////// |
20190 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 20191 | |
9b371988 PH |
20192 | .chapter "The smtp transport" "CHAPsmtptrans" |
20193 | .cindex "transports" "&(smtp)&" | |
20194 | .cindex "&(smtp)& transport" | |
20195 | The &(smtp)& transport delivers messages over TCP/IP connections using the SMTP | |
168e428f PH |
20196 | or LMTP protocol. The list of hosts to try can either be taken from the address |
20197 | that is being processed (having been set up by the router), or specified | |
20198 | explicitly for the transport. Timeout and retry processing (see chapter | |
9b371988 | 20199 | &<<CHAPretry>>&) is applied to each IP address independently. |
168e428f PH |
20200 | |
20201 | ||
9b371988 | 20202 | .section "Multiple messages on a single connection" |
168e428f PH |
20203 | The sending of multiple messages over a single TCP/IP connection can arise in |
20204 | two ways: | |
20205 | ||
9b371988 PH |
20206 | .ilist |
20207 | If a message contains more than &%max_rcpt%& (see below) addresses that are | |
168e428f PH |
20208 | routed to the same host, more than one copy of the message has to be sent to |
20209 | that host. In this situation, multiple copies may be sent in a single run of | |
9b371988 PH |
20210 | the &(smtp)& transport over a single TCP/IP connection. (What Exim actually |
20211 | does when it has too many addresses to send in one message also depends on the | |
20212 | value of the global &%remote_max_parallel%& option. Details are given in | |
20213 | section &<<SECToutSMTPTCP>>&.) | |
20214 | .next | |
20215 | .cindex "hints database" "remembering routing" | |
168e428f PH |
20216 | When a message has been successfully delivered over a TCP/IP connection, Exim |
20217 | looks in its hints database to see if there are any other messages awaiting a | |
20218 | connection to the same host. If there are, a new delivery process is started | |
20219 | for one of them, and the current TCP/IP connection is passed on to it. The new | |
20220 | process may in turn send multiple copies and possibly create yet another | |
20221 | process. | |
9b371988 | 20222 | .endlist |
168e428f PH |
20223 | |
20224 | ||
20225 | For each copy sent over the same TCP/IP connection, a sequence counter is | |
9b371988 | 20226 | incremented, and if it ever gets to the value of &%connection_max_messages%&, |
168e428f PH |
20227 | no further messages are sent over that connection. |
20228 | ||
20229 | ||
20230 | ||
9b371988 PH |
20231 | .section "Use of the $host variable" |
20232 | .cindex "&$host$&" | |
20233 | .cindex "&$host_address$&" | |
20234 | At the start of a run of the &(smtp)& transport, the values of &$host$& and | |
20235 | &$host_address$& are the name and IP address of the first host on the host list | |
168e428f | 20236 | passed by the router. However, when the transport is about to connect to a |
9b371988 PH |
20237 | specific host, and while it is connected to that host, &$host$& and |
20238 | &$host_address$& are set to the values for that host. These are the values | |
20239 | that are in force when the &%helo_data%&, &%hosts_try_auth%&, &%interface%&, | |
20240 | &%serialize_hosts%&, and the various TLS options are expanded. | |
168e428f PH |
20241 | |
20242 | ||
20243 | ||
9b371988 PH |
20244 | .section "Private options for smtp" |
20245 | .cindex "options" "&(smtp)& transport" | |
20246 | The private options of the &(smtp)& transport are as follows: | |
168e428f PH |
20247 | |
20248 | ||
9b371988 PH |
20249 | .option allow_localhost smtp boolean false |
20250 | .cindex "local host" "sending to" | |
20251 | .cindex "fallback" "hosts specified on transport" | |
20252 | When a host specified in &%hosts%& or &%fallback_hosts%& (see below) turns out | |
20253 | to be the local host, or is listed in &%hosts_treat_as_local%&, delivery is | |
20254 | deferred by default. However, if &%allow_localhost%& is set, Exim goes on to do | |
168e428f PH |
20255 | the delivery anyway. This should be used only in special cases when the |
20256 | configuration ensures that no looping will result (for example, a differently | |
20257 | configured Exim is listening on the port to which the message is sent). | |
20258 | ||
20259 | ||
9b371988 PH |
20260 | .option authenticated_sender smtp string&!! unset |
20261 | .cindex "Cyrus" | |
168e428f PH |
20262 | When Exim has authenticated as a client, this option sets a value for the |
20263 | AUTH= item on outgoing MAIL commands, overriding any existing | |
20264 | authenticated sender value. If the string expansion is forced to fail, the | |
20265 | option is ignored. Other expansion failures cause delivery to be deferred. If | |
20266 | the result of expansion is an empty string, that is also ignored. | |
20267 | ||
20268 | If the SMTP session is not authenticated, the expansion of | |
9b371988 | 20269 | &%authenticated_sender%& still happens (and can cause the delivery to be |
168e428f PH |
20270 | deferred if it fails), but no AUTH= item is added to MAIL commands. |
20271 | ||
9b371988 | 20272 | This option allows you to use the &(smtp)& transport in LMTP mode to |
168e428f | 20273 | deliver mail to Cyrus IMAP and provide the proper local part as the |
9b371988 PH |
20274 | &"authenticated sender"&, via a setting such as: |
20275 | .code | |
20276 | authenticated_sender = $local_part | |
20277 | .endd | |
168e428f PH |
20278 | This removes the need for IMAP subfolders to be assigned special ACLs to |
20279 | allow direct delivery to those subfolders. | |
20280 | ||
20281 | Because of expected uses such as that just described for Cyrus (when no | |
20282 | domain is involved), there is no checking on the syntax of the provided | |
20283 | value. | |
20284 | ||
20285 | ||
9b371988 | 20286 | .option command_timeout smtp time 5m |
168e428f PH |
20287 | This sets a timeout for receiving a response to an SMTP command that has been |
20288 | sent out. It is also used when waiting for the initial banner line from the | |
20289 | remote host. Its value must not be zero. | |
20290 | ||
20291 | ||
9b371988 PH |
20292 | .option connect_timeout smtp time 5m |
20293 | This sets a timeout for the &[connect()]& function, which sets up a TCP/IP call | |
168e428f PH |
20294 | to a remote host. A setting of zero allows the system timeout (typically |
20295 | several minutes) to act. To have any effect, the value of this option must be | |
20296 | less than the system timeout. However, it has been observed that on some | |
20297 | systems there is no system timeout, which is why the default value for this | |
20298 | option is 5 minutes, a value recommended by RFC 1123. | |
20299 | ||
20300 | ||
9b371988 PH |
20301 | .option connection_max_messages smtp integer 500 |
20302 | .cindex "SMTP" "passed connection" | |
20303 | .cindex "SMTP" "multiple deliveries" | |
20304 | .cindex "multiple SMTP deliveries" | |
168e428f PH |
20305 | This controls the maximum number of separate message deliveries that are sent |
20306 | over a single TCP/IP connection. If the value is zero, there is no limit. | |
9b371988 | 20307 | For testing purposes, this value can be overridden by the &%-oB%& command line |
168e428f PH |
20308 | option. |
20309 | ||
20310 | ||
9b371988 | 20311 | .option data_timeout smtp time 5m |
168e428f PH |
20312 | This sets a timeout for the transmission of each block in the data portion of |
20313 | the message. As a result, the overall timeout for a message depends on the size | |
9b371988 | 20314 | of the message. Its value must not be zero. See also &%final_timeout%&. |
168e428f PH |
20315 | |
20316 | ||
9b371988 | 20317 | .option delay_after_cutoff smtp boolean true |
168e428f PH |
20318 | This option controls what happens when all remote IP addresses for a given |
20319 | domain have been inaccessible for so long that they have passed their retry | |
20320 | cutoff times. | |
20321 | ||
20322 | In the default state, if the next retry time has not been reached for any of | |
20323 | them, the address is bounced without trying any deliveries. In other words, | |
20324 | Exim delays retrying an IP address after the final cutoff time until a new | |
20325 | retry time is reached, and can therefore bounce an address without ever trying | |
20326 | a delivery, when machines have been down for a long time. Some people are | |
20327 | unhappy at this prospect, so... | |
20328 | ||
9b371988 | 20329 | If &%delay_after_cutoff%& is set false, Exim behaves differently. If all IP |
168e428f PH |
20330 | addresses are past their final cutoff time, Exim tries to deliver to those |
20331 | IP addresses that have not been tried since the message arrived. If there are | |
20332 | none, of if they all fail, the address is bounced. In other words, it does not | |
20333 | delay when a new message arrives, but immediately tries those expired IP | |
20334 | addresses that haven't been tried since the message arrived. If there is a | |
20335 | continuous stream of messages for the dead hosts, unsetting | |
9b371988 | 20336 | &%delay_after_cutoff%& means that there will be many more attempts to deliver |
168e428f PH |
20337 | to them. |
20338 | ||
20339 | ||
9b371988 PH |
20340 | .option dns_qualify_single smtp boolean true |
20341 | If the &%hosts%& or &%fallback_hosts%& option is being used, | |
20342 | and the &%gethostbyname%& option is false, | |
20343 | the RES_DEFNAMES resolver option is set. See the &%qualify_single%& option | |
20344 | in chapter &<<CHAPdnslookup>>& for more details. | |
168e428f | 20345 | |
168e428f | 20346 | |
9b371988 PH |
20347 | .option dns_search_parents smtp boolean false |
20348 | .cindex "&%search_parents%&" | |
20349 | If the &%hosts%& or &%fallback_hosts%& option is being used, and the | |
20350 | &%gethostbyname%& option is false, the RES_DNSRCH resolver option is set. | |
20351 | See the &%search_parents%& option in chapter &<<CHAPdnslookup>>& for more | |
20352 | details. | |
168e428f PH |
20353 | |
20354 | ||
168e428f | 20355 | |
9b371988 PH |
20356 | .option fallback_hosts smtp "string list" unset |
20357 | .new | |
20358 | .cindex "fallback" "hosts specified on transport" | |
168e428f | 20359 | String expansion is not applied to this option. The argument must be a |
068aaea8 PH |
20360 | colon-separated list of host names or IP addresses, optionally also including |
20361 | port numbers, though the separator can be changed, as described in section | |
9b371988 PH |
20362 | &<<SECTlistconstruct>>&. Each individual item in the list is the same as an |
20363 | item in a &%route_list%& setting for the &(manualroute)& router, as described | |
20364 | in section &<<SECTformatonehostitem>>&. | |
20365 | .wen | |
068aaea8 PH |
20366 | |
20367 | Fallback hosts can also be specified on routers, which associate them with the | |
9b371988 PH |
20368 | addresses they process. As for the &%hosts%& option without &%hosts_override%&, |
20369 | &%fallback_hosts%& specified on the transport is used only if the address does | |
20370 | not have its own associated fallback host list. Unlike &%hosts%&, a setting of | |
20371 | &%fallback_hosts%& on an address is not overridden by &%hosts_override%&. | |
20372 | However, &%hosts_randomize%& does apply to fallback host lists. | |
168e428f PH |
20373 | |
20374 | If Exim is unable to deliver to any of the hosts for a particular address, and | |
20375 | the errors are not permanent rejections, the address is put on a separate | |
20376 | transport queue with its host list replaced by the fallback hosts, unless the | |
20377 | address was routed via MX records and the current host was in the original MX | |
20378 | list. In that situation, the fallback host list is not used. | |
20379 | ||
20380 | Once normal deliveries are complete, the fallback queue is delivered by | |
20381 | re-running the same transports with the new host lists. If several failing | |
9b371988 | 20382 | addresses have the same fallback hosts (and &%max_rcpt%& permits it), a single |
168e428f PH |
20383 | copy of the message is sent. |
20384 | ||
20385 | The resolution of the host names on the fallback list is controlled by the | |
9b371988 | 20386 | &%gethostbyname%& option, as for the &%hosts%& option. Fallback hosts apply |
168e428f | 20387 | both to cases when the host list comes with the address and when it is taken |
9b371988 PH |
20388 | from &%hosts%&. This option provides a &"use a smart host only if delivery |
20389 | fails"& facility. | |
168e428f PH |
20390 | |
20391 | ||
9b371988 | 20392 | .option final_timeout smtp time 10m |
168e428f | 20393 | This is the timeout that applies while waiting for the response to the final |
9b371988 PH |
20394 | line containing just &"."& that terminates a message. Its value must not be |
20395 | zero. | |
168e428f | 20396 | |
168e428f | 20397 | |
9b371988 PH |
20398 | .option gethostbyname smtp boolean false |
20399 | If this option is true when the &%hosts%& and/or &%fallback_hosts%& options are | |
20400 | being used, names are looked up using &[gethostbyname()]& | |
20401 | (or &[getipnodebyname()]& when available) | |
168e428f | 20402 | instead of using the DNS. Of course, that function may in fact use the DNS, but |
9b371988 PH |
20403 | it may also consult other sources of information such as &_/etc/hosts_&. |
20404 | ||
20405 | .option helo_data smtp string&!! &`$primary_hostname`& | |
20406 | .cindex "HELO argument" "setting" | |
20407 | .cindex "EHLO argument" "setting" | |
20408 | .new | |
20409 | The value of this option is expanded, and used as the argument for the EHLO or | |
20410 | HELO command that starts the outgoing SMTP session. The variables &$host$& and | |
20411 | &$host_address$& are set to the identity of the remote host, and can be used to | |
20412 | generate different values for different servers. | |
20413 | .wen | |
20414 | ||
20415 | .option hosts smtp "string list&!!" unset | |
20416 | Hosts are associated with an address by a router such as &(dnslookup)&, which | |
068aaea8 | 20417 | finds the hosts by looking up the address domain in the DNS, or by |
9b371988 PH |
20418 | &(manualroute)&, which has lists of hosts in its configuration. However, |
20419 | email addresses can be passed to the &(smtp)& transport by any router, and not | |
068aaea8 PH |
20420 | all of them can provide an associated list of hosts. |
20421 | ||
9b371988 | 20422 | The &%hosts%& option specifies a list of hosts to be used if the address being |
068aaea8 | 20423 | processed does not have any hosts associated with it. The hosts specified by |
9b371988 PH |
20424 | &%hosts%& are also used, whether or not the address has its own hosts, if |
20425 | &%hosts_override%& is set. | |
168e428f | 20426 | |
9b371988 | 20427 | .new |
168e428f | 20428 | The string is first expanded, before being interpreted as a colon-separated |
068aaea8 PH |
20429 | list of host names or IP addresses, possibly including port numbers. The |
20430 | separator may be changed to something other than colon, as described in section | |
9b371988 PH |
20431 | &<<SECTlistconstruct>>&. Each individual item in the list is the same as an |
20432 | item in a &%route_list%& setting for the &(manualroute)& router, as described | |
20433 | in section &<<SECTformatonehostitem>>&. However, note that the &`/MX`& facility | |
20434 | of the &(manualroute)& router is not available here. | |
20435 | .wen | |
068aaea8 PH |
20436 | |
20437 | If the expansion fails, delivery is deferred. Unless the failure was caused by | |
20438 | the inability to complete a lookup, the error is logged to the panic log as | |
20439 | well as the main log. Host names are looked up either by searching directly for | |
9b371988 PH |
20440 | address records in the DNS or by calling &[gethostbyname()]& (or |
20441 | &[getipnodebyname()]& when available), depending on the setting of the | |
20442 | &%gethostbyname%& option. When Exim is compiled with IPv6 support, if a host | |
20443 | that is looked up in the DNS has both IPv4 and IPv6 addresses, both types of | |
20444 | address are used. | |
168e428f PH |
20445 | |
20446 | During delivery, the hosts are tried in order, subject to their retry status, | |
9b371988 | 20447 | unless &%hosts_randomize%& is set. |
168e428f | 20448 | |
168e428f | 20449 | |
9b371988 PH |
20450 | .option hosts_avoid_esmtp smtp "host list&!!" unset |
20451 | .cindex "ESMTP" "avoiding use of" | |
20452 | .cindex "HELO" "forcing use of" | |
20453 | .cindex "EHLO" "avoiding use of" | |
20454 | .cindex "PIPELINING" "avoiding the use of" | |
168e428f PH |
20455 | This option is for use with broken hosts that announce ESMTP facilities (for |
20456 | example, PIPELINING) and then fail to implement them properly. When a host | |
9b371988 | 20457 | matches &%hosts_avoid_esmtp%&, Exim sends HELO rather than EHLO at the |
168e428f PH |
20458 | start of the SMTP session. This means that it cannot use any of the ESMTP |
20459 | facilities such as AUTH, PIPELINING, SIZE, and STARTTLS. | |
20460 | ||
20461 | ||
9b371988 PH |
20462 | .option hosts_avoid_tls smtp "host list&!!" unset |
20463 | .cindex "TLS" "avoiding for certain hosts" | |
168e428f | 20464 | Exim will not try to start a TLS session when delivering to any host that |
9b371988 | 20465 | matches this list. See chapter &<<CHAPTLS>>& for details of TLS. |
168e428f | 20466 | |
168e428f | 20467 | |
9b371988 PH |
20468 | .option hosts_max_try smtp integer 5 |
20469 | .cindex "host" "maximum number to try" | |
20470 | .cindex "limit" "number of hosts tried" | |
20471 | .cindex "limit" "number of MX tried" | |
20472 | .cindex "MX record" "maximum tried" | |
168e428f PH |
20473 | This option limits the number of IP addresses that are tried for any one |
20474 | delivery in cases where there are temporary delivery errors. Section | |
9b371988 | 20475 | &<<SECTvalhosmax>>& describes in detail how the value of this option is used. |
168e428f PH |
20476 | |
20477 | ||
9b371988 | 20478 | .option hosts_max_try_hardlimit smtp integer 50 |
168e428f | 20479 | This is an additional check on the maximum number of IP addresses that Exim |
9b371988 PH |
20480 | tries for any one delivery. Section &<<SECTvalhosmax>>& describes its use and |
20481 | why it exists. | |
168e428f PH |
20482 | |
20483 | ||
168e428f | 20484 | |
9b371988 PH |
20485 | .option hosts_nopass_tls smtp "host list&!!" unset |
20486 | .cindex "TLS" "passing connection" | |
20487 | .cindex "multiple SMTP deliveries" | |
20488 | .cindex "TLS" "multiple message deliveries" | |
168e428f PH |
20489 | For any host that matches this list, a connection on which a TLS session has |
20490 | been started will not be passed to a new delivery process for sending another | |
9b371988 PH |
20491 | message on the same connection. See section &<<SECTmulmessam>>& for an |
20492 | explanation of when this might be needed. | |
168e428f PH |
20493 | |
20494 | ||
9b371988 PH |
20495 | .option hosts_override smtp boolean false |
20496 | If this option is set and the &%hosts%& option is also set, any hosts that are | |
168e428f | 20497 | attached to the address are ignored, and instead the hosts specified by the |
9b371988 PH |
20498 | &%hosts%& option are always used. This option does not apply to |
20499 | &%fallback_hosts%&. | |
168e428f | 20500 | |
168e428f | 20501 | |
9b371988 PH |
20502 | .option hosts_randomize smtp boolean false |
20503 | .cindex "randomized host list" | |
20504 | .cindex "host" "list of; randomized" | |
20505 | .cindex "fallback" "randomized hosts" | |
168e428f | 20506 | If this option is set, and either the list of hosts is taken from the |
9b371988 | 20507 | &%hosts%& or the &%fallback_hosts%& option, or the hosts supplied by the router |
168e428f PH |
20508 | were not obtained from MX records (this includes fallback hosts from the |
20509 | router), and were not randomizied by the router, the order of trying the hosts | |
20510 | is randomized each time the transport runs. Randomizing the order of a host | |
20511 | list can be used to do crude load sharing. | |
20512 | ||
9b371988 | 20513 | When &%hosts_randomize%& is true, a host list may be split into groups whose |
168e428f PH |
20514 | order is separately randomized. This makes it possible to set up MX-like |
20515 | behaviour. The boundaries between groups are indicated by an item that is just | |
9b371988 PH |
20516 | &`+`& in the host list. For example: |
20517 | .code | |
20518 | hosts = host1:host2:host3:+:host4:host5 | |
20519 | .endd | |
168e428f PH |
20520 | The order of the first three hosts and the order of the last two hosts is |
20521 | randomized for each use, but the first three always end up before the last two. | |
9b371988 | 20522 | If &%hosts_randomize%& is not set, a &`+`& item in the list is ignored. |
168e428f | 20523 | |
9b371988 PH |
20524 | .option hosts_require_auth smtp "host list&!!" unset |
20525 | .cindex "authentication" "required by client" | |
168e428f PH |
20526 | This option provides a list of servers for which authentication must succeed |
20527 | before Exim will try to transfer a message. If authentication fails for | |
20528 | servers which are not in this list, Exim tries to send unauthenticated. If | |
20529 | authentication fails for one of these servers, delivery is deferred. This | |
20530 | temporary error is detectable in the retry rules, so it can be turned into a | |
9b371988 PH |
20531 | hard failure if required. See also &%hosts_try_auth%&, and chapter |
20532 | &<<CHAPSMTPAUTH>>& for details of authentication. | |
168e428f | 20533 | |
168e428f | 20534 | |
9b371988 PH |
20535 | .option hosts_require_tls smtp "host list&!!" unset |
20536 | .cindex "TLS" "requiring for certain servers" | |
168e428f | 20537 | Exim will insist on using a TLS session when delivering to any host that |
9b371988 PH |
20538 | matches this list. See chapter &<<CHAPTLS>>& for details of TLS. |
20539 | &*Note*&: This option affects outgoing mail only. To insist on TLS for | |
168e428f PH |
20540 | incoming messages, use an appropriate ACL. |
20541 | ||
9b371988 PH |
20542 | .option hosts_try_auth smtp "host list&!!" unset |
20543 | .cindex "authentication" "optional in client" | |
168e428f PH |
20544 | This option provides a list of servers to which, provided they announce |
20545 | authentication support, Exim will attempt to authenticate as a client when it | |
20546 | connects. If authentication fails, Exim will try to transfer the message | |
9b371988 PH |
20547 | unauthenticated. See also &%hosts_require_auth%&, and chapter |
20548 | &<<CHAPSMTPAUTH>>& for details of authentication. | |
20549 | ||
20550 | .option interface smtp "string list&!!" unset | |
20551 | .cindex "bind IP address" | |
20552 | .cindex "IP address" "binding" | |
20553 | .cindex "&$host$&" | |
20554 | .cindex "&$host_address$&" | |
168e428f | 20555 | This option specifies which interface to bind to when making an outgoing SMTP |
9b371988 | 20556 | call. The variables &$host$& and &$host_address$& refer to the host to which a |
168e428f PH |
20557 | connection is about to be made during the expansion of the string. Forced |
20558 | expansion failure, or an empty string result causes the option to be ignored. | |
20559 | Otherwise, after expansion, | |
20560 | the string must be a list of IP addresses, colon-separated by default, but the | |
20561 | separator can be changed in the usual way. | |
20562 | For example: | |
9b371988 PH |
20563 | .code |
20564 | interface = <; 192.168.123.123 ; 3ffe:ffff:836f::fe86:a061 | |
20565 | .endd | |
168e428f PH |
20566 | The first interface of the correct type (IPv4 or IPv6) is used for the outgoing |
20567 | connection. If none of them are the correct type, the option is ignored. If | |
9b371988 | 20568 | &%interface%& is not set, or is ignored, the system's IP functions choose which |
168e428f PH |
20569 | interface to use if the host has more than one. |
20570 | ||
20571 | ||
9b371988 PH |
20572 | .option keepalive smtp boolean true |
20573 | .cindex "keepalive" "on outgoing connection" | |
168e428f PH |
20574 | This option controls the setting of SO_KEEPALIVE on outgoing TCP/IP socket |
20575 | connections. When set, it causes the kernel to probe idle connections | |
9b371988 PH |
20576 | periodically, by sending packets with &"old"& sequence numbers. The other end |
20577 | of the connection should send a acknowledgement if the connection is still okay | |
20578 | or a reset if the connection has been aborted. The reason for doing this is | |
20579 | that it has the beneficial effect of freeing up certain types of connection | |
20580 | that can get stuck when the remote host is disconnected without tidying up the | |
20581 | TCP/IP call properly. The keepalive mechanism takes several hours to detect | |
168e428f PH |
20582 | unreachable hosts. |
20583 | ||
20584 | ||
9b371988 PH |
20585 | .new |
20586 | .option lmtp_ignore_quota smtp boolean false | |
20587 | .cindex "LMTP" "ignoring quota errors" | |
20588 | If this option is set true when the &%protocol%& option is set to &"lmtp"&, the | |
20589 | string &`IGNOREQUOTA`& is added to RCPT commands, provided that the LMTP server | |
068aaea8 | 20590 | has advertised support for IGNOREQUOTA in its response to the LHLO command. |
9b371988 | 20591 | .wen |
068aaea8 | 20592 | |
9b371988 PH |
20593 | .option max_rcpt smtp integer 100 |
20594 | .cindex "RCPT" "maximum number of outgoing" | |
168e428f PH |
20595 | This option limits the number of RCPT commands that are sent in a single |
20596 | SMTP message transaction. Each set of addresses is treated independently, and | |
9b371988 | 20597 | so can cause parallel connections to the same host if &%remote_max_parallel%& |
168e428f PH |
20598 | permits this. |
20599 | ||
20600 | ||
9b371988 PH |
20601 | .option multi_domain smtp boolean true |
20602 | .cindex "&$domain$&" | |
20603 | When this option is set, the &(smtp)& transport can handle a number of | |
20604 | addresses containing a mixture of different domains provided they all resolve | |
20605 | to the same list of hosts. Turning the option off restricts the transport to | |
20606 | handling only one domain at a time. This is useful if you want to use | |
20607 | &$domain$& in an expansion for the transport, because it is set only when there | |
20608 | is a single domain involved in a remote delivery. | |
168e428f PH |
20609 | |
20610 | ||
9b371988 PH |
20611 | .option port smtp string&!! "see below" |
20612 | .cindex "port" "sending TCP/IP" | |
20613 | .cindex "TCP/IP" "setting outgoing port" | |
168e428f PH |
20614 | This option specifies the TCP/IP port on the server to which Exim connects. If |
20615 | it begins with a digit it is taken as a port number; otherwise it is looked up | |
9b371988 PH |
20616 | using &[getservbyname()]&. The default value is normally &"smtp"&, but if |
20617 | &%protocol%& is set to &"lmtp"&, the default is &"lmtp"&. | |
168e428f PH |
20618 | If the expansion fails, or if a port number cannot be found, delivery is |
20619 | deferred. | |
20620 | ||
20621 | ||
20622 | ||
9b371988 PH |
20623 | .option protocol smtp string smtp |
20624 | .cindex "LMTP" "over TCP/IP" | |
20625 | If this option is set to &"lmtp"& instead of &"smtp"&, the default value for | |
20626 | the &%port%& option changes to &"lmtp"&, and the transport operates the LMTP | |
20627 | protocol (RFC 2033) instead of SMTP. This protocol is sometimes used for local | |
168e428f | 20628 | deliveries into closed message stores. Exim also has support for running LMTP |
9b371988 | 20629 | over a pipe to a local process &-- see chapter &<<CHAPLMTP>>&. |
168e428f PH |
20630 | |
20631 | ||
9b371988 | 20632 | .option retry_include_ip_address smtp boolean true |
168e428f PH |
20633 | Exim normally includes both the host name and the IP address in the key it |
20634 | constructs for indexing retry data after a temporary delivery failure. This | |
20635 | means that when one of several IP addresses for a host is failing, it gets | |
20636 | tried periodically (controlled by the retry rules), but use of the other IP | |
20637 | addresses is not affected. | |
20638 | ||
20639 | However, in some dialup environments hosts are assigned a different IP address | |
20640 | each time they connect. In this situation the use of the IP address as part of | |
20641 | the retry key leads to undesirable behaviour. Setting this option false causes | |
20642 | Exim to use only the host name. This should normally be done on a separate | |
9b371988 PH |
20643 | instance of the &(smtp)& transport, set up specially to handle the dialup |
20644 | hosts. | |
168e428f | 20645 | |
168e428f | 20646 | |
9b371988 PH |
20647 | .option serialize_hosts smtp "host list&!!" unset |
20648 | .cindex "serializing connections" | |
20649 | .cindex "host" "serializing connections" | |
168e428f PH |
20650 | Because Exim operates in a distributed manner, if several messages for the same |
20651 | host arrive at around the same time, more than one simultaneous connection to | |
20652 | the remote host can occur. This is not usually a problem except when there is a | |
20653 | slow link between the hosts. In that situation it may be helpful to restrict | |
20654 | Exim to one connection at a time. This can be done by setting | |
9b371988 | 20655 | &%serialize_hosts%& to match the relevant hosts. |
168e428f | 20656 | |
9b371988 | 20657 | .cindex "hints database" "serializing deliveries to a host" |
168e428f PH |
20658 | Exim implements serialization by means of a hints database in which a record is |
20659 | written whenever a process connects to one of the restricted hosts. The record | |
20660 | is deleted when the connection is completed. Obviously there is scope for | |
20661 | records to get left lying around if there is a system or program crash. To | |
20662 | guard against this, Exim ignores any records that are more than six hours old. | |
20663 | ||
20664 | If you set up this kind of serialization, you should also arrange to delete the | |
20665 | relevant hints database whenever your system reboots. The names of the files | |
9b371988 | 20666 | start with &_misc_& and they are kept in the &_spool/db_& directory. There |
168e428f PH |
20667 | may be one or two files, depending on the type of DBM in use. The same files |
20668 | are used for ETRN serialization. | |
20669 | ||
20670 | ||
9b371988 PH |
20671 | .option size_addition smtp integer 1024 |
20672 | .cindex "SMTP" "SIZE" | |
20673 | .cindex "message" "size issue for transport filter" | |
20674 | .cindex "size" "of message" | |
20675 | .cindex "transport" "filter" | |
20676 | .cindex "filter" "transport filter" | |
168e428f PH |
20677 | If a remote SMTP server indicates that it supports the SIZE option of the |
20678 | MAIL command, Exim uses this to pass over the message size at the start of | |
9b371988 | 20679 | an SMTP transaction. It adds the value of &%size_addition%& to the value it |
168e428f PH |
20680 | sends, to allow for headers and other text that may be added during delivery by |
20681 | configuration options or in a transport filter. It may be necessary to increase | |
20682 | this if a lot of text is added to messages. | |
20683 | ||
9b371988 | 20684 | Alternatively, if the value of &%size_addition%& is set negative, it disables |
168e428f PH |
20685 | the use of the SIZE option altogether. |
20686 | ||
20687 | ||
9b371988 PH |
20688 | .option tls_certificate smtp string&!! unset |
20689 | .cindex "TLS client certificate" "location of" | |
20690 | .cindex "certificate for client" "location of" | |
20691 | .cindex "&$host$&" | |
20692 | .cindex "&$host_address$&" | |
168e428f | 20693 | The value of this option must be the absolute path to a file which contains the |
9b371988 PH |
20694 | client's certificate, for possible use when sending a message over an encrypted |
20695 | connection. The values of &$host$& and &$host_address$& are set to the name and | |
20696 | address of the server during the expansion. See chapter &<<CHAPTLS>>& for | |
168e428f PH |
20697 | details of TLS. |
20698 | ||
9b371988 PH |
20699 | &*Note*&: This option must be set if you want Exim to be able to use a TLS |
20700 | certificate when sending messages as a client. The global option of the same | |
20701 | name specifies the certificate for Exim as a server; it is not automatically | |
20702 | assumed that the same certificate should be used when Exim is operating as a | |
20703 | client. | |
168e428f PH |
20704 | |
20705 | ||
9b371988 PH |
20706 | .option tls_crl smtp string&!! unset |
20707 | .cindex "TLS" "client certificate revocation list" | |
20708 | .cindex "certificate" "revocation list for client" | |
168e428f PH |
20709 | This option specifies a certificate revocation list. The expanded value must |
20710 | be the name of a file that contains a CRL in PEM format. | |
20711 | ||
20712 | ||
9b371988 PH |
20713 | .option tls_privatekey smtp string&!! unset |
20714 | .cindex "TLS client private key" "location of" | |
20715 | .cindex "&$host$&" | |
20716 | .cindex "&$host_address$&" | |
168e428f | 20717 | The value of this option must be the absolute path to a file which contains the |
9b371988 PH |
20718 | client's private key. This is used when sending a message over an encrypted |
20719 | connection using a client certificate. The values of &$host$& and | |
20720 | &$host_address$& are set to the name and address of the server during the | |
20721 | expansion. If this option is unset, the private key is assumed to be in the | |
20722 | same file as the certificate. See chapter &<<CHAPTLS>>& for details of TLS. | |
20723 | ||
20724 | ||
20725 | .option tls_require_ciphers smtp string&!! unset | |
20726 | .cindex "TLS" "requiring specific ciphers" | |
20727 | .cindex "cipher" "requiring specific" | |
20728 | .cindex "&$host$&" | |
20729 | .cindex "&$host_address$&" | |
168e428f PH |
20730 | The value of this option must be a list of permitted cipher suites, for use |
20731 | when setting up an outgoing encrypted connection. (There is a global option of | |
9b371988 PH |
20732 | the same name for controlling incoming connections.) The values of &$host$& and |
20733 | &$host_address$& are set to the name and address of the server during the | |
20734 | expansion. See chapter &<<CHAPTLS>>& for details of TLS; note that this option | |
20735 | is used in different ways by OpenSSL and GnuTLS (see sections | |
20736 | &<<SECTreqciphssl>>& and &<<SECTreqciphgnu>>&). For GnuTLS, the order of the | |
20737 | ciphers is a preference order. | |
168e428f PH |
20738 | |
20739 | ||
20740 | ||
9b371988 PH |
20741 | .option tls_tempfail_tryclear smtp boolean true |
20742 | When the server host is not in &%hosts_require_tls%&, and there is a problem in | |
168e428f PH |
20743 | setting up a TLS session, this option determines whether or not Exim should try |
20744 | to deliver the message unencrypted. If it is set false, delivery to the | |
20745 | current host is deferred; if there are other hosts, they are tried. If this | |
9b371988 | 20746 | option is set true, Exim attempts to deliver unencrypted after a 4&'xx'& |
168e428f PH |
20747 | response to STARTTLS. Also, if STARTTLS is accepted, but the subsequent |
20748 | TLS negotiation fails, Exim closes the current connection (because it is in an | |
20749 | unknown state), opens a new one to the same host, and then tries the delivery | |
20750 | in clear. | |
20751 | ||
20752 | ||
9b371988 PH |
20753 | .option tls_verify_certificates smtp string&!! unset |
20754 | .cindex "TLS" "server certificate verification" | |
20755 | .cindex "certificate" "verification of server" | |
20756 | .cindex "&$host$&" | |
20757 | .cindex "&$host_address$&" | |
168e428f PH |
20758 | The value of this option must be the absolute path to a file containing |
20759 | permitted server certificates, for use when setting up an encrypted connection. | |
20760 | Alternatively, if you are using OpenSSL, you can set | |
9b371988 | 20761 | &%tls_verify_certificates%& to the name of a directory containing certificate |
168e428f | 20762 | files. This does not work with GnuTLS; the option must be set to the name of a |
9b371988 PH |
20763 | single file if you are using GnuTLS. The values of &$host$& and |
20764 | &$host_address$& are set to the name and address of the server during the | |
20765 | expansion of this option. See chapter &<<CHAPTLS>>& for details of TLS. | |
168e428f PH |
20766 | |
20767 | ||
20768 | ||
20769 | ||
9b371988 PH |
20770 | .section "How the limits for the number of hosts to try are used" &&& |
20771 | "SECTvalhosmax" | |
20772 | .cindex "host" "maximum number to try" | |
20773 | .cindex "limit" "hosts; maximum number tried" | |
168e428f | 20774 | There are two options that are concerned with the number of hosts that are |
9b371988 PH |
20775 | tried when an SMTP delivery takes place. They are &%hosts_max_try%& and |
20776 | &%hosts_max_try_hardlimit%&. | |
168e428f PH |
20777 | |
20778 | ||
9b371988 PH |
20779 | The &%hosts_max_try%& option limits the number of hosts that are tried |
20780 | for a single delivery. However, despite the term &"host"& in its name, the | |
20781 | option actually applies to each IP address independently. In other words, a | |
20782 | multihomed host is treated as several independent hosts, just as it is for | |
20783 | retrying. | |
168e428f PH |
20784 | |
20785 | Many of the larger ISPs have multiple MX records which often point to | |
20786 | multihomed hosts. As a result, a list of a dozen or more IP addresses may be | |
20787 | created as a result of routing one of these domains. | |
20788 | ||
20789 | Trying every single IP address on such a long list does not seem sensible; if | |
20790 | several at the top of the list fail, it is reasonable to assume there is some | |
20791 | problem that is likely to affect all of them. Roughly speaking, the value of | |
9b371988 | 20792 | &%hosts_max_try%& is the maximum number that are tried before deferring the |
168e428f PH |
20793 | delivery. However, the logic cannot be quite that simple. |
20794 | ||
20795 | Firstly, IP addresses that are skipped because their retry times have not | |
20796 | arrived do not count, and in addition, addresses that are past their retry | |
20797 | limits are also not counted, even when they are tried. This means that when | |
20798 | some IP addresses are past their retry limits, more than the value of | |
9b371988 | 20799 | &%hosts_max_retry%& may be tried. The reason for this behaviour is to ensure |
168e428f PH |
20800 | that all IP addresses are considered before timing out an email address (but |
20801 | see below for an exception). | |
20802 | ||
9b371988 | 20803 | Secondly, when the &%hosts_max_try%& limit is reached, Exim looks down the host |
168e428f PH |
20804 | list to see if there is a subsequent host with a different (higher valued) MX. |
20805 | If there is, that host is considered next, and the current IP address is used | |
20806 | but not counted. This behaviour helps in the case of a domain with a retry rule | |
20807 | that hardly ever delays any hosts, as is now explained: | |
20808 | ||
20809 | Consider the case of a long list of hosts with one MX value, and a few with a | |
9b371988 | 20810 | higher MX value. If &%hosts_max_try%& is small (the default is 5) only a few |
168e428f PH |
20811 | hosts at the top of the list are tried at first. With the default retry rule, |
20812 | which specifies increasing retry times, the higher MX hosts are eventually | |
20813 | tried when those at the top of the list are skipped because they have not | |
20814 | reached their retry times. | |
20815 | ||
20816 | However, it is common practice to put a fixed short retry time on domains for | |
20817 | large ISPs, on the grounds that their servers are rarely down for very long. | |
20818 | Unfortunately, these are exactly the domains that tend to resolve to long lists | |
20819 | of hosts. The short retry time means that the lowest MX hosts are tried every | |
20820 | time. The attempts may be in a different order because of random sorting, but | |
9b371988 PH |
20821 | without the special MX check, the higher MX hosts would never be tried until |
20822 | all the lower MX hosts had timed out (which might be several days), because | |
20823 | there are always some lower MX hosts that have reached their retry times. With | |
20824 | the special check, Exim considers at least one IP address from each MX value at | |
20825 | every delivery attempt, even if the &%hosts_max_try%& limit has already been | |
20826 | reached. | |
20827 | ||
20828 | The above logic means that &%hosts_max_try%& is not a hard limit, and in | |
168e428f | 20829 | particular, Exim normally eventually tries all the IP addresses before timing |
9b371988 | 20830 | out an email address. When &%hosts_max_try%& was implemented, this seemed a |
168e428f PH |
20831 | reasonable thing to do. Recently, however, some lunatic DNS configurations have |
20832 | been set up with hundreds of IP addresses for some domains. It can | |
20833 | take a very long time indeed for an address to time out in these cases. | |
20834 | ||
9b371988 | 20835 | The &%hosts_max_try_hardlimit%& option was added to help with this problem. |
168e428f PH |
20836 | Exim never tries more than this number of IP addresses; if it hits this limit |
20837 | and they are all timed out, the email address is bounced, even though not all | |
20838 | possible IP addresses have been tried. | |
20839 | ||
20840 | ||
20841 | ||
20842 | ||
20843 | ||
9b371988 PH |
20844 | . //////////////////////////////////////////////////////////////////////////// |
20845 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 20846 | |
9b371988 PH |
20847 | .chapter "Address rewriting" "CHAPrewrite" |
20848 | .cindex "rewriting" "addresses" | |
168e428f PH |
20849 | There are some circumstances in which Exim automatically rewrites domains in |
20850 | addresses. The two most common are when an address is given without a domain | |
9b371988 | 20851 | (referred to as an &"unqualified address"&) or when an address contains an |
168e428f PH |
20852 | abbreviated domain that is expanded by DNS lookup. |
20853 | ||
20854 | Unqualified envelope addresses are accepted only for locally submitted | |
9b371988 PH |
20855 | messages, or for messages that are received from hosts matching |
20856 | &%sender_unqualified_hosts%& or &%recipient_unqualified_hosts%&, as | |
20857 | appropriate. Unqualified addresses in header lines are qualified if they are in | |
20858 | locally submitted messages, or messages from hosts that are permitted to send | |
20859 | unqualified envelope addresses. Otherwise, unqualified addresses in header | |
20860 | lines are neither qualified nor rewritten. | |
20861 | ||
20862 | One situation in which Exim does &'not'& automatically rewrite a domain is | |
168e428f | 20863 | when it is the name of a CNAME record in the DNS. The older RFCs suggest that |
9b371988 PH |
20864 | such a domain should be rewritten using the &"canonical"& name, and some MTAs |
20865 | do this. The new RFCs do not contain this suggestion. | |
168e428f PH |
20866 | |
20867 | ||
9b371988 | 20868 | .section "Explicitly configured address rewriting" |
168e428f PH |
20869 | This chapter describes the rewriting rules that can be used in the |
20870 | main rewrite section of the configuration file, and also in the generic | |
9b371988 | 20871 | &%headers_rewrite%& option that can be set on any transport. |
168e428f PH |
20872 | |
20873 | Some people believe that configured address rewriting is a Mortal Sin. | |
20874 | Others believe that life is not possible without it. Exim provides the | |
20875 | facility; you do not have to use it. | |
20876 | ||
9b371988 | 20877 | The main rewriting rules that appear in the &"rewrite"& section of the |
168e428f PH |
20878 | configuration file are applied to addresses in incoming messages, both envelope |
20879 | addresses and addresses in header lines. Each rule specifies the types of | |
20880 | address to which it applies. | |
20881 | ||
20882 | Rewriting of addresses in header lines applies only to those headers that | |
20883 | were received with the message, and, in the case of transport rewriting, those | |
20884 | that were added by a system filter. That is, it applies only to those headers | |
20885 | that are common to all copies of the message. Header lines that are added by | |
20886 | individual routers or transports (and which are therefore specific to | |
20887 | individual recipient addresses) are not rewritten. | |
20888 | ||
20889 | In general, rewriting addresses from your own system or domain has some | |
20890 | legitimacy. Rewriting other addresses should be done only with great care and | |
20891 | in special circumstances. The author of Exim believes that rewriting should be | |
9b371988 | 20892 | used sparingly, and mainly for &"regularizing"& addresses in your own domains. |
168e428f PH |
20893 | Although it can sometimes be used as a routing tool, this is very strongly |
20894 | discouraged. | |
20895 | ||
20896 | There are two commonly encountered circumstances where rewriting is used, as | |
20897 | illustrated by these examples: | |
20898 | ||
9b371988 PH |
20899 | .ilist |
20900 | The company whose domain is &'hitch.fict.example'& has a number of hosts that | |
168e428f | 20901 | exchange mail with each other behind a firewall, but there is only a single |
9b371988 PH |
20902 | gateway to the outer world. The gateway rewrites &'*.hitch.fict.example'& as |
20903 | &'hitch.fict.example'& when sending mail off-site. | |
20904 | .next | |
20905 | A host rewrites the local parts of its own users so that, for example, | |
20906 | &'fp42@hitch.fict.example'& becomes &'Ford.Prefect@hitch.fict.example'&. | |
20907 | .endlist | |
168e428f PH |
20908 | |
20909 | ||
20910 | ||
9b371988 PH |
20911 | .section "When does rewriting happen?" |
20912 | .cindex "rewriting" "timing of" | |
20913 | .cindex "&ACL;" "rewriting addresses in" | |
168e428f PH |
20914 | Configured address rewriting can take place at several different stages of a |
20915 | message's processing. | |
20916 | ||
9b371988 | 20917 | .cindex "&$sender_address$&" |
168e428f | 20918 | At the start of an ACL for MAIL, the sender address may have been rewritten |
9b371988 | 20919 | by a special SMTP-time rewrite rule (see section &<<SECTrewriteS>>&), but no |
168e428f PH |
20920 | ordinary rewrite rules have yet been applied. If, however, the sender address |
20921 | is verified in the ACL, it is rewritten before verification, and remains | |
9b371988 | 20922 | rewritten thereafter. The subsequent value of &$sender_address$& is the |
168e428f PH |
20923 | rewritten address. This also applies if sender verification happens in a |
20924 | RCPT ACL. Otherwise, when the sender address is not verified, it is | |
20925 | rewritten as soon as a message's header lines have been received. | |
20926 | ||
9b371988 PH |
20927 | .cindex "&$domain$&" |
20928 | .cindex "&$local_part$&" | |
168e428f PH |
20929 | Similarly, at the start of an ACL for RCPT, the current recipient's address |
20930 | may have been rewritten by a special SMTP-time rewrite rule, but no ordinary | |
20931 | rewrite rules have yet been applied to it. However, the behaviour is different | |
20932 | from the sender address when a recipient is verified. The address is rewritten | |
20933 | for the verification, but the rewriting is not remembered at this stage. The | |
9b371988 PH |
20934 | value of &$local_part$& and &$domain$& after verification are always the same |
20935 | as they were before (that is, they contain the unrewritten &-- except for | |
20936 | SMTP-time rewriting &-- address). | |
168e428f PH |
20937 | |
20938 | Once a message's header lines have been received, all the envelope recipient | |
20939 | addresses are permanently rewritten, and rewriting is also applied to the | |
20940 | addresses in the header lines (if configured). | |
9b371988 | 20941 | .cindex "&[local_scan()]& function" "address rewriting; timing of" |
168e428f | 20942 | Thus, all the rewriting is completed before the DATA ACL and |
9b371988 | 20943 | &[local_scan()]& functions are run. |
168e428f PH |
20944 | |
20945 | When an address is being routed, either for delivery or for verification, | |
20946 | rewriting is applied immediately to child addresses that are generated by | |
9b371988 | 20947 | redirection, unless &%no_rewrite%& is set on the router. |
168e428f | 20948 | |
9b371988 PH |
20949 | .cindex "envelope sender" "rewriting" |
20950 | .cindex "rewriting" "at transport time" | |
168e428f | 20951 | At transport time, additional rewriting of addresses in header lines can be |
9b371988 PH |
20952 | specified by setting the generic &%headers_rewrite%& option on a transport. |
20953 | This option contains rules that are identical in form to those in the rewrite | |
168e428f | 20954 | section of the configuration file. In addition, the outgoing envelope sender |
9b371988 | 20955 | can be rewritten by means of the &%return_path%& transport option. However, it |
168e428f PH |
20956 | is not possible to rewrite envelope recipients at transport time. |
20957 | ||
20958 | ||
20959 | ||
20960 | ||
9b371988 PH |
20961 | .section "Testing the rewriting rules that apply on input" |
20962 | .cindex "rewriting" "testing" | |
20963 | .cindex "testing" "rewriting" | |
168e428f | 20964 | Exim's input rewriting configuration appears in a part of the run time |
9b371988 PH |
20965 | configuration file headed by &"begin rewrite"&. It can be tested by the |
20966 | &%-brw%& command line option. This takes an address (which can be a full RFC | |
20967 | 2822 address) as its argument. The output is a list of how the address would be | |
168e428f PH |
20968 | transformed by the rewriting rules for each of the different places it might |
20969 | appear in an incoming message, that is, for each different header and for the | |
20970 | envelope sender and recipient fields. For example, | |
9b371988 PH |
20971 | .code |
20972 | exim -brw ph10@exim.workshop.example | |
20973 | .endd | |
168e428f | 20974 | might produce the output |
9b371988 PH |
20975 | .code |
20976 | sender: Philip.Hazel@exim.workshop.example | |
20977 | from: Philip.Hazel@exim.workshop.example | |
20978 | to: ph10@exim.workshop.example | |
20979 | cc: ph10@exim.workshop.example | |
20980 | bcc: ph10@exim.workshop.example | |
20981 | reply-to: Philip.Hazel@exim.workshop.example | |
20982 | env-from: Philip.Hazel@exim.workshop.example | |
20983 | env-to: ph10@exim.workshop.example | |
20984 | .endd | |
168e428f PH |
20985 | which shows that rewriting has been set up for that address when used in any of |
20986 | the source fields, but not when it appears as a recipient address. At the | |
20987 | present time, there is no equivalent way of testing rewriting rules that are | |
20988 | set for a particular transport. | |
20989 | ||
20990 | ||
9b371988 PH |
20991 | .section "Rewriting rules" |
20992 | .cindex "rewriting" "rules" | |
168e428f PH |
20993 | The rewrite section of the configuration file consists of lines of rewriting |
20994 | rules in the form | |
9b371988 PH |
20995 | .display |
20996 | <&'source pattern'&> <&'replacement'&> <&'flags'&> | |
20997 | .endd | |
20998 | Rewriting rules that are specified for the &%headers_rewrite%& generic | |
20999 | transport option are given as a colon-separated list. Each item in the list | |
21000 | takes the same form as a line in the main rewriting configuration (except that | |
21001 | any colons must be doubled, of course). | |
168e428f PH |
21002 | |
21003 | The formats of source patterns and replacement strings are described below. | |
21004 | Each is terminated by white space, unless enclosed in double quotes, in which | |
21005 | case normal quoting conventions apply inside the quotes. The flags are single | |
21006 | characters which may appear in any order. Spaces and tabs between them are | |
21007 | ignored. | |
21008 | ||
21009 | For each address that could potentially be rewritten, the rules are scanned in | |
21010 | order, and replacements for the address from earlier rules can themselves be | |
9b371988 | 21011 | replaced by later rules (but see the &"q"& and &"R"& flags). |
168e428f PH |
21012 | |
21013 | The order in which addresses are rewritten is undefined, may change between | |
21014 | releases, and must not be relied on, with one exception: when a message is | |
21015 | received, the envelope sender is always rewritten first, before any header | |
21016 | lines are rewritten. For example, the replacement string for a rewrite of an | |
9b371988 PH |
21017 | address in &'To:'& must not assume that the message's address in &'From:'& has |
21018 | (or has not) already been rewritten. However, a rewrite of &'From:'& may assume | |
21019 | that the envelope sender has already been rewritten. | |
168e428f | 21020 | |
9b371988 PH |
21021 | .cindex "&$domain$&" |
21022 | .cindex "&$local_part$&" | |
21023 | The variables &$local_part$& and &$domain$& can be used in the replacement | |
168e428f PH |
21024 | string to refer to the address that is being rewritten. Note that lookup-driven |
21025 | rewriting can be done by a rule of the form | |
9b371988 PH |
21026 | .code |
21027 | *@* ${lookup ... | |
21028 | .endd | |
21029 | where the lookup key uses &$1$& and &$2$& or &$local_part$& and &$domain$& to | |
168e428f PH |
21030 | refer to the address that is being rewritten. |
21031 | ||
21032 | ||
9b371988 PH |
21033 | .section "Rewriting patterns" |
21034 | .cindex "rewriting" "patterns" | |
21035 | .cindex "address list" "in a rewriting pattern" | |
168e428f | 21036 | The source pattern in a rewriting rule is any item which may appear in an |
9b371988 | 21037 | address list (see section &<<SECTaddresslist>>&). It is in fact processed as a |
168e428f | 21038 | single-item address list, which means that it is expanded before being tested |
068aaea8 | 21039 | against the address. As always, if you use a regular expression as a pattern, |
9b371988 | 21040 | you must take care to escape dollar and backslash characters, or use the &`\N`& |
068aaea8 | 21041 | facility to suppress string expansion within the regular expression. |
168e428f PH |
21042 | |
21043 | Domains in patterns should be given in lower case. Local parts in patterns are | |
21044 | case-sensitive. If you want to do case-insensitive matching of local parts, you | |
9b371988 | 21045 | can use a regular expression that starts with &`^(?i)`&. |
168e428f | 21046 | |
9b371988 PH |
21047 | .cindex "numerical variables (&$1$& &$2$& etc)" "in rewriting rules" |
21048 | After matching, the numerical variables &$1$&, &$2$&, etc. may be set, | |
168e428f | 21049 | depending on the type of match which occurred. These can be used in the |
9b371988 | 21050 | replacement string to insert portions of the incoming address. &$0$& always |
168e428f PH |
21051 | refers to the complete incoming address. When a regular expression is used, the |
21052 | numerical variables are set from its capturing subexpressions. For other types | |
21053 | of pattern they are set as follows: | |
21054 | ||
9b371988 PH |
21055 | .ilist |
21056 | If a local part or domain starts with an asterisk, the numerical variables | |
21057 | refer to the character strings matched by asterisks, with &$1$& associated with | |
21058 | the first asterisk, and &$2$& with the second, if present. For example, if the | |
168e428f | 21059 | pattern |
9b371988 PH |
21060 | .code |
21061 | *queen@*.fict.example | |
21062 | .endd | |
21063 | is matched against the address &'hearts-queen@wonderland.fict.example'& then | |
21064 | .code | |
21065 | $0 = hearts-queen@wonderland.fict.example | |
21066 | $1 = hearts- | |
21067 | $2 = wonderland | |
21068 | .endd | |
168e428f | 21069 | Note that if the local part does not start with an asterisk, but the domain |
9b371988 | 21070 | does, it is &$1$& that contains the wild part of the domain. |
168e428f | 21071 | |
9b371988 PH |
21072 | .next |
21073 | If the domain part of the pattern is a partial lookup, the wild and fixed parts | |
168e428f | 21074 | of the domain are placed in the next available numerical variables. Suppose, |
9b371988 | 21075 | for example, that the address &'foo@bar.baz.example'& is processed by a |
168e428f | 21076 | rewriting rule of the form |
9b371988 PH |
21077 | .display |
21078 | &`*@partial-dbm;/some/dbm/file`& <&'replacement string'&> | |
21079 | .endd | |
21080 | and the key in the file that matches the domain is &`*.baz.example`&. Then | |
21081 | .code | |
21082 | $1 = foo | |
21083 | $2 = bar | |
21084 | $3 = baz.example | |
21085 | .endd | |
21086 | If the address &'foo@baz.example'& is looked up, this matches the same | |
21087 | wildcard file entry, and in this case &$2$& is set to the empty string, but | |
21088 | &$3$& is still set to &'baz.example'&. If a non-wild key is matched in a | |
21089 | partial lookup, &$2$& is again set to the empty string and &$3$& is set to the | |
168e428f | 21090 | whole domain. For non-partial domain lookups, no numerical variables are set. |
9b371988 | 21091 | .endlist |
168e428f PH |
21092 | |
21093 | ||
9b371988 PH |
21094 | .section "Rewriting replacements" |
21095 | .cindex "rewriting" "replacements" | |
168e428f | 21096 | If the replacement string for a rule is a single asterisk, addresses that |
9b371988 | 21097 | match the pattern and the flags are &'not'& rewritten, and no subsequent |
168e428f | 21098 | rewriting rules are scanned. For example, |
9b371988 PH |
21099 | .code |
21100 | hatta@lookingglass.fict.example * f | |
21101 | .endd | |
21102 | specifies that &'hatta@lookingglass.fict.example'& is never to be rewritten in | |
21103 | &'From:'& headers. | |
21104 | ||
21105 | .cindex "&$domain$&" | |
21106 | .cindex "&$local_part$&" | |
168e428f PH |
21107 | If the replacement string is not a single asterisk, it is expanded, and must |
21108 | yield a fully qualified address. Within the expansion, the variables | |
9b371988 PH |
21109 | &$local_part$& and &$domain$& refer to the address that is being rewritten. |
21110 | Any letters they contain retain their original case &-- they are not lower | |
168e428f PH |
21111 | cased. The numerical variables are set up according to the type of pattern that |
21112 | matched the address, as described above. If the expansion is forced to fail by | |
9b371988 | 21113 | the presence of &"fail"& in a conditional or lookup item, rewriting by the |
168e428f PH |
21114 | current rule is abandoned, but subsequent rules may take effect. Any other |
21115 | expansion failure causes the entire rewriting operation to be abandoned, and an | |
21116 | entry written to the panic log. | |
21117 | ||
21118 | ||
21119 | ||
9b371988 | 21120 | .section "Rewriting flags" |
168e428f PH |
21121 | There are three different kinds of flag that may appear on rewriting rules: |
21122 | ||
9b371988 PH |
21123 | .ilist |
21124 | Flags that specify which headers and envelope addresses to rewrite: E, F, T, b, | |
168e428f | 21125 | c, f, h, r, s, t. |
9b371988 PH |
21126 | .next |
21127 | A flag that specifies rewriting at SMTP time: S. | |
21128 | .next | |
21129 | Flags that control the rewriting process: Q, q, R, w. | |
21130 | .endlist | |
168e428f | 21131 | |
9b371988 | 21132 | For rules that are part of the &%headers_rewrite%& generic transport option, |
168e428f PH |
21133 | E, F, T, and S are not permitted. |
21134 | ||
21135 | ||
21136 | ||
9b371988 PH |
21137 | .section "Flags specifying which headers and envelope addresses to rewrite" |
21138 | .cindex "rewriting" "flags" | |
21139 | If none of the following flag letters, nor the &"S"& flag (see section | |
21140 | &<<SECTrewriteS>>&) are present, a main rewriting rule applies to all headers | |
21141 | and to both the sender and recipient fields of the envelope, whereas a | |
168e428f PH |
21142 | transport-time rewriting rule just applies to all headers. Otherwise, the |
21143 | rewriting rule is skipped unless the relevant addresses are being processed. | |
9b371988 PH |
21144 | .display |
21145 | &`E`& rewrite all envelope fields | |
21146 | &`F`& rewrite the envelope From field | |
21147 | &`T`& rewrite the envelope To field | |
21148 | &`b`& rewrite the &'Bcc:'& header | |
21149 | &`c`& rewrite the &'Cc:'& header | |
21150 | &`f`& rewrite the &'From:'& header | |
21151 | &`h`& rewrite all headers | |
21152 | &`r`& rewrite the &'Reply-To:'& header | |
21153 | &`s`& rewrite the &'Sender:'& header | |
21154 | &`t`& rewrite the &'To:'& header | |
21155 | .endd | |
21156 | You should be particularly careful about rewriting &'Sender:'& headers, and | |
168e428f PH |
21157 | restrict this to special known cases in your own domains. |
21158 | ||
21159 | ||
9b371988 PH |
21160 | .section "The SMTP-time rewriting flag" "SECTrewriteS" |
21161 | .cindex "SMTP" "rewriting malformed addresses" | |
21162 | .cindex "RCPT" "rewriting argument of" | |
21163 | .cindex "MAIL" "rewriting argument of" | |
21164 | The rewrite flag &"S"& specifies a rewrite of incoming envelope addresses at | |
21165 | SMTP time, as soon as an address is received in a MAIL or RCPT command, and | |
168e428f PH |
21166 | before any other processing; even before syntax checking. The pattern is |
21167 | required to be a regular expression, and it is matched against the whole of the | |
21168 | data for the command, including any surrounding angle brackets. | |
21169 | ||
9b371988 PH |
21170 | .cindex "&$domain$&" |
21171 | .cindex "&$local_part$&" | |
168e428f | 21172 | This form of rewrite rule allows for the handling of addresses that are not |
9b371988 | 21173 | compliant with RFCs 2821 and 2822 (for example, &"bang paths"& in batched SMTP |
168e428f | 21174 | input). Because the input is not required to be a syntactically valid address, |
9b371988 | 21175 | the variables &$local_part$& and &$domain$& are not available during the |
168e428f PH |
21176 | expansion of the replacement string. The result of rewriting replaces the |
21177 | original address in the MAIL or RCPT command. | |
21178 | ||
21179 | ||
9b371988 | 21180 | .section "Flags controlling the rewriting process" |
168e428f PH |
21181 | There are four flags which control the way the rewriting process works. These |
21182 | take effect only when a rule is invoked, that is, when the address is of the | |
21183 | correct type (matches the flags) and matches the pattern: | |
21184 | ||
9b371988 PH |
21185 | .ilist |
21186 | If the &"Q"& flag is set on a rule, the rewritten address is permitted to be an | |
21187 | unqualified local part. It is qualified with &%qualify_recipient%&. In the | |
21188 | absence of &"Q"& the rewritten address must always include a domain. | |
21189 | .next | |
21190 | If the &"q"& flag is set on a rule, no further rewriting rules are considered, | |
21191 | even if no rewriting actually takes place because of a &"fail"& in the | |
21192 | expansion. The &"q"& flag is not effective if the address is of the wrong type | |
21193 | (does not match the flags) or does not match the pattern. | |
21194 | .next | |
21195 | The &"R"& flag causes a successful rewriting rule to be re-applied to the new | |
21196 | address, up to ten times. It can be combined with the &"q"& flag, to stop | |
168e428f | 21197 | rewriting once it fails to match (after at least one successful rewrite). |
9b371988 PH |
21198 | .next |
21199 | .cindex "rewriting" "whole addresses" | |
168e428f | 21200 | When an address in a header is rewritten, the rewriting normally applies only |
9b371988 | 21201 | to the working part of the address, with any comments and RFC 2822 &"phrase"& |
168e428f | 21202 | left unchanged. For example, rewriting might change |
9b371988 PH |
21203 | .code |
21204 | From: Ford Prefect <fp42@restaurant.hitch.fict.example> | |
21205 | .endd | |
168e428f | 21206 | into |
9b371988 PH |
21207 | .code |
21208 | From: Ford Prefect <prefectf@hitch.fict.example> | |
21209 | .endd | |
21210 | .cindex "RFC 2047" | |
168e428f | 21211 | Sometimes there is a need to replace the whole address item, and this can be |
9b371988 | 21212 | done by adding the flag letter &"w"& to a rule. If this is set on a rule that |
168e428f PH |
21213 | causes an address in a header line to be rewritten, the entire address is |
21214 | replaced, not just the working part. The replacement must be a complete RFC | |
21215 | 2822 address, including the angle brackets if necessary. If text outside angle | |
21216 | brackets contains a character whose value is greater than 126 or less than 32 | |
d1e83bff | 21217 | (except for tab), the text is encoded according to RFC 2047. The character set |
9b371988 | 21218 | is taken from &%headers_charset%&, which defaults to ISO-8859-1. |
168e428f | 21219 | |
9b371988 PH |
21220 | When the &"w"& flag is set on a rule that causes an envelope address to be |
21221 | rewritten, all but the working part of the replacement address is discarded. | |
21222 | .endlist | |
168e428f PH |
21223 | |
21224 | ||
9b371988 | 21225 | .section "Rewriting examples" |
168e428f | 21226 | Here is an example of the two common rewriting paradigms: |
9b371988 | 21227 | .code |
168e428f PH |
21228 | *@*.hitch.fict.example $1@hitch.fict.example |
21229 | *@hitch.fict.example ${lookup{$1}dbm{/etc/realnames}\ | |
21230 | {$value}fail}@hitch.fict.example bctfrF | |
9b371988 PH |
21231 | .endd |
21232 | Note the use of &"fail"& in the lookup expansion in the second rule, forcing | |
168e428f PH |
21233 | the string expansion to fail if the lookup does not succeed. In this context it |
21234 | has the effect of leaving the original address unchanged, but Exim goes on to | |
9b371988 PH |
21235 | consider subsequent rewriting rules, if any, because the &"q"& flag is not |
21236 | present in that rule. An alternative to &"fail"& would be to supply &$1$& | |
168e428f PH |
21237 | explicitly, which would cause the rewritten address to be the same as before, |
21238 | at the cost of a small bit of processing. Not supplying either of these is an | |
21239 | error, since the rewritten address would then contain no local part. | |
21240 | ||
21241 | The first example above replaces the domain with a superior, more general | |
21242 | domain. This may not be desirable for certain local parts. If the rule | |
9b371988 PH |
21243 | .code |
21244 | root@*.hitch.fict.example * | |
21245 | .endd | |
168e428f | 21246 | were inserted before the first rule, rewriting would be suppressed for the |
9b371988 | 21247 | local part &'root'& at any domain ending in &'hitch.fict.example'&. |
168e428f PH |
21248 | |
21249 | Rewriting can be made conditional on a number of tests, by making use of | |
9b371988 | 21250 | &${if$& in the expansion item. For example, to apply a rewriting rule only to |
168e428f | 21251 | messages that originate outside the local host: |
9b371988 | 21252 | .code |
168e428f PH |
21253 | *@*.hitch.fict.example "${if !eq {$sender_host_address}{}\ |
21254 | {$1@hitch.fict.example}fail}" | |
9b371988 | 21255 | .endd |
168e428f PH |
21256 | The replacement string is quoted in this example because it contains white |
21257 | space. | |
21258 | ||
9b371988 PH |
21259 | .cindex "rewriting" "bang paths" |
21260 | .cindex "bang paths" "rewriting" | |
21261 | Exim does not handle addresses in the form of &"bang paths"&. If it sees such | |
21262 | an address it treats it as an unqualified local part which it qualifies with | |
21263 | the local qualification domain (if the source of the message is local or if the | |
168e428f PH |
21264 | remote host is permitted to send unqualified addresses). Rewriting can |
21265 | sometimes be used to handle simple bang paths with a fixed number of | |
21266 | components. For example, the rule | |
9b371988 PH |
21267 | .code |
21268 | \N^([^!]+)!(.*)@your.domain.example$\N $2@$1 | |
21269 | .endd | |
21270 | rewrites a two-component bang path &'host.name!user'& as the domain address | |
21271 | &'user@host.name'&. However, there is a security implication in using this as | |
168e428f PH |
21272 | a global rewriting rule for envelope addresses. It can provide a backdoor |
21273 | method for using your system as a relay, because the incoming addresses appear | |
21274 | to be local. If the bang path addresses are received via SMTP, it is safer to | |
9b371988 | 21275 | use the &"S"& flag to rewrite them as they are received, so that relay checking |
168e428f PH |
21276 | can be done on the rewritten addresses. |
21277 | ||
21278 | ||
21279 | ||
21280 | ||
21281 | ||
9b371988 PH |
21282 | . //////////////////////////////////////////////////////////////////////////// |
21283 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 21284 | |
9b371988 PH |
21285 | .chapter "Retry configuration" "CHAPretry" |
21286 | .cindex "retry configuration" "description of" | |
21287 | .cindex "configuration file" "retry section" | |
21288 | The &"retry"& section of the run time configuration file contains a list of | |
21289 | retry rules which control how often Exim tries to deliver messages that cannot | |
21290 | be delivered at the first attempt. If there are no retry rules, temporary | |
21291 | errors are treated as permanent. The &%-brt%& command line option can be used | |
21292 | to test which retry rule will be used for a given address or domain. | |
168e428f PH |
21293 | |
21294 | The most common cause of retries is temporary failure to deliver to a remote | |
21295 | host because the host is down, or inaccessible because of a network problem. | |
21296 | Exim's retry processing in this case is applied on a per-host (strictly, per IP | |
21297 | address) basis, not on a per-message basis. Thus, if one message has recently | |
21298 | been delayed, delivery of a new message to the same host is not immediately | |
9b371988 PH |
21299 | tried, but waits for the host's retry time to arrive. If the &%retry_defer%& |
21300 | log selector is set, the message | |
21301 | .cindex "retry" "time not reached" | |
21302 | &"retry time not reached"& is written to the main log whenever a delivery is | |
21303 | skipped for this reason. Section &<<SECToutSMTPerr>>& contains more details of | |
21304 | the handling of errors during remote deliveries. | |
168e428f PH |
21305 | |
21306 | Retry processing applies to routing as well as to delivering, except as covered | |
21307 | in the next paragraph. The retry rules do not distinguish between these | |
21308 | actions. It is not possible, for example, to specify different behaviour for | |
9b371988 PH |
21309 | failures to route the domain &'snark.fict.example'& and failures to deliver to |
21310 | the host &'snark.fict.example'&. I didn't think anyone would ever need this | |
168e428f PH |
21311 | added complication, so did not implement it. However, although they share the |
21312 | same retry rule, the actual retry times for routing and transporting a given | |
21313 | domain are maintained independently. | |
21314 | ||
21315 | When a delivery is not part of a queue run (typically an immediate delivery on | |
21316 | receipt of a message), the routers are always run, and local deliveries are | |
21317 | always attempted, even if retry times are set for them. This makes for better | |
21318 | behaviour if one particular message is causing problems (for example, causing | |
21319 | quota overflow, or provoking an error in a filter file). If such a delivery | |
21320 | suffers a temporary failure, the retry data is updated as normal, and | |
21321 | subsequent delivery attempts from queue runs occur only when the retry time for | |
21322 | the local address is reached. | |
21323 | ||
21324 | ||
21325 | ||
9b371988 PH |
21326 | .section "Retry rules" |
21327 | .cindex "retry" "rules" | |
168e428f PH |
21328 | Each retry rule occupies one line and consists of three or four parts, |
21329 | separated by white space: a pattern, an error name, an optional list of sender | |
21330 | addresses, and a list of retry parameters. The pattern and sender lists must be | |
9b371988 PH |
21331 | enclosed in double quotes if they contain white space. The rules are searched |
21332 | in order until one is found where the pattern, error name, and sender list (if | |
168e428f PH |
21333 | present) match the failing host or address, the error that occurred, and the |
21334 | message's sender, respectively. | |
21335 | ||
21336 | ||
21337 | The pattern is any single item that may appear in an address list (see section | |
9b371988 PH |
21338 | &<<SECTaddresslist>>&). It is in fact processed as a one-item address list, |
21339 | which means that it is expanded before being tested against the address that | |
21340 | has been delayed. Address list processing treats a plain domain name as if it | |
21341 | were preceded by &"*@"&, which makes it possible for many retry rules to start | |
21342 | with just a domain. For example, | |
21343 | .code | |
21344 | lookingglass.fict.example * F,24h,30m; | |
21345 | .endd | |
21346 | provides a rule for any address in the &'lookingglass.fict.example'& domain, | |
168e428f | 21347 | whereas |
9b371988 PH |
21348 | .code |
21349 | alice@lookingglass.fict.example * F,24h,30m; | |
21350 | .endd | |
21351 | applies only to temporary failures involving the local part &%alice%&. | |
168e428f PH |
21352 | In practice, almost all rules start with a domain name pattern without a local |
21353 | part. | |
21354 | ||
9b371988 PH |
21355 | .cindex "regular expressions" "in retry rules" |
21356 | &*Warning*&: If you use a regular expression in a routing rule pattern, it | |
168e428f PH |
21357 | must match a complete address, not just a domain, because that is how regular |
21358 | expressions work in address lists. | |
9b371988 PH |
21359 | .display |
21360 | &`^\Nxyz\d+\.abc\.example$\N * G,1h,10m,2`& &%Wrong%& | |
21361 | &`^\N[^@]+@xyz\d+\.abc\.example$\N * G,1h,10m,2`& &%Right%& | |
21362 | .endd | |
168e428f PH |
21363 | |
21364 | ||
9b371988 | 21365 | .section "Choosing which retry rule to use for address errors" |
168e428f PH |
21366 | When Exim is looking for a retry rule after a routing attempt has failed (for |
21367 | example, after a DNS timeout), each line in the retry configuration is tested | |
9b371988 | 21368 | against the complete address only if &%retry_use_local_part%& is set for the |
168e428f | 21369 | router. Otherwise, only the domain is used, except when matching against a |
9b371988 | 21370 | regular expression, when the local part of the address is replaced with &"*"&. |
168e428f | 21371 | A domain on its own can match a domain pattern, or a pattern that starts with |
9b371988 PH |
21372 | &"*@"&. By default, &%retry_use_local_part%& is true for routers where |
21373 | &%check_local_user%& is true, and false for other routers. | |
168e428f PH |
21374 | |
21375 | Similarly, when Exim is looking for a retry rule after a local delivery has | |
21376 | failed (for example, after a mailbox full error), each line in the retry | |
21377 | configuration is tested against the complete address only if | |
9b371988 | 21378 | &%retry_use_local_part%& is set for the transport (it defaults true for all |
168e428f PH |
21379 | local transports). |
21380 | ||
21381 | When Exim is looking for a retry rule after a remote delivery attempt has | |
9b371988 | 21382 | failed, what happens depends on the type of failure. After a 4&'xx'& SMTP |
168e428f PH |
21383 | response for a recipient address, the whole address is used when searching the |
21384 | retry rules. The rule that is found is used to create a retry time for the | |
21385 | failing address. | |
21386 | ||
068aaea8 | 21387 | |
9b371988 | 21388 | .section "Choosing which retry rule to use for host errors" |
068aaea8 PH |
21389 | For a temporary error that is not related to an individual address (for |
21390 | example, a connection timeout), each line in the retry configuration is checked | |
21391 | twice. First, the name of the remote host is used as a domain name (preceded by | |
9b371988 | 21392 | &"*@"& when matching a regular expression). If this does not match the line, |
068aaea8 | 21393 | the domain from the email address is tried in a similar fashion. For example, |
9b371988 PH |
21394 | suppose the MX records for &'a.b.c.example'& are |
21395 | .code | |
21396 | a.b.c.example MX 5 x.y.z.example | |
21397 | MX 6 p.q.r.example | |
21398 | MX 7 m.n.o.example | |
21399 | .endd | |
168e428f | 21400 | and the retry rules are |
9b371988 PH |
21401 | .code |
21402 | p.q.r.example * F,24h,30m; | |
21403 | a.b.c.example * F,4d,45m; | |
21404 | .endd | |
21405 | and a delivery to the host &'x.y.z.example'& suffers a connection failure. The | |
068aaea8 PH |
21406 | first rule matches neither the host nor the domain, so Exim looks at the second |
21407 | rule. This does not match the host, but it does match the domain, so it is used | |
9b371988 PH |
21408 | to calculate the retry time for the host &'x.y.z.example'&. Meanwhile, Exim |
21409 | tries to deliver to &'p.q.r.example'&. If this also suffers a host error, the | |
21410 | first retry rule is used, because it matches the host. | |
168e428f | 21411 | |
9b371988 | 21412 | In other words, temporary failures to deliver to host &'p.q.r.example'& use the |
068aaea8 | 21413 | first rule to determine retry times, but for all the other hosts for the domain |
9b371988 PH |
21414 | &'a.b.c.example'&, the second rule is used. The second rule is also used if |
21415 | routing to &'a.b.c.example'& suffers a temporary failure. | |
168e428f | 21416 | |
9b371988 PH |
21417 | .new |
21418 | &*Note*&: The host name is used when matching the patterns, not its IP address. | |
068aaea8 | 21419 | However, if a message is routed directly to an IP address without the use of a |
9b371988 PH |
21420 | host name, for example, if a &(manualroute)& router contains a setting such as: |
21421 | .code | |
21422 | route_list = *.a.example 192.168.34.23 | |
21423 | .endd | |
21424 | then the &"host name"& that is used when searching for a retry rule is the | |
068aaea8 | 21425 | textual form of the IP address. |
9b371988 | 21426 | .wen |
068aaea8 | 21427 | |
9b371988 PH |
21428 | .section "Retry rules for specific errors" |
21429 | .cindex "retry" "specific errors; specifying" | |
168e428f PH |
21430 | The second field in a retry rule is the name of a particular error, or an |
21431 | asterisk, which matches any error. The errors that can be tested for are: | |
21432 | ||
9b371988 PH |
21433 | .vlist |
21434 | .vitem &%auth_failed%& | |
21435 | Authentication failed when trying to send to a host in the | |
21436 | &%hosts_require_auth%& list in an &(smtp)& transport. | |
168e428f | 21437 | |
9b371988 PH |
21438 | .vitem &%rcpt_4xx%& |
21439 | A 4&'xx'& error was received for an outgoing RCPT command. Either the first or | |
21440 | both of the x's can be given as specific digits, for example: &`rcpt_45x`& or | |
21441 | &`rcpt_436`&. For example, to recognize 452 errors given to RCPT commands by a | |
168e428f PH |
21442 | particular host, and have retries every ten minutes and a one-hour timeout, you |
21443 | could set up a retry rule of this form: | |
9b371988 PH |
21444 | .code |
21445 | the.host.name rcpt_452 F,1h,10m | |
21446 | .endd | |
21447 | These errors apply to both outgoing SMTP (the &(smtp)& transport) and outgoing | |
21448 | LMTP (either the &(lmtp)& transport, or the &(smtp)& transport in LMTP mode). | |
168e428f PH |
21449 | Note, however, that they apply only to responses to RCPT commands. |
21450 | ||
9b371988 | 21451 | .vitem &%refused_MX%& |
168e428f PH |
21452 | A connection to a host obtained from an MX record was refused. |
21453 | ||
9b371988 | 21454 | .vitem &%refused_A%& |
168e428f PH |
21455 | A connection to a host not obtained from an MX record was refused. |
21456 | ||
9b371988 | 21457 | .vitem &%refused%& |
168e428f PH |
21458 | A connection was refused. |
21459 | ||
9b371988 | 21460 | .vitem &%timeout_connect_MX%& |
168e428f PH |
21461 | A connection attempt to a host obtained from an MX record timed out. |
21462 | ||
9b371988 | 21463 | .vitem &%timeout_connect_A%& |
168e428f PH |
21464 | A connection attempt to a host not obtained from an MX record timed out. |
21465 | ||
9b371988 | 21466 | .vitem &%timeout_connect%& |
168e428f PH |
21467 | A connection attempt timed out. |
21468 | ||
9b371988 | 21469 | .vitem &%timeout_MX%& |
168e428f PH |
21470 | There was a timeout while connecting or during an SMTP session with a host |
21471 | obtained from an MX record. | |
21472 | ||
9b371988 | 21473 | .vitem &%timeout_A%& |
168e428f PH |
21474 | There was a timeout while connecting or during an SMTP session with a host not |
21475 | obtained from an MX record. | |
21476 | ||
9b371988 | 21477 | .vitem &%timeout%& |
168e428f PH |
21478 | There was a timeout while connecting or during an SMTP session. |
21479 | ||
9b371988 PH |
21480 | .vitem &%quota%& |
21481 | A mailbox quota was exceeded in a local delivery by the &(appendfile)& | |
21482 | transport. | |
168e428f | 21483 | |
9b371988 PH |
21484 | .vitem &%quota_%&<&'time'&> |
21485 | .cindex "quota" "error testing in retry rule" | |
21486 | .cindex "retry" "quota error testing" | |
21487 | A mailbox quota was exceeded in a local delivery by the &(appendfile)& | |
21488 | transport, and the mailbox has not been accessed for <&'time'&>. For example, | |
21489 | &'quota_4d'& applies to a quota error when the mailbox has not been accessed | |
21490 | for four days. | |
21491 | .endlist | |
21492 | ||
21493 | .cindex "mailbox" "time of last read" | |
21494 | The idea of &%quota_%&<&'time'&> is to make it possible to have shorter | |
21495 | timeouts when the mailbox is full and is not being read by its owner. Ideally, | |
21496 | it should be based on the last time that the user accessed the mailbox. | |
21497 | However, it is not always possible to determine this. Exim uses the following | |
21498 | heuristic rules: | |
21499 | ||
21500 | .ilist | |
21501 | If the mailbox is a single file, the time of last access (the &"atime"&) is | |
21502 | used. As no new messages are being delivered (because the mailbox is over | |
21503 | quota), Exim does not access the file, so this is the time of last user access. | |
21504 | .next | |
21505 | .cindex "maildir format" "time of last read" | |
21506 | For a maildir delivery, the time of last modification of the &_new_& | |
168e428f | 21507 | subdirectory is used. As the mailbox is over quota, no new files are created in |
9b371988 PH |
21508 | the &_new_& subdirectory, because no new messages are being delivered. Any |
21509 | change to the &_new_& subdirectory is therefore assumed to be the result of an | |
21510 | MUA moving a new message to the &_cur_& directory when it is first read. The | |
168e428f | 21511 | time that is used is therefore the last time that the user read a new message. |
9b371988 PH |
21512 | .next |
21513 | For other kinds of multi-file mailbox, the time of last access cannot be | |
168e428f | 21514 | obtained, so a retry rule that uses this type of error field is never matched. |
9b371988 | 21515 | .endlist |
168e428f PH |
21516 | |
21517 | The quota errors apply both to system-enforced quotas and to Exim's own quota | |
9b371988 | 21518 | mechanism in the &(appendfile)& transport. The &'quota'& error also applies |
168e428f PH |
21519 | when a local delivery is deferred because a partition is full (the ENOSPC |
21520 | error). | |
21521 | ||
21522 | ||
21523 | ||
9b371988 PH |
21524 | .section "Retry rules for specified senders" |
21525 | .cindex "retry" "rules; sender-specific" | |
168e428f PH |
21526 | You can specify retry rules that apply only when the failing message has a |
21527 | specific sender. In particular, this can be used to define retry rules that | |
21528 | apply only to bounce messages. The third item in a retry rule can be of this | |
21529 | form: | |
9b371988 PH |
21530 | .code |
21531 | senders=<address list> | |
21532 | .endd | |
168e428f | 21533 | The retry timings themselves are then the fourth item. For example: |
9b371988 | 21534 | .code |
068aaea8 | 21535 | * rcpt_4xx senders=: F,1h,30m |
9b371988 PH |
21536 | .endd |
21537 | matches 4&'xx'& errors for bounce messages sent to any host. If the address | |
068aaea8 | 21538 | list contains white space, it must be enclosed in quotes. For example: |
9b371988 PH |
21539 | .code |
21540 | a.domain auth_failed senders="xb.dom : yc.dom" G,8h,10m,1.5 | |
21541 | .endd | |
21542 | .new | |
21543 | &*Warning*&: This facility can be unhelpful if it is used for host errors | |
21544 | (those that do not depend on the recipient). The reason is that the sender is | |
21545 | used only to match the retry rule. Once the rule has been found for a host | |
21546 | error, its contents are used to set a retry time for the host, and this will | |
21547 | apply to all messages, not just those with specific senders. | |
21548 | .wen | |
168e428f | 21549 | |
9b371988 PH |
21550 | When testing retry rules using &%-brt%&, you can supply a sender using the |
21551 | &%-f%& command line option, like this: | |
21552 | .code | |
21553 | exim -f "" -brt user@dom.ain | |
21554 | .endd | |
21555 | If you do not set &%-f%& with &%-brt%&, a retry rule that contains a senders | |
21556 | list is never matched. | |
168e428f | 21557 | |
168e428f PH |
21558 | |
21559 | ||
21560 | ||
21561 | ||
9b371988 PH |
21562 | .section "Retry parameters" |
21563 | .cindex "retry" "parameters in rules" | |
168e428f PH |
21564 | The third (or fourth, if a senders list is present) field in a retry rule is a |
21565 | sequence of retry parameter sets, separated by semicolons. Each set consists of | |
9b371988 PH |
21566 | .display |
21567 | <&'letter'&>,<&'cutoff time'&>,<&'arguments'&> | |
21568 | .endd | |
168e428f PH |
21569 | The letter identifies the algorithm for computing a new retry time; the cutoff |
21570 | time is the time beyond which this algorithm no longer applies, and the | |
21571 | arguments vary the algorithm's action. The cutoff time is measured from the | |
21572 | time that the first failure for the domain (combined with the local part if | |
21573 | relevant) was detected, not from the time the message was received. | |
21574 | ||
9b371988 PH |
21575 | .cindex "retry" "algorithms" |
21576 | .cindex "retry" "fixed intervals" | |
21577 | .cindex "retry" "increasing intervals" | |
21578 | .cindex "retry" "random intervals" | |
168e428f PH |
21579 | The available algorithms are: |
21580 | ||
9b371988 PH |
21581 | .ilist |
21582 | &'F'&: retry at fixed intervals. There is a single time parameter specifying | |
168e428f | 21583 | the interval. |
9b371988 PH |
21584 | .next |
21585 | &'G'&: retry at geometrically increasing intervals. The first argument | |
168e428f PH |
21586 | specifies a starting value for the interval, and the second a multiplier, which |
21587 | is used to increase the size of the interval at each retry. | |
9b371988 PH |
21588 | .next |
21589 | .new | |
21590 | &'H'&: retry at randomized intervals. The arguments are as for &'G'&. For each | |
068aaea8 PH |
21591 | retry, the previous interval is multiplied by the factor in order to get a |
21592 | maximum for the next interval. The mininum interval is the first argument of | |
21593 | the parameter, and an actual interval is chosen randomly between them. Such a | |
21594 | rule has been found to be helpful in cluster configurations when all the | |
21595 | members of the cluster restart at once, and may therefore synchronize their | |
21596 | queue processing times. | |
9b371988 PH |
21597 | .wen |
21598 | .endlist | |
068aaea8 | 21599 | |
168e428f PH |
21600 | When computing the next retry time, the algorithm definitions are scanned in |
21601 | order until one whose cutoff time has not yet passed is reached. This is then | |
21602 | used to compute a new retry time that is later than the current time. In the | |
21603 | case of fixed interval retries, this simply means adding the interval to the | |
21604 | current time. For geometrically increasing intervals, retry intervals are | |
21605 | computed from the rule's parameters until one that is greater than the previous | |
21606 | interval is found. The main configuration variable | |
9b371988 PH |
21607 | .cindex "limit" "retry interval" |
21608 | .cindex "retry interval" "maximum" | |
21609 | .cindex "&%retry_interval_max%&" | |
21610 | &%retry_interval_max%& limits the maximum interval between retries. | |
168e428f PH |
21611 | |
21612 | A single remote domain may have a number of hosts associated with it, and each | |
21613 | host may have more than one IP address. Retry algorithms are selected on the | |
21614 | basis of the domain name, but are applied to each IP address independently. If, | |
21615 | for example, a host has two IP addresses and one is unusable, Exim will | |
21616 | generate retry times for it and will not try to use it until its next retry | |
21617 | time comes. Thus the good IP address is likely to be tried first most of the | |
21618 | time. | |
21619 | ||
9b371988 | 21620 | .cindex "hints database" "use for retrying" |
168e428f PH |
21621 | Retry times are hints rather than promises. Exim does not make any attempt to |
21622 | run deliveries exactly at the computed times. Instead, a queue runner process | |
21623 | starts delivery processes for delayed messages periodically, and these attempt | |
21624 | new deliveries only for those addresses that have passed their next retry time. | |
21625 | If a new message arrives for a deferred address, an immediate delivery attempt | |
21626 | occurs only if the address has passed its retry time. In the absence of new | |
21627 | messages, the minimum time between retries is the interval between queue runner | |
21628 | processes. There is not much point in setting retry times of five minutes if | |
21629 | your queue runners happen only once an hour, unless there are a significant | |
21630 | number of incoming messages (which might be the case on a system that is | |
21631 | sending everything to a smart host, for example). | |
21632 | ||
21633 | The data in the retry hints database can be inspected by using the | |
9b371988 PH |
21634 | &'exim_dumpdb'& or &'exim_fixdb'& utility programs (see chapter |
21635 | &<<CHAPutils>>&). The latter utility can also be used to change the data. The | |
21636 | &'exinext'& utility script can be used to find out what the next retry times | |
21637 | are for the hosts associated with a particular mail domain, and also for local | |
21638 | deliveries that have been deferred. | |
168e428f PH |
21639 | |
21640 | ||
9b371988 | 21641 | .section "Retry rule examples" |
168e428f | 21642 | Here are some example retry rules: |
9b371988 PH |
21643 | .code |
21644 | alice@wonderland.fict.example quota_5d F,7d,3h | |
21645 | wonderland.fict.example quota_5d | |
21646 | wonderland.fict.example * F,1h,15m; G,2d,1h,2; | |
21647 | lookingglass.fict.example * F,24h,30m; | |
21648 | * refused_A F,2h,20m; | |
21649 | * * F,2h,15m; G,16h,1h,1.5; F,5d,8h | |
21650 | .endd | |
168e428f | 21651 | The first rule sets up special handling for mail to |
9b371988 | 21652 | &'alice@wonderland.fict.example'& when there is an over-quota error and the |
168e428f PH |
21653 | mailbox has not been read for at least 5 days. Retries continue every three |
21654 | hours for 7 days. The second rule handles over-quota errors for all other local | |
9b371988 PH |
21655 | parts at &'wonderland.fict.example'&; the absence of a local part has the same |
21656 | effect as supplying &"*@"&. As no retry algorithms are supplied, messages that | |
168e428f PH |
21657 | fail are bounced immediately if the mailbox has not been read for at least 5 |
21658 | days. | |
21659 | ||
9b371988 | 21660 | The third rule handles all other errors at &'wonderland.fict.example'&; retries |
168e428f PH |
21661 | happen every 15 minutes for an hour, then with geometrically increasing |
21662 | intervals until two days have passed since a delivery first failed. After the | |
21663 | first hour there is a delay of one hour, then two hours, then four hours, and | |
21664 | so on (this is a rather extreme example). | |
21665 | ||
9b371988 | 21666 | The fourth rule controls retries for the domain &'lookingglass.fict.example'&. |
168e428f PH |
21667 | They happen every 30 minutes for 24 hours only. The remaining two rules handle |
21668 | all other domains, with special action for connection refusal from hosts that | |
21669 | were not obtained from an MX record. | |
21670 | ||
21671 | The final rule in a retry configuration should always have asterisks in the | |
21672 | first two fields so as to provide a general catch-all for any addresses that do | |
21673 | not have their own special handling. This example tries every 15 minutes for 2 | |
21674 | hours, then with intervals starting at one hour and increasing by a factor of | |
21675 | 1.5 up to 16 hours, then every 8 hours up to 5 days. | |
21676 | ||
21677 | ||
21678 | ||
9b371988 PH |
21679 | .section "Timeout of retry data" |
21680 | .cindex "timeout" "of retry data" | |
21681 | .cindex "&%retry_data_expire%&" | |
21682 | .cindex "hints database" "data expiry" | |
21683 | .cindex "retry" "timeout of data" | |
168e428f PH |
21684 | Exim timestamps the data that it writes to its retry hints database. When it |
21685 | consults the data during a delivery it ignores any that is older than the value | |
9b371988 | 21686 | set in &%retry_data_expire%& (default 7 days). If, for example, a host hasn't |
168e428f PH |
21687 | been tried for 7 days, Exim will try to deliver to it immediately a message |
21688 | arrives, and if that fails, it will calculate a retry time as if it were | |
21689 | failing for the first time. | |
21690 | ||
21691 | This improves the behaviour for messages routed to rarely-used hosts such as MX | |
21692 | backups. If such a host was down at one time, and happens to be down again when | |
21693 | Exim tries a month later, using the old retry data would imply that it had been | |
21694 | down all the time, which is not a justified assumption. | |
21695 | ||
21696 | If a host really is permanently dead, this behaviour causes a burst of retries | |
21697 | every now and again, but only if messages routed to it are rare. It there is a | |
21698 | message at least once every 7 days the retry data never expires. | |
21699 | ||
21700 | ||
21701 | ||
21702 | ||
9b371988 PH |
21703 | .section "Long-term failures" |
21704 | .cindex "delivery failure" "long-term" | |
21705 | .cindex "retry" "after long-term failure" | |
168e428f PH |
21706 | Special processing happens when an email address has been failing for so long |
21707 | that the cutoff time for the last algorithm is reached. For example, using the | |
21708 | default retry rule: | |
9b371988 | 21709 | .code |
168e428f | 21710 | * * F,2h,15m; G,16h,1h,1.5; F,4d,6h |
9b371988 | 21711 | .endd |
168e428f PH |
21712 | the cutoff time is four days. Reaching the retry cutoff is independent of how |
21713 | long any specific message has been failing; it is the length of continuous | |
21714 | failure for the recipient address that counts. | |
21715 | ||
21716 | When the cutoff time is reached for a local delivery, or for all the IP | |
21717 | addresses associated with a remote delivery, a subsequent delivery failure | |
21718 | causes Exim to give up on the address, and a bounce message is generated. | |
21719 | In order to cater for new messages that use the failing address, a next retry | |
21720 | time is still computed from the final algorithm, and is used as follows: | |
21721 | ||
21722 | For local deliveries, one delivery attempt is always made for any subsequent | |
21723 | messages. If this delivery fails, the address fails immediately. The | |
21724 | post-cutoff retry time is not used. | |
21725 | ||
21726 | If the delivery is remote, there are two possibilities, controlled by the | |
9b371988 PH |
21727 | .cindex "&%delay_after_cutoff%&" |
21728 | &%delay_after_cutoff%& option of the &(smtp)& transport. The option is true by | |
168e428f PH |
21729 | default. Until the post-cutoff retry time for one of the IP addresses is |
21730 | reached, the failing email address is bounced immediately, without a delivery | |
21731 | attempt taking place. After that time, one new delivery attempt is made to | |
21732 | those IP addresses that are past their retry times, and if that still fails, | |
21733 | the address is bounced and new retry times are computed. | |
21734 | ||
21735 | In other words, when all the hosts for a given email address have been failing | |
21736 | for a long time, Exim bounces rather then defers until one of the hosts' retry | |
21737 | times is reached. Then it tries once, and bounces if that attempt fails. This | |
21738 | behaviour ensures that few resources are wasted in repeatedly trying to deliver | |
21739 | to a broken destination, but if the host does recover, Exim will eventually | |
21740 | notice. | |
21741 | ||
9b371988 | 21742 | If &%delay_after_cutoff%& is set false, Exim behaves differently. If all IP |
168e428f PH |
21743 | addresses are past their final cutoff time, Exim tries to deliver to those IP |
21744 | addresses that have not been tried since the message arrived. If there are | |
21745 | no suitable IP addresses, or if they all fail, the address is bounced. In other | |
21746 | words, it does not delay when a new message arrives, but tries the expired | |
21747 | addresses immediately, unless they have been tried since the message arrived. | |
21748 | If there is a continuous stream of messages for the failing domains, setting | |
9b371988 PH |
21749 | &%delay_after_cutoff%& false means that there will be many more attempts to |
21750 | deliver to permanently failing IP addresses than when &%delay_after_cutoff%& is | |
168e428f PH |
21751 | true. |
21752 | ||
21753 | ||
9b371988 PH |
21754 | .section "Ultimate address timeout" |
21755 | .cindex "retry" "ultimate address timeout" | |
168e428f PH |
21756 | An additional rule is needed to cope with cases where a host is intermittently |
21757 | available, or when a message has some attribute that prevents its delivery when | |
21758 | others to the same address get through. In this situation, because some | |
9b371988 | 21759 | messages are successfully delivered, the &"retry clock"& for the address keeps |
168e428f PH |
21760 | getting restarted, and so a message could remain on the queue for ever. To |
21761 | prevent this, if a message has been on the queue for longer than the cutoff | |
21762 | time of any applicable retry rule for a given address, a delivery is attempted | |
21763 | for that address, even if it is not yet time, and if this delivery fails, the | |
21764 | address is timed out. A new retry time is not computed in this case, so that | |
21765 | other messages for the same address are considered immediately. | |
21766 | ||
21767 | ||
21768 | ||
21769 | ||
21770 | ||
9b371988 PH |
21771 | . //////////////////////////////////////////////////////////////////////////// |
21772 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 21773 | |
9b371988 PH |
21774 | .chapter "SMTP authentication" "CHAPSMTPAUTH" |
21775 | .cindex "SMTP" "authentication configuration" | |
21776 | .cindex "authentication" | |
21777 | The &"authenticators"& section of Exim's run time configuration is concerned | |
21778 | with SMTP authentication. This facility is an extension to the SMTP protocol, | |
168e428f | 21779 | described in RFC 2554, which allows a client SMTP host to authenticate itself |
9b371988 PH |
21780 | to a server. This is a common way for a server to recognize clients that are |
21781 | permitted to use it as a relay. SMTP authentication is not of relevance to the | |
21782 | transfer of mail between servers that have no managerial connection with each | |
21783 | other. | |
168e428f | 21784 | |
9b371988 | 21785 | .cindex "AUTH" "description of" |
168e428f PH |
21786 | Very briefly, the way SMTP authentication works is as follows: |
21787 | ||
9b371988 PH |
21788 | .ilist |
21789 | The server advertises a number of authentication &'mechanisms'& in response to | |
168e428f | 21790 | the client's EHLO command. |
9b371988 PH |
21791 | .next |
21792 | The client issues an AUTH command, naming a specific mechanism. The command | |
168e428f | 21793 | may, optionally, contain some authentication data. |
9b371988 PH |
21794 | .next |
21795 | The server may issue one or more &'challenges'&, to which the client must send | |
168e428f PH |
21796 | appropriate responses. In simple authentication mechanisms, the challenges are |
21797 | just prompts for user names and passwords. The server does not have to issue | |
9b371988 | 21798 | any challenges &-- in some mechanisms the relevant data may all be transmitted |
168e428f | 21799 | with the AUTH command. |
9b371988 PH |
21800 | .next |
21801 | The server either accepts or denies authentication. | |
21802 | .next | |
21803 | If authentication succeeds, the client may optionally make use of the AUTH | |
168e428f PH |
21804 | option on the MAIL command to pass an authenticated sender in subsequent |
21805 | mail transactions. Authentication lasts for the remainder of the SMTP | |
21806 | connection. | |
9b371988 PH |
21807 | .next |
21808 | If authentication fails, the client may give up, or it may try a different | |
168e428f PH |
21809 | authentication mechanism, or it may try transferring mail over the |
21810 | unauthenticated connection. | |
9b371988 | 21811 | .endlist |
168e428f PH |
21812 | |
21813 | If you are setting up a client, and want to know which authentication | |
21814 | mechanisms the server supports, you can use Telnet to connect to port 25 (the | |
21815 | SMTP port) on the server, and issue an EHLO command. The response to this | |
21816 | includes the list of supported mechanisms. For example: | |
9b371988 PH |
21817 | .display |
21818 | &`$ `&&*&`telnet server.example 25`&*& | |
21819 | &`Trying 192.168.34.25...`& | |
21820 | &`Connected to server.example.`& | |
21821 | &`Escape character is '^]'.`& | |
21822 | &`220 server.example ESMTP Exim 4.20 ...`& | |
21823 | &*&`ehlo client.example`&*& | |
21824 | &`250-server.example Hello client.example [10.8.4.5]`& | |
21825 | &`250-SIZE 52428800`& | |
21826 | &`250-PIPELINING`& | |
21827 | &`250-AUTH PLAIN`& | |
21828 | &`250 HELP`& | |
21829 | .endd | |
168e428f PH |
21830 | The second-last line of this example output shows that the server supports |
21831 | authentication using the PLAIN mechanism. In Exim, the different authentication | |
9b371988 | 21832 | mechanisms are configured by specifying &'authenticator'& drivers. Like the |
168e428f PH |
21833 | routers and transports, which authenticators are included in the binary is |
21834 | controlled by build-time definitions. The following are currently available, | |
21835 | included by setting | |
9b371988 PH |
21836 | .code |
21837 | AUTH_CRAM_MD5=yes | |
21838 | AUTH_CYRUS_SASL=yes | |
21839 | AUTH_PLAINTEXT=yes | |
21840 | AUTH_SPA=yes | |
21841 | .endd | |
21842 | in &_Local/Makefile_&, respectively. The first of these supports the CRAM-MD5 | |
068aaea8 PH |
21843 | authentication mechanism (RFC 2195), and the second provides an interface to |
21844 | the Cyrus SASL authentication library. The third can be configured to support | |
21845 | the PLAIN authentication mechanism (RFC 2595) or the LOGIN mechanism, which is | |
21846 | not formally documented, but used by several MUAs. The fourth authenticator | |
9b371988 | 21847 | supports Microsoft's &'Secure Password Authentication'& mechanism. |
168e428f PH |
21848 | |
21849 | The authenticators are configured using the same syntax as other drivers (see | |
9b371988 PH |
21850 | section &<<SECTfordricon>>&). If no authenticators are required, no |
21851 | authentication section need be present in the configuration file. Each | |
21852 | authenticator can in principle have both server and client functions. When Exim | |
21853 | is receiving SMTP mail, it is acting as a server; when it is sending out | |
21854 | messages over SMTP, it is acting as a client. Authenticator configuration | |
21855 | options are provided for use in both these circumstances. | |
168e428f PH |
21856 | |
21857 | To make it clear which options apply to which situation, the prefixes | |
9b371988 PH |
21858 | &%server_%& and &%client_%& are used on option names that are specific to |
21859 | either the server or the client function, respectively. Server and client | |
21860 | functions are disabled if none of their options are set. If an authenticator is | |
21861 | to be used for both server and client functions, a single definition, using | |
21862 | both sets of options, is required. For example: | |
21863 | .code | |
21864 | cram: | |
21865 | driver = cram_md5 | |
21866 | public_name = CRAM-MD5 | |
21867 | server_secret = ${if eq{$1}{ph10}{secret1}fail} | |
21868 | client_name = ph10 | |
21869 | client_secret = secret2 | |
21870 | .endd | |
21871 | The &%server_%& option is used when Exim is acting as a server, and the | |
21872 | &%client_%& options when it is acting as a client. | |
168e428f PH |
21873 | |
21874 | Descriptions of the individual authenticators are given in subsequent chapters. | |
21875 | The remainder of this chapter covers the generic options for the | |
21876 | authenticators, followed by general discussion of the way authentication works | |
21877 | in Exim. | |
21878 | ||
21879 | ||
21880 | ||
9b371988 PH |
21881 | .section "Generic options for authenticators" |
21882 | .cindex "authentication" "generic options" | |
21883 | .cindex "options" "generic; for authenticators" | |
168e428f PH |
21884 | |
21885 | ||
9b371988 | 21886 | .option driver authenticators string unset |
168e428f PH |
21887 | This option must always be set. It specifies which of the available |
21888 | authenticators is to be used. | |
21889 | ||
21890 | ||
9b371988 | 21891 | .option public_name authenticators string unset |
168e428f PH |
21892 | This option specifies the name of the authentication mechanism that the driver |
21893 | implements, and by which it is known to the outside world. These names should | |
21894 | contain only upper case letters, digits, underscores, and hyphens (RFC 2222), | |
9b371988 | 21895 | but Exim in fact matches them caselessly. If &%public_name%& is not set, it |
168e428f PH |
21896 | defaults to the driver's instance name. |
21897 | ||
21898 | ||
9b371988 | 21899 | .option server_advertise_condition authenticators string&!! unset |
168e428f | 21900 | When a server is about to advertise an authentication mechanism, the condition |
9b371988 | 21901 | is expanded. If it yields the empty string, &"0"&, &"no"&, or &"false"&, the |
168e428f PH |
21902 | mechanism is not advertised. |
21903 | If the expansion fails, the mechanism is not advertised. If the failure was not | |
21904 | forced, and was not caused by a lookup defer, the incident is logged. | |
9b371988 | 21905 | See section &<<SECTauthexiser>>& below for further discussion. |
168e428f | 21906 | |
168e428f | 21907 | |
9b371988 PH |
21908 | .option server_debug_print authenticators string&!! unset |
21909 | If this option is set and authentication debugging is enabled (see the &%-d%& | |
168e428f PH |
21910 | command line option), the string is expanded and included in the debugging |
21911 | output when the authenticator is run as a server. This can help with checking | |
21912 | out the values of variables. | |
21913 | If expansion of the string fails, the error message is written to the debugging | |
21914 | output, and Exim carries on processing. | |
21915 | ||
21916 | ||
9b371988 PH |
21917 | .option server_set_id authenticators string&!! unset |
21918 | .cindex "&$authenticated_id$&" | |
168e428f PH |
21919 | When an Exim server successfully authenticates a client, this string is |
21920 | expanded using data from the authentication, and preserved for any incoming | |
9b371988 | 21921 | messages in the variable &$authenticated_id$&. It is also included in the log |
168e428f PH |
21922 | lines for incoming messages. For example, a user/password authenticator |
21923 | configuration might preserve the user name that was used to authenticate, and | |
21924 | refer to it subsequently during delivery of the message. | |
21925 | If expansion fails, the option is ignored. | |
21926 | ||
21927 | ||
9b371988 | 21928 | .option server_mail_auth_condition authenticators string&!! unset |
168e428f PH |
21929 | This option allows a server to discard authenticated sender addresses supplied |
21930 | as part of MAIL commands in SMTP connections that are authenticated by the | |
9b371988 | 21931 | driver on which &%server_mail_auth_condition%& is set. The option is not used |
168e428f PH |
21932 | as part of the authentication process; instead its (unexpanded) value is |
21933 | remembered for later use. | |
21934 | How it is used is described in the following section. | |
21935 | ||
21936 | ||
21937 | ||
21938 | ||
21939 | ||
9b371988 PH |
21940 | .section "The AUTH parameter on MAIL commands" "SECTauthparamail" |
21941 | .cindex "authentication" "sender; authenticated" | |
21942 | .cindex "AUTH" "on MAIL command" | |
168e428f PH |
21943 | When a client supplied an AUTH= item on a MAIL command, Exim applies |
21944 | the following checks before accepting it as the authenticated sender of the | |
21945 | message: | |
21946 | ||
9b371988 PH |
21947 | .ilist |
21948 | If the connection is not using extended SMTP (that is, HELO was used rather | |
168e428f | 21949 | than EHLO), the use of AUTH= is a syntax error. |
9b371988 PH |
21950 | .next |
21951 | If the value of the AUTH= parameter is &"<>"&, it is ignored. | |
21952 | .next | |
21953 | .cindex "&$authenticated_sender$&" | |
21954 | If &%acl_smtp_mailauth%& is defined, the ACL it specifies is run. While it is | |
21955 | running, the value of &$authenticated_sender$& is set to the value obtained | |
21956 | from the AUTH= parameter. If the ACL does not yield &"accept"&, the value of | |
21957 | &$authenticated_sender$& is deleted. The &%acl_smtp_mailauth%& ACL may not | |
21958 | return &"drop"& or &"discard"&. If it defers, a temporary error code (451) is | |
21959 | given for the MAIL command. | |
21960 | .next | |
21961 | If &%acl_smtp_mailauth%& is not defined, the value of the AUTH= parameter | |
21962 | is accepted and placed in &$authenticated_sender$& only if the client has | |
168e428f | 21963 | authenticated. |
9b371988 PH |
21964 | .next |
21965 | If the AUTH= value was accepted by either of the two previous rules, and | |
168e428f | 21966 | the client has authenticated, and the authenticator has a setting for the |
9b371988 | 21967 | &%server_mail_auth_condition%&, the condition is checked at this point. The |
168e428f | 21968 | valued that was saved from the authenticator is expanded. If the expansion |
9b371988 PH |
21969 | fails, or yields an empty string, &"0"&, &"no"&, or &"false"&, the value of |
21970 | &$authenticated_sender$& is deleted. If the expansion yields any other value, | |
21971 | the value of &$authenticated_sender$& is retained and passed on with the | |
168e428f | 21972 | message. |
9b371988 | 21973 | .endlist |
168e428f PH |
21974 | |
21975 | ||
9b371988 | 21976 | When &$authenticated_sender$& is set for a message, it is passed on to other |
168e428f | 21977 | hosts to which Exim authenticates as a client. Do not confuse this value with |
9b371988 | 21978 | &$authenticated_id$&, which is a string obtained from the authentication |
168e428f PH |
21979 | process, and which is not usually a complete email address. |
21980 | ||
9b371988 | 21981 | .cindex "&$sender_address$&" |
168e428f PH |
21982 | Whenever an AUTH= value is ignored, the incident is logged. The ACL for |
21983 | MAIL, if defined, is run after AUTH= is accepted or ignored. It can | |
9b371988 PH |
21984 | therefore make use of &$authenticated_sender$&. The converse is not true: the |
21985 | value of &$sender_address$& is not yet set up when the &%acl_smtp_mailauth%& | |
168e428f PH |
21986 | ACL is run. |
21987 | ||
21988 | ||
21989 | ||
9b371988 PH |
21990 | .section "Authentication on an Exim server" "SECTauthexiser" |
21991 | .cindex "authentication" "on an Exim server" | |
168e428f PH |
21992 | When Exim receives an EHLO command, it advertises the public names of those |
21993 | authenticators that are configured as servers, subject to the following | |
21994 | conditions: | |
21995 | ||
9b371988 PH |
21996 | .ilist |
21997 | The client host must match &%auth_advertise_hosts%& (default *). | |
21998 | .next | |
21999 | It the &%server_advertise_condition%& option is set, its expansion must not | |
22000 | yield the empty string, &"0"&, &"no"&, or &"false"&. | |
22001 | .endlist | |
168e428f PH |
22002 | |
22003 | The order in which the authenticators are defined controls the order in which | |
22004 | the mechanisms are advertised. | |
22005 | ||
22006 | Some mail clients (for example, some versions of Netscape) require the user to | |
22007 | provide a name and password for authentication whenever AUTH is advertised, | |
22008 | even though authentication may not in fact be needed (for example, Exim may be | |
22009 | set up to allow unconditional relaying from the client by an IP address check). | |
22010 | You can make such clients more friendly by not advertising AUTH to them. | |
22011 | For example, if clients on the 10.9.8.0/24 network are permitted (by the ACL | |
22012 | that runs for RCPT) to relay without authentication, you should set | |
9b371988 PH |
22013 | .code |
22014 | auth_advertise_hosts = ! 10.9.8.0/24 | |
22015 | .endd | |
168e428f PH |
22016 | so that no authentication mechanisms are advertised to them. |
22017 | ||
9b371988 | 22018 | The &%server_advertise_condition%& controls the advertisement of individual |
168e428f PH |
22019 | authentication mechanisms. For example, it can be used to restrict the |
22020 | advertisement of a patricular mechanism to encrypted connections, by a setting | |
22021 | such as: | |
9b371988 PH |
22022 | .code |
22023 | server_advertise_condition = ${if eq{$tls_cipher}{}{no}{yes}} | |
22024 | .endd | |
22025 | .cindex "&$tls_cipher$&" | |
22026 | If the session is encrypted, &$tls_cipher$& is not empty, and so the expansion | |
22027 | yields &"yes"&, which allows the advertisement to happen. | |
168e428f PH |
22028 | |
22029 | When an Exim server receives an AUTH command from a client, it rejects it | |
22030 | immediately if AUTH was not advertised in response to an earlier EHLO | |
22031 | command. This is the case if | |
22032 | ||
9b371988 PH |
22033 | .ilist |
22034 | The client host does not match &%auth_advertise_hosts%&; or | |
22035 | .next | |
22036 | No authenticators are configured with server options; or | |
22037 | .next | |
22038 | Expansion of &%server_advertise_condition%& blocked the advertising of all the | |
168e428f | 22039 | server authenticators. |
9b371988 | 22040 | .endlist |
168e428f PH |
22041 | |
22042 | ||
9b371988 PH |
22043 | Otherwise, Exim runs the ACL specified by &%acl_smtp_auth%& in order |
22044 | to decide whether to accept the command. If &%acl_smtp_auth%& is not set, | |
168e428f PH |
22045 | AUTH is accepted from any client host. |
22046 | ||
22047 | If AUTH is not rejected by the ACL, Exim searches its configuration for a | |
22048 | server authentication mechanism that was advertised in response to EHLO and | |
22049 | that matches the one named in the AUTH command. If it finds one, it runs | |
22050 | the appropriate authentication protocol, and authentication either succeeds or | |
22051 | fails. If there is no matching advertised mechanism, the AUTH command is | |
22052 | rejected with a 504 error. | |
22053 | ||
9b371988 PH |
22054 | .cindex "&$received_protocol$&" |
22055 | .cindex "&$sender_host_authenticated$&" | |
168e428f | 22056 | When a message is received from an authenticated host, the value of |
9b371988 PH |
22057 | &$received_protocol$& is set to &"esmtpa"& or &"esmtpsa"& instead of &"esmtp"& |
22058 | or &"esmtps"&, and &$sender_host_authenticated$& contains the name (not the | |
22059 | public name) of the authenticator driver that successfully authenticated the | |
22060 | client from which the message was received. This variable is empty if there was | |
22061 | no successful authentication. | |
168e428f PH |
22062 | |
22063 | ||
22064 | ||
22065 | ||
9b371988 PH |
22066 | .section "Testing server authentication" |
22067 | .cindex "authentication" "testing a server" | |
22068 | .cindex "AUTH" "testing a server" | |
22069 | .cindex "base64 encoding" "creating authentication test data" | |
22070 | Exim's &%-bh%& option can be useful for testing server authentication | |
168e428f PH |
22071 | configurations. The data for the AUTH command has to be sent using base64 |
22072 | encoding. A quick way to produce such data for testing is the following Perl | |
22073 | script: | |
9b371988 PH |
22074 | .code |
22075 | use MIME::Base64; | |
22076 | printf ("%s", encode_base64(eval "\"$ARGV[0]\"")); | |
22077 | .endd | |
22078 | .cindex "binary zero" "in authentication data" | |
168e428f PH |
22079 | This interprets its argument as a Perl string, and then encodes it. The |
22080 | interpretation as a Perl string allows binary zeros, which are required for | |
22081 | some kinds of authentication, to be included in the data. For example, a | |
22082 | command line to run this script on such data might be | |
9b371988 PH |
22083 | .code |
22084 | encode '\0user\0password' | |
22085 | .endd | |
168e428f PH |
22086 | Note the use of single quotes to prevent the shell interpreting the |
22087 | backslashes, so that they can be interpreted by Perl to specify characters | |
22088 | whose code value is zero. | |
22089 | ||
9b371988 | 22090 | &*Warning 1*&: If either of the user or password strings starts with an octal |
168e428f PH |
22091 | digit, you must use three zeros instead of one after the leading backslash. If |
22092 | you do not, the octal digit that starts your string will be incorrectly | |
22093 | interpreted as part of the code for the first character. | |
22094 | ||
9b371988 | 22095 | &*Warning 2*&: If there are characters in the strings that Perl interprets |
168e428f PH |
22096 | specially, you must use a Perl escape to prevent them being misinterpreted. For |
22097 | example, a command such as | |
9b371988 PH |
22098 | .code |
22099 | encode '\0user@domain.com\0pas$$word' | |
22100 | .endd | |
22101 | gives an incorrect answer because of the unescaped &"@"& and &"$"& characters. | |
168e428f | 22102 | |
9b371988 | 22103 | If you have the &%mimencode%& command installed, another way to do produce |
168e428f | 22104 | base64-encoded strings is to run the command |
9b371988 PH |
22105 | .code |
22106 | echo -e -n `\0user\0password' | mimencode | |
22107 | .endd | |
22108 | The &%-e%& option of &%echo%& enables the interpretation of backslash escapes | |
22109 | in the argument, and the &%-n%& option specifies no newline at the end of its | |
22110 | output. However, not all versions of &%echo%& recognize these options, so you | |
168e428f PH |
22111 | should check your version before relying on this suggestion. |
22112 | ||
22113 | ||
22114 | ||
9b371988 PH |
22115 | .section "Authentication by an Exim client" |
22116 | .cindex "authentication" "on an Exim client" | |
22117 | The &(smtp)& transport has two options called &%hosts_require_auth%& and | |
22118 | &%hosts_try_auth%&. When the &(smtp)& transport connects to a server that | |
168e428f PH |
22119 | announces support for authentication, and the host matches an entry in either |
22120 | of these options, Exim (as a client) tries to authenticate as follows: | |
22121 | ||
9b371988 PH |
22122 | .ilist |
22123 | For each authenticator that is configured as a client, it searches the | |
168e428f PH |
22124 | authentication mechanisms announced by the server for one whose name |
22125 | matches the public name of the authenticator. | |
9b371988 PH |
22126 | .next |
22127 | .cindex "&$host$&" | |
22128 | .cindex "&$host_address$&" | |
068aaea8 | 22129 | When it finds one that matches, it runs the authenticator's client code. |
9b371988 | 22130 | The variables &$host$& and &$host_address$& are available for any string |
168e428f PH |
22131 | expansions that the client might do. They are set to the server's name and |
22132 | IP address. If any expansion is forced to fail, the authentication attempt | |
22133 | is abandoned, | |
22134 | and Exim moves on to the next authenticator. | |
22135 | Otherwise an expansion failure causes delivery to be | |
22136 | deferred. | |
9b371988 PH |
22137 | .next |
22138 | If the result of the authentication attempt is a temporary error or a timeout, | |
168e428f PH |
22139 | Exim abandons trying to send the message to the host for the moment. It will |
22140 | try again later. If there are any backup hosts available, they are tried in the | |
22141 | usual way. | |
9b371988 PH |
22142 | .next |
22143 | If the response to authentication is a permanent error (5&'xx'& code), Exim | |
22144 | carries on searching the list of authenticators and tries another one if | |
22145 | possible. If all authentication attempts give permanent errors, or if there are | |
22146 | no attempts because no mechanisms match (or option expansions force failure), | |
22147 | what happens depends on whether the host matches &%hosts_require_auth%& or | |
22148 | &%hosts_try_auth%&. In the first case, a temporary error is generated, and | |
168e428f PH |
22149 | delivery is deferred. The error can be detected in the retry rules, and thereby |
22150 | turned into a permanent error if you wish. In the second case, Exim tries to | |
22151 | deliver the message unauthenticated. | |
9b371988 | 22152 | .endlist |
168e428f | 22153 | |
9b371988 | 22154 | .cindex "AUTH" "on MAIL command" |
168e428f | 22155 | When Exim has authenticated itself to a remote server, it adds the AUTH |
9b371988 PH |
22156 | parameter to the MAIL commands it sends, if it has an authenticated sender for |
22157 | the message. If the message came from a remote host, the authenticated sender | |
22158 | is the one that was receiving on an incoming MAIL command, provided that the | |
22159 | incoming connection was authenticated and the &%server_mail_auth%& condition | |
22160 | allowed the authenticated sender to be retained. If a local process calls Exim | |
22161 | to send a message, the sender address that is built from the login name and | |
22162 | &%qualify_domain%& is treated as authenticated. However, if the | |
22163 | &%authenticated_sender%& option is set on the &(smtp)& transport, it overrides | |
168e428f PH |
22164 | the authenticated sender that was received with the message. |
22165 | ||
22166 | ||
22167 | ||
22168 | ||
22169 | ||
22170 | ||
9b371988 PH |
22171 | . //////////////////////////////////////////////////////////////////////////// |
22172 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 22173 | |
9b371988 PH |
22174 | .chapter "The plaintext authenticator" "CHAPplaintext" |
22175 | .cindex "&(plaintext)& authenticator" | |
22176 | .cindex "authenticators" "&(plaintext)&" | |
22177 | The &(plaintext)& authenticator can be configured to support the PLAIN and | |
168e428f PH |
22178 | LOGIN authentication mechanisms, both of which transfer authentication data as |
22179 | plain (unencrypted) text (though base64 encoded). The use of plain text is a | |
22180 | security risk. If you use one of these mechanisms without also making use of | |
9b371988 PH |
22181 | SMTP encryption (see chapter &<<CHAPTLS>>&) you should not use the same |
22182 | passwords for SMTP connections as you do for login accounts. | |
168e428f PH |
22183 | |
22184 | ||
9b371988 PH |
22185 | .section "Using plaintext in a server" |
22186 | .cindex "options" "&(plaintext)& authenticator (server)" | |
22187 | When running as a server, &(plaintext)& performs the authentication test by | |
168e428f PH |
22188 | expanding a string. It has the following options: |
22189 | ||
9b371988 | 22190 | .option server_prompts plaintext string&!! unset |
168e428f PH |
22191 | The contents of this option, after expansion, must be a colon-separated list of |
22192 | prompt strings. If expansion fails, a temporary authentication rejection is | |
22193 | given. | |
22194 | ||
9b371988 | 22195 | .option server_condition plaintext string&!! unset |
168e428f PH |
22196 | This option must be set in order to configure the driver as a server. Its use |
22197 | is described below. | |
22198 | ||
9b371988 PH |
22199 | .cindex "AUTH" "in &(plaintext)& authenticator" |
22200 | .cindex "binary zero" "in &(plaintext)& authenticator" | |
22201 | .cindex "numerical variables (&$1$& &$2$& etc)" &&& | |
22202 | "in &(plaintext)& authenticator" | |
22203 | .cindex "base64 encoding" "in &(plaintext)& authenticator" | |
168e428f PH |
22204 | The data sent by the client with the AUTH command, or in response to |
22205 | subsequent prompts, is base64 encoded, and so may contain any byte values | |
22206 | when decoded. If any data is supplied with the command, it is treated as a | |
22207 | list of strings, separated by NULs (binary zeros), which are placed in the | |
9b371988 PH |
22208 | expansion variables &$1$&, &$2$&, etc. If there are more strings in |
22209 | &%server_prompts%& than the number of strings supplied with the AUTH | |
168e428f PH |
22210 | command, the remaining prompts are used to obtain more data. Each response from |
22211 | the client may be a list of NUL-separated strings. | |
22212 | ||
9b371988 PH |
22213 | .cindex "&$authenticated_id$&" |
22214 | Once a sufficient number of data strings have been received, | |
22215 | &%server_condition%& is expanded. If the expansion is forced to fail, | |
22216 | authentication fails. Any other expansion failure causes a temporary error code | |
22217 | to be returned. If the result of a successful expansion is an empty string, | |
22218 | &"0"&, &"no"&, or &"false"&, authentication fails. If the result of the | |
22219 | expansion is &"1"&, &"yes"&, or &"true"&, authentication succeeds and the | |
22220 | generic &%server_set_id%& option is expanded and saved in &$authenticated_id$&. | |
22221 | For any other result, a temporary error code is returned, with the expanded | |
22222 | string as the error text. | |
22223 | ||
22224 | &*Warning*&: If you use a lookup in the expansion to find the user's | |
168e428f PH |
22225 | password, be sure to make the authentication fail if the user is unknown. |
22226 | There are good and bad examples at the end of the next section. | |
22227 | ||
22228 | ||
22229 | ||
9b371988 PH |
22230 | .section "The PLAIN authentication mechanism" |
22231 | .cindex "PLAIN authentication mechanism" | |
22232 | .cindex "authentication" "PLAIN mechanism" | |
22233 | .cindex "binary zero" "in &(plaintext)& authenticator" | |
168e428f PH |
22234 | The PLAIN authentication mechanism (RFC 2595) specifies that three strings be |
22235 | sent as one item of data (that is, one combined string containing two NUL | |
22236 | separators). The data is sent either as part of the AUTH command, or | |
22237 | subsequently in response to an empty prompt from the server. | |
22238 | ||
22239 | The second and third strings are a user name and a corresponding password. | |
22240 | Using a single fixed user name and password as an example, this could be | |
22241 | configured as follows: | |
9b371988 | 22242 | .code |
168e428f PH |
22243 | fixed_plain: |
22244 | driver = plaintext | |
22245 | public_name = PLAIN | |
22246 | server_prompts = : | |
22247 | server_condition = \ | |
22248 | ${if and {{eq{$2}{username}}{eq{$3}{mysecret}}}{yes}{no}} | |
22249 | server_set_id = $2 | |
9b371988 PH |
22250 | .endd |
22251 | The &%server_prompts%& setting specifies a single, empty prompt (empty items at | |
168e428f PH |
22252 | the end of a string list are ignored). If all the data comes as part of the |
22253 | AUTH command, as is commonly the case, the prompt is not used. This | |
22254 | authenticator is advertised in the response to EHLO as | |
9b371988 PH |
22255 | .code |
22256 | 250-AUTH PLAIN | |
22257 | .endd | |
168e428f | 22258 | and a client host can authenticate itself by sending the command |
9b371988 PH |
22259 | .code |
22260 | AUTH PLAIN AHVzZXJuYW1lAG15c2VjcmV0 | |
22261 | .endd | |
168e428f PH |
22262 | As this contains three strings (more than the number of prompts), no further |
22263 | data is required from the client. Alternatively, the client may just send | |
9b371988 PH |
22264 | .code |
22265 | AUTH PLAIN | |
22266 | .endd | |
168e428f PH |
22267 | to initiate authentication, in which case the server replies with an empty |
22268 | prompt. The client must respond with the combined data string. | |
22269 | ||
22270 | The data string is base64 encoded, as required by the RFC. This example, | |
9b371988 PH |
22271 | when decoded, is <&'NUL'&>&`username`&<&'NUL'&>&`mysecret`&, where <&'NUL'&> |
22272 | represents a zero byte. This is split up into three strings, the first of which | |
22273 | is empty. The &%server_condition%& option in the authenticator checks that the | |
22274 | second two are &`username`& and &`mysecret`& respectively. | |
168e428f PH |
22275 | |
22276 | Having just one fixed user name and password, as in this example, is not very | |
22277 | realistic, though for a small organization with only a handful of | |
22278 | authenticating clients it could make sense. | |
22279 | ||
22280 | A more sophisticated instance of this authenticator could use the user name in | |
9b371988 PH |
22281 | &$2$& to look up a password in a file or database, and maybe do an encrypted |
22282 | comparison (see &%crypteq%& in chapter &<<CHAPexpand>>&). Here is a example of | |
22283 | this approach, where the passwords are looked up in a DBM file. &*Warning*&: | |
22284 | This is an incorrect example: | |
22285 | .code | |
168e428f PH |
22286 | server_condition = \ |
22287 | ${if eq{$3}{${lookup{$2}dbm{/etc/authpwd}}}{yes}{no}} | |
9b371988 PH |
22288 | .endd |
22289 | The expansion uses the user name (&$2$&) as the key to look up a password, | |
22290 | which it then compares to the supplied password (&$3$&). Why is this example | |
168e428f PH |
22291 | incorrect? It works fine for existing users, but consider what happens if a |
22292 | non-existent user name is given. The lookup fails, but as no success/failure | |
22293 | strings are given for the lookup, it yields an empty string. Thus, to defeat | |
22294 | the authentication, all a client has to do is to supply a non-existent user | |
22295 | name and an empty password. The correct way of writing this test is: | |
9b371988 | 22296 | .code |
168e428f PH |
22297 | server_condition = ${lookup{$2}dbm{/etc/authpwd}\ |
22298 | {${if eq{$value}{$3}{yes}{no}}}{no}} | |
9b371988 | 22299 | .endd |
168e428f | 22300 | In this case, if the lookup succeeds, the result is checked; if the lookup |
9b371988 PH |
22301 | fails, authentication fails. If &%crypteq%& is being used instead of &%eq%&, |
22302 | the first example is in fact safe, because &%crypteq%& always fails if its | |
22303 | second argument is empty. However, the second way of writing the test makes the | |
22304 | logic clearer. | |
168e428f PH |
22305 | |
22306 | ||
22307 | ||
9b371988 PH |
22308 | .section "The LOGIN authentication mechanism" |
22309 | .cindex "LOGIN authentication mechanism" | |
22310 | .cindex "authentication" "LOGIN mechanism" | |
168e428f PH |
22311 | The LOGIN authentication mechanism is not documented in any RFC, but is in use |
22312 | in a number of programs. No data is sent with the AUTH command. Instead, a | |
22313 | user name and password are supplied separately, in response to prompts. The | |
22314 | plaintext authenticator can be configured to support this as in this example: | |
9b371988 | 22315 | .code |
168e428f PH |
22316 | fixed_login: |
22317 | driver = plaintext | |
22318 | public_name = LOGIN | |
22319 | server_prompts = User Name : Password | |
22320 | server_condition = \ | |
22321 | ${if and {{eq{$1}{username}}{eq{$2}{mysecret}}}{yes}{no}} | |
22322 | server_set_id = $1 | |
9b371988 | 22323 | .endd |
168e428f PH |
22324 | Because of the way plaintext operates, this authenticator accepts data supplied |
22325 | with the AUTH command (in contravention of the specification of LOGIN), but | |
22326 | if the client does not supply it (as is the case for LOGIN clients), the prompt | |
22327 | strings are used to obtain two data items. | |
22328 | ||
22329 | Some clients are very particular about the precise text of the prompts. For | |
9b371988 PH |
22330 | example, Outlook Express is reported to recognize only &"Username:"& and |
22331 | &"Password:"&. Here is an example of a LOGIN authenticator that uses those | |
22332 | strings. It uses the &%ldapauth%& expansion condition to check the user | |
168e428f | 22333 | name and password by binding to an LDAP server: |
9b371988 | 22334 | .code |
168e428f PH |
22335 | login: |
22336 | driver = plaintext | |
22337 | public_name = LOGIN | |
22338 | server_prompts = Username:: : Password:: | |
22339 | server_condition = ${if ldapauth \ | |
22340 | {user="cn=${quote_ldap_dn:$1},ou=people,o=example.org" \ | |
22341 | pass=${quote:$2} \ | |
22342 | ldap://ldap.example.org/}{yes}{no}} | |
22343 | server_set_id = uid=$1,ou=people,o=example.org | |
9b371988 PH |
22344 | .endd |
22345 | Note the use of the &%quote_ldap_dn%& operator to correctly quote the DN for | |
22346 | authentication. However, the basic &%quote%& operator, rather than any of the | |
168e428f PH |
22347 | LDAP quoting operators, is the correct one to use for the password, because |
22348 | quoting is needed only to make the password conform to the Exim syntax. At the | |
22349 | LDAP level, the password is an uninterpreted string. | |
22350 | ||
22351 | ||
22352 | ||
9b371988 | 22353 | .section "Support for different kinds of authentication" |
168e428f PH |
22354 | A number of string expansion features are provided for the purpose of |
22355 | interfacing to different ways of user authentication. These include checking | |
9b371988 PH |
22356 | traditionally encrypted passwords from &_/etc/passwd_& (or equivalent), PAM, |
22357 | Radius, &%ldapauth%&, and &'pwcheck'&. For details see section | |
22358 | &<<SECTexpcond>>&. | |
168e428f PH |
22359 | |
22360 | ||
22361 | ||
22362 | ||
9b371988 PH |
22363 | .section "Using plaintext in a client" |
22364 | .cindex "options" "&(plaintext)& authenticator (client)" | |
22365 | The &(plaintext)& authenticator has just one client option: | |
168e428f PH |
22366 | |
22367 | ||
22368 | ||
9b371988 | 22369 | .option client_send plaintext string&!! unset |
168e428f PH |
22370 | The string is a colon-separated list of authentication data strings. Each |
22371 | string is independently expanded before being sent to the server. The first | |
22372 | string is sent with the AUTH command; any more strings are sent in response | |
22373 | to prompts from the server. | |
22374 | ||
9b371988 | 22375 | &*Note*&: You cannot use expansion to create multiple strings, because |
168e428f PH |
22376 | splitting takes priority and happens first. |
22377 | ||
22378 | Because the PLAIN authentication mechanism requires NUL (binary zero) bytes in | |
22379 | the data, further processing is applied to each string before it is sent. If | |
22380 | there are any single circumflex characters in the string, they are converted to | |
22381 | NULs. Should an actual circumflex be required as data, it must be doubled in | |
22382 | the string. | |
22383 | ||
22384 | This is an example of a client configuration that implements the PLAIN | |
22385 | authentication mechanism with a fixed user name and password: | |
9b371988 PH |
22386 | .code |
22387 | fixed_plain: | |
22388 | driver = plaintext | |
22389 | public_name = PLAIN | |
22390 | client_send = ^username^mysecret | |
22391 | .endd | |
168e428f PH |
22392 | The lack of colons means that the entire text is sent with the AUTH |
22393 | command, with the circumflex characters converted to NULs. A similar example | |
22394 | that uses the LOGIN mechanism is: | |
9b371988 PH |
22395 | .code |
22396 | fixed_login: | |
22397 | driver = plaintext | |
22398 | public_name = LOGIN | |
22399 | client_send = : username : mysecret | |
22400 | .endd | |
168e428f PH |
22401 | The initial colon means that the first string is empty, so no data is sent with |
22402 | the AUTH command itself. The remaining strings are sent in response to | |
22403 | prompts. | |
22404 | ||
22405 | ||
22406 | ||
22407 | ||
9b371988 PH |
22408 | . //////////////////////////////////////////////////////////////////////////// |
22409 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 22410 | |
9b371988 PH |
22411 | .chapter "The cram_md5 authenticator" |
22412 | .cindex "&(cram_md5)& authenticator" | |
22413 | .cindex "authenticators" "&(cram_md5)&" | |
22414 | .cindex "CRAM-MD5 authentication mechanism" | |
22415 | .cindex "authentication" "CRAM-MD5 mechanism" | |
168e428f PH |
22416 | The CRAM-MD5 authentication mechanism is described in RFC 2195. The server |
22417 | sends a challenge string to the client, and the response consists of a user | |
22418 | name and the CRAM-MD5 digest of the challenge string combined with a secret | |
22419 | string (password) which is known to both server and client. Thus, the secret | |
22420 | is not sent over the network as plain text, which makes this authenticator more | |
9b371988 | 22421 | secure than &(plaintext)&. However, the downside is that the secret has to be |
168e428f PH |
22422 | available in plain text at either end. |
22423 | ||
22424 | ||
9b371988 PH |
22425 | .section "Using cram_md5 as a server" |
22426 | .cindex "options" "&(cram_md5)& authenticator (server)" | |
168e428f PH |
22427 | This authenticator has one server option, which must be set to configure the |
22428 | authenticator as a server: | |
22429 | ||
9b371988 PH |
22430 | .option server_secret cram_md5 string&!! unset |
22431 | .cindex "numerical variables (&$1$& &$2$& etc)" "in &(cram_md5)& authenticator" | |
168e428f | 22432 | When the server receives the client's response, the user name is placed in |
9b371988 | 22433 | the expansion variable &$1$&, and &%server_secret%& is expanded to obtain the |
168e428f PH |
22434 | password for that user. The server then computes the CRAM-MD5 digest that the |
22435 | client should have sent, and checks that it received the correct string. If the | |
9b371988 | 22436 | expansion of &%server_secret%& is forced to fail, authentication fails. If the |
168e428f PH |
22437 | expansion fails for some other reason, a temporary error code is returned to |
22438 | the client. | |
22439 | ||
22440 | For example, the following authenticator checks that the user name given by the | |
9b371988 PH |
22441 | client is &"ph10"&, and if so, uses &"secret"& as the password. For any other |
22442 | user name, authentication fails. | |
22443 | .code | |
22444 | fixed_cram: | |
22445 | driver = cram_md5 | |
22446 | public_name = CRAM-MD5 | |
22447 | server_secret = ${if eq{$1}{ph10}{secret}fail} | |
22448 | server_set_id = $1 | |
22449 | .endd | |
22450 | .cindex "&$authenticated_id$&" | |
22451 | If authentication succeeds, the setting of &%server_set_id%& preserves the user | |
22452 | name in &$authenticated_id$&. A more tyical configuration might look up the | |
068aaea8 | 22453 | secret string in a file, using the user name as the key. For example: |
9b371988 PH |
22454 | .code |
22455 | lookup_cram: | |
22456 | driver = cram_md5 | |
22457 | public_name = CRAM-MD5 | |
22458 | server_secret = ${lookup{$1}lsearch{/etc/authpwd}{$value}fail} | |
22459 | server_set_id = $1 | |
22460 | .endd | |
168e428f | 22461 | Note that this expansion explicitly forces failure if the lookup fails |
9b371988 | 22462 | because &$1$& contains an unknown user name. |
168e428f PH |
22463 | |
22464 | ||
9b371988 PH |
22465 | .section "Using cram_md5 as a client" |
22466 | .cindex "options" "&(cram_md5)& authenticator (client)" | |
22467 | When used as a client, the &(cram_md5)& authenticator has two options: | |
168e428f PH |
22468 | |
22469 | ||
22470 | ||
9b371988 | 22471 | .option client_name cram_md5 string&!! "the primary host name" |
168e428f PH |
22472 | This string is expanded, and the result used as the user name data when |
22473 | computing the response to the server's challenge. | |
22474 | ||
22475 | ||
9b371988 | 22476 | .option client_secret cram_md5 string&!! unset |
168e428f PH |
22477 | This option must be set for the authenticator to work as a client. Its value is |
22478 | expanded and the result used as the secret string when computing the response. | |
22479 | ||
22480 | ||
9b371988 PH |
22481 | .cindex "&$host$&" |
22482 | .cindex "&$host_address$&" | |
168e428f | 22483 | Different user names and secrets can be used for different servers by referring |
9b371988 PH |
22484 | to &$host$& or &$host_address$& in the options. Forced failure of either |
22485 | expansion string is treated as an indication that this authenticator is not | |
22486 | prepared to handle this case. Exim moves on to the next configured client | |
22487 | authenticator. Any other expansion failure causes Exim to give up trying to | |
22488 | send the message to the current server. | |
168e428f | 22489 | |
9b371988 | 22490 | A simple example configuration of a &(cram_md5)& authenticator, using fixed |
168e428f | 22491 | strings, is: |
9b371988 PH |
22492 | .code |
22493 | fixed_cram: | |
22494 | driver = cram_md5 | |
22495 | public_name = CRAM-MD5 | |
22496 | client_name = ph10 | |
22497 | client_secret = secret | |
22498 | .endd | |
168e428f PH |
22499 | |
22500 | ||
22501 | ||
9b371988 PH |
22502 | . //////////////////////////////////////////////////////////////////////////// |
22503 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 22504 | |
9b371988 PH |
22505 | .chapter "The cyrus_sasl authenticator" |
22506 | .cindex "&(cyrus_sasl)& authenticator" | |
22507 | .cindex "authenticators" "&(cyrus_sasl)&" | |
22508 | .cindex "Cyrus" "SASL library" | |
168e428f | 22509 | The code for this authenticator was provided by Matthew Byng-Maddick of A L |
9b371988 | 22510 | Digital Ltd (&url(http://www.aldigital.co.uk)). |
168e428f | 22511 | |
9b371988 PH |
22512 | The &(cyrus_sasl)& authenticator provides server support for the Cyrus SASL |
22513 | library implementation of the RFC 2222 (&"Simple Authentication and Security | |
22514 | Layer"&). This library supports a number of authentication mechanisms, | |
22515 | including PLAIN and LOGIN, but also several others that Exim does not support | |
22516 | directly. In particular, there is support for Kerberos authentication. | |
168e428f | 22517 | |
9b371988 | 22518 | The &(cyrus_sasl)& authenticator provides a gatewaying mechanism directly to |
168e428f | 22519 | the Cyrus interface, so if your Cyrus library can do, for example, CRAM-MD5, |
9b371988 | 22520 | then so can the &(cyrus_sasl)& authenticator. By default it uses the public |
168e428f PH |
22521 | name of the driver to determine which mechanism to support. |
22522 | ||
22523 | Where access to some kind of secret file is required, for example in GSSAPI | |
9b371988 | 22524 | or CRAM-MD5, it is worth noting that the authenticator runs as the Exim |
168e428f PH |
22525 | user, and that the Cyrus SASL library has no way of escalating privileges |
22526 | by default. You may also find you need to set environment variables, | |
22527 | depending on the driver you are using. | |
22528 | ||
22529 | ||
9b371988 PH |
22530 | .section "Using cyrus_sasl as a server" |
22531 | The &(cyrus_sasl)& authenticator has four private options. It puts the | |
22532 | username (on a successful authentication) into &$1$&. | |
168e428f | 22533 | |
9b371988 | 22534 | .option server_hostname cyrus_sasl string&!! &`$primary_hostname`& |
168e428f PH |
22535 | This option selects the hostname that is used when communicating with |
22536 | the library. It is up to the underlying SASL plug-in what it does with | |
22537 | this data. | |
22538 | ||
22539 | ||
9b371988 | 22540 | .option server_mech cyrus_sasl string &`public_name`& |
168e428f PH |
22541 | This option selects the authentication mechanism this driver should |
22542 | use. It allows you to use a different underlying mechanism from the | |
22543 | advertised name. For example: | |
9b371988 PH |
22544 | .code |
22545 | sasl: | |
22546 | driver = cyrus_sasl | |
22547 | public_name = X-ANYTHING | |
22548 | server_mech = CRAM-MD5 | |
22549 | server_set_id = $1 | |
22550 | .endd | |
168e428f | 22551 | |
9b371988 | 22552 | .option server_realm cyrus_sasl string unset |
168e428f PH |
22553 | This specifies the SASL realm that the server claims to be in. |
22554 | ||
22555 | ||
9b371988 | 22556 | .option server_service cyrus_sasl string &`smtp`& |
168e428f PH |
22557 | This is the SASL service that the server claims to implement. |
22558 | ||
22559 | ||
22560 | For straightforward cases, you do not need to set any of the authenticator's | |
22561 | private options. All you need to do is to specify an appropriate mechanism as | |
22562 | the public name. Thus, if you have a SASL library that supports CRAM-MD5 and | |
22563 | PLAIN, you could have two authenticators as follows: | |
9b371988 PH |
22564 | .code |
22565 | sasl_cram_md5: | |
22566 | driver = cyrus_sasl | |
22567 | public_name = CRAM-MD5 | |
22568 | server_set_id = $1 | |
168e428f | 22569 | |
9b371988 PH |
22570 | sasl_plain: |
22571 | driver = cyrus_sasl | |
22572 | public_name = PLAIN | |
22573 | server_set_id = $1 | |
22574 | .endd | |
168e428f PH |
22575 | Cyrus SASL does implement the LOGIN authentication method, even though it is |
22576 | not a standard method. It is disabled by default in the source distribution, | |
22577 | but it is present in many binary distributions. | |
22578 | ||
22579 | ||
22580 | ||
22581 | ||
9b371988 PH |
22582 | . //////////////////////////////////////////////////////////////////////////// |
22583 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 22584 | |
9b371988 PH |
22585 | .chapter "The spa authenticator" |
22586 | .cindex "&(spa)& authenticator" | |
22587 | .cindex "authenticators" "&(spa)&" | |
22588 | .cindex "authentication" "Microsoft Secure Password" | |
22589 | .cindex "authentication" "NTLM" | |
22590 | .cindex "Microsoft Secure Password Authentication" | |
22591 | .cindex "NTLM authentication" | |
22592 | The &(spa)& authenticator provides client support for Microsoft's &'Secure | |
22593 | Password Authentication'& mechanism, | |
168e428f PH |
22594 | which is also sometimes known as NTLM (NT LanMan). The code for client side of |
22595 | this authenticator was contributed by Marc Prud'hommeaux, and much of it is | |
9b371988 | 22596 | taken from the Samba project (&url(http://www.samba.org)). The code for the |
168e428f PH |
22597 | server side was subsequently contributed by Tom Kistner. The mechanism works as |
22598 | follows: | |
22599 | ||
9b371988 PH |
22600 | .ilist |
22601 | After the AUTH command has been accepted, the client sends an SPA | |
168e428f | 22602 | authentication request based on the user name and optional domain. |
9b371988 PH |
22603 | .next |
22604 | The server sends back a challenge. | |
22605 | .next | |
22606 | The client builds a challenge response which makes use of the user's password | |
168e428f | 22607 | and sends it to the server, which then accepts or rejects it. |
9b371988 | 22608 | .endlist |
168e428f PH |
22609 | |
22610 | Encryption is used to protect the password in transit. | |
22611 | ||
22612 | ||
22613 | ||
9b371988 PH |
22614 | .section "Using spa as a server" |
22615 | .cindex "options" "&(spa)& authenticator (server)" | |
22616 | The &(spa)& authenticator has just one server option: | |
168e428f | 22617 | |
9b371988 PH |
22618 | .option server_password spa string&!! unset |
22619 | .cindex "numerical variables (&$1$& &$2$& etc)" "in &(spa)& authenticator" | |
168e428f | 22620 | This option is expanded, and the result must be the cleartext password for the |
9b371988 PH |
22621 | authenticating user, whose name is at this point in &$1$&. For example: |
22622 | .code | |
068aaea8 PH |
22623 | spa: |
22624 | driver = spa | |
22625 | public_name = NTLM | |
22626 | server_password = ${lookup{$1}lsearch{/etc/exim/spa_clearpass}\ | |
22627 | {$value}fail} | |
9b371988 | 22628 | .endd |
168e428f PH |
22629 | If the expansion is forced to fail, authentication fails. Any other expansion |
22630 | failure causes a temporary error code to be returned. | |
22631 | ||
22632 | ||
22633 | ||
22634 | ||
22635 | ||
9b371988 PH |
22636 | .section "Using spa as a client" |
22637 | .cindex "options" "&(spa)& authenticator (client)" | |
22638 | The &(spa)& authenticator has the following client options: | |
168e428f PH |
22639 | |
22640 | ||
168e428f | 22641 | |
9b371988 | 22642 | .option client_domain spa string&!! unset |
168e428f PH |
22643 | This option specifies an optional domain for the authentication. |
22644 | ||
22645 | ||
9b371988 | 22646 | .option client_password spa string&!! unset |
168e428f PH |
22647 | This option specifies the user's password, and must be set. |
22648 | ||
22649 | ||
9b371988 PH |
22650 | .option client_username spa string&!! unset |
22651 | This option specifies the user name, and must be set. Here is an example of a | |
22652 | configuration of this authenticator for use with the mail servers at | |
22653 | &'msn.com'&: | |
22654 | .code | |
22655 | msn: | |
22656 | driver = spa | |
22657 | public_name = MSN | |
22658 | client_username = msn/msn_username | |
22659 | client_password = msn_plaintext_password | |
22660 | client_domain = DOMAIN_OR_UNSET | |
22661 | .endd | |
168e428f PH |
22662 | |
22663 | ||
22664 | ||
22665 | ||
22666 | ||
9b371988 PH |
22667 | . //////////////////////////////////////////////////////////////////////////// |
22668 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 22669 | |
9b371988 PH |
22670 | .chapter "Encrypted SMTP connections using TLS/SSL" "CHAPTLS" &&& |
22671 | "Encrypted SMTP connections" | |
22672 | .cindex "encryption" "on SMTP connection" | |
22673 | .cindex "SMTP" "encryption" | |
22674 | .cindex "TLS" "on SMTP connection" | |
22675 | .cindex "OpenSSL" | |
22676 | .cindex "GnuTLS" | |
168e428f PH |
22677 | Support for TLS (Transport Layer Security), formerly known as SSL (Secure |
22678 | Sockets Layer), is implemented by making use of the OpenSSL library or the | |
22679 | GnuTLS library (Exim requires GnuTLS release 1.0 or later). There is no | |
22680 | cryptographic code in the Exim distribution itself for implementing TLS. In | |
22681 | order to use this feature you must install OpenSSL or GnuTLS, and then build a | |
9b371988 PH |
22682 | version of Exim that includes TLS support (see section &<<SECTinctlsssl>>&). |
22683 | You also need to understand the basic concepts of encryption at a managerial | |
22684 | level, and in particular, the way that public keys, private keys, and | |
22685 | certificates are used. | |
168e428f | 22686 | |
068aaea8 | 22687 | RFC 3207 defines how SMTP connections can make use of encryption. Once a |
168e428f PH |
22688 | connection is established, the client issues a STARTTLS command. If the |
22689 | server accepts this, the client and the server negotiate an encryption | |
22690 | mechanism. If the negotiation succeeds, the data that subsequently passes | |
22691 | between them is encrypted. | |
22692 | ||
22693 | Exim's ACLs can detect whether the current SMTP session is encrypted or not, | |
22694 | and if so, what cipher suite is in use, whether the client supplied a | |
22695 | certificate, and whether or not that certificate was verified. This makes it | |
22696 | possible for an Exim server to deny or accept certain commands based on the | |
22697 | encryption state. | |
22698 | ||
9b371988 | 22699 | &*Warning*&: Certain types of firewall and certain anti-virus products can |
168e428f PH |
22700 | disrupt TLS connections. You need to turn off SMTP scanning for these products |
22701 | in order to get TLS to work. | |
22702 | ||
22703 | ||
22704 | ||
9b371988 PH |
22705 | .section "Support for the legacy &""ssmtp""& (aka &""smtps""&) protocol" |
22706 | .cindex "ssmtp protocol" | |
22707 | .cindex "smtps protocol" | |
22708 | .cindex "SMTP" "ssmtp protocol" | |
22709 | .cindex "SMTP" "smtps protocol" | |
168e428f PH |
22710 | Early implementations of encrypted SMTP used a different TCP port from normal |
22711 | SMTP, and expected an encryption negotiation to start immediately, instead of | |
22712 | waiting for a STARTTLS command from the client using the standard SMTP | |
9b371988 PH |
22713 | port. The protocol was called &"ssmtp"& or &"smtps"&, and port 465 was |
22714 | allocated for this purpose. | |
168e428f PH |
22715 | |
22716 | This approach was abandoned when encrypted SMTP was standardised, but there are | |
22717 | still some legacy clients that use it. Exim supports these clients by means of | |
9b371988 | 22718 | the &%tls_on_connect_ports%& global option. Its value must be a list of port |
168e428f | 22719 | numbers; the most common use is expected to be: |
9b371988 PH |
22720 | .code |
22721 | tls_on_connect_ports = 465 | |
22722 | .endd | |
168e428f | 22723 | The port numbers specified by this option apply to all SMTP connections, both |
9b371988 PH |
22724 | via the daemon and via &'inetd'&. You still need to specify all the ports that |
22725 | the daemon uses (by setting &%daemon_smtp_ports%& or &%local_interfaces%& or | |
22726 | the &%-oX%& command line option) because &%tls_on_connect_ports%& does not add | |
22727 | an extra port &-- rather, it specifies different behaviour on a port that is | |
168e428f PH |
22728 | defined elsewhere. |
22729 | ||
9b371988 PH |
22730 | There is also a &%-tls-on-connect%& command line option. This overrides |
22731 | &%tls_on_connect_ports%&; it forces the legacy behaviour for all ports. | |
168e428f PH |
22732 | |
22733 | ||
22734 | ||
22735 | ||
22736 | ||
22737 | ||
9b371988 PH |
22738 | .section "OpenSSL vs GnuTLS" "SECTopenvsgnu" |
22739 | .cindex "TLS" "OpenSSL &'vs'& GnuTLS" | |
168e428f PH |
22740 | The first TLS support in Exim was implemented using OpenSSL. Support for GnuTLS |
22741 | followed later, when the first versions of GnuTLS were released. To build Exim | |
22742 | to use GnuTLS, you need to set | |
9b371988 PH |
22743 | .code |
22744 | USE_GNUTLS=yes | |
22745 | .endd | |
168e428f | 22746 | in Local/Makefile, in addition to |
9b371988 PH |
22747 | .code |
22748 | SUPPORT_TLS=yes | |
22749 | .endd | |
168e428f PH |
22750 | You must also set TLS_LIBS and TLS_INCLUDE appropriately, so that the |
22751 | include files and libraries for GnuTLS can be found. | |
22752 | ||
22753 | There are some differences in usage when using GnuTLS instead of OpenSSL: | |
22754 | ||
9b371988 PH |
22755 | .ilist |
22756 | The &%tls_verify_certificates%& option must contain the name of a file, not the | |
168e428f | 22757 | name of a directory (for OpenSSL it can be either). |
9b371988 PH |
22758 | .next |
22759 | The &%tls_dhparam%& option is ignored, because early versions of GnuTLS had no | |
168e428f PH |
22760 | facility for varying its Diffie-Hellman parameters. I understand that this has |
22761 | changed, but Exim has not been updated to provide this facility. | |
9b371988 PH |
22762 | .next |
22763 | .cindex "&$tls_peerdn$&" | |
068aaea8 | 22764 | Distinguished Name (DN) strings reported by the OpenSSL library use a slash for |
168e428f | 22765 | separating fields; GnuTLS uses commas, in accordance with RFC 2253. This |
9b371988 PH |
22766 | affects the value of the &$tls_peerdn$& variable. |
22767 | .next | |
22768 | OpenSSL identifies cipher suites using hyphens as separators, for example: | |
168e428f PH |
22769 | DES-CBC3-SHA. GnuTLS uses underscores, for example: RSA_ARCFOUR_SHA. What is |
22770 | more, OpenSSL complains if underscores are present in a cipher list. To make | |
22771 | life simpler, Exim changes underscores to hyhens for OpenSSL and hyphens to | |
22772 | underscores for GnuTLS when processing lists of cipher suites in the | |
9b371988 | 22773 | &%tls_require_ciphers%& options (the global option and the &(smtp)& transport |
168e428f | 22774 | option). |
9b371988 PH |
22775 | .next |
22776 | The &%tls_require_ciphers%& options operate differently, as described in the | |
22777 | sections &<<SECTreqciphssl>>& and &<<SECTreqciphgnu>>&. | |
22778 | .endlist | |
168e428f | 22779 | |
068aaea8 | 22780 | |
9b371988 | 22781 | .section "GnuTLS parameter computation" |
068aaea8 PH |
22782 | GnuTLS uses RSA and D-H parameters that take a substantial amount of time to |
22783 | compute. It is unreasonable to re-compute them for every TLS session. | |
22784 | Therefore, Exim keeps this data in a file in its spool directory, called | |
9b371988 PH |
22785 | &_gnutls-params_&. The file is owned by the Exim user and is readable only by |
22786 | its owner. Every Exim process that start up GnuTLS reads the RSA and D-H | |
22787 | parameters from this file. If the file does not exist, the first Exim process | |
22788 | that needs it computes the data and writes it to a temporary file which is | |
22789 | renamed once it is complete. It does not matter if several Exim processes do | |
22790 | this simultaneously (apart from wasting a few resources). Once a file is in | |
22791 | place, new Exim processes immediately start using it. | |
22792 | ||
22793 | .new | |
068aaea8 PH |
22794 | For maximum security, the parameters that are stored in this file should be |
22795 | recalculated periodically, the frequency depending on your paranoia level. | |
22796 | Arranging this is easy in principle; just delete the file when you want new | |
22797 | values to be computed. However, there may be a problem. The calculation of new | |
9b371988 PH |
22798 | parameters needs random numbers, and these are obtained from &_/dev/random_&. |
22799 | If the system is not very active, &_/dev/random_& may delay returning data | |
22800 | until enough randomness (entropy) is available. This may cause Exim to hang for | |
22801 | a substantial amount of time, causing timeouts on incoming connections. | |
068aaea8 | 22802 | |
068aaea8 | 22803 | The solution is to generate the parameters externally to Exim. They are stored |
9b371988 PH |
22804 | in &_gnutls-params_& in PEM format, which means that they can be generated |
22805 | externally using the &(certtool)& command that is part of GnuTLS. | |
068aaea8 | 22806 | |
068aaea8 PH |
22807 | To replace the parameters with new ones, instead of deleting the file |
22808 | and letting Exim re-create it, you can generate new parameters using | |
9b371988 | 22809 | &(certtool)& and, when this has been done, replace Exim's cache file by |
068aaea8 | 22810 | renaming. The relevant commands are something like this: |
9b371988 | 22811 | .code |
068aaea8 PH |
22812 | # rm -f new-params |
22813 | # touch new-params | |
22814 | # chown exim:exim new-params | |
22815 | # chmod 0400 new-params | |
22816 | # certtool --generate-privkey --bits 512 >new-params | |
22817 | # echo "" >>new-params | |
22818 | # certtool --generate-dh-params --bits 1024 >> new-params | |
22819 | # mv new-params gnutls-params | |
9b371988 | 22820 | .endd |
068aaea8 PH |
22821 | If Exim never has to generate the parameters itself, the possibility of |
22822 | stalling is removed. | |
9b371988 | 22823 | .wen |
168e428f PH |
22824 | |
22825 | ||
9b371988 PH |
22826 | .section "Requiring specific ciphers in OpenSSL" "SECTreqciphssl" |
22827 | .cindex "TLS" "requiring specific ciphers (OpenSSL)" | |
22828 | .cindex "&%tls_require_ciphers%&" "OpenSSL" | |
168e428f PH |
22829 | There is a function in the OpenSSL library that can be passed a list of cipher |
22830 | suites before the cipher negotiation takes place. This specifies which ciphers | |
22831 | are acceptable. The list is colon separated and may contain names like | |
9b371988 | 22832 | DES-CBC3-SHA. Exim passes the expanded value of &%tls_require_ciphers%& |
168e428f PH |
22833 | directly to this function call. The following quotation from the OpenSSL |
22834 | documentation specifies what forms of item are allowed in the cipher string: | |
22835 | ||
9b371988 PH |
22836 | .ilist |
22837 | It can consist of a single cipher suite such as RC4-SHA. | |
22838 | .next | |
22839 | It can represent a list of cipher suites containing a certain algorithm, | |
168e428f PH |
22840 | or cipher suites of a certain type. For example SHA1 represents all |
22841 | ciphers suites using the digest algorithm SHA1 and SSLv3 represents all | |
22842 | SSL v3 algorithms. | |
9b371988 PH |
22843 | .next |
22844 | Lists of cipher suites can be combined in a single cipher string using | |
168e428f PH |
22845 | the + character. This is used as a logical and operation. For example |
22846 | SHA1+DES represents all cipher suites containing the SHA1 and the DES | |
22847 | algorithms. | |
9b371988 | 22848 | .endlist |
168e428f | 22849 | |
9b371988 PH |
22850 | Each cipher string can be optionally preceded by one of the characters &`!`&, |
22851 | &`-`& or &`+`&. | |
22852 | .ilist | |
22853 | If &`!`& is used, the ciphers are permanently deleted from the list. The | |
168e428f PH |
22854 | ciphers deleted can never reappear in the list even if they are explicitly |
22855 | stated. | |
9b371988 PH |
22856 | .next |
22857 | If &`-`& is used, the ciphers are deleted from the list, but some or all | |
168e428f | 22858 | of the ciphers can be added again by later options. |
9b371988 PH |
22859 | .next |
22860 | If &`+`& is used, the ciphers are moved to the end of the list. This | |
22861 | option does not add any new ciphers; it just moves matching existing ones. | |
22862 | .endlist | |
22863 | ||
22864 | If none of these characters is present, the string is interpreted as | |
168e428f PH |
22865 | a list of ciphers to be appended to the current preference list. If the list |
22866 | includes any ciphers already present they will be ignored: that is, they will | |
9b371988 PH |
22867 | not be moved to the end of the list. |
22868 | .endlist | |
168e428f PH |
22869 | |
22870 | ||
22871 | ||
22872 | ||
9b371988 PH |
22873 | .section "Requiring specific ciphers in GnuTLS" "SECTreqciphgnu" |
22874 | .cindex "TLS" "requiring specific ciphers (GnuTLS)" | |
22875 | .cindex "&%tls_require_ciphers%&" "GnuTLS" | |
168e428f PH |
22876 | The GnuTLS library does not have a combined function like OpenSSL. Instead, |
22877 | it allows the caller to specify separate lists of key-exchange methods, | |
22878 | main cipher algorithms, and MAC algorithms. Unfortunately, these lists are | |
22879 | numerical, and the library does not have a function for turning names into | |
22880 | numbers. Consequently, the list of recognized names has to be built into | |
22881 | the application. | |
22882 | ||
22883 | At present, Exim permits only the list of main cipher algorithms to be | |
9b371988 | 22884 | changed. The &%tls_require_ciphers%& option is in the same format as for |
168e428f PH |
22885 | OpenSSL. Exim searches each item for the name of available algorithm. For |
22886 | example, if the list contains RSA_AES_SHA then AES is recognized. | |
22887 | ||
22888 | The cipher algorithms list starts out with a default set of algorithms. If | |
9b371988 | 22889 | the first item in &%tls_require_ciphers%& does &'not'& start with an |
168e428f | 22890 | exclamation mark, all the default items are deleted. Thus, only those specified |
9b371988 | 22891 | can be used. If the first item in &%tls_require_ciphers%& &'does'& start with |
168e428f PH |
22892 | an exclamation mark, the defaults are left on the list. |
22893 | ||
9b371988 | 22894 | Then, any item that starts with an exclamation mark causes the relevant |
168e428f PH |
22895 | algorithms to be removed from the list, and any item that does not start |
22896 | with an exclamation mark causes the relevant algorithms to be added to the | |
22897 | list. Thus, | |
9b371988 PH |
22898 | .code |
22899 | tls_require_ciphers = !RSA_ARCFOUR_SHA | |
22900 | .endd | |
168e428f | 22901 | allows all the defaults except those that use ARCFOUR, whereas |
9b371988 PH |
22902 | .code |
22903 | tls_require_ciphers = AES : 3DES | |
22904 | .endd | |
168e428f PH |
22905 | allows only cipher suites that use AES and 3DES. The currently recognized |
22906 | algorithms are: AES_256, AES_128, AES (both of the preceding), 3DES, and | |
22907 | ARCFOUR_128. Unrecognized algorithms are ignored. In a server, the order of the | |
22908 | list is unimportant; the server will advertise the availability of all the | |
22909 | relevant cipher suites. However, in a client, the order of the list specifies a | |
22910 | preference order for the algorithms. The first one in the client's list that is | |
22911 | also advertised by the server is tried first. The default order is as listed | |
22912 | above. | |
22913 | ||
22914 | ||
22915 | ||
22916 | ||
9b371988 PH |
22917 | .section "Configuring an Exim server to use TLS" |
22918 | .cindex "TLS" "configuring an Exim server" | |
168e428f | 22919 | When Exim has been built with TLS support, it advertises the availability of |
9b371988 | 22920 | the STARTTLS command to client hosts that match &%tls_advertise_hosts%&, |
168e428f PH |
22921 | but not to any others. The default value of this option is unset, which means |
22922 | that STARTTLS is not advertised at all. This default is chosen because you | |
22923 | need to set some other options in order to make TLS avaliable, and also it is | |
22924 | sensible for systems that want to use TLS only as a client. | |
22925 | ||
22926 | If a client issues a STARTTLS command and there is some configuration | |
22927 | problem in the server, the command is rejected with a 454 error. If the client | |
22928 | persists in trying to issue SMTP commands, all except QUIT are rejected | |
22929 | with the error | |
9b371988 PH |
22930 | .code |
22931 | 554 Security failure | |
22932 | .endd | |
168e428f PH |
22933 | If a STARTTLS command is issued within an existing TLS session, it is |
22934 | rejected with a 554 error code. | |
22935 | ||
9b371988 PH |
22936 | To enable TLS operations on a server, you must set &%tls_advertise_hosts%& to |
22937 | match some hosts. You can, of course, set it to * to match all hosts. | |
168e428f PH |
22938 | However, this is not all you need to do. TLS sessions to a server won't work |
22939 | without some further configuration at the server end. | |
22940 | ||
22941 | It is rumoured that all existing clients that support TLS/SSL use RSA | |
22942 | encryption. To make this work you need to set, in the server, | |
9b371988 PH |
22943 | .code |
22944 | tls_certificate = /some/file/name | |
22945 | tls_privatekey = /some/file/name | |
22946 | .endd | |
168e428f PH |
22947 | The first file contains the server's X509 certificate, and the second contains |
22948 | the private key that goes with it. These files need to be readable by the Exim | |
22949 | user, and must always be given as full path names. They can be the same file if | |
9b371988 | 22950 | both the certificate and the key are contained within it. If &%tls_privatekey%& |
168e428f PH |
22951 | is not set, this is assumed to be the case. The certificate file may also |
22952 | contain intermediate certificates that need to be sent to the client to enable | |
22953 | it to authenticate the server's certificate. | |
22954 | ||
22955 | If you do not understand about certificates and keys, please try to find a | |
22956 | source of this background information, which is not Exim-specific. (There are a | |
9b371988 | 22957 | few comments below in section &<<SECTcerandall>>&.) |
168e428f | 22958 | |
9b371988 | 22959 | &*Note*&: These options do not apply when Exim is operating as a client &-- |
168e428f | 22960 | they apply only in the case of a server. For a client, you must set the options |
9b371988 | 22961 | of the same name in an &(smtp)& transport. |
168e428f PH |
22962 | |
22963 | With just these options, Exim will work as a server with clients such as | |
22964 | Netscape. It does not require the client to have a certificate (but see below | |
22965 | for how to insist on this). There is one other option that may be needed in | |
22966 | other situations. If | |
9b371988 PH |
22967 | .code |
22968 | tls_dhparam = /some/file/name | |
22969 | .endd | |
168e428f PH |
22970 | is set, the SSL library is initialized for the use of Diffie-Hellman ciphers |
22971 | with the parameters contained in the file. This increases the set of cipher | |
22972 | suites that the server supports. See the command | |
9b371988 PH |
22973 | .code |
22974 | openssl dhparam | |
22975 | .endd | |
168e428f | 22976 | for a way of generating this data. |
9b371988 PH |
22977 | At present, &%tls_dhparam%& is used only when Exim is linked with OpenSSL. It |
22978 | is ignored if GnuTLS is being used. | |
168e428f PH |
22979 | |
22980 | The strings supplied for these three options are expanded every time a client | |
22981 | host connects. It is therefore possible to use different certificates and keys | |
22982 | for different hosts, if you so wish, by making use of the client's IP address | |
9b371988 | 22983 | in &$sender_host_address$& to control the expansion. If a string expansion is |
168e428f PH |
22984 | forced to fail, Exim behaves as if the option is not set. |
22985 | ||
9b371988 PH |
22986 | .cindex "cipher" "logging" |
22987 | .cindex "log" "TLS cipher" | |
22988 | .cindex "&$tls_cipher$&" | |
22989 | The variable &$tls_cipher$& is set to the cipher suite that was negotiated for | |
22990 | an incoming TLS connection. It is included in the &'Received:'& header of an | |
22991 | incoming message (by default &-- you can, of course, change this), and it is | |
22992 | also included in the log line that records a message's arrival, keyed by | |
22993 | &"X="&, unless the &%tls_cipher%& log selector is turned off. The &%encrypted%& | |
22994 | condition can be used to test for specific cipher suites in ACLs. | |
168e428f PH |
22995 | |
22996 | The ACLs that run for subsequent SMTP commands can check the name of the cipher | |
22997 | suite and vary their actions accordingly. The cipher suite names are those used | |
22998 | by OpenSSL. These may differ from the names used elsewhere. For example, | |
22999 | OpenSSL uses the name DES-CBC3-SHA for the cipher suite which in other contexts | |
23000 | is known as TLS_RSA_WITH_3DES_EDE_CBC_SHA. Check the OpenSSL | |
23001 | documentation for more details. | |
23002 | ||
23003 | ||
23004 | ||
9b371988 PH |
23005 | .section "Requesting and verifying client certificates" |
23006 | .cindex "certificate" "verification of client" | |
23007 | .cindex "TLS" "client certificate verification" | |
168e428f | 23008 | If you want an Exim server to request a certificate when negotiating a TLS |
9b371988 PH |
23009 | session with a client, you must set either &%tls_verify_hosts%& or |
23010 | &%tls_try_verify_hosts%&. You can, of course, set either of them to * to | |
168e428f PH |
23011 | apply to all TLS connections. For any host that matches one of these options, |
23012 | Exim requests a certificate as part of the setup of the TLS session. The | |
23013 | contents of the certificate are verified by comparing it with a list of | |
23014 | expected certificates. These must be available in a file or, | |
23015 | for OpenSSL only (not GnuTLS), a directory, identified by | |
9b371988 | 23016 | &%tls_verify_certificates%&. |
168e428f PH |
23017 | |
23018 | A file can contain multiple certificates, concatenated end to end. If a | |
23019 | directory is used | |
23020 | (OpenSSL only), | |
23021 | each certificate must be in a separate file, with a name (or a symbolic link) | |
9b371988 | 23022 | of the form <&'hash'&>.0, where <&'hash'&> is a hash value constructed from the |
168e428f | 23023 | certificate. You can compute the relevant hash by running the command |
9b371988 PH |
23024 | .code |
23025 | openssl x509 -hash -noout -in /cert/file | |
23026 | .endd | |
23027 | where &_/cert/file_& contains a single certificate. | |
168e428f | 23028 | |
9b371988 | 23029 | The difference between &%tls_verify_hosts%& and &%tls_try_verify_hosts%& is |
168e428f PH |
23030 | what happens if the client does not supply a certificate, or if the certificate |
23031 | does not match any of the certificates in the collection named by | |
9b371988 | 23032 | &%tls_verify_certificates%&. If the client matches &%tls_verify_hosts%&, the |
168e428f | 23033 | attempt to set up a TLS session is aborted, and the incoming connection is |
9b371988 | 23034 | dropped. If the client matches &%tls_try_verify_hosts%&, the (encrypted) SMTP |
168e428f PH |
23035 | session continues. ACLs that run for subsequent SMTP commands can detect the |
23036 | fact that no certificate was verified, and vary their actions accordingly. For | |
23037 | example, you can insist on a certificate before accepting a message for | |
23038 | relaying, but not when the message is destined for local delivery. | |
23039 | ||
9b371988 | 23040 | .cindex "&$tls_peerdn$&" |
168e428f PH |
23041 | When a client supplies a certificate (whether it verifies or not), the value of |
23042 | the Distinguished Name of the certificate is made available in the variable | |
9b371988 | 23043 | &$tls_peerdn$& during subsequent processing of the message. |
168e428f | 23044 | |
9b371988 | 23045 | .cindex "log" "distinguished name" |
168e428f | 23046 | Because it is often a long text string, it is not included in the log line or |
9b371988 PH |
23047 | &'Received:'& header by default. You can arrange for it to be logged, keyed by |
23048 | &"DN="&, by setting the &%tls_peerdn%& log selector, and you can use | |
23049 | &%received_header_text%& to change the &'Received:'& header. When no | |
23050 | certificate is supplied, &$tls_peerdn$& is empty. | |
168e428f PH |
23051 | |
23052 | ||
9b371988 PH |
23053 | .section "Revoked certificates" |
23054 | .cindex "TLS" "revoked certificates" | |
23055 | .cindex "revocation list" | |
23056 | .cindex "certificate" "revocation list" | |
168e428f PH |
23057 | Certificate issuing authorities issue Certificate Revocation Lists (CRLs) when |
23058 | certificates are revoked. If you have such a list, you can pass it to an Exim | |
9b371988 PH |
23059 | server using the global option called &%tls_crl%& and to an Exim client using |
23060 | an identically named option for the &(smtp)& transport. In each case, the value | |
23061 | of the option is expanded and must then be the name of a file that contains a | |
23062 | CRL in PEM format. | |
23063 | ||
23064 | ||
23065 | .section "Configuring an Exim client to use TLS" | |
23066 | .cindex "cipher" "logging" | |
23067 | .cindex "log" "TLS cipher" | |
23068 | .cindex "log" "distinguished name" | |
23069 | .cindex "TLS" "configuring an Exim client" | |
23070 | The &%tls_cipher%& and &%tls_peerdn%& log selectors apply to outgoing SMTP | |
168e428f PH |
23071 | deliveries as well as to incoming, the latter one causing logging of the |
23072 | server certificate's DN. The remaining client configuration for TLS is all | |
9b371988 | 23073 | within the &(smtp)& transport. |
168e428f | 23074 | |
9b371988 | 23075 | It is not necessary to set any options to have TLS work in the &(smtp)& |
168e428f | 23076 | transport. If Exim is built with TLS support, and TLS is advertised by a |
9b371988 PH |
23077 | server, the &(smtp)& transport always tries to start a TLS session. However, |
23078 | this can be prevented by setting &%hosts_avoid_tls%& (an option of the | |
168e428f PH |
23079 | transport) to a list of server hosts for which TLS should not be used. |
23080 | ||
23081 | If you do not want Exim to attempt to send messages unencrypted when an attempt | |
23082 | to set up an encrypted connection fails in any way, you can set | |
9b371988 | 23083 | &%hosts_require_tls%& to a list of hosts for which encryption is mandatory. For |
168e428f PH |
23084 | those hosts, delivery is always deferred if an encrypted connection cannot be |
23085 | set up. If there are any other hosts for the address, they are tried in the | |
23086 | usual way. | |
23087 | ||
9b371988 | 23088 | When the server host is not in &%hosts_require_tls%&, Exim may try to deliver |
168e428f | 23089 | the message unencrypted. It always does this if the response to STARTTLS is |
9b371988 | 23090 | a 5&'xx'& code. For a temporary error code, or for a failure to negotiate a TLS |
168e428f | 23091 | session after a success response code, what happens is controlled by the |
9b371988 | 23092 | &%tls_tempfail_tryclear%& option of the &(smtp)& transport. If it is false, |
168e428f | 23093 | delivery to this host is deferred, and other hosts (if available) are tried. If |
9b371988 | 23094 | it is true, Exim attempts to deliver unencrypted after a 4&'xx'& response to |
168e428f PH |
23095 | STARTTLS, and if STARTTLS is accepted, but the subsequent TLS |
23096 | negotiation fails, Exim closes the current connection (because it is in an | |
23097 | unknown state), opens a new one to the same host, and then tries the delivery | |
23098 | unencrypted. | |
23099 | ||
23100 | ||
9b371988 PH |
23101 | The &%tls_certificate%& and &%tls_privatekey%& options of the &(smtp)& |
23102 | transport provide the client with a certificate, which is passed to the server | |
23103 | if it requests it. If the server is Exim, it will request a certificate only if | |
23104 | &%tls_verify_hosts%& or &%tls_try_verify_hosts%& matches the client. &*Note*&: | |
23105 | These options must be set in the &(smtp)& transport for Exim to use TLS when it | |
23106 | is operating as a client. Exim does not assume that a server certificate (set | |
23107 | by the global options of the same name) should also be used when operating as a | |
23108 | client. | |
168e428f | 23109 | |
9b371988 | 23110 | If &%tls_verify_certificates%& is set, it must name a file or, |
168e428f PH |
23111 | for OpenSSL only (not GnuTLS), a directory, that contains a collection of |
23112 | expected server certificates. The client verifies the server's certificate | |
23113 | against this collection, taking into account any revoked certificates that are | |
9b371988 | 23114 | in the list defined by &%tls_crl%&. |
168e428f PH |
23115 | |
23116 | If | |
9b371988 | 23117 | &%tls_require_ciphers%& is set on the &(smtp)& transport, it must contain a |
168e428f | 23118 | list of permitted cipher suites. If either of these checks fails, delivery to |
9b371988 | 23119 | the current host is abandoned, and the &(smtp)& transport tries to deliver to |
168e428f PH |
23120 | alternative hosts, if any. |
23121 | ||
9b371988 PH |
23122 | .cindex "&$host$&" |
23123 | .cindex "&$host_address$&" | |
23124 | All the TLS options in the &(smtp)& transport are expanded before use, with | |
23125 | &$host$& and &$host_address$& containing the name and address of the server to | |
168e428f PH |
23126 | which the client is connected. Forced failure of an expansion causes Exim to |
23127 | behave as if the relevant option were unset. | |
23128 | ||
23129 | ||
23130 | ||
9b371988 PH |
23131 | .section "Multiple messages on the same encrypted TCP/IP connection" &&& |
23132 | "SECTmulmessam" | |
23133 | .cindex "multiple SMTP deliveries with TLS" | |
23134 | .cindex "TLS" "multiple message deliveries" | |
168e428f PH |
23135 | Exim sends multiple messages down the same TCP/IP connection by starting up |
23136 | an entirely new delivery process for each message, passing the socket from | |
23137 | one process to the next. This implementation does not fit well with the use | |
23138 | of TLS, because there is quite a lot of state information associated with a TLS | |
23139 | connection, not just a socket identification. Passing all the state information | |
23140 | to a new process is not feasible. Consequently, Exim shuts down an existing TLS | |
23141 | session before passing the socket to a new process. The new process may then | |
23142 | try to start a new TLS session, and if successful, may try to re-authenticate | |
23143 | if AUTH is in use, before sending the next message. | |
23144 | ||
23145 | The RFC is not clear as to whether or not an SMTP session continues in clear | |
23146 | after TLS has been shut down, or whether TLS may be restarted again later, as | |
23147 | just described. However, if the server is Exim, this shutdown and | |
23148 | reinitialization works. It is not known which (if any) other servers operate | |
23149 | successfully if the client closes a TLS session and continues with unencrypted | |
23150 | SMTP, but there are certainly some that do not work. For such servers, Exim | |
23151 | should not pass the socket to another process, because the failure of the | |
23152 | subsequent attempt to use it would cause Exim to record a temporary host error, | |
23153 | and delay other deliveries to that host. | |
23154 | ||
23155 | To test for this case, Exim sends an EHLO command to the server after | |
23156 | closing down the TLS session. If this fails in any way, the connection is | |
23157 | closed instead of being passed to a new delivery process, but no retry | |
23158 | information is recorded. | |
23159 | ||
9b371988 PH |
23160 | There is also a manual override; you can set &%hosts_nopass_tls%& on the |
23161 | &(smtp)& transport to match those hosts for which Exim should not pass | |
168e428f PH |
23162 | connections to new processes if TLS has been used. |
23163 | ||
23164 | ||
23165 | ||
23166 | ||
9b371988 PH |
23167 | .section "Certificates and all that" "SECTcerandall" |
23168 | .cindex "certificate" "references to discussion" | |
168e428f PH |
23169 | In order to understand fully how TLS works, you need to know about |
23170 | certificates, certificate signing, and certificate authorities. This is not the | |
23171 | place to give a tutorial, especially as I do not know very much about it | |
23172 | myself. Some helpful introduction can be found in the FAQ for the SSL addition | |
23173 | to Apache, currently at | |
9b371988 PH |
23174 | .display |
23175 | &url(http://www.modssl.org/docs/2.7/ssl_faq.html#ToC24) | |
23176 | .endd | |
23177 | Other parts of the &'modssl'& documentation are also helpful, and have | |
168e428f | 23178 | links to further files. |
9b371988 | 23179 | Eric Rescorla's book, &'SSL and TLS'&, published by Addison-Wesley (ISBN |
168e428f PH |
23180 | 0-201-61598-3), contains both introductory and more in-depth descriptions. |
23181 | Some sample programs taken from the book are available from | |
9b371988 PH |
23182 | .display |
23183 | &url(http://www.rtfm.com/openssl-examples/) | |
23184 | .endd | |
168e428f | 23185 | |
168e428f | 23186 | |
9b371988 PH |
23187 | .section "Certificate chains" |
23188 | The file named by &%tls_certificate%& may contain more than one | |
168e428f PH |
23189 | certificate. This is useful in the case where the certificate that is being |
23190 | sent is validated by an intermediate certificate which the other end does | |
23191 | not have. Multiple certificates must be in the correct order in the file. | |
23192 | First the host's certificate itself, then the first intermediate | |
23193 | certificate to validate the issuer of the host certificate, then the next | |
23194 | intermediate certificate to validate the issuer of the first intermediate | |
23195 | certificate, and so on, until finally (optionally) the root certificate. | |
23196 | The root certificate must already be trusted by the recipient for | |
23197 | validation to succeed, of course, but if it's not preinstalled, sending the | |
23198 | root certificate along with the rest makes it available for the user to | |
23199 | install if the receiving end is a client MUA that can interact with a user. | |
23200 | ||
23201 | ||
9b371988 PH |
23202 | .section "Self-signed certificates" |
23203 | .cindex "certificate" "self-signed" | |
23204 | You can create a self-signed certificate using the &'req'& command provided | |
168e428f | 23205 | with OpenSSL, like this: |
9b371988 | 23206 | .code |
168e428f PH |
23207 | openssl req -x509 -newkey rsa:1024 -keyout file1 -out file2 \ |
23208 | -days 9999 -nodes | |
9b371988 PH |
23209 | .endd |
23210 | &_file1_& and &_file2_& can be the same file; the key and the certificate are | |
23211 | delimited and so can be identified independently. The &%-days%& option | |
23212 | specifies a period for which the certificate is valid. The &%-nodes%& option is | |
168e428f PH |
23213 | important: if you do not set it, the key is encrypted with a passphrase |
23214 | that you are prompted for, and any use that is made of the key causes more | |
23215 | prompting for the passphrase. This is not helpful if you are going to use | |
23216 | this certificate and key in an MTA, where prompting is not possible. | |
23217 | ||
23218 | A self-signed certificate made in this way is sufficient for testing, and | |
23219 | may be adequate for all your requirements if you are mainly interested in | |
23220 | encrypting transfers, and not in secure identification. | |
23221 | ||
23222 | However, many clients require that the certificate presented by the server be a | |
9b371988 | 23223 | user (also called &"leaf"& or &"site"&) certificate, and not a self-signed |
168e428f | 23224 | certificate. In this situation, the self-signed certificate described above |
9b371988 PH |
23225 | must be installed on the client host as a trusted root &'certification |
23226 | authority'& (CA), and the certificate used by Exim must be a user certificate | |
168e428f PH |
23227 | signed with that self-signed certificate. |
23228 | ||
23229 | For information on creating self-signed CA certificates and using them to sign | |
9b371988 PH |
23230 | user certificates, see the &'General implementation overview'& chapter of the |
23231 | Open-source PKI book, available online at | |
23232 | &url(http://ospkibook.sourceforge.net/). | |
168e428f PH |
23233 | |
23234 | ||
23235 | ||
9b371988 PH |
23236 | . //////////////////////////////////////////////////////////////////////////// |
23237 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 23238 | |
9b371988 PH |
23239 | .chapter "Access control lists" "CHAPACL" |
23240 | .cindex "&ACL;" "description" | |
23241 | .cindex "control of incoming mail" | |
23242 | .cindex "message" "controlling incoming" | |
23243 | .cindex "policy control" "access control lists" | |
168e428f | 23244 | Access Control Lists (ACLs) are defined in a separate section of the run time |
9b371988 | 23245 | configuration file, headed by &"begin acl"&. Each ACL definition starts with a |
168e428f PH |
23246 | name, terminated by a colon. Here is a complete ACL section that contains just |
23247 | one very small ACL: | |
9b371988 PH |
23248 | .code |
23249 | begin acl | |
168e428f | 23250 | |
9b371988 PH |
23251 | small_acl: |
23252 | accept hosts = one.host.only | |
23253 | .endd | |
168e428f PH |
23254 | You can have as many lists as you like in the ACL section, and the order in |
23255 | which they appear does not matter. The lists are self-terminating. | |
23256 | ||
23257 | The majority of ACLs are used to control Exim's behaviour when it receives | |
23258 | certain SMTP commands. This applies both to incoming TCP/IP connections, and | |
9b371988 | 23259 | when a local process submits a message using SMTP by specifying the &%-bs%& |
168e428f PH |
23260 | option. The most common use is for controlling which recipients are accepted |
23261 | in incoming messages. In addition, you can define an ACL that is used to check | |
23262 | local non-SMTP messages. The default configuration file contains an example of | |
23263 | a realistic ACL for checking RCPT commands. This is discussed in chapter | |
9b371988 | 23264 | &<<CHAPdefconfil>>&. |
168e428f PH |
23265 | |
23266 | ||
9b371988 PH |
23267 | .section "Testing ACLs" |
23268 | The &%-bh%& command line option provides a way of testing your ACL | |
23269 | configuration locally by running a fake SMTP session with which you interact. | |
23270 | The host &'relay-test.mail-abuse.org'& provides a service for checking your | |
23271 | relaying configuration (see section &<<SECTcheralcon>>& for more details). | |
168e428f PH |
23272 | |
23273 | ||
23274 | ||
9b371988 PH |
23275 | .section "Specifying when ACLs are used" |
23276 | .cindex "&ACL;" "options for specifying" | |
168e428f PH |
23277 | In order to cause an ACL to be used, you have to name it in one of the relevant |
23278 | options in the main part of the configuration. These options are: | |
9b371988 PH |
23279 | .cindex "AUTH" "ACL for" |
23280 | .cindex "DATA" "ACLs for" | |
23281 | .cindex "ETRN" "ACL for" | |
23282 | .cindex "EXPN" "ACL for" | |
23283 | .cindex "HELO" "ACL for" | |
23284 | .cindex "EHLO" "ACL for" | |
23285 | .cindex "MAIL" "ACL for" | |
23286 | .cindex "QUIT" "ACL for" | |
23287 | .cindex "RCPT" "ACL for" | |
23288 | .cindex "STARTTLS" "ACL for" | |
23289 | .cindex "VRFY" "ACL for" | |
23290 | .cindex "SMTP connection" "ACL for" | |
23291 | .cindex "non-smtp message" "ACL for" | |
23292 | ||
23293 | .table2 140pt | |
23294 | .row &~&%acl_not_smtp%& "ACL for non-SMTP messages" | |
23295 | .row &~&%acl_smtp_auth%& "ACL for AUTH" | |
23296 | .row &~&%acl_smtp_connect%& "ACL for start of SMTP connection" | |
23297 | .row &~&%acl_smtp_data%& "ACL after DATA is complete" | |
23298 | .row &~&%acl_smtp_etrn%& "ACL for ETRN" | |
23299 | .row &~&%acl_smtp_expn%& "ACL for EXPN" | |
23300 | .row &~&%acl_smtp_helo%& "ACL for HELO or EHLO" | |
23301 | .row &~&%acl_smtp_mail%& "ACL for MAIL" | |
23302 | .row &~&%acl_smtp_mailauth%& "ACL for the AUTH parameter of MAIL" | |
23303 | .row &~&%acl_smtp_mime%& "ACL for content-scanning MIME parts" | |
23304 | .row &~&%acl_smtp_predata%& "ACL at start of DATA command" | |
23305 | .row &~&%acl_smtp_quit%& "ACL for QUIT" | |
23306 | .row &~&%acl_smtp_rcpt%& "ACL for RCPT" | |
23307 | .row &~&%acl_smtp_starttls%& "ACL for STARTTLS" | |
23308 | .row &~&%acl_smtp_vrfy%& "ACL for VRFY" | |
23309 | .endtable | |
168e428f PH |
23310 | |
23311 | For example, if you set | |
9b371988 PH |
23312 | .code |
23313 | acl_smtp_rcpt = small_acl | |
23314 | .endd | |
168e428f PH |
23315 | the little ACL defined above is used whenever Exim receives a RCPT command |
23316 | in an SMTP dialogue. The majority of policy tests on incoming messages can be | |
23317 | done when RCPT commands arrive. A rejection of RCPT should cause the | |
23318 | sending MTA to give up on the recipient address contained in the RCPT | |
23319 | command, whereas rejection at other times may cause the client MTA to keep on | |
23320 | trying to deliver the message. It is therefore recommended that you do as much | |
23321 | testing as possible at RCPT time. | |
23322 | ||
23323 | ||
9b371988 PH |
23324 | .section "The non-SMTP ACL" |
23325 | .cindex "non-smtp message" "ACL for" | |
168e428f PH |
23326 | The non-SMTP ACL applies to all non-interactive incoming messages, that is, it |
23327 | applies to batch SMTP as well as to non-SMTP messages. (Batch SMTP is not | |
9b371988 | 23328 | really SMTP.) This ACL is run just before the &[local_scan()]& function. Any |
168e428f PH |
23329 | kind of rejection is treated as permanent, because there is no way of sending a |
23330 | temporary error for these kinds of message. Many of the ACL conditions (for | |
23331 | example, host tests, and tests on the state of the SMTP connection such as | |
23332 | encryption and authentication) are not relevant and are forbidden in this ACL. | |
23333 | ||
23334 | ||
9b371988 PH |
23335 | .section "The connect ACL" |
23336 | .cindex "SMTP connection" "ACL for" | |
23337 | The ACL test specified by &%acl_smtp_connect%& happens after the test specified | |
23338 | by &%host_reject_connection%& (which is now an anomaly) and any TCP Wrappers | |
168e428f PH |
23339 | testing (if configured). |
23340 | ||
23341 | ||
9b371988 PH |
23342 | .section "The DATA ACLs" |
23343 | .cindex "DATA" "ACLs for" | |
168e428f PH |
23344 | Two ACLs are associated with the DATA command, because it is two-stage |
23345 | command, with two responses being sent to the client. | |
9b371988 | 23346 | When the DATA command is received, the ACL defined by &%acl_smtp_predata%& |
168e428f PH |
23347 | is obeyed. This gives you control after all the RCPT commands, but before |
23348 | the message itself is received. It offers the opportunity to give a negative | |
23349 | response to the DATA command before the data is transmitted. Header lines | |
23350 | added by MAIL or RCPT ACLs are not visible at this time, but any that | |
9b371988 | 23351 | are defined here are visible when the &%acl_smtp_data%& ACL is run. |
168e428f PH |
23352 | |
23353 | You cannot test the contents of the message, for example, to verify addresses | |
23354 | in the headers, at RCPT time or when the DATA command is received. Such | |
23355 | tests have to appear in the ACL that is run after the message itself has been | |
23356 | received, before the final response to the DATA command is sent. This is | |
9b371988 | 23357 | the ACL specified by &%acl_smtp_data%&, which is the second ACL that is |
168e428f PH |
23358 | associated with the DATA command. |
23359 | ||
23360 | For both of these ACLs, it is not possible to reject individual recipients. An | |
23361 | error response rejects the entire message. Unfortunately, it is known that some | |
9b371988 PH |
23362 | MTAs do not treat hard (5&'xx'&) responses to the DATA command (either |
23363 | before or after the data) correctly &-- they keep the message on their queues | |
168e428f PH |
23364 | and try again later, but that is their problem, though it does waste some of |
23365 | your resources. | |
23366 | ||
23367 | ||
9b371988 PH |
23368 | .section "The MIME ACL" |
23369 | The &%acl_smtp_mime%& option is available only when Exim is compiled with the | |
23370 | content-scanning extension. For details, see chapter &<<CHAPexiscan>>&. | |
168e428f PH |
23371 | |
23372 | ||
9b371988 PH |
23373 | .section "The QUIT ACL" "SECTQUITACL" |
23374 | .cindex "QUIT" "ACL for" | |
068aaea8 PH |
23375 | The ACL for the SMTP QUIT command is anomalous, in that the outcome of the ACL |
23376 | does not affect the response code to QUIT, which is always 221. Thus, the ACL | |
23377 | does not in fact control any access. For this reason, the only verbs that are | |
9b371988 | 23378 | permitted are &%accept%& and &%warn%&. |
168e428f PH |
23379 | |
23380 | This ACL can be used for tasks such as custom logging at the end of an SMTP | |
23381 | session. For example, you can use ACL variables in other ACLs to count | |
23382 | messages, recipients, etc., and log the totals at QUIT time using one or | |
9b371988 | 23383 | more &%logwrite%& modifiers on a &%warn%& verb. |
168e428f | 23384 | |
9b371988 PH |
23385 | .new |
23386 | &*Warning*&: Only the &$acl_c$&&'x'& variables can be used for this, because | |
23387 | the &$acl_m$&&'x'& variables are reset at the end of each incoming message. | |
23388 | .wen | |
068aaea8 | 23389 | |
9b371988 PH |
23390 | You do not need to have a final &%accept%&, but if you do, you can use a |
23391 | &%message%& modifier to specify custom text that is sent as part of the 221 | |
168e428f PH |
23392 | response to QUIT. |
23393 | ||
9b371988 | 23394 | This ACL is run only for a &"normal"& QUIT. For certain kinds of disastrous |
168e428f PH |
23395 | failure (for example, failure to open a log file, or when Exim is bombing out |
23396 | because it has detected an unrecoverable error), all SMTP commands from the | |
23397 | client are given temporary error responses until QUIT is received or the | |
23398 | connection is closed. In these special cases, the QUIT ACL does not run. | |
23399 | ||
23400 | ||
23401 | ||
9b371988 PH |
23402 | .section "Finding an ACL to use" |
23403 | .cindex "&ACL;" "finding which to use" | |
23404 | The value of an &%acl_smtp_%&&'xxx'& option is expanded before use, so you can | |
168e428f PH |
23405 | use different ACLs in different circumstances. The resulting string does not |
23406 | have to be the name of an ACL in the configuration file; there are other | |
23407 | possibilities. Having expanded the string, Exim searches for an ACL as follows: | |
23408 | ||
9b371988 PH |
23409 | .ilist |
23410 | If the string begins with a slash, Exim uses it as a file name, and reads its | |
168e428f PH |
23411 | contents as an ACL. The lines are processed in the same way as lines in the |
23412 | Exim configuration file. In particular, continuation lines are supported, blank | |
9b371988 | 23413 | lines are ignored, as are lines whose first non-whitespace character is &"#"&. |
168e428f PH |
23414 | If the file does not exist or cannot be read, an error occurs (typically |
23415 | causing a temporary failure of whatever caused the ACL to be run). For example: | |
9b371988 | 23416 | .code |
168e428f PH |
23417 | acl_smtp_data = /etc/acls/\ |
23418 | ${lookup{$sender_host_address}lsearch\ | |
23419 | {/etc/acllist}{$value}{default}} | |
9b371988 | 23420 | .endd |
168e428f PH |
23421 | This looks up an ACL file to use on the basis of the host's IP address, falling |
23422 | back to a default if the lookup fails. If an ACL is successfully read from a | |
23423 | file, it is retained in memory for the duration of the Exim process, so that it | |
23424 | can be re-used without having to re-read the file. | |
9b371988 PH |
23425 | .next |
23426 | If the string does not start with a slash, and does not contain any spaces, | |
168e428f PH |
23427 | Exim searches the ACL section of the configuration for an ACL whose name |
23428 | matches the string. | |
9b371988 PH |
23429 | .next |
23430 | If no named ACL is found, or if the string contains spaces, Exim parses | |
168e428f PH |
23431 | the string as an inline ACL. This can save typing in cases where you just |
23432 | want to have something like | |
9b371988 PH |
23433 | .code |
23434 | acl_smtp_vrfy = accept | |
23435 | .endd | |
168e428f PH |
23436 | in order to allow free use of the VRFY command. Such a string may contain |
23437 | newlines; it is processed in the same way as an ACL that is read from a file. | |
9b371988 | 23438 | .endlist |
168e428f PH |
23439 | |
23440 | ||
23441 | ||
23442 | ||
9b371988 PH |
23443 | .section "ACL return codes" |
23444 | .cindex "&ACL;" "return codes" | |
168e428f | 23445 | Except for the QUIT ACL, which does not affect the SMTP return code (see |
9b371988 PH |
23446 | section &<<SECTQUITACL>>& above), the result of running an ACL is either |
23447 | &"accept"& or &"deny"&, or, if some test cannot be completed (for example, if a | |
23448 | database is down), &"defer"&. These results cause 2&'xx'&, 5&'xx'&, and 4&'xx'& | |
23449 | return codes, respectively, to be used in the SMTP dialogue. A fourth return, | |
23450 | &"error"&, occurs when there is an error such as invalid syntax in the ACL. | |
23451 | This also causes a 4&'xx'& return code. | |
23452 | ||
23453 | For the non-SMTP ACL, &"defer"& and &"error"& are treated in the same way as | |
23454 | &"deny"&, because there is no mechanism for passing temporary errors to the | |
168e428f PH |
23455 | submitters of non-SMTP messages. |
23456 | ||
23457 | ||
9b371988 PH |
23458 | ACLs that are relevant to message reception may also return &"discard"&. This |
23459 | has the effect of &"accept"&, but causes either the entire message or an | |
168e428f PH |
23460 | individual recipient address to be discarded. In other words, it is a |
23461 | blackholing facility. Use it with care. | |
23462 | ||
9b371988 PH |
23463 | If the ACL for MAIL returns &"discard"&, all recipients are discarded, and no |
23464 | ACL is run for subsequent RCPT commands. The effect of &"discard"& in a | |
168e428f PH |
23465 | RCPT ACL is to discard just the one recipient address. If there are no |
23466 | recipients left when the message's data is received, the DATA ACL is not | |
9b371988 PH |
23467 | run. A &"discard"& return from the DATA or the non-SMTP ACL discards all the |
23468 | remaining recipients. The &"discard"& return is not permitted for the | |
23469 | &%acl_smtp_predata%& ACL. | |
168e428f | 23470 | |
168e428f | 23471 | |
9b371988 PH |
23472 | .cindex "&[local_scan()]& function" "when all recipients discarded" |
23473 | The &[local_scan()]& function is always run, even if there are no remaining | |
168e428f PH |
23474 | recipients; it may create new recipients. |
23475 | ||
23476 | ||
23477 | ||
9b371988 PH |
23478 | .section "Unset ACL options" |
23479 | .cindex "&ACL;" "unset options" | |
23480 | The default actions when any of the &%acl_%&&'xxx'& options are unset are not | |
23481 | all the same. &*Note*&: These defaults apply only when the relevant ACL is | |
23482 | not defined at all. For any defined ACL, the default action when control | |
23483 | reaches the end of the ACL statements is &"deny"&. | |
168e428f | 23484 | |
9b371988 PH |
23485 | For &%acl_not_smtp%&, &%acl_smtp_auth%&, &%acl_smtp_connect%&, |
23486 | &%acl_smtp_data%&, &%acl_smtp_helo%&, &%acl_smtp_mail%&, &%acl_smtp_mailauth%&, | |
23487 | &%acl_smtp_mime%&, &%acl_smtp_predata%&, &%acl_smtp_quit%&, and | |
23488 | &%acl_smtp_starttls%&, the action when the ACL is not defined is &"accept"&. | |
168e428f | 23489 | |
9b371988 PH |
23490 | For the others (&%acl_smtp_etrn%&, &%acl_smtp_expn%&, &%acl_smtp_rcpt%&, and |
23491 | &%acl_smtp_vrfy%&), the action when the ACL is not defined is &"deny"&. | |
23492 | This means that &%acl_smtp_rcpt%& must be defined in order to receive any | |
168e428f PH |
23493 | messages over an SMTP connection. For an example, see the ACL in the default |
23494 | configuration file. | |
23495 | ||
23496 | ||
23497 | ||
23498 | ||
9b371988 PH |
23499 | .section "Data for message ACLs" |
23500 | .cindex "&ACL;" "data for message ACL" | |
23501 | .cindex &$domain$& | |
23502 | .cindex &$local_part$& | |
23503 | .cindex &$sender_address$& | |
23504 | .cindex &$sender_host_address$& | |
23505 | .cindex &$smtp_command$& | |
068aaea8 PH |
23506 | When a MAIL or RCPT ACL, or either of the DATA ACLs, is running, the variables |
23507 | that contain information about the host and the message's sender (for example, | |
9b371988 PH |
23508 | &$sender_host_address$& and &$sender_address$&) are set, and can be used in ACL |
23509 | statements. In the case of RCPT (but not MAIL or DATA), &$domain$& and | |
23510 | &$local_part$& are set from the argument address. &new("The entire SMTP command | |
23511 | is available in &$smtp_command$&.") | |
168e428f PH |
23512 | |
23513 | When an ACL for the AUTH parameter of MAIL is running, the variables that | |
9b371988 PH |
23514 | contain information about the host are set, but &$sender_address$& is not yet |
23515 | set. Section &<<SECTauthparamail>>& contains a discussion of this parameter and | |
168e428f PH |
23516 | how it is used. |
23517 | ||
9b371988 PH |
23518 | .cindex "&$message_size$&" |
23519 | The &$message_size$& variable is set to the value of the SIZE parameter on | |
168e428f PH |
23520 | the MAIL command at MAIL, RCPT and pre-data time, or to -1 if |
23521 | that parameter is not given. The value is updated to the true message size by | |
23522 | the time the final DATA ACL is run (after the message data has been | |
23523 | received). | |
23524 | ||
9b371988 PH |
23525 | .cindex "&$rcpt_count$&" |
23526 | .cindex "&$recipients_count$&" | |
23527 | The &$rcpt_count$& variable increases by one for each RCPT command received. | |
23528 | The &$recipients_count$& variable increases by one each time a RCPT command is | |
068aaea8 PH |
23529 | accepted, so while an ACL for RCPT is being processed, it contains the number |
23530 | of previously accepted recipients. At DATA time (for both the DATA ACLs), | |
9b371988 PH |
23531 | &$rcpt_count$& contains the total number of RCPT commands, and |
23532 | &$recipients_count$& contains the total number of accepted recipients. | |
168e428f PH |
23533 | |
23534 | ||
23535 | ||
23536 | ||
23537 | ||
9b371988 PH |
23538 | .section "Data for non-message ACLs" "SECTdatfornon" |
23539 | .cindex "&ACL;" "data for non-message ACL" | |
23540 | .cindex &$smtp_command_argument$& | |
23541 | .cindex &$smtp_command$& | |
168e428f | 23542 | When an ACL is being run for AUTH, EHLO, ETRN, EXPN, HELO, STARTTLS, or VRFY, |
9b371988 PH |
23543 | the remainder of the SMTP command line is placed in &$smtp_command_argument$&, |
23544 | &new("and the entire SMTP command is available in &$smtp_command$&.") | |
23545 | These variables can be tested using a &%condition%& condition. For example, | |
23546 | here is an ACL for use with AUTH, which insists that either the session is | |
23547 | encrypted, or the CRAM-MD5 authentication method is used. In other words, it | |
23548 | does not permit authentication methods that use cleartext passwords on | |
23549 | unencrypted connections. | |
23550 | .code | |
168e428f PH |
23551 | acl_check_auth: |
23552 | accept encrypted = * | |
23553 | accept condition = ${if eq{${uc:$smtp_command_argument}}\ | |
23554 | {CRAM-MD5}} | |
23555 | deny message = TLS encryption or CRAM-MD5 required | |
9b371988 | 23556 | .endd |
168e428f PH |
23557 | (Another way of applying this restriction is to arrange for the authenticators |
23558 | that use cleartext passwords not to be advertised when the connection is not | |
9b371988 | 23559 | encrypted. You can use the generic &%server_advertise_condition%& authenticator |
168e428f PH |
23560 | option to do this.) |
23561 | ||
23562 | ||
23563 | ||
9b371988 PH |
23564 | .section "Format of an ACL" |
23565 | .cindex "&ACL;" "format of" | |
23566 | .cindex "&ACL;" "verbs; definition of" | |
168e428f | 23567 | An individual ACL consists of a number of statements. Each statement starts |
9b371988 | 23568 | with a verb, optionally followed by a number of conditions and &"modifiers"&. |
168e428f PH |
23569 | Modifiers can change the way the verb operates, define error and log messages, |
23570 | set variables, insert delays, and vary the processing of accepted messages. | |
23571 | ||
23572 | If all the conditions are met, the verb is obeyed. The same condition may be | |
23573 | used (with different arguments) more than once in the same statement. This | |
9b371988 | 23574 | provides a means of specifying an &"and"& conjunction between conditions. For |
168e428f | 23575 | example: |
9b371988 PH |
23576 | .code |
23577 | deny dnslists = list1.example | |
23578 | dnslists = list2.example | |
23579 | .endd | |
168e428f PH |
23580 | If there are no conditions, the verb is always obeyed. Exim stops evaluating |
23581 | the conditions and modifiers when it reaches a condition that fails. What | |
23582 | happens then depends on the verb (and in one case, on a special modifier). Not | |
23583 | all the conditions make sense at every testing point. For example, you cannot | |
23584 | test a sender address in the ACL that is run for a VRFY command. | |
23585 | ||
23586 | ||
9b371988 | 23587 | .section "ACL verbs" |
168e428f PH |
23588 | The ACL verbs are as follows: |
23589 | ||
9b371988 PH |
23590 | .ilist |
23591 | .cindex "&%accept%&" "ACL verb" | |
23592 | &%accept%&: If all the conditions are met, the ACL returns &"accept"&. If any | |
23593 | of the conditions are not met, what happens depends on whether &%endpass%& | |
23594 | appears among the conditions (for syntax see below). If the failing condition | |
23595 | is before &%endpass%&, control is passed to the next ACL statement; if it is | |
23596 | after &%endpass%&, the ACL returns &"deny"&. Consider this statement, used to | |
23597 | check a RCPT command: | |
23598 | .code | |
23599 | accept domains = +local_domains | |
23600 | endpass | |
23601 | verify = recipient | |
23602 | .endd | |
23603 | If the recipient domain does not match the &%domains%& condition, control | |
23604 | passes to the next statement. If it does match, the recipient is verified, and | |
23605 | the command is accepted if verification succeeds. However, if verification | |
23606 | fails, the ACL yields &"deny"&, because the failing condition is after | |
23607 | &%endpass%&. | |
23608 | ||
23609 | .next | |
23610 | .cindex "&%defer%&" "ACL verb" | |
23611 | &%defer%&: If all the conditions are met, the ACL returns &"defer"& which, in | |
23612 | an SMTP session, causes a 4&'xx'& response to be given. For a non-SMTP ACL, | |
23613 | &%defer%& is the same as &%deny%&, because there is no way of sending a | |
23614 | temporary error. For a RCPT command, &%defer%& is much the same as using a | |
23615 | &(redirect)& router and &`:defer:`& while verifying, but the &%defer%& verb can | |
168e428f | 23616 | be used in any ACL, and even for a recipient it might be a simpler approach. |
9b371988 PH |
23617 | .next |
23618 | .cindex "&%deny%&" "ACL verb" | |
23619 | &%deny%&: If all the conditions are met, the ACL returns &"deny"&. If any of | |
23620 | the conditions are not met, control is passed to the next ACL statement. For | |
168e428f | 23621 | example, |
9b371988 PH |
23622 | .code |
23623 | deny dnslists = blackholes.mail-abuse.org | |
23624 | .endd | |
168e428f PH |
23625 | rejects commands from hosts that are on a DNS black list. |
23626 | ||
9b371988 PH |
23627 | .next |
23628 | .cindex "&%discard%&" "ACL verb" | |
23629 | &%discard%&: This verb behaves like &%accept%&, except that it returns | |
23630 | &"discard"& from the ACL instead of &"accept"&. It is permitted only on ACLs | |
23631 | that are concerned with receiving messages, and it causes recipients to be | |
23632 | discarded. If the &%log_message%& modifier is set when &%discard%& operates, | |
23633 | its contents are added to the line that is automatically written to the log. | |
23634 | ||
23635 | If &%discard%& is used in an ACL for RCPT, just the one recipient is | |
168e428f PH |
23636 | discarded; if used for MAIL, DATA or in the non-SMTP ACL, all the |
23637 | message's recipients are discarded. Recipients that are discarded before | |
9b371988 | 23638 | DATA do not appear in the log line when the &%log_recipients%& log selector |
168e428f | 23639 | is set. |
9b371988 PH |
23640 | .next |
23641 | .cindex "&%drop%&" "ACL verb" | |
23642 | &%drop%&: This verb behaves like &%deny%&, except that an SMTP connection is | |
23643 | forcibly closed after the 5&'xx'& error message has been sent. For example: | |
23644 | .code | |
23645 | drop message = I don't take more than 20 RCPTs | |
23646 | condition = ${if > {$rcpt_count}{20}} | |
23647 | .endd | |
23648 | There is no difference between &%deny%& and &%drop%& for the connect-time ACL. | |
23649 | The connection is always dropped after sending a 550 response. | |
23650 | ||
23651 | .next | |
23652 | .cindex "&%require%&" "ACL verb" | |
23653 | &%require%&: If all the conditions are met, control is passed to the next ACL | |
23654 | statement. If any of the conditions are not met, the ACL returns &"deny"&. For | |
168e428f | 23655 | example, when checking a RCPT command, |
9b371988 PH |
23656 | .code |
23657 | require verify = sender | |
23658 | .endd | |
168e428f PH |
23659 | passes control to subsequent statements only if the message's sender can be |
23660 | verified. Otherwise, it rejects the command. | |
23661 | ||
9b371988 PH |
23662 | .next |
23663 | .cindex "&%warn%&" "ACL verb" | |
23664 | &%warn%&: If all the conditions are met, a header line is added to an incoming | |
168e428f PH |
23665 | message and/or a line is written to Exim's main log. In all cases, control |
23666 | passes to the next ACL statement. The text of the added header line and the log | |
9b371988 PH |
23667 | line are specified by modifiers; if they are not present, a &%warn%& verb just |
23668 | checks its conditions and obeys any &"immediate"& modifiers such as &%set%& and | |
23669 | &%logwrite%&. There is more about adding header lines in section | |
23670 | &<<SECTaddheadwarn>>&. | |
23671 | ||
23672 | If any condition on a &%warn%& statement cannot be completed (that is, there is | |
168e428f | 23673 | some sort of defer), no header lines are added and the configured log line is |
9b371988 | 23674 | not written. No further conditions or modifiers in the &%warn%& statement are |
168e428f PH |
23675 | processed. The incident is logged, but the ACL continues to be processed, from |
23676 | the next statement onwards. | |
9b371988 PH |
23677 | |
23678 | If a &%message%& modifier is present on a &%warn%& verb in an ACL that is not | |
168e428f | 23679 | testing an incoming message, it is ignored, and the incident is logged. |
9b371988 PH |
23680 | |
23681 | A &%warn%& statement may use the &%log_message%& modifier to cause a line to be | |
168e428f PH |
23682 | written to the main log when the statement's conditions are true. |
23683 | If an identical log line is requested several times in the same message, only | |
23684 | one copy is actually written to the log. If you want to force duplicates to be | |
9b371988 | 23685 | written, use the &%logwrite%& modifier instead. |
168e428f | 23686 | |
9b371988 PH |
23687 | .cindex "&$acl_verify_message$&" |
23688 | When one of the &%warn%& conditions is an address verification that fails, the | |
23689 | text of the verification failure message is in &$acl_verify_message$&. If you | |
23690 | want this logged, you must set it up explicitly. For example: | |
23691 | .code | |
23692 | warn !verify = sender | |
23693 | log_message = sender verify failed: $acl_verify_message | |
23694 | .endd | |
23695 | .endlist | |
168e428f | 23696 | |
9b371988 | 23697 | At the end of each ACL there is an implicit unconditional &%deny%&. |
168e428f PH |
23698 | |
23699 | As you can see from the examples above, the conditions and modifiers are | |
23700 | written one to a line, with the first one on the same line as the verb, and | |
23701 | subsequent ones on following lines. If you have a very long condition, you can | |
23702 | continue it onto several physical lines by the usual backslash continuation | |
23703 | mechanism. It is conventional to align the conditions vertically. | |
23704 | ||
23705 | ||
23706 | ||
9b371988 PH |
23707 | .section "ACL variables" "SECTaclvariables" |
23708 | .cindex "&ACL;" "variables" | |
168e428f PH |
23709 | There are some special variables that can be set during ACL processing. They |
23710 | can be used to pass information between different ACLs, different invocations | |
23711 | of the same ACL in the same SMTP connection, and between ACLs and the routers, | |
23712 | transports, and filters that are used to deliver a message. There are two sets | |
23713 | of these variables: | |
23714 | ||
9b371988 PH |
23715 | .ilist |
23716 | The values of &$acl_c0$& to &$acl_c9$& persist throughout an SMTP connection. | |
168e428f PH |
23717 | They are never reset. Thus, a value that is set while receiving one message is |
23718 | still available when receiving the next message on the same SMTP connection. | |
9b371988 PH |
23719 | .next |
23720 | The values of &$acl_m0$& to &$acl_m9$& persist only while a message is being | |
168e428f PH |
23721 | received. They are reset afterwards. They are also reset by MAIL, RSET, |
23722 | EHLO, HELO, and after starting up a TLS session. | |
9b371988 | 23723 | .endlist |
168e428f PH |
23724 | |
23725 | When a message is accepted, the current values of all the ACL variables are | |
23726 | preserved with the message and are subsequently made available at delivery | |
9b371988 PH |
23727 | time. The ACL variables are set by modifier called &%set%&. For example: |
23728 | .code | |
23729 | accept hosts = whatever | |
23730 | set acl_m4 = some value | |
23731 | .endd | |
23732 | &*Note*&: A leading dollar sign is not used when naming a variable that is to | |
168e428f | 23733 | be set. If you want to set a variable without taking any action, you can use a |
9b371988 | 23734 | &%warn%& verb without any other modifiers or conditions. |
168e428f PH |
23735 | |
23736 | ||
23737 | ||
9b371988 PH |
23738 | .section "Condition and modifier processing" |
23739 | .cindex "&ACL;" "conditions; processing" | |
23740 | .cindex "&ACL;" "modifiers; processing" | |
068aaea8 | 23741 | An exclamation mark preceding a condition negates its result. For example: |
9b371988 PH |
23742 | .code |
23743 | deny domains = *.dom.example | |
23744 | !verify = recipient | |
23745 | .endd | |
23746 | .new | |
23747 | causes the ACL to return &"deny"& if the recipient domain ends in | |
23748 | &'dom.example'& and the recipient address cannot be verified. Sometimes | |
23749 | negation can be used on the right-hand side of a condition. For example, these | |
23750 | two statements are equivalent: | |
23751 | .code | |
068aaea8 PH |
23752 | deny hosts = !192.168.3.4 |
23753 | deny !hosts = 192.168.3.4 | |
9b371988 PH |
23754 | .endd |
23755 | However, for many conditions (&%verify%& being a good example), only left-hand | |
068aaea8 | 23756 | side negation of the whole condition is possible. |
9b371988 | 23757 | .wen |
168e428f PH |
23758 | |
23759 | The arguments of conditions and modifiers are expanded. A forced failure | |
23760 | of an expansion causes a condition to be ignored, that is, it behaves as if the | |
23761 | condition is true. Consider these two statements: | |
9b371988 | 23762 | .code |
168e428f PH |
23763 | accept senders = ${lookup{$host_name}lsearch\ |
23764 | {/some/file}{$value}fail} | |
23765 | accept senders = ${lookup{$host_name}lsearch\ | |
23766 | {/some/file}{$value}{}} | |
9b371988 | 23767 | .endd |
168e428f PH |
23768 | Each attempts to look up a list of acceptable senders. If the lookup succeeds, |
23769 | the returned list is searched, but if the lookup fails the behaviour is | |
9b371988 PH |
23770 | different in the two cases. The &%fail%& in the first statement causes the |
23771 | condition to be ignored, leaving no further conditions. The &%accept%& verb | |
168e428f PH |
23772 | therefore succeeds. The second statement, however, generates an empty list when |
23773 | the lookup fails. No sender can match an empty list, so the condition fails, | |
9b371988 | 23774 | and therefore the &%accept%& also fails. |
168e428f PH |
23775 | |
23776 | ACL modifiers appear mixed in with conditions in ACL statements. Some of them | |
23777 | specify actions that are taken as the conditions for a statement are checked; | |
23778 | others specify text for messages that are used when access is denied or a | |
9b371988 | 23779 | warning is generated. The &%control%& modifier affects the way an incoming |
168e428f PH |
23780 | message is handled. |
23781 | ||
23782 | The positioning of the modifiers in an ACL statement important, because the | |
23783 | processing of a verb ceases as soon as its outcome is known. Only those | |
23784 | modifiers that have already been encountered will take effect. For example, | |
9b371988 PH |
23785 | consider this use of the &%message%& modifier: |
23786 | .code | |
23787 | require message = Can't verify sender | |
23788 | verify = sender | |
23789 | message = Can't verify recipient | |
23790 | verify = recipient | |
23791 | message = This message cannot be used | |
23792 | .endd | |
168e428f | 23793 | If sender verification fails, Exim knows that the result of the statement is |
9b371988 PH |
23794 | &"deny"&, so it goes no further. The first &%message%& modifier has been seen, |
23795 | so its text is used as the error message. If sender verification succeeds, but | |
168e428f | 23796 | recipient verification fails, the second message is used. If recipient |
9b371988 | 23797 | verification succeeds, the third message becomes &"current"&, but is never used |
168e428f PH |
23798 | because there are no more conditions to cause failure. |
23799 | ||
9b371988 | 23800 | For the &%deny%& verb, on the other hand, it is always the last &%message%& |
168e428f | 23801 | modifier that is used, because all the conditions must be true for rejection to |
9b371988 | 23802 | happen. Specifying more than one &%message%& modifier does not make sense, and |
168e428f | 23803 | the message can even be specified after all the conditions. For example: |
9b371988 PH |
23804 | .code |
23805 | deny hosts = ... | |
23806 | !senders = *@my.domain.example | |
23807 | message = Invalid sender from client host | |
23808 | .endd | |
23809 | The &"deny"& result does not happen until the end of the statement is reached, | |
168e428f PH |
23810 | by which time Exim has set up the message. |
23811 | ||
23812 | ||
23813 | ||
9b371988 PH |
23814 | .section "ACL modifiers" "SECTACLmodi" |
23815 | .cindex "&ACL;" "modifiers; list of" | |
168e428f PH |
23816 | The ACL modifiers are as follows: |
23817 | ||
9b371988 PH |
23818 | .vlist |
23819 | .vitem &*control*&&~=&~<&'text'&> | |
23820 | .cindex "&%control%&" "ACL modifier" | |
168e428f PH |
23821 | This modifier affects the subsequent processing of the SMTP connection or of an |
23822 | incoming message that is accepted. The effect of the first type of control | |
23823 | lasts for the duration of the connection, whereas the effect of the second type | |
23824 | lasts only until the current message has been received. The message-specific | |
23825 | controls always apply to the whole message, not to individual recipients, | |
9b371988 PH |
23826 | even if the &%control%& modifier appears in a RCPT ACL. |
23827 | ||
168e428f | 23828 | As there are now quite a few controls that can be applied, they are described |
9b371988 PH |
23829 | separately in section &<<SECTcontrols>>&. The &%control%& modifier can be used |
23830 | in several different ways. For example: | |
23831 | ||
23832 | . ==== As this is a nested list, any displays it contains must be indented | |
23833 | . ==== as otherwise they are too far to the left. | |
23834 | ||
23835 | .ilist | |
23836 | It can be at the end of an &%accept%& statement: | |
23837 | .code | |
23838 | accept ...some conditions | |
23839 | control = queue_only | |
23840 | .endd | |
23841 | In this case, the control is applied when this statement yields &"accept"&, in | |
168e428f PH |
23842 | other words, when the conditions are all true. |
23843 | ||
9b371988 PH |
23844 | .next |
23845 | It can be in the middle of an &%accept%& statement: | |
23846 | .code | |
23847 | accept ...some conditions... | |
23848 | control = queue_only | |
23849 | ...some more conditions... | |
23850 | .endd | |
168e428f PH |
23851 | If the first set of conditions are true, the control is applied, even if the |
23852 | statement does not accept because one of the second set of conditions is false. | |
9b371988 PH |
23853 | In this case, some subsequent statement must yield &"accept"& for the control |
23854 | to be relevant. | |
168e428f | 23855 | |
9b371988 PH |
23856 | .next |
23857 | It can be used with &%warn%& to apply the control, leaving the | |
168e428f PH |
23858 | decision about accepting or denying to a subsequent verb. For |
23859 | example: | |
9b371988 PH |
23860 | .code |
23861 | warn ...some conditions... | |
23862 | control = freeze | |
23863 | accept ... | |
23864 | .endd | |
23865 | This example of &%warn%& does not contain &%message%&, &%log_message%&, or | |
23866 | &%logwrite%&, so it does not add anything to the message and does not write a | |
23867 | log entry. | |
23868 | ||
23869 | .next | |
23870 | If you want to apply a control unconditionally, you can use it with a | |
23871 | &%require%& verb. For example: | |
23872 | .code | |
23873 | require control = no_multiline_response | |
23874 | .endd | |
23875 | .endlist | |
23876 | ||
23877 | .vitem &*delay*&&~=&~<&'time'&> | |
23878 | .cindex "&%delay%&" "ACL modifier" | |
23879 | .cindex "&%-bh%& option" | |
168e428f PH |
23880 | This modifier causes Exim to wait for the time interval before proceeding. The |
23881 | time is given in the usual Exim notation. This modifier may appear in any ACL. | |
23882 | The delay happens as soon as the modifier is processed. However, when testing | |
9b371988 PH |
23883 | Exim using the &%-bh%& option, the delay is not actually imposed (an |
23884 | appropriate message is output instead). | |
23885 | ||
23886 | Like &%control%&, &%delay%& can be used with &%accept%& or &%deny%&, for | |
23887 | example: | |
23888 | .code | |
23889 | deny ...some conditions... | |
23890 | delay = 30s | |
23891 | .endd | |
168e428f | 23892 | The delay happens if all the conditions are true, before the statement returns |
9b371988 PH |
23893 | &"deny"&. Compare this with: |
23894 | .code | |
23895 | deny delay = 30s | |
23896 | ...some conditions... | |
23897 | .endd | |
23898 | which waits for 30s before processing the conditions. The &%delay%& modifier | |
23899 | can also be used with &%warn%& and together with &%control%&: | |
23900 | .code | |
23901 | warn ...some conditions... | |
23902 | delay = 2m | |
23903 | control = freeze | |
23904 | accept ... | |
23905 | .endd | |
23906 | ||
23907 | .vitem &*endpass*& | |
23908 | .cindex "&%endpass%&" "ACL modifier" | |
23909 | This modifier, which has no argument, is recognized only in &%accept%& | |
168e428f PH |
23910 | statements. It marks the boundary between the conditions whose failure causes |
23911 | control to pass to the next statement, and the conditions whose failure causes | |
9b371988 | 23912 | the ACL to return &"deny"&. See the description of &%accept%& above. |
168e428f | 23913 | |
9b371988 PH |
23914 | .vitem &*log_message*&&~=&~<&'text'&> |
23915 | .cindex "&%log_message%&" "ACL modifier" | |
168e428f | 23916 | This modifier sets up a message that is used as part of the log message if the |
9b371988 PH |
23917 | ACL denies access or a &%warn%& statement's conditions are true. For example: |
23918 | .code | |
23919 | require log_message = wrong cipher suite $tls_cipher | |
23920 | encrypted = DES-CBC3-SHA | |
23921 | .endd | |
23922 | &%log_message%& adds to any underlying error message that may exist because of | |
168e428f | 23923 | the condition failure. For example, while verifying a recipient address, a |
9b371988 PH |
23924 | &':fail:'& redirection might have already set up a message. Although the |
23925 | message is usually defined before the conditions to which it applies, the | |
23926 | expansion does not happen until Exim decides that access is to be denied. This | |
23927 | means that any variables that are set by the condition are available for | |
23928 | inclusion in the message. For example, the &$dnslist_$&<&'xxx'&> variables are | |
23929 | set after a DNS black list lookup succeeds. If the expansion of &%log_message%& | |
23930 | fails, or if the result is an empty string, the modifier is ignored. | |
23931 | ||
23932 | .cindex "&$acl_verify_message$&" | |
23933 | If you want to use a &%warn%& statement to log the result of an address | |
23934 | verification, you can use &$acl_verify_message$& to include the verification | |
168e428f | 23935 | error message. |
9b371988 PH |
23936 | |
23937 | If &%log_message%& is used with a &%warn%& statement, &"Warning:"& is added to | |
23938 | the start of the logged message. If the same warning log message is requested | |
23939 | more than once while receiving a single email message, only one copy is | |
23940 | actually logged. If you want to log multiple copies, use &%logwrite%& instead | |
23941 | of &%log_message%&. In the absence of &%log_message%& and &%logwrite%&, nothing | |
23942 | is logged for a succesful &%warn%& statement. | |
23943 | ||
23944 | If &%log_message%& is not present and there is no underlying error message (for | |
23945 | example, from the failure of address verification), but &%message%& is present, | |
23946 | the &%message%& text is used for logging rejections. However, if any text for | |
168e428f | 23947 | logging contains newlines, only the first line is logged. In the absence of |
9b371988 | 23948 | both &%log_message%& and &%message%&, a default built-in message is used for |
168e428f PH |
23949 | logging rejections. |
23950 | ||
9b371988 PH |
23951 | .vitem &*logwrite*&&~=&~<&'text'&> |
23952 | .cindex "&%logwrite%&" "ACL modifier" | |
23953 | .cindex "logging in ACL" "immediate" | |
168e428f | 23954 | This modifier writes a message to a log file as soon as it is encountered when |
9b371988 PH |
23955 | processing an ACL. (Compare &%log_message%&, which, except in the case of |
23956 | &%warn%&, is used only if the ACL statement denies access.) The &%logwrite%& | |
168e428f | 23957 | modifier can be used to log special incidents in ACLs. For example: |
9b371988 PH |
23958 | .display |
23959 | &`accept `&<&'some special conditions'&> | |
23960 | &` control = freeze`& | |
23961 | &` logwrite = froze message because ...`& | |
23962 | .endd | |
168e428f PH |
23963 | By default, the message is written to the main log. However, it may begin |
23964 | with a colon, followed by a comma-separated list of log names, and then | |
23965 | another colon, to specify exactly which logs are to be written. For | |
23966 | example: | |
9b371988 PH |
23967 | .code |
23968 | logwrite = :main,reject: text for main and reject logs | |
23969 | logwrite = :panic: text for panic log only | |
23970 | .endd | |
168e428f | 23971 | |
9b371988 PH |
23972 | .vitem &*message*&&~=&~<&'text'&> |
23973 | .cindex "&%message%&" "ACL modifier" | |
168e428f PH |
23974 | This modifier sets up a text string that is expanded and used as an error |
23975 | message if the current statement causes the ACL to deny access. The expansion | |
23976 | happens at the time Exim decides that access is to be denied, not at the time | |
9b371988 | 23977 | it processes &%message%&. If the expansion fails, or generates an empty string, |
168e428f PH |
23978 | the modifier is ignored. For ACLs that are triggered by SMTP commands, the |
23979 | message is returned as part of the SMTP error response. | |
9b371988 PH |
23980 | |
23981 | The &%message%& modifier is also used with the &%warn%& verb to specify one or | |
23982 | more header lines to be added to an incoming message when all the conditions | |
23983 | are true. See section &<<SECTaddheadwarn>>& for more details. If &%message%& is | |
23984 | used with &%warn%& in an ACL that is not concerned with receiving a message, it | |
23985 | has no effect. | |
23986 | ||
168e428f PH |
23987 | The text is literal; any quotes are taken as literals, but because the string |
23988 | is expanded, backslash escapes are processed anyway. If the message contains | |
9b371988 PH |
23989 | newlines, this gives rise to a multi-line SMTP response. Like &%log_message%&, |
23990 | the contents of &%message%& are not expanded until after a condition has | |
23991 | failed. | |
23992 | ||
23993 | .cindex "&$acl_verify_message$&" | |
23994 | If &%message%& is used on a statement that verifies an address, the message | |
168e428f PH |
23995 | specified overrides any message that is generated by the verification process. |
23996 | However, the original message is available in the variable | |
9b371988 PH |
23997 | &$acl_verify_message$&, so you can incorporate it into your message if you |
23998 | wish. In particular, if you want the text from &%:fail:%& items in &(redirect)& | |
23999 | routers to be passed back as part of the SMTP response, you should either not | |
24000 | use a &%message%& modifier, or make use of &$acl_verify_message$&. | |
168e428f | 24001 | |
9b371988 PH |
24002 | .vitem &*set*&&~<&'acl_name'&>&~=&~<&'value'&> |
24003 | .cindex "&%set%&" "ACL modifier" | |
168e428f | 24004 | This modifier puts a value into one of the ACL variables (see section |
9b371988 PH |
24005 | &<<SECTaclvariables>>&). |
24006 | .endlist | |
168e428f PH |
24007 | |
24008 | ||
24009 | ||
9b371988 PH |
24010 | .section "Use of the control modifier" "SECTcontrols" |
24011 | .cindex "&%control%&" "ACL modifier" | |
24012 | The &%control%& modifier supports the following settings: | |
168e428f | 24013 | |
9b371988 PH |
24014 | .vlist |
24015 | .vitem &*control&~=&~caseful_local_part*& | |
168e428f PH |
24016 | See below. |
24017 | ||
9b371988 PH |
24018 | .vitem &*control&~=&~caselower_local_part*& |
24019 | .cindex "&ACL;" "case of local part in" | |
24020 | .cindex "case of local parts" | |
24021 | .cindex "&$local_part$&" | |
24022 | These two controls are permitted only in the ACL specified by &%acl_smtp_rcpt%& | |
24023 | (that is, during RCPT processing). By default, the contents of &$local_part$& | |
24024 | are lower cased before ACL processing. If &"caseful_local_part"& is specified, | |
24025 | any uppercase letters in the original local part are restored in &$local_part$& | |
24026 | for the rest of the ACL, or until a control that sets &"caselower_local_part"& | |
24027 | is encountered. | |
24028 | ||
168e428f PH |
24029 | These controls affect only the current recipient. Moreover, they apply only to |
24030 | local part handling that takes place directly in the ACL (for example, as a key | |
24031 | in lookups). If a test to verify the recipient is obeyed, the case-related | |
24032 | handling of the local part during the verification is controlled by the router | |
9b371988 PH |
24033 | configuration (see the &%caseful_local_part%& generic router option). |
24034 | ||
168e428f | 24035 | This facility could be used, for example, to add a spam score to local parts |
9b371988 | 24036 | containing upper case letters. For example, using &$acl_m4$& to accumulate the |
168e428f | 24037 | spam score: |
9b371988 | 24038 | .code |
168e428f PH |
24039 | warn control = caseful_local_part |
24040 | set acl_m4 = ${eval:\ | |
24041 | $acl_m4 + \ | |
24042 | ${if match{$local_part}{[A-Z]}{1}{0}}\ | |
24043 | } | |
24044 | control = caselower_local_part | |
9b371988 | 24045 | .endd |
168e428f PH |
24046 | Notice that we put back the lower cased version afterwards, assuming that |
24047 | is what is wanted for subsequent tests. | |
24048 | ||
9b371988 | 24049 | .vitem &*control&~=&~enforce_sync*& |
168e428f PH |
24050 | See below. |
24051 | ||
9b371988 PH |
24052 | .vitem &*control&~=&~no_enforce_sync*& |
24053 | .cindex "SMTP" "synchronization checking" | |
24054 | .cindex "synchronization checking in SMTP" | |
168e428f | 24055 | These controls make it possible to be selective about when SMTP synchronization |
9b371988 | 24056 | is enforced. The global option &%smtp_enforce_sync%& specifies the initial |
168e428f | 24057 | state of the switch (it is true by default). See the description of this option |
9b371988 PH |
24058 | in chapter &<<CHAPmainconfig>>& for details of SMTP synchronization checking. |
24059 | ||
168e428f PH |
24060 | The effect of these two controls lasts for the remainder of the SMTP |
24061 | connection. They can appear in any ACL except the one for the non-SMTP | |
24062 | messages. The most straightforward place to put them is in the ACL defined by | |
9b371988 | 24063 | &%acl_smtp_connect%&, which is run at the start of an incoming SMTP connection, |
168e428f PH |
24064 | before the first synchronization check. The expected use is to turn off the |
24065 | synchronization checks for badly-behaved hosts that you nevertheless need to | |
24066 | work with. | |
24067 | ||
068aaea8 | 24068 | |
9b371988 PH |
24069 | .new |
24070 | .vitem &*control&~=&~fakedefer/*&<&'message'&> | |
24071 | .cindex "fake defer" | |
24072 | .cindex "defer" "fake" | |
24073 | This control works in exactly the same way as &%fakereject%& (described below) | |
068aaea8 | 24074 | except that it causes an SMTP 450 response after the message data instead of a |
9b371988 | 24075 | 550 response. You must take care when using &%fakedefer%& because it causes the |
068aaea8 | 24076 | messages to be duplicated when the sender retries. Therefore, you should not |
9b371988 PH |
24077 | use &%fakedefer%& if the message is to be delivered normally. |
24078 | .wen | |
068aaea8 | 24079 | |
9b371988 PH |
24080 | .vitem &*control&~=&~fakereject/*&<&'message'&> |
24081 | .cindex "fake rejection" | |
24082 | .cindex "rejection" "fake" | |
168e428f PH |
24083 | This control is permitted only for the MAIL, RCPT, and DATA ACLs, in other |
24084 | words, only when an SMTP message is being received. If Exim accepts the | |
24085 | message, instead the final 250 response, a 550 rejection message is sent. | |
24086 | However, Exim proceeds to deliver the message as normal. The control applies | |
24087 | only to the current message, not to any subsequent ones that may be received in | |
24088 | the same SMTP connection. | |
168e428f | 24089 | |
9b371988 PH |
24090 | The text for the 550 response is taken from the &%control%& modifier. If no |
24091 | message is supplied, the following is used: | |
24092 | .code | |
24093 | 550-Your message has been rejected but is being | |
24094 | 550-kept for evaluation. | |
24095 | 550-If it was a legitimate message, it may still be | |
24096 | 550 delivered to the target recipient(s). | |
24097 | .endd | |
168e428f PH |
24098 | This facilty should be used with extreme caution. |
24099 | ||
9b371988 PH |
24100 | .vitem &*control&~=&~freeze*& |
24101 | .cindex "frozen messages" "forcing in ACL" | |
168e428f PH |
24102 | This control is permitted only for the MAIL, RCPT, DATA, and non-SMTP ACLs, in |
24103 | other words, only when a message is being received. If the message is accepted, | |
24104 | it is placed on Exim's queue and frozen. The control applies only to the | |
24105 | current message, not to any subsequent ones that may be received in the same | |
24106 | SMTP connection. | |
24107 | ||
9b371988 | 24108 | .vitem &*control&~=&~no_mbox_unspool*& |
168e428f PH |
24109 | This control is available when Exim is compiled with the content scanning |
24110 | extension. Content scanning may require a copy of the current message, or parts | |
9b371988 | 24111 | of it, to be written in &"mbox format"& to a spool file, for passing to a virus |
168e428f PH |
24112 | or spam scanner. Normally, such copies are deleted when they are no longer |
24113 | needed. If this control is set, the copies are not deleted. The control applies | |
24114 | only to the current message, not to any subsequent ones that may be received in | |
24115 | the same SMTP connection. It is provided for debugging purposes and is unlikely | |
24116 | to be useful in production. | |
24117 | ||
9b371988 PH |
24118 | .vitem &*control&~=&~no_multiline_response*& |
24119 | .cindex "multiline responses" "suppressing" | |
168e428f PH |
24120 | This control is permitted for any ACL except the one for non-SMTP messages. |
24121 | It seems that there are broken clients in use that cannot handle multiline | |
24122 | SMTP responses, despite the fact that RFC 821 defined them over 20 years ago. | |
9b371988 | 24123 | |
168e428f PH |
24124 | If this control is set, multiline SMTP responses from ACL rejections are |
24125 | suppressed. One way of doing this would have been to put out these responses as | |
24126 | one long line. However, RFC 2821 specifies a maximum of 512 bytes per response | |
9b371988 PH |
24127 | (&"use multiline responses for more"& it says &-- ha!), and some of the |
24128 | responses might get close to that. So this facility, which is after all only a | |
24129 | sop to broken clients, is implemented by doing two very easy things: | |
24130 | ||
24131 | .ilist | |
24132 | Extra information that is normally output as part of a rejection caused by | |
24133 | sender verification failure is omitted. Only the final line (typically &"sender | |
24134 | verification failed"&) is sent. | |
24135 | .next | |
24136 | If a &%message%& modifier supplies a multiline response, only the first | |
168e428f | 24137 | line is output. |
9b371988 PH |
24138 | .endlist |
24139 | ||
168e428f PH |
24140 | The setting of the switch can, of course, be made conditional on the |
24141 | calling host. Its effect lasts until the end of the SMTP connection. | |
24142 | ||
9b371988 PH |
24143 | .vitem &*control&~=&~queue_only*& |
24144 | .cindex "&%queue_only%&" | |
24145 | .cindex "queueing incoming messages" | |
168e428f PH |
24146 | This control is permitted only for the MAIL, RCPT, DATA, and non-SMTP ACLs, in |
24147 | other words, only when a message is being received. If the message is accepted, | |
24148 | it is placed on Exim's queue and left there for delivery by a subsequent queue | |
24149 | runner. No immediate delivery process is started. In other words, it has the | |
9b371988 PH |
24150 | effect as the &%queue_only%& global option. However, the control applies only |
24151 | to the current message, not to any subsequent ones that may be received in the | |
168e428f PH |
24152 | same SMTP connection. |
24153 | ||
9b371988 PH |
24154 | .vitem &*control&~=&~submission/*&<&'options'&> |
24155 | .cindex "message" "submission" | |
24156 | .cindex "submission mode" | |
168e428f | 24157 | This control is permitted only for the MAIL, RCPT, and start of data ACLs (the |
9b371988 | 24158 | latter is the one defined by &%acl_smtp_predata%&). Setting it tells Exim that |
168e428f | 24159 | the current message is a submission from a local MUA. In this case, Exim |
9b371988 PH |
24160 | operates in &"submission mode"&, and applies certain fixups to the message if |
24161 | necessary. For example, it add a &'Date:'& header line if one is not present. | |
24162 | This control is not permitted in the &%acl_smtp_data%& ACL, because that is too | |
168e428f | 24163 | late (the message has already been created). |
168e428f | 24164 | |
9b371988 PH |
24165 | Chapter &<<CHAPmsgproc>>& describes the processing that Exim applies to |
24166 | messages. Section &<<SECTsubmodnon>>& covers the processing that happens in | |
24167 | submission mode; the available options for this control are described there. | |
24168 | The control applies only to the current message, not to any subsequent ones | |
24169 | that may be received in the same SMTP connection. | |
24170 | ||
24171 | .new | |
24172 | .vitem &*control&~=&~suppress_local_fixups*& | |
24173 | .cindex "submission fixups" "suppressing" | |
068aaea8 | 24174 | This control applies to locally submitted (non TCP/IP) messages, and is the |
9b371988 PH |
24175 | complement of &`control`& &`=`& &`submission`&. It disables the fixups that are |
24176 | normally applied to locally-submitted messages. Specifically: | |
24177 | ||
24178 | .ilist | |
24179 | Any &'Sender:'& header line is left alone (in this respect, it is a | |
24180 | dynamic version of &%local_sender_retain%&). | |
24181 | .next | |
24182 | No &'Message-ID:'&, &'From:'&, or &'Date:'& header lines are added. | |
24183 | .next | |
24184 | There is no check that &'From:'& corresponds to the actual sender. | |
24185 | .endlist ilist | |
24186 | ||
068aaea8 PH |
24187 | This feature may be useful when a remotely-originated message is accepted, |
24188 | passed to some scanning program, and then re-submitted for delivery. | |
9b371988 | 24189 | .endlist vlist |
068aaea8 | 24190 | |
068aaea8 PH |
24191 | All four possibilities for message fixups can be specified: |
24192 | ||
9b371988 PH |
24193 | .ilist |
24194 | Locally submitted, fixups applied: the default. | |
24195 | .next | |
24196 | Locally submitted, no fixups applied: use &`control`& &`=`& | |
24197 | &`suppress_local_fixups`&. | |
24198 | .next | |
24199 | Remotely submitted, no fixups applied: the default. | |
24200 | .next | |
24201 | Remotely submitted, fixups applied: use &`control`& &`=`& &`submission`&. | |
24202 | .endlist | |
24203 | .wen | |
24204 | ||
24205 | ||
24206 | ||
24207 | ||
24208 | .section "Adding header lines with the warn verb" "SECTaddheadwarn" | |
24209 | .cindex "header lines" "adding in an ACL" | |
24210 | .cindex "header lines" "position of added lines" | |
24211 | .cindex "&%warn%&" "ACL verb" | |
24212 | .cindex "&%message%&" "ACL modifier" | |
24213 | The &%message%& modifier can be used on a &%warn%& statement to add an extra | |
24214 | header line to an incoming message, as in this example: | |
24215 | .code | |
168e428f PH |
24216 | warn message = X-blacklisted-at: $dnslist_domain |
24217 | dnslists = sbl.spamhaus.org : \ | |
24218 | dialup.mail-abuse.org | |
9b371988 | 24219 | .endd |
168e428f PH |
24220 | If an identical header line is requested several times (provoked, for example, |
24221 | by multiple RCPT commands), only one copy is actually added to the message. | |
9b371988 | 24222 | If the text of the &%message%& modifier contains one or more newlines that are |
168e428f | 24223 | not followed by a space or a tab, it is assumed to contain multiple header |
9b371988 | 24224 | lines. Each one is checked for valid syntax; &`X-ACL-Warn:`& is added to the |
168e428f PH |
24225 | front of any line that is not a valid header line. |
24226 | ||
24227 | By default, new lines are added at the end of the existing header lines. | |
24228 | However, you can specify that any particular header line should be added right | |
9b371988 PH |
24229 | at the start (before all the &'Received:'& lines), immediately after the first |
24230 | block of &'Received:'& lines, or immediately before any line that is not a | |
24231 | &'Received:'& or &'Resent-something:'& header. | |
168e428f | 24232 | |
9b371988 PH |
24233 | This is done by specifying &":at_start:"&, &":after_received:"&, or |
24234 | &":at_start_rfc:"& (or, for completeness, &":at_end:"&) before the text of the | |
168e428f PH |
24235 | header line, respectively. (Header text cannot start with a colon, as there has |
24236 | to be a header name first.) For example: | |
9b371988 PH |
24237 | .code |
24238 | warn message = :after_received:X-My-Header: something or other... | |
24239 | .endd | |
168e428f PH |
24240 | If more than one header is supplied in a single warn statement, each one is |
24241 | treated independently and can therefore be placed differently. If you add | |
24242 | more than one line at the start, or after the Received: block, they will | |
24243 | end up in reverse order. | |
24244 | ||
9b371988 | 24245 | &*Warning*&: This facility currently applies only to header lines that are |
168e428f PH |
24246 | added in an ACL. It does NOT work for header lines that are added in a |
24247 | system filter or in a router or transport. | |
24248 | ||
9b371988 PH |
24249 | .new |
24250 | .cindex "header lines" "added; visibility of" | |
068aaea8 PH |
24251 | Header lines that are added by an ACL at MAIL or RCPT time are not visible in |
24252 | string expansions in ACLs for subsequent RCPT commands or in the | |
9b371988 PH |
24253 | &%acl_smtp_predata%& ACL. However, they are visible in string expansions in the |
24254 | ACL that is run after DATA is complete (the &%acl_smtp_data%& ACL). This is | |
24255 | also true for header lines that are added in the &%acl_smtp_predata%& ACL. | |
24256 | However, header lines that are added in the &%acl_smtp_data%& itself are not | |
24257 | visible during that ACL. If a message is rejected after DATA, all added header | |
24258 | lines are included in the entry that is written to the reject log. | |
24259 | .wen | |
168e428f PH |
24260 | |
24261 | If you want to preserve data between MAIL, RCPT, and the | |
9b371988 PH |
24262 | &%acl_smtp_predata%& ACLs, you can use ACL variables, as described in section |
24263 | &<<SECTaclvariables>>&. | |
168e428f PH |
24264 | |
24265 | ||
24266 | ||
24267 | ||
24268 | ||
9b371988 PH |
24269 | .section "ACL conditions" "SECTaclconditions" |
24270 | .cindex "&ACL;" "conditions; list of" | |
168e428f PH |
24271 | Some of conditions listed in this section are available only when Exim is |
24272 | compiled with the content-scanning extension. They are included here briefly | |
24273 | for completeness. More detailed descriptions can be found in the discussion on | |
9b371988 | 24274 | content scanning in chapter &<<CHAPexiscan>>&. |
168e428f PH |
24275 | |
24276 | Not all conditions are relevant in all circumstances. For example, testing | |
24277 | senders and recipients does not make sense in an ACL that is being run as the | |
24278 | result of the arrival of an ETRN command, and checks on message headers can be | |
9b371988 PH |
24279 | done only in the ACLs specified by &%acl_smtp_data%& and &%acl_not_smtp%&. You |
24280 | can use the same condition (with different parameters) more than once in the | |
24281 | same ACL statement. This provides a way of specifying an &"and"& conjunction. | |
24282 | The conditions are as follows: | |
24283 | ||
24284 | ||
24285 | .vlist | |
24286 | .vitem &*acl&~=&~*&<&'name&~of&~acl&~or&~ACL&~string&~or&~file&~name&~'&> | |
24287 | .cindex "&ACL;" "nested" | |
24288 | .cindex "&ACL;" "indirect" | |
24289 | .cindex "&%acl%&" "ACL condition" | |
24290 | The possible values of the argument are the same as for the | |
24291 | &%acl_smtp_%&&'xxx'& options. The named or inline ACL is run. If it returns | |
24292 | &"accept"& the condition is true; if it returns &"deny"& the condition is | |
24293 | false. If it returns &"defer"&, the current ACL returns &"defer"& unless the | |
24294 | condition is on a &%warn%& verb. In that case, a &"defer"& return makes the | |
24295 | condition false. This means that further processing of the &%warn%& verb | |
24296 | ceases, but processing of the ACL continues. | |
24297 | ||
24298 | If the nested &%acl%& returns &"drop"& and the outer condition denies access, | |
24299 | the connection is dropped. If it returns &"discard"&, the verb must be | |
24300 | &%accept%& or &%discard%&, and the action is taken immediately &-- no further | |
24301 | conditions are tested. | |
24302 | ||
168e428f PH |
24303 | ACLs may be nested up to 20 deep; the limit exists purely to catch runaway |
24304 | loops. This condition allows you to use different ACLs in different | |
24305 | circumstances. For example, different ACLs can be used to handle RCPT commands | |
24306 | for different local users or different local domains. | |
24307 | ||
9b371988 PH |
24308 | .vitem &*authenticated&~=&~*&<&'string&~list'&> |
24309 | .cindex "&%authenticated%&" "ACL condition" | |
24310 | .cindex "authentication" "ACL checking" | |
24311 | .cindex "&ACL;" "testing for authentication" | |
168e428f PH |
24312 | If the SMTP connection is not authenticated, the condition is false. Otherwise, |
24313 | the name of the authenticator is tested against the list. To test for | |
24314 | authentication by any authenticator, you can set | |
9b371988 PH |
24315 | .code |
24316 | authenticated = * | |
24317 | .endd | |
24318 | ||
24319 | .vitem &*condition&~=&~*&<&'string'&> | |
24320 | .cindex "&%condition%&" "ACL condition" | |
24321 | .cindex "customizing" "ACL condition" | |
24322 | .cindex "&ACL;" "customized test" | |
24323 | .cindex "&ACL;" "testing; customized" | |
168e428f PH |
24324 | This feature allows you to make up custom conditions. If the result of |
24325 | expanding the string is an empty string, the number zero, or one of the strings | |
9b371988 PH |
24326 | &"no"& or &"false"&, the condition is false. If the result is any non-zero |
24327 | number, or one of the strings &"yes"& or &"true"&, the condition is true. For | |
24328 | any other values, some error is assumed to have occurred, and the ACL returns | |
24329 | &"defer"&. | |
168e428f | 24330 | |
9b371988 PH |
24331 | .vitem &*decode&~=&~*&<&'location'&> |
24332 | .cindex "&%decode%&" "ACL condition" | |
168e428f PH |
24333 | This condition is available only when Exim is compiled with the |
24334 | content-scanning extension, and it is allowed only the the ACL defined by | |
9b371988 PH |
24335 | &%acl_smtp_mime%&. It causes the current MIME part to be decoded into a file. |
24336 | For details, see chapter &<<CHAPexiscan>>&. | |
168e428f | 24337 | |
9b371988 PH |
24338 | .vitem &*demime&~=&~*&<&'extension&~list'&> |
24339 | .cindex "&%demime%&" "ACL condition" | |
068aaea8 | 24340 | This condition is available only when Exim is compiled with the |
9b371988 PH |
24341 | content-scanning extension. Its use is described in section |
24342 | &<<SECTdemimecond>>&. | |
24343 | ||
24344 | .vitem &*dnslists&~=&~*&<&'list&~of&~domain&~names&~and&~other&~data'&> | |
24345 | .cindex "&%dnslists%&" "ACL condition" | |
24346 | .cindex "DNS list" "in ACL" | |
24347 | .cindex "black list (DNS)" | |
24348 | .cindex "&ACL;" "testing a DNS list" | |
168e428f | 24349 | This condition checks for entries in DNS black lists. These are also known as |
9b371988 PH |
24350 | &"RBL lists"&, after the original Realtime Blackhole List, but note that the |
24351 | use of the lists at &'mail-abuse.org'& now carries a charge. There are too many | |
168e428f | 24352 | different variants of this condition to describe briefly here. See sections |
9b371988 | 24353 | &<<SECTmorednslists>>&--&<<SECTmorednslistslast>>& for details. |
168e428f | 24354 | |
9b371988 PH |
24355 | .vitem &*domains&~=&~*&<&'domain&~list'&> |
24356 | .cindex "&%domains%&" "ACL condition" | |
24357 | .cindex "domain" "ACL checking" | |
24358 | .cindex "&ACL;" "testing a recipient domain" | |
24359 | .cindex "&$domain_data$&" | |
168e428f PH |
24360 | This condition is relevant only after a RCPT command. It checks that the domain |
24361 | of the recipient address is in the domain list. If percent-hack processing is | |
24362 | enabled, it is done before this test is done. If the check succeeds with a | |
9b371988 PH |
24363 | lookup, the result of the lookup is placed in &$domain_data$& until the next |
24364 | &%domains%& test. | |
168e428f | 24365 | |
9b371988 PH |
24366 | .vitem &*encrypted&~=&~*&<&'string&~list'&> |
24367 | .cindex "&%encrypted%&" "ACL condition" | |
24368 | .cindex "encryption" "checking in an ACL" | |
24369 | .cindex "&ACL;" "testing for encryption" | |
168e428f PH |
24370 | If the SMTP connection is not encrypted, the condition is false. Otherwise, the |
24371 | name of the cipher suite in use is tested against the list. To test for | |
24372 | encryption without testing for any specific cipher suite(s), set | |
9b371988 PH |
24373 | .code |
24374 | encrypted = * | |
24375 | .endd | |
24376 | ||
24377 | .vitem &*hosts&~=&~*&<&'&~host&~list'&> | |
24378 | .cindex "&%hosts%&" "ACL condition" | |
24379 | .cindex "host" "ACL checking" | |
24380 | .cindex "&ACL;" "testing the client host" | |
168e428f PH |
24381 | This condition tests that the calling host matches the host list. If you have |
24382 | name lookups or wildcarded host names and IP addresses in the same host list, | |
24383 | you should normally put the IP addresses first. For example, you could have: | |
9b371988 PH |
24384 | .code |
24385 | accept hosts = 10.9.8.7 : dbm;/etc/friendly/hosts | |
24386 | .endd | |
168e428f PH |
24387 | The reason for this lies in the left-to-right way that Exim processes lists. |
24388 | It can test IP addresses without doing any DNS lookups, but when it reaches an | |
24389 | item that requires a host name, it fails if it cannot find a host name to | |
24390 | compare with the pattern. If the above list is given in the opposite order, the | |
9b371988 | 24391 | &%accept%& statement fails for a host whose name cannot be found, even if its |
168e428f | 24392 | IP address is 10.9.8.7. |
9b371988 | 24393 | |
168e428f PH |
24394 | If you really do want to do the name check first, and still recognize the IP |
24395 | address even if the name lookup fails, you can rewrite the ACL like this: | |
9b371988 PH |
24396 | .code |
24397 | accept hosts = dbm;/etc/friendly/hosts | |
24398 | accept hosts = 10.9.8.7 | |
24399 | .endd | |
168e428f | 24400 | The default action on failing to find the host name is to assume that the host |
9b371988 PH |
24401 | is not in the list, so the first &%accept%& statement fails. The second |
24402 | statement can then check the IP address. | |
168e428f | 24403 | |
9b371988 PH |
24404 | .cindex "&$host_data$&" |
24405 | If a &%hosts%& condition is satisfied by means of a lookup, the result | |
24406 | of the lookup is made available in the &$host_data$& variable. This | |
24407 | allows you, for example, to set up a statement like this: | |
24408 | .code | |
24409 | deny hosts = net-lsearch;/some/file | |
24410 | message = $host_data | |
24411 | .endd | |
168e428f PH |
24412 | which gives a custom error message for each denied host. |
24413 | ||
9b371988 PH |
24414 | .vitem &*local_parts&~=&~*&<&'local&~part&~list'&> |
24415 | .cindex "&%local_parts%&" "ACL condition" | |
24416 | .cindex "local part" "ACL checking" | |
24417 | .cindex "&ACL;" "testing a local part" | |
24418 | .cindex "&$local_part_data$&" | |
168e428f PH |
24419 | This condition is relevant only after a RCPT command. It checks that the local |
24420 | part of the recipient address is in the list. If percent-hack processing is | |
24421 | enabled, it is done before this test. If the check succeeds with a lookup, the | |
9b371988 PH |
24422 | result of the lookup is placed in &$local_part_data$&, which remains set until |
24423 | the next &%local_parts%& test. | |
168e428f | 24424 | |
9b371988 PH |
24425 | .vitem &*malware&~=&~*&<&'option'&> |
24426 | .cindex "&%malware%&" "ACL condition" | |
24427 | .cindex "&ACL;" "virus scanning" | |
24428 | .cindex "&ACL;" "scanning for viruses" | |
168e428f PH |
24429 | This condition is available only when Exim is compiled with the |
24430 | content-scanning extension. It causes the incoming message to be scanned for | |
9b371988 | 24431 | viruses. For details, see chapter &<<CHAPexiscan>>&. |
168e428f | 24432 | |
9b371988 PH |
24433 | .vitem &*mime_regex&~=&~*&<&'list&~of&~regular&~expressions'&> |
24434 | .cindex "&%mime_regex%&" "ACL condition" | |
24435 | .cindex "&ACL;" "testing by regex matching" | |
168e428f PH |
24436 | This condition is available only when Exim is compiled with the |
24437 | content-scanning extension, and it is allowed only the the ACL defined by | |
9b371988 PH |
24438 | &%acl_smtp_mime%&. It causes the current MIME part to be scanned for a match |
24439 | with any of the regular expressions. For details, see chapter | |
24440 | &<<CHAPexiscan>>&. | |
168e428f | 24441 | |
9b371988 PH |
24442 | .new |
24443 | .vitem &*ratelimit&~=&~*&<&'parameters'&> | |
24444 | .cindex "rate limiting" | |
068aaea8 | 24445 | This condition can be used to limit the rate at which a user or host submits |
9b371988 PH |
24446 | messages. Details are given in section &<<SECTratelimiting>>&. |
24447 | .wen | |
068aaea8 | 24448 | |
9b371988 PH |
24449 | .vitem &*recipients&~=&~*&<&'address&~list'&> |
24450 | .cindex "&%recipients%&" "ACL condition" | |
24451 | .cindex "recipient" "ACL checking" | |
24452 | .cindex "&ACL;" "testing a recipient" | |
168e428f PH |
24453 | This condition is relevant only after a RCPT command. It checks the entire |
24454 | recipient address against a list of recipients. | |
24455 | ||
9b371988 PH |
24456 | .vitem &*regex&~=&~*&<&'list&~of&~regular&~expressions'&> |
24457 | .cindex "&%regex%&" "ACL condition" | |
24458 | .cindex "&ACL;" "testing by regex matching" | |
168e428f | 24459 | This condition is available only when Exim is compiled with the |
068aaea8 PH |
24460 | content-scanning extension, and is available only in the DATA, MIME, and |
24461 | non-SMTP ACLs. It causes the incoming message to be scanned for a match with | |
9b371988 PH |
24462 | any of the regular expressions. For details, see chapter &<<CHAPexiscan>>&. |
24463 | ||
24464 | .vitem &*sender_domains&~=&~*&<&'domain&~list'&> | |
24465 | .cindex "&%sender_domains%&" "ACL condition" | |
24466 | .cindex "sender" "ACL checking" | |
24467 | .cindex "&ACL;" "testing a sender domain" | |
24468 | .cindex "&$domain$&" | |
24469 | .cindex "&$sender_address_domain$&" | |
168e428f | 24470 | This condition tests the domain of the sender of the message against the given |
9b371988 PH |
24471 | domain list. &*Note*&: The domain of the sender address is in |
24472 | &$sender_address_domain$&. It is &'not'& put in &$domain$& during the testing | |
24473 | of this condition. This is an exception to the general rule for testing domain | |
24474 | lists. It is done this way so that, if this condition is used in an ACL for a | |
24475 | RCPT command, the recipient's domain (which is in &$domain$&) can be used to | |
24476 | influence the sender checking. | |
24477 | ||
24478 | .new | |
24479 | &*Warning*&: It is a bad idea to use this condition on its own as a control on | |
068aaea8 | 24480 | relaying, because sender addresses are easily, and commonly, forged. |
9b371988 | 24481 | .wen |
168e428f | 24482 | |
9b371988 PH |
24483 | .vitem &*senders&~=&~*&<&'address&~list'&> |
24484 | .cindex "&%senders%&" "ACL condition" | |
24485 | .cindex "sender" "ACL checking" | |
24486 | .cindex "&ACL;" "testing a sender" | |
168e428f PH |
24487 | This condition tests the sender of the message against the given list. To test |
24488 | for a bounce message, which has an empty sender, set | |
9b371988 PH |
24489 | .code |
24490 | senders = : | |
24491 | .endd | |
24492 | .new | |
24493 | &*Warning*&: It is a bad idea to use this condition on its own as a control on | |
068aaea8 | 24494 | relaying, because sender addresses are easily, and commonly, forged. |
9b371988 | 24495 | .wen |
168e428f | 24496 | |
9b371988 PH |
24497 | .vitem &*spam&~=&~*&<&'username'&> |
24498 | .cindex "&%spam%&" "ACL condition" | |
24499 | .cindex "&ACL;" "scanning for spam" | |
168e428f PH |
24500 | This condition is available only when Exim is compiled with the |
24501 | content-scanning extension. It causes the incoming message to be scanned by | |
9b371988 PH |
24502 | SpamAssassin. For details, see chapter &<<CHAPexiscan>>&. |
24503 | ||
24504 | .vitem &*verify&~=&~certificate*& | |
24505 | .cindex "&%verify%&" "ACL condition" | |
24506 | .cindex "TLS" "client certificate verification" | |
24507 | .cindex "certificate" "verification of client" | |
24508 | .cindex "&ACL;" "certificate verification" | |
24509 | .cindex "&ACL;" "testing a TLS certificate" | |
168e428f PH |
24510 | This condition is true in an SMTP session if the session is encrypted, and a |
24511 | certificate was received from the client, and the certificate was verified. The | |
9b371988 PH |
24512 | server requests a certificate only if the client matches &%tls_verify_hosts%& |
24513 | or &%tls_try_verify_hosts%& (see chapter &<<CHAPTLS>>&). | |
168e428f | 24514 | |
9b371988 PH |
24515 | .new |
24516 | .vitem &*verify&~=&~csa*& | |
24517 | .cindex "CSA verification" | |
068aaea8 PH |
24518 | This condition checks whether the sending host (the client) is authorized to |
24519 | send email. Details of how this works are given in section | |
9b371988 PH |
24520 | &<<SECTverifyCSA>>&. |
24521 | .wen | |
24522 | ||
24523 | .vitem &*verify&~=&~header_sender/*&<&'options'&> | |
24524 | .cindex "&%verify%&" "ACL condition" | |
24525 | .cindex "&ACL;" "verifying sender in the header" | |
24526 | .cindex "header lines" "verifying the sender in" | |
24527 | .cindex "sender" "verifying in header" | |
24528 | .cindex "verifying" "sender in header" | |
168e428f | 24529 | This condition is relevant only in an ACL that is run after a message has been |
9b371988 PH |
24530 | received, that is, in an ACL specified by &%acl_smtp_data%& or |
24531 | &%acl_not_smtp%&. It checks that there is a verifiable address in at least one | |
24532 | of the &'Sender:'&, &'Reply-To:'&, or &'From:'& header lines. Such an address | |
24533 | is loosely thought of as a &"sender"& address (hence the name of the test). | |
24534 | However, an address that appears in one of these headers need not be an address | |
24535 | that accepts bounce messages; only sender addresses in envelopes are required | |
24536 | to accept bounces. Therefore, if you use the callout option on this check, you | |
24537 | might want to arrange for a non-empty address in the MAIL command. | |
24538 | ||
168e428f | 24539 | Details of address verification and the options are given later, starting at |
9b371988 PH |
24540 | section &<<SECTaddressverification>>& (callouts are described in section |
24541 | &<<SECTcallver>>&). You can combine this condition with the &%senders%& | |
24542 | condition to restrict it to bounce messages only: | |
24543 | .code | |
24544 | deny senders = : | |
24545 | message = A valid sender header is required for bounces | |
24546 | !verify = header_sender | |
24547 | .endd | |
24548 | ||
24549 | .vitem &*verify&~=&~header_syntax*& | |
24550 | .cindex "&%verify%&" "ACL condition" | |
24551 | .cindex "&ACL;" "verifying header syntax" | |
24552 | .cindex "header lines" "verifying syntax" | |
24553 | .cindex "verifying" "header syntax" | |
168e428f | 24554 | This condition is relevant only in an ACL that is run after a message has been |
9b371988 PH |
24555 | received, that is, in an ACL specified by &%acl_smtp_data%& or |
24556 | &%acl_not_smtp%&. It checks the syntax of all header lines that can contain | |
24557 | lists of addresses (&'Sender:'&, &'From:'&, &'Reply-To:'&, &'To:'&, &'Cc:'&, | |
24558 | and &'Bcc:'&). Unqualified addresses (local parts without domains) are | |
24559 | permitted only in locally generated messages and from hosts that match | |
24560 | &%sender_unqualified_hosts%& or &%recipient_unqualified_hosts%&, as | |
24561 | appropriate. | |
24562 | ||
168e428f PH |
24563 | Note that this condition is a syntax check only. However, a common spamming |
24564 | ploy used to be to send syntactically invalid headers such as | |
9b371988 PH |
24565 | .code |
24566 | To: @ | |
24567 | .endd | |
168e428f PH |
24568 | and this condition can be used to reject such messages, though they are not as |
24569 | common as they used to be. | |
24570 | ||
9b371988 PH |
24571 | .vitem &*verify&~=&~helo*& |
24572 | .cindex "&%verify%&" "ACL condition" | |
24573 | .cindex "&ACL;" "verifying HELO/EHLO" | |
24574 | .cindex "HELO" "verifying" | |
24575 | .cindex "EHLO" "verifying" | |
24576 | .cindex "verifying" "EHLO" | |
24577 | .cindex "verifying" "HELO" | |
24578 | .new | |
168e428f | 24579 | This condition is true if a HELO or EHLO command has been received from the |
068aaea8 PH |
24580 | client host, and its contents have been verified. It there has been no previous |
24581 | attempt to verify the the HELO/EHLO contents, it is carried out when this | |
9b371988 PH |
24582 | condition is encountered. See the description of the &%helo_verify_hosts%& and |
24583 | &%helo_try_verify_hosts%& options for details of how to request verification | |
068aaea8 | 24584 | independently of this condition. |
9b371988 | 24585 | .wen |
068aaea8 | 24586 | |
9b371988 PH |
24587 | .new |
24588 | .vitem &*verify&~=&~not_blind*& | |
24589 | .cindex "verifying" "not blind" | |
24590 | .cindex "bcc recipients" "verifying none" | |
068aaea8 | 24591 | This condition checks that there are no blind (bcc) recipients in the message. |
9b371988 PH |
24592 | Every envelope recipient must appear either in a &'To:'& header line or in a |
24593 | &'Cc:'& header line for this condition to be true. Local parts are checked | |
24594 | case-sensitively; domains are checked case-insensitively. If &'Resent-To:'& or | |
24595 | &'Resent-Cc:'& header lines exist, they are also checked. This condition can be | |
068aaea8 | 24596 | used only in a DATA or non-SMTP ACL. |
068aaea8 | 24597 | |
9b371988 PH |
24598 | There are, of course, many legitimate messages that make use of blind (bcc) |
24599 | recipients. This check should not be used on its own for blocking messages. | |
24600 | .wen | |
068aaea8 | 24601 | |
168e428f | 24602 | |
9b371988 PH |
24603 | .vitem &*verify&~=&~recipient/*&<&'options'&> |
24604 | .cindex "&%verify%&" "ACL condition" | |
24605 | .cindex "&ACL;" "verifying recipient" | |
24606 | .cindex "recipient" "verifying" | |
24607 | .cindex "verifying" "recipient" | |
24608 | .cindex "&$address_data$&" | |
168e428f PH |
24609 | This condition is relevant only after a RCPT command. It verifies the current |
24610 | recipient. Details of address verification are given later, starting at section | |
9b371988 PH |
24611 | &<<SECTaddressverification>>&. After a recipient has been verified, the value |
24612 | of &$address_data$& is the last value that was set while routing the address. | |
24613 | This applies even if the verification fails. When an address that is being | |
24614 | verified is redirected to a single address, verification continues with the new | |
24615 | address, and in that case, the subsequent value of &$address_data$& is the | |
24616 | value for the child address. | |
24617 | ||
24618 | .vitem &*verify&~=&~reverse_host_lookup*& | |
24619 | .cindex "&%verify%&" "ACL condition" | |
24620 | .cindex "&ACL;" "verifying host reverse lookup" | |
24621 | .cindex "host" "verifying reverse lookup" | |
168e428f PH |
24622 | This condition ensures that a verified host name has been looked up from the IP |
24623 | address of the client host. (This may have happened already if the host name | |
9b371988 | 24624 | was needed for checking a host list, or if the host matched &%host_lookup%&.) |
168e428f PH |
24625 | Verification ensures that the host name obtained from a reverse DNS lookup, or |
24626 | one of its aliases, does, when it is itself looked up in the DNS, yield the | |
24627 | original IP address. | |
9b371988 | 24628 | |
168e428f PH |
24629 | If this condition is used for a locally generated message (that is, when there |
24630 | is no client host involved), it always succeeds. | |
24631 | ||
9b371988 PH |
24632 | .vitem &*verify&~=&~sender/*&<&'options'&> |
24633 | .cindex "&%verify%&" "ACL condition" | |
24634 | .cindex "&ACL;" "verifying sender" | |
24635 | .cindex "sender" "verifying" | |
24636 | .cindex "verifying" "sender" | |
168e428f | 24637 | This condition is relevant only after a MAIL or RCPT command, or after a |
9b371988 PH |
24638 | message has been received (the &%acl_smtp_data%& or &%acl_not_smtp%& ACLs). If |
24639 | the message's sender is empty (that is, this is a bounce message), the | |
24640 | condition is true. Otherwise, the sender address is verified. | |
24641 | ||
24642 | .cindex "&$address_data$&" | |
24643 | .cindex "&$sender_address_data$&" | |
24644 | If there is data in the &$address_data$& variable at the end of routing, its | |
24645 | value is placed in &$sender_address_data$& at the end of verification. This | |
168e428f PH |
24646 | value can be used in subsequent conditions and modifiers in the same ACL |
24647 | statement. It does not persist after the end of the current statement. If you | |
24648 | want to preserve the value for longer, you can save it in an ACL variable. | |
9b371988 | 24649 | |
168e428f | 24650 | Details of verification are given later, starting at section |
9b371988 PH |
24651 | &<<SECTaddressverification>>&. Exim caches the result of sender verification, |
24652 | to avoid doing it more than once per message. | |
168e428f | 24653 | |
9b371988 PH |
24654 | .vitem &*verify&~=&~sender=*&<&'address'&>&*/*&<&'options'&> |
24655 | .cindex "&%verify%&" "ACL condition" | |
168e428f PH |
24656 | This is a variation of the previous option, in which a modified address is |
24657 | verified as a sender. | |
9b371988 | 24658 | .endlist |
168e428f PH |
24659 | |
24660 | ||
24661 | ||
9b371988 PH |
24662 | .section "Using DNS lists" "SECTmorednslists" |
24663 | .cindex "DNS list" "in ACL" | |
24664 | .cindex "black list (DNS)" | |
24665 | .cindex "&ACL;" "testing a DNS list" | |
24666 | In its simplest form, the &%dnslists%& condition tests whether the calling host | |
168e428f PH |
24667 | is on at least one of a number of DNS lists by looking up the inverted IP |
24668 | address in one or more DNS domains. For example, if the calling host's IP | |
24669 | address is 192.168.62.43, and the ACL statement is | |
9b371988 | 24670 | .code |
168e428f PH |
24671 | deny dnslists = blackholes.mail-abuse.org : \ |
24672 | dialups.mail-abuse.org | |
9b371988 | 24673 | .endd |
168e428f | 24674 | the following records are looked up: |
9b371988 PH |
24675 | .code |
24676 | 43.62.168.192.blackholes.mail-abuse.org | |
24677 | 43.62.168.192.dialups.mail-abuse.org | |
24678 | .endd | |
168e428f | 24679 | As soon as Exim finds an existing DNS record, processing of the list stops. |
9b371988 PH |
24680 | Thus, multiple entries on the list provide an &"or"& conjunction. If you want |
24681 | to test that a host is on more than one list (an &"and"& conjunction), you can | |
24682 | use two separate conditions: | |
24683 | .code | |
24684 | deny dnslists = blackholes.mail-abuse.org | |
24685 | dnslists = dialups.mail-abuse.org | |
24686 | .endd | |
168e428f PH |
24687 | If a DNS lookup times out or otherwise fails to give a decisive answer, Exim |
24688 | behaves as if the host does not match the list item, that is, as if the DNS | |
24689 | record does not exist. If there are further items in the DNS list, they are | |
24690 | processed. | |
24691 | ||
9b371988 PH |
24692 | This is usually the required action when &%dnslists%& is used with &%deny%& |
24693 | (which is the most common usage), because it prevents a DNS failure from | |
24694 | blocking mail. However, you can change this behaviour by putting one of the | |
24695 | following special items in the list: | |
24696 | .display | |
24697 | &`+include_unknown `& behave as if the item is on the list | |
24698 | &`+exclude_unknown `& behave as if the item is not on the list (default) | |
24699 | &`+defer_unknown `& give a temporary error | |
24700 | .endd | |
24701 | .cindex "&`+include_unknown`&" | |
24702 | .cindex "&`+exclude_unknown`&" | |
24703 | .cindex "&`+defer_unknown`&" | |
168e428f | 24704 | Each of these applies to any subsequent items on the list. For example: |
9b371988 PH |
24705 | .code |
24706 | deny dnslists = +defer_unknown : foo.bar.example | |
24707 | .endd | |
168e428f PH |
24708 | Testing the list of domains stops as soon as a match is found. If you want to |
24709 | warn for one list and block for another, you can use two different statements: | |
9b371988 PH |
24710 | .code |
24711 | deny dnslists = blackholes.mail-abuse.org | |
24712 | warn message = X-Warn: sending host is on dialups list | |
24713 | dnslists = dialups.mail-abuse.org | |
24714 | .endd | |
168e428f PH |
24715 | DNS list lookups are cached by Exim for the duration of the SMTP session, |
24716 | so a lookup based on the IP address is done at most once for any incoming | |
24717 | connection. Exim does not share information between multiple incoming | |
24718 | connections (but your local name server cache should be active). | |
24719 | ||
24720 | ||
24721 | ||
9b371988 PH |
24722 | .section "Specifying the IP address for a DNS list lookup" |
24723 | .cindex "DNS list" "keyed by explicit IP address" | |
168e428f PH |
24724 | By default, the IP address that is used in a DNS list lookup is the IP address |
24725 | of the calling host. However, you can specify another IP address by listing it | |
24726 | after the domain name, introduced by a slash. For example: | |
9b371988 PH |
24727 | .code |
24728 | deny dnslists = black.list.tld/192.168.1.2 | |
24729 | .endd | |
168e428f PH |
24730 | This feature is not very helpful with explicit IP addresses; it is intended for |
24731 | use with IP addresses that are looked up, for example, the IP addresses of the | |
24732 | MX hosts or nameservers of an email sender address. For an example, see section | |
9b371988 | 24733 | &<<SECTmulkeyfor>>& below. |
168e428f PH |
24734 | |
24735 | ||
24736 | ||
24737 | ||
9b371988 PH |
24738 | .section "DNS lists keyed on domain names" |
24739 | .cindex "DNS list" "keyed by domain name" | |
168e428f | 24740 | There are some lists that are keyed on domain names rather than inverted IP |
9b371988 PH |
24741 | addresses (see for example the &'domain based zones'& link at |
24742 | &url(http://www.rfc-ignorant.org/)). No reversing of components is used | |
24743 | with these lists. You can change the name that is looked up in a DNS list by | |
24744 | listing it after the domain name, introduced by a slash. For example, | |
24745 | .code | |
24746 | deny message = Sender's domain is listed at $dnslist_domain | |
24747 | dnslists = dsn.rfc-ignorant.org/$sender_address_domain | |
24748 | .endd | |
168e428f PH |
24749 | This particular example is useful only in ACLs that are obeyed after the |
24750 | RCPT or DATA commands, when a sender address is available. If (for | |
9b371988 | 24751 | example) the message's sender is &'user@tld.example'& the name that is looked |
168e428f | 24752 | up by this example is |
9b371988 PH |
24753 | .code |
24754 | tld.example.dsn.rfc-ignorant.org | |
24755 | .endd | |
24756 | A single &%dnslists%& condition can contain entries for both names and IP | |
168e428f | 24757 | addresses. For example: |
9b371988 | 24758 | .code |
168e428f PH |
24759 | deny dnslists = sbl.spamhaus.org : \ |
24760 | dsn.rfc-ignorant.org/$sender_address_domain | |
9b371988 | 24761 | .endd |
168e428f PH |
24762 | The first item checks the sending host's IP address; the second checks a domain |
24763 | name. The whole condition is true if either of the DNS lookups succeeds. | |
24764 | ||
24765 | ||
24766 | ||
24767 | ||
9b371988 PH |
24768 | .section "Multiple explicit keys for a DNS list" "SECTmulkeyfor" |
24769 | .cindex "DNS list" "multiple keys for" | |
168e428f PH |
24770 | The syntax described above for looking up explicitly-defined values (either |
24771 | names or IP addresses) in a DNS blacklist is a simplification. After the domain | |
24772 | name for the DNS list, what follows the slash can in fact be a list of items. | |
24773 | As with all lists in Exim, the default separator is a colon. However, because | |
24774 | this is a sublist within the list of DNS blacklist domains, it is necessary | |
24775 | either to double the separators like this: | |
9b371988 PH |
24776 | .code |
24777 | dnslists = black.list.tld/name.1::name.2 | |
24778 | .endd | |
168e428f | 24779 | or to change the separator character, like this: |
9b371988 PH |
24780 | .code |
24781 | dnslists = black.list.tld/<;name.1;name.2 | |
24782 | .endd | |
168e428f PH |
24783 | If an item in the list is an IP address, it is inverted before the DNS |
24784 | blacklist domain is appended. If it is not an IP address, no inversion | |
24785 | occurs. Consider this condition: | |
9b371988 PH |
24786 | .code |
24787 | dnslists = black.list.tld/<;192.168.1.2;a.domain | |
24788 | .endd | |
168e428f | 24789 | The DNS lookups that occur are: |
9b371988 PH |
24790 | .code |
24791 | 2.1.168.192.black.list.tld | |
24792 | a.domain.black.list.tld | |
24793 | .endd | |
168e428f | 24794 | Once a DNS record has been found (that matches a specific IP return |
9b371988 PH |
24795 | address, if specified &-- see section &<<SECTaddmatcon>>&), no further lookups |
24796 | are done. If there is a temporary DNS error, the rest of the sublist of domains | |
24797 | or IP addresses is tried. A temporary error for the whole dnslists item occurs | |
168e428f PH |
24798 | only if no other DNS lookup in this sublist succeeds. In other words, a |
24799 | successful lookup for any of the items in the sublist overrides a temporary | |
24800 | error for a previous item. | |
24801 | ||
24802 | The ability to supply a list of items after the slash is in some sense just a | |
24803 | syntactic convenience. These two examples have the same effect: | |
9b371988 PH |
24804 | .code |
24805 | dnslists = black.list.tld/a.domain : black.list.tld/b.domain | |
24806 | dnslists = black.list.tld/a.domain::b.domain | |
24807 | .endd | |
168e428f PH |
24808 | However, when the data for the list is obtained from a lookup, the second form |
24809 | is usually much more convenient. Consider this example: | |
9b371988 PH |
24810 | .code |
24811 | deny message = The mail servers for the domain \ | |
24812 | $sender_address_domain \ | |
24813 | are listed at $dnslist_domain ($dnslist_value); \ | |
24814 | see $dnslist_text. | |
24815 | dnslists = sbl.spamhaus.org/<|${lookup dnsdb {>|a=<|\ | |
24816 | ${lookup dnsdb {>|mxh=\ | |
24817 | $sender_address_domain} }} } | |
24818 | .endd | |
24819 | Note the use of &`>|`& in the dnsdb lookup to specify the separator for | |
168e428f PH |
24820 | multiple DNS records. The inner dnsdb lookup produces a list of MX hosts |
24821 | and the outer dnsdb lookup finds the IP addresses for these hosts. The result | |
24822 | of expanding the condition might be something like this: | |
9b371988 PH |
24823 | .code |
24824 | dnslists = sbl.spahmaus.org/<|192.168.2.3|192.168.5.6|... | |
24825 | .endd | |
168e428f PH |
24826 | Thus, this example checks whether or not the IP addresses of the sender |
24827 | domain's mail servers are on the Spamhaus black list. | |
24828 | ||
24829 | ||
24830 | ||
24831 | ||
24832 | ||
9b371988 PH |
24833 | .section "Data returned by DNS lists" |
24834 | .cindex "DNS list" "data returned from" | |
168e428f PH |
24835 | DNS lists are constructed using address records in the DNS. The original RBL |
24836 | just used the address 127.0.0.1 on the right hand side of each record, but the | |
24837 | RBL+ list and some other lists use a number of values with different meanings. | |
24838 | The values used on the RBL+ list are: | |
9b371988 | 24839 | .display |
168e428f PH |
24840 | 127.1.0.1 RBL |
24841 | 127.1.0.2 DUL | |
24842 | 127.1.0.3 DUL and RBL | |
24843 | 127.1.0.4 RSS | |
24844 | 127.1.0.5 RSS and RBL | |
24845 | 127.1.0.6 RSS and DUL | |
24846 | 127.1.0.7 RSS and DUL and RBL | |
9b371988 | 24847 | .endd |
168e428f PH |
24848 | Some DNS lists may return more than one address record. |
24849 | ||
24850 | ||
9b371988 PH |
24851 | .section "Variables set from DNS lists" |
24852 | .cindex "DNS list" "variables set from" | |
24853 | .cindex "&$dnslist_domain$&" | |
24854 | .cindex "&$dnslist_text$&" | |
24855 | .cindex "&$dnslist_value$&" | |
24856 | When an entry is found in a DNS list, the variable &$dnslist_domain$& | |
24857 | contains the name of the domain that matched, &$dnslist_value$& contains the | |
24858 | data from the entry, and &$dnslist_text$& contains the contents of any | |
168e428f | 24859 | associated TXT record. If more than one address record is returned by the DNS |
9b371988 | 24860 | lookup, all the IP addresses are included in &$dnslist_value$&, separated by |
168e428f PH |
24861 | commas and spaces. |
24862 | ||
9b371988 | 24863 | You can use these variables in &%message%& or &%log_message%& modifiers &-- |
168e428f PH |
24864 | although these appear before the condition in the ACL, they are not expanded |
24865 | until after it has failed. For example: | |
9b371988 | 24866 | .code |
168e428f PH |
24867 | deny hosts = !+local_networks |
24868 | message = $sender_host_address is listed \ | |
24869 | at $dnslist_domain | |
24870 | dnslists = rbl-plus.mail-abuse.example | |
9b371988 | 24871 | .endd |
168e428f PH |
24872 | |
24873 | ||
24874 | ||
9b371988 PH |
24875 | .section "Additional matching conditions for DNS lists" "SECTaddmatcon" |
24876 | .cindex "DNS list" "matching specific returned data" | |
24877 | You can add an equals sign and an IP address after a &%dnslists%& domain name | |
24878 | in order to restrict its action to DNS records with a matching right hand side. | |
168e428f | 24879 | For example, |
9b371988 PH |
24880 | .code |
24881 | deny dnslists = rblplus.mail-abuse.org=127.0.0.2 | |
24882 | .endd | |
168e428f PH |
24883 | rejects only those hosts that yield 127.0.0.2. Without this additional data, |
24884 | any address record is considered to be a match. If more than one address record | |
24885 | is found on the list, they are all checked for a matching right-hand side. | |
24886 | ||
24887 | More than one IP address may be given for checking, using a comma as a | |
9b371988 PH |
24888 | separator. These are alternatives &-- if any one of them matches, the |
24889 | &%dnslists%& condition is true. For example: | |
24890 | .code | |
24891 | deny dnslists = a.b.c=127.0.0.2,127.0.0.3 | |
24892 | .endd | |
168e428f PH |
24893 | If you want to specify a constraining address list and also specify names or IP |
24894 | addresses to be looked up, the constraining address list must be specified | |
24895 | first. For example: | |
9b371988 | 24896 | .code |
168e428f PH |
24897 | deny dnslists = dsn.rfc-ignorant.org\ |
24898 | =127.0.0.2/$sender_address_domain | |
9b371988 | 24899 | .endd |
168e428f | 24900 | |
9b371988 PH |
24901 | If the character &`&&`& is used instead of &`=`&, the comparison for each |
24902 | listed IP address is done by a bitwise &"and"& instead of by an equality test. | |
24903 | In other words, the listed addresses are used as bit masks. The comparison is | |
168e428f PH |
24904 | true if all the bits in the mask are present in the address that is being |
24905 | tested. For example: | |
9b371988 PH |
24906 | .code |
24907 | dnslists = a.b.c&0.0.0.3 | |
24908 | .endd | |
24909 | matches if the address is &'x.x.x.'&3, &'x.x.x.'&7, &'x.x.x.'&11, etc. If you | |
168e428f PH |
24910 | want to test whether one bit or another bit is present (as opposed to both |
24911 | being present), you must use multiple values. For example: | |
9b371988 PH |
24912 | .code |
24913 | dnslists = a.b.c&0.0.0.1,0.0.0.2 | |
24914 | .endd | |
168e428f PH |
24915 | matches if the final component of the address is an odd number or two times |
24916 | an odd number. | |
24917 | ||
24918 | ||
24919 | ||
9b371988 PH |
24920 | .section "Negated DNS matching conditions" |
24921 | You can supply a negative list of IP addresses as part of a &%dnslists%& | |
168e428f | 24922 | condition. Whereas |
9b371988 PH |
24923 | .code |
24924 | deny dnslists = a.b.c=127.0.0.2,127.0.0.3 | |
24925 | .endd | |
24926 | means &"deny if the host is in the black list at the domain &'a.b.c'& and the | |
24927 | IP address yielded by the list is either 127.0.0.2 or 127.0.0.3"&, | |
24928 | .code | |
24929 | deny dnslists = a.b.c!=127.0.0.2,127.0.0.3 | |
24930 | .endd | |
24931 | means &"deny if the host is in the black list at the domain &'a.b.c'& and the | |
24932 | IP address yielded by the list is not 127.0.0.2 and not 127.0.0.3"&. In other | |
168e428f | 24933 | words, the result of the test is inverted if an exclamation mark appears before |
9b371988 | 24934 | the &`=`& (or the &`&&`&) sign. |
168e428f | 24935 | |
9b371988 | 24936 | &*Note*&: This kind of negation is not the same as negation in a domain, |
168e428f PH |
24937 | host, or address list (which is why the syntax is different). |
24938 | ||
24939 | If you are using just one list, the negation syntax does not gain you much. The | |
24940 | previous example is precisely equivalent to | |
9b371988 PH |
24941 | .code |
24942 | deny dnslists = a.b.c | |
24943 | !dnslists = a.b.c=127.0.0.2,127.0.0.3 | |
24944 | .endd | |
168e428f PH |
24945 | However, if you are using multiple lists, the negation syntax is clearer. |
24946 | Consider this example: | |
9b371988 | 24947 | .code |
168e428f PH |
24948 | deny dnslists = sbl.spamhaus.org : \ |
24949 | list.dsbl.org : \ | |
24950 | dnsbl.njabl.org!=127.0.0.3 : \ | |
24951 | relays.ordb.org | |
9b371988 | 24952 | .endd |
168e428f | 24953 | Using only positive lists, this would have to be: |
9b371988 | 24954 | .code |
168e428f PH |
24955 | deny dnslists = sbl.spamhaus.org : \ |
24956 | list.dsbl.org | |
24957 | deny dnslists = dnsbl.njabl.org | |
24958 | !dnslists = dnsbl.njabl.org=127.0.0.3 | |
24959 | deny dnslists = relays.ordb.org | |
9b371988 | 24960 | .endd |
168e428f PH |
24961 | which is less clear, and harder to maintain. |
24962 | ||
24963 | ||
24964 | ||
24965 | ||
9b371988 PH |
24966 | .section "DNS lists and IPv6" "SECTmorednslistslast" |
24967 | .cindex "IPv6" "DNS black lists" | |
24968 | .cindex "DNS list" "IPv6 usage" | |
168e428f PH |
24969 | If Exim is asked to do a dnslist lookup for an IPv6 address, it inverts it |
24970 | nibble by nibble. For example, if the calling host's IP address is | |
24971 | 3ffe:ffff:836f:0a00:000a:0800:200a:c031, Exim might look up | |
9b371988 PH |
24972 | .code |
24973 | 1.3.0.c.a.0.0.2.0.0.8.0.a.0.0.0.0.0.a.0.f.6.3.8. | |
24974 | f.f.f.f.e.f.f.3.blackholes.mail-abuse.org | |
24975 | .endd | |
168e428f PH |
24976 | (split over two lines here to fit on the page). Unfortunately, some of the DNS |
24977 | lists contain wildcard records, intended for IPv4, that interact badly with | |
24978 | IPv6. For example, the DNS entry | |
9b371988 PH |
24979 | .code |
24980 | *.3.some.list.example. A 127.0.0.1 | |
24981 | .endd | |
168e428f PH |
24982 | is probably intended to put the entire 3.0.0.0/8 IPv4 network on the list. |
24983 | Unfortunately, it also matches the entire 3::/4 IPv6 network. | |
24984 | ||
24985 | You can exclude IPv6 addresses from DNS lookups by making use of a suitable | |
9b371988 PH |
24986 | &%condition%& condition, as in this example: |
24987 | .code | |
24988 | deny condition = ${if isip4{$sender_host_address}} | |
24989 | dnslists = some.list.example | |
24990 | .endd | |
24991 | ||
24992 | .new | |
24993 | .section "Rate limiting senders" "SECTratelimiting" | |
24994 | .cindex "rate limiting" "client sending" | |
24995 | .cindex "limiting client sending rates" | |
24996 | .oindex "&%smpt_ratelimit_*%&" | |
24997 | The &%ratelimit%& ACL condition can be used to measure and control the rate at | |
24998 | which clients can send email. This is more powerful than the | |
24999 | &%smtp_ratelimit_*%& options, because those options control the rate of | |
25000 | commands in a single SMTP session only, whereas the &%ratelimit%& condition | |
25001 | works across all connections (concurrent and sequential) from the same client | |
25002 | host. The syntax of the &%ratelimit%& condition is: | |
25003 | .display | |
25004 | &`ratelimit =`& <&'m'&> &`/`& <&'p'&> &`/`& <&'options'&> &`/`& <&'key'&> | |
25005 | .endd | |
25006 | If the average client sending rate is less than &'m'& messages per time | |
25007 | period &'p'& then the condition is false; otherwise it is true. | |
25008 | ||
25009 | .new | |
25010 | As a side-effect, the &%ratelimit%& condition sets the expansion variable | |
25011 | &$sender_rate$& to the client's computed rate, &$sender_rate_limit$& to the | |
25012 | configured value of &'m'&, and &$sender_rate_period$& to the configured value | |
25013 | of &'p'&. | |
25014 | ||
25015 | The parameter &'p'& is the smoothing time constant, in the form of an Exim | |
25016 | time interval, for example, &`8h`& for eight hours. A larger time constant | |
25017 | means that it takes Exim longer to forget a client's past behaviour. The | |
25018 | parameter &'m'& is the maximum number of messages that a client is permitted to | |
25019 | send in each time interval. It also specifies the number of messages permitted | |
25020 | in a fast burst. By increasing both &'m'& and &'p'& but keeping &'m/p'& | |
25021 | constant, you can allow a client to send more messages in a burst without | |
25022 | changing its overall sending rate limit. Conversely, if &'m'& and &'p'& are | |
25023 | both small, messages must be sent at an even rate. | |
25024 | ||
25025 | There is a script in &_util/ratelimit.pl_& which extracts sending rates from | |
25026 | log files, to assist with choosing appropriate settings for &'m'& and &'p'& | |
25027 | when deploying the &%ratelimit%& ACL condition. The script prints usage | |
25028 | instructions when it is run with no arguments. | |
25029 | ||
068aaea8 PH |
25030 | The key is used to look up the data for calculating the client's average |
25031 | sending rate. This data is stored in a database maintained by Exim in its spool | |
9b371988 PH |
25032 | directory, alongside the retry and other hints databases. The default key is |
25033 | &$sender_host_address$&, which applies the limit to each client host IP address. | |
25034 | By changing the key you can change how Exim identifies clients for the purpose | |
25035 | of ratelimiting. For example, to limit the sending rate of each authenticated | |
25036 | user, independent of the computer they are sending from, set the key to | |
25037 | &$authenticated_id$&. You must ensure that the lookup key is meaningful; for | |
25038 | example, &$authenticated_id$& is only meaningful if the client has | |
25039 | authenticated, and you can check with with the &%authenticated%& ACL condition. | |
25040 | .wen | |
25041 | ||
25042 | Internally, Exim includes the smoothing constant &'p'& and the options in the | |
068aaea8 | 25043 | lookup key because they alter the meaning of the stored data. This is not true |
9b371988 | 25044 | for the limit &'m'&, so you can alter the configured maximum rate and Exim will |
068aaea8 PH |
25045 | still remember clients' past behaviour, but if you alter the other ratelimit |
25046 | parameters Exim forgets past behaviour. | |
25047 | ||
9b371988 | 25048 | Each &%ratelimit%& condition can have up to two options. The first option |
068aaea8 PH |
25049 | specifies what Exim measures the rate of, and the second specifies how Exim |
25050 | handles excessively fast clients. The options are separated by a slash, like | |
25051 | the other parameters. | |
25052 | ||
9b371988 PH |
25053 | The &%per_conn%& option limits the client's connection rate. |
25054 | ||
25055 | The &%per_mail%& option limits the client's rate of sending messages. This is | |
25056 | the default if none of the &%per_*%& options is specified. | |
068aaea8 | 25057 | |
9b371988 PH |
25058 | The &%per_byte%& option limits the sender's email bandwidth. Note that it is |
25059 | best to use this option in the DATA ACL; if it is used in an earlier ACL it | |
25060 | relies on the SIZE parameter on the MAIL command, which may be inaccurate or | |
25061 | completely missing. You can follow the limit &'m'& in the configuration with K, | |
068aaea8 PH |
25062 | M, or G to specify limits in kilobytes, megabytes, or gigabytes, respectively. |
25063 | ||
9b371988 PH |
25064 | The &%per_cmd%& option causes Exim to recompute the rate every time the |
25065 | condition is processed. This can be used to limit the SMTP command rate. The | |
25066 | alias &%per_rcpt%& is provided for use in the RCPT ACL instead of &%per_cmd%& | |
25067 | to make it clear that the effect is to limit the rate at which recipients are | |
25068 | accepted. Note that in this case the rate limiting engine will see a message | |
25069 | with many recipients as a large high-speed burst. | |
068aaea8 | 25070 | |
068aaea8 PH |
25071 | If a client's average rate is greater than the maximum, the rate limiting |
25072 | engine can react in two possible ways, depending on the presence of the | |
9b371988 PH |
25073 | &%strict%& or &%leaky%& options. This is independent of the other |
25074 | counter-measures (such as rejecting the message) that may be specified by the | |
25075 | rest of the ACL. The default mode is leaky, which avoids a sender's | |
25076 | over-aggressive retry rate preventing it from getting any email through. | |
068aaea8 | 25077 | |
9b371988 | 25078 | The &%strict%& option means that the client's recorded rate is always updated. |
068aaea8 PH |
25079 | The effect of this is that Exim measures the client's average rate of attempts |
25080 | to send email, which can be much higher than the maximum. If the client is over | |
25081 | the limit it will be subjected to counter-measures until it slows down below | |
25082 | the maximum rate. The smoothing period determines the time it takes for a high | |
25083 | sending rate to decay exponentially to 37% of its peak value, which means that | |
25084 | you can work out the time (the number of smoothing periods) that a client is | |
25085 | subjected to counter-measures after an over-limit burst with this formula: | |
9b371988 PH |
25086 | .code |
25087 | ln(peakrate/maxrate) | |
25088 | .endd | |
25089 | The &%leaky%& option means that the client's recorded rate is not updated if it | |
068aaea8 PH |
25090 | is above the limit. The effect of this is that Exim measures the client's |
25091 | average rate of successfully sent email, which cannot be greater than the | |
25092 | maximum. If the client is over the limit it will suffer some counter-measures, | |
25093 | but it will still be able to send email at the configured maximum rate, | |
9b371988 PH |
25094 | whatever the rate of its attempts. This is generally the better choice if you |
25095 | have clients that retry automatically. | |
068aaea8 | 25096 | |
068aaea8 PH |
25097 | Exim's other ACL facilities are used to define what counter-measures are taken |
25098 | when the rate limit is exceeded. This might be anything from logging a warning | |
25099 | (for example, while measuring existing sending rates in order to define | |
25100 | policy), through time delays to slow down fast senders, up to rejecting the | |
25101 | message. For example: | |
9b371988 | 25102 | .code |
068aaea8 PH |
25103 | # Log all senders' rates |
25104 | warn | |
25105 | ratelimit = 0 / 1h / strict | |
25106 | log_message = Sender rate $sender_rate / $sender_rate_period | |
25107 | ||
9b371988 PH |
25108 | # Slow down fast senders; note the need to truncate $sender_rate at the |
25109 | # decimal point. | |
068aaea8 PH |
25110 | warn |
25111 | ratelimit = 100 / 1h / per_rcpt / strict | |
9b371988 PH |
25112 | delay = ${eval: ${sg{$sender_rate}{[.].*}{}} - \ |
25113 | $sender_rate_limit }s | |
068aaea8 PH |
25114 | |
25115 | # Keep authenticated users under control | |
25116 | deny | |
9b371988 | 25117 | authenticated = * |
068aaea8 PH |
25118 | ratelimit = 100 / 1d / strict / $authenticated_id |
25119 | ||
25120 | # System-wide rate limit | |
25121 | defer | |
25122 | message = Sorry, too busy. Try again later. | |
25123 | ratelimit = 10 / 1s / $primary_hostname | |
25124 | ||
25125 | # Restrict incoming rate from each host, with a default | |
25126 | # set using a macro and special cases looked up in a table. | |
25127 | defer | |
25128 | message = Sender rate exceeds $sender_rate_limit \ | |
25129 | messages per $sender_rate_period | |
25130 | ratelimit = ${lookup {$sender_host_address} \ | |
25131 | cdb {DB/ratelimits.cdb} \ | |
25132 | {$value} {RATELIMIT} } | |
9b371988 PH |
25133 | .endd |
25134 | &*Warning*&: If you have a busy server with a lot of &%ratelimit%& tests, | |
25135 | especially with the &%per_rcpt%& option, you may suffer from a performance | |
068aaea8 PH |
25136 | bottleneck caused by locking on the ratelimit hints database. Apart from |
25137 | making your ACLs less complicated, you can reduce the problem by using a | |
9b371988 | 25138 | RAM disk for Exim's hints directory (usually &_/var/spool/exim/db/_&). However |
068aaea8 PH |
25139 | this means that Exim will lose its hints data after a reboot (including retry |
25140 | hints, the callout cache, and ratelimit data). | |
9b371988 PH |
25141 | .wen |
25142 | ||
25143 | ||
25144 | .section "Address verification" "SECTaddressverification" | |
25145 | .cindex "verifying address" "options for" | |
25146 | .cindex "policy control" "address verification" | |
25147 | Several of the &%verify%& conditions described in section | |
25148 | &<<SECTaclconditions>>& cause addresses to be verified. These conditions can be | |
25149 | followed by options that modify the verification process. The options are | |
25150 | separated from the keyword and from each other by slashes, and some of them | |
25151 | contain parameters. For example: | |
25152 | .code | |
25153 | verify = sender/callout | |
25154 | verify = recipient/defer_ok/callout=10s,defer_ok | |
25155 | .endd | |
168e428f | 25156 | The first stage of address verification, which always happens, is to run the |
9b371988 | 25157 | address through the routers, in &"verify mode"&. Routers can detect the |
168e428f | 25158 | difference between verification and routing for delivery, and their actions can |
9b371988 PH |
25159 | be varied by a number of generic options such as &%verify%& and &%verify_only%& |
25160 | (see chapter &<<CHAProutergeneric>>&). If routing fails, verification fails. | |
168e428f PH |
25161 | The available options are as follows: |
25162 | ||
9b371988 PH |
25163 | .ilist |
25164 | If the &%callout%& option is specified, successful routing to one or more | |
25165 | remote hosts is followed by a &"callout"& to those hosts as an additional | |
25166 | check. Callouts and their sub-options are discussed in the next section. | |
25167 | .next | |
25168 | If there is a defer error while doing verification routing, the ACL | |
25169 | normally returns &"defer"&. However, if you include &%defer_ok%& in the | |
25170 | options, the condition is forced to be true instead. Note that this is a main | |
168e428f | 25171 | verification option as well as a suboption for callouts. |
9b371988 PH |
25172 | .next |
25173 | The &%no_details%& option is covered in section &<<SECTsenaddver>>&, which | |
068aaea8 | 25174 | discusses the reporting of sender address verification failures. |
9b371988 PH |
25175 | .next |
25176 | .new | |
25177 | The &%success_on_redirect%& option causes verification always to succeed | |
068aaea8 PH |
25178 | immediately after a successful redirection. By default, if a redirection |
25179 | generates just one address, that address is also verified. See further | |
9b371988 PH |
25180 | discussion in section &<<SECTredirwhilveri>>&. |
25181 | .endlist | |
25182 | ||
25183 | .cindex "verifying address" "differentiating failures" | |
25184 | .cindex "&$recipient_verify_failure$&" | |
25185 | .cindex "&$sender_verify_failure$&" | |
25186 | .cindex "&$acl_verify_message$&" | |
25187 | After an address verification failure, &$acl_verify_message$& contains the | |
25188 | error message that is associated with the failure. It can be preserved by | |
25189 | coding like this: | |
25190 | .code | |
25191 | warn !verify = sender | |
25192 | set acl_m0 = $acl_verify_message | |
25193 | .endd | |
068aaea8 PH |
25194 | If you are writing your own custom rejection message or log message when |
25195 | denying access, you can use this variable to include information about the | |
25196 | verification failure. | |
9b371988 | 25197 | .wen |
068aaea8 | 25198 | |
9b371988 | 25199 | In addition, &$sender_verify_failure$& or &$recipient_verify_failure$& (as |
068aaea8 | 25200 | appropriate) contains one of the following words: |
168e428f | 25201 | |
9b371988 PH |
25202 | .ilist |
25203 | &%qualify%&: The address was unqualified (no domain), and the message | |
168e428f | 25204 | was neither local nor came from an exempted host. |
9b371988 PH |
25205 | .next |
25206 | &%route%&: Routing failed. | |
25207 | .next | |
25208 | &%mail%&: Routing succeeded, and a callout was attempted; rejection | |
168e428f PH |
25209 | occurred at or before the MAIL command (that is, on initial |
25210 | connection, HELO, or MAIL). | |
9b371988 PH |
25211 | .next |
25212 | &%recipient%&: The RCPT command in a callout was rejected. | |
25213 | .next | |
25214 | &%postmaster%&: The postmaster check in a callout was rejected. | |
25215 | .endlist | |
168e428f | 25216 | |
168e428f PH |
25217 | The main use of these variables is expected to be to distinguish between |
25218 | rejections of MAIL and rejections of RCPT in callouts. | |
25219 | ||
25220 | ||
25221 | ||
25222 | ||
9b371988 PH |
25223 | .section "Callout verification" "SECTcallver" |
25224 | .cindex "verifying address" "by callout" | |
25225 | .cindex "callout" "verification" | |
25226 | .cindex "SMTP" "callout verification" | |
25227 | .new | |
168e428f PH |
25228 | For non-local addresses, routing verifies the domain, but is unable to do any |
25229 | checking of the local part. There are situations where some means of verifying | |
25230 | the local part is desirable. One way this can be done is to make an SMTP | |
9b371988 PH |
25231 | &'callback'& to a delivery host for the sender address or a &'callforward'& to |
25232 | a subsequent host for a recipient address, to see if the host accepts the | |
25233 | address. We use the term &'callout'& to cover both cases. Note that for a | |
25234 | sender address, the callback is not to the client host that is trying to | |
25235 | deliver the message, but to one of the hosts that accepts incoming mail for the | |
25236 | sender's domain. | |
068aaea8 | 25237 | |
068aaea8 | 25238 | Exim does not do callouts by default. If you want them to happen, you must |
9b371988 | 25239 | request them by setting appropriate options on the &%verify%& condition, as |
068aaea8 PH |
25240 | described below. This facility should be used with care, because it can add a |
25241 | lot of resource usage to the cost of verifying an address. However, Exim does | |
25242 | cache the results of callouts, which helps to reduce the cost. Details of | |
9b371988 PH |
25243 | caching are in section &<<SECTcallvercache>>&. |
25244 | .wen | |
168e428f PH |
25245 | |
25246 | Recipient callouts are usually used only between hosts that are controlled by | |
25247 | the same administration. For example, a corporate gateway host could use | |
068aaea8 PH |
25248 | callouts to check for valid recipients on an internal mailserver. A successful |
25249 | callout does not guarantee that a real delivery to the address would succeed; | |
25250 | on the other hand, a failing callout does guarantee that a delivery would fail. | |
168e428f | 25251 | |
9b371988 | 25252 | If the &%callout%& option is present on a condition that verifies an address, a |
168e428f | 25253 | second stage of verification occurs if the address is successfully routed to |
9b371988 PH |
25254 | one or more remote hosts. The usual case is routing by a &(dnslookup)& or a |
25255 | &(manualroute)& router, where the router specifies the hosts. However, if a | |
25256 | router that does not set up hosts routes to an &(smtp)& transport with a | |
25257 | &%hosts%& setting, the transport's hosts are used. If an &(smtp)& transport has | |
25258 | &%hosts_override%& set, its hosts are always used, whether or not the router | |
168e428f PH |
25259 | supplies a host list. |
25260 | ||
25261 | The port that is used is taken from the transport, if it is specified and is a | |
25262 | remote transport. (For routers that do verification only, no transport need be | |
25263 | specified.) Otherwise, the default SMTP port is used. If a remote transport | |
25264 | specifies an outgoing interface, this is used; otherwise the interface is not | |
25265 | specified. | |
25266 | ||
25267 | For a sender callout check, Exim makes SMTP connections to the remote hosts, to | |
25268 | test whether a bounce message could be delivered to the sender address. The | |
25269 | following SMTP commands are sent: | |
9b371988 PH |
25270 | .display |
25271 | &`HELO `&<&'smtp active host name'&> | |
25272 | &`MAIL FROM:<>`& | |
25273 | &`RCPT TO:`&<&'the address to be tested'&> | |
25274 | &`QUIT`& | |
25275 | .endd | |
25276 | LHLO is used instead of HELO if the transport's &%protocol%& option is | |
25277 | set to &"lmtp"&. | |
168e428f PH |
25278 | |
25279 | A recipient callout check is similar. By default, it also uses an empty address | |
25280 | for the sender. This default is chosen because most hosts do not make use of | |
25281 | the sender address when verifying a recipient. Using the same address means | |
25282 | that a single cache entry can be used for each recipient. Some sites, however, | |
25283 | do make use of the sender address when verifying. These are catered for by the | |
9b371988 | 25284 | &%use_sender%& and &%use_postmaster%& options, described in the next section. |
168e428f | 25285 | |
9b371988 PH |
25286 | If the response to the RCPT command is a 2&'xx'& code, the verification |
25287 | succeeds. If it is 5&'xx'&, the verification fails. For any other condition, | |
168e428f | 25288 | Exim tries the next host, if any. If there is a problem with all the remote |
9b371988 PH |
25289 | hosts, the ACL yields &"defer"&, unless the &%defer_ok%& parameter of the |
25290 | &%callout%& option is given, in which case the condition is forced to succeed. | |
168e428f PH |
25291 | |
25292 | ||
25293 | ||
25294 | ||
168e428f | 25295 | |
9b371988 PH |
25296 | .section "Additional parameters for callouts" "CALLaddparcall" |
25297 | .cindex "callout" "additional parameters for" | |
25298 | The &%callout%& option can be followed by an equals sign and a number of | |
25299 | optional parameters, separated by commas. For example: | |
25300 | .code | |
25301 | verify = recipient/callout=10s,defer_ok | |
25302 | .endd | |
25303 | The old syntax, which had &%callout_defer_ok%& and &%check_postmaster%& as | |
168e428f | 25304 | separate verify options, is retained for backwards compatibility, but is now |
9b371988 | 25305 | deprecated. The additional parameters for &%callout%& are as follows: |
168e428f PH |
25306 | |
25307 | ||
9b371988 PH |
25308 | .vlist |
25309 | .vitem <&'a&~time&~interval'&> | |
25310 | .cindex "callout timeout" "specifying" | |
168e428f PH |
25311 | This specifies the timeout that applies for the callout attempt to each host. |
25312 | For example: | |
9b371988 PH |
25313 | .code |
25314 | verify = sender/callout=5s | |
25315 | .endd | |
168e428f PH |
25316 | The default is 30 seconds. The timeout is used for each response from the |
25317 | remote host. It is also used for the intial connection, unless overridden by | |
9b371988 | 25318 | the &%connect%& parameter. |
168e428f PH |
25319 | |
25320 | ||
9b371988 PH |
25321 | .vitem &*connect&~=&~*&<&'time&~interval'&> |
25322 | .cindex "callout connection timeout" "specifying" | |
168e428f PH |
25323 | This parameter makes it possible to set a different (usually smaller) timeout |
25324 | for making the SMTP connection. For example: | |
9b371988 PH |
25325 | .code |
25326 | verify = sender/callout=5s,connect=1s | |
25327 | .endd | |
168e428f PH |
25328 | If not specified, this timeout defaults to the general timeout value. |
25329 | ||
9b371988 PH |
25330 | .vitem &*defer_ok*& |
25331 | .cindex "callout defer" "action on" | |
168e428f PH |
25332 | When this parameter is present, failure to contact any host, or any other kind |
25333 | of temporary error, is treated as success by the ACL. However, the cache is not | |
25334 | updated in this circumstance. | |
25335 | ||
9b371988 PH |
25336 | .new |
25337 | .vitem &*fullpostmaster*& | |
25338 | .cindex "callout" "full postmaster check" | |
25339 | This operates like the &%postmaster%& option (see below), but if the check for | |
25340 | &'postmaster@domain'& fails, it tries just &'postmaster'&, without a domain, in | |
068aaea8 | 25341 | accordance with the specification in RFC 2821. The RFC states that the |
9b371988 PH |
25342 | unqualified address &'postmaster'& should be accepted. |
25343 | .wen | |
25344 | ||
25345 | ||
25346 | .vitem &*mailfrom&~=&~*&<&'email&~address'&> | |
25347 | .cindex "callout" "sender when verifying header" | |
25348 | When verifying addresses in header lines using the &%header_sender%& | |
25349 | verification option, Exim behaves by default as if the addresses are envelope | |
25350 | sender addresses from a message. Callout verification therefore tests to see | |
25351 | whether a bounce message could be delivered, by using an empty address in the | |
25352 | MAIL command. However, it is arguable that these addresses might never be used | |
25353 | as envelope senders, and could therefore justifiably reject bounce messages | |
25354 | (empty senders). The &%mailfrom%& callout parameter allows you to specify what | |
25355 | address to use in the MAIL command. For example: | |
25356 | .code | |
25357 | require verify = header_sender/callout=mailfrom=abcd@x.y.z | |
25358 | .endd | |
25359 | This parameter is available only for the &%header_sender%& verification option. | |
25360 | ||
25361 | ||
25362 | .vitem &*maxwait&~=&~*&<&'time&~interval'&> | |
25363 | .cindex "callout overall timeout" "specifying" | |
168e428f PH |
25364 | This parameter sets an overall timeout for performing a callout verification. |
25365 | For example: | |
9b371988 PH |
25366 | .code |
25367 | verify = sender/callout=5s,maxwait=30s | |
25368 | .endd | |
168e428f PH |
25369 | This timeout defaults to four times the callout timeout for individual SMTP |
25370 | commands. The overall timeout applies when there is more than one host that can | |
25371 | be tried. The timeout is checked before trying the next host. This prevents | |
25372 | very long delays if there are a large number of hosts and all are timing out | |
25373 | (for example, when network connections are timing out). | |
25374 | ||
25375 | ||
9b371988 PH |
25376 | .vitem &*no_cache*& |
25377 | .cindex "callout cache" "suppressing" | |
25378 | .cindex "caching callout" "suppressing" | |
168e428f PH |
25379 | When this parameter is given, the callout cache is neither read nor updated. |
25380 | ||
9b371988 PH |
25381 | .vitem &*postmaster*& |
25382 | .cindex "callout" "postmaster; checking" | |
168e428f | 25383 | When this parameter is set, a sucessful callout check is followed by a similar |
9b371988 PH |
25384 | check for the local part &'postmaster'& at the same domain. If this address is |
25385 | rejected, the callout fails (but see &%fullpostmaster%& above). The result of | |
25386 | the postmaster check is recorded in a cache record; if it is a failure, this is | |
068aaea8 PH |
25387 | used to fail subsequent callouts for the domain without a connection being |
25388 | made, until the cache record expires. | |
168e428f | 25389 | |
9b371988 | 25390 | .vitem &*postmaster_mailfrom&~=&~*&<&'email&~address'&> |
168e428f PH |
25391 | The postmaster check uses an empty sender in the MAIL command by default. |
25392 | You can use this parameter to do a postmaster check using a different address. | |
25393 | For example: | |
9b371988 PH |
25394 | .code |
25395 | require verify = sender/callout=postmaster_mailfrom=abc@x.y.z | |
25396 | .endd | |
25397 | If both &%postmaster%& and &%postmaster_mailfrom%& are present, the rightmost | |
25398 | one overrides. The &%postmaster%& parameter is equivalent to this example: | |
25399 | .code | |
25400 | require verify = sender/callout=postmaster_mailfrom= | |
25401 | .endd | |
25402 | &*Warning*&: The caching arrangements for postmaster checking do not take | |
168e428f PH |
25403 | account of the sender address. It is assumed that either the empty address or |
25404 | a fixed non-empty address will be used. All that Exim remembers is that the | |
25405 | postmaster check for the domain succeeded or failed. | |
25406 | ||
25407 | ||
9b371988 PH |
25408 | .vitem &*random*& |
25409 | .cindex "callout" "&""random""& check" | |
168e428f | 25410 | When this parameter is set, before doing the normal callout check, Exim does a |
9b371988 PH |
25411 | check for a &"random"& local part at the same domain. The local part is not |
25412 | really random &-- it is defined by the expansion of the option | |
25413 | &%callout_random_local_part%&, which defaults to | |
25414 | .code | |
25415 | $primary_host_name-$tod_epoch-testing | |
25416 | .endd | |
168e428f PH |
25417 | The idea here is to try to determine whether the remote host accepts all local |
25418 | parts without checking. If it does, there is no point in doing callouts for | |
9b371988 | 25419 | specific local parts. If the &"random"& check succeeds, the result is saved in |
168e428f PH |
25420 | a cache record, and used to force the current and subsequent callout checks to |
25421 | succeed without a connection being made, until the cache record expires. | |
25422 | ||
9b371988 PH |
25423 | .vitem &*use_postmaster*& |
25424 | .cindex "callout" "sender for recipient check" | |
168e428f | 25425 | This parameter applies to recipient callouts only. For example: |
9b371988 PH |
25426 | .code |
25427 | deny !verify = recipient/callout=use_postmaster | |
25428 | .endd | |
25429 | .new | |
25430 | .cindex "&$qualify_domain$&" | |
068aaea8 | 25431 | It causes a non-empty postmaster address to be used in the MAIL command when |
9b371988 PH |
25432 | performing the callout for the recipient, and also for a &"random"& check if |
25433 | that is configured. The local part of the address is &`postmaster`& and the | |
25434 | domain is the contents of &$qualify_domain$&. | |
25435 | .wen | |
168e428f | 25436 | |
9b371988 | 25437 | .vitem &*use_sender*& |
168e428f | 25438 | This option applies to recipient callouts only. For example: |
9b371988 PH |
25439 | .code |
25440 | require verify = recipient/callout=use_sender | |
25441 | .endd | |
168e428f PH |
25442 | It causes the message's actual sender address to be used in the MAIL |
25443 | command when performing the callout, instead of an empty address. There is no | |
25444 | need to use this option unless you know that the called hosts make use of the | |
25445 | sender when checking recipients. If used indiscriminately, it reduces the | |
25446 | usefulness of callout caching. | |
9b371988 | 25447 | .endlist |
168e428f PH |
25448 | |
25449 | If you use any of the parameters that set a non-empty sender for the MAIL | |
9b371988 PH |
25450 | command (&%mailfrom%&, &%postmaster_mailfrom%&, &%use_postmaster%&, or |
25451 | &%use_sender%&), you should think about possible loops. Recipient checking is | |
168e428f PH |
25452 | usually done between two hosts that are under the same management, and the host |
25453 | that receives the callouts is not normally configured to do callouts itself. | |
9b371988 | 25454 | Therefore, it is normally safe to use &%use_postmaster%& or &%use_sender%& in |
168e428f PH |
25455 | these circumstances. |
25456 | ||
25457 | However, if you use a non-empty sender address for a callout to an arbitrary | |
25458 | host, there is the likelihood that the remote host will itself initiate a | |
25459 | callout check back to your host. As it is checking what appears to be a message | |
25460 | sender, it is likely to use an empty address in MAIL, thus avoiding a | |
25461 | callout loop. However, to be on the safe side it would be best to set up your | |
25462 | own ACLs so that they do not do sender verification checks when the recipient | |
25463 | is the address you use for header sender or postmaster callout checking. | |
25464 | ||
25465 | Another issue to think about when using non-empty senders for callouts is | |
9b371988 PH |
25466 | caching. When you set &%mailfrom%& or &%use_sender%&, the cache record is keyed |
25467 | by the sender/recipient combination; thus, for any given recipient, many more | |
168e428f PH |
25468 | actual callouts are performed than when an empty sender or postmaster is used. |
25469 | ||
25470 | ||
25471 | ||
25472 | ||
9b371988 PH |
25473 | .section "Callout caching" "SECTcallvercache" |
25474 | .cindex "hints database" "callout cache" | |
25475 | .cindex "callout" "caching" | |
25476 | .cindex "caching" "callout" | |
168e428f | 25477 | Exim caches the results of callouts in order to reduce the amount of resources |
9b371988 PH |
25478 | used, unless you specify the &%no_cache%& parameter with the &%callout%& |
25479 | option. A hints database called &"callout"& is used for the cache. Two | |
25480 | different record types are used: one records the result of a callout check for | |
25481 | a specific address, and the other records information that applies to the | |
25482 | entire domain (for example, that it accepts the local part &'postmaster'&). | |
168e428f PH |
25483 | |
25484 | When an original callout fails, a detailed SMTP error message is given about | |
25485 | the failure. However, for subsequent failures use the cache data, this message | |
25486 | is not available. | |
25487 | ||
25488 | The expiry times for negative and positive address cache records are | |
9b371988 PH |
25489 | independent, and can be set by the global options &%callout_negative_expire%& |
25490 | (default 2h) and &%callout_positive_expire%& (default 24h), respectively. | |
168e428f PH |
25491 | |
25492 | If a host gives a negative response to an SMTP connection, or rejects any | |
25493 | commands up to and including | |
9b371988 PH |
25494 | .code |
25495 | MAIL FROM:<> | |
25496 | .endd | |
168e428f PH |
25497 | (but not including the MAIL command with a non-empty address), |
25498 | any callout attempt is bound to fail. Exim remembers such failures in a | |
25499 | domain cache record, which it uses to fail callouts for the domain without | |
25500 | making new connections, until the domain record times out. There are two | |
25501 | separate expiry times for domain cache records: | |
9b371988 PH |
25502 | &%callout_domain_negative_expire%& (default 3h) and |
25503 | &%callout_domain_positive_expire%& (default 7d). | |
168e428f PH |
25504 | |
25505 | Domain records expire when the negative expiry time is reached if callouts | |
25506 | cannot be made for the domain, or if the postmaster check failed. | |
25507 | Otherwise, they expire when the positive expiry time is reached. This | |
9b371988 | 25508 | ensures that, for example, a host that stops accepting &"random"& local parts |
168e428f PH |
25509 | will eventually be noticed. |
25510 | ||
25511 | The callout caching mechanism is based on the domain of the address that is | |
25512 | being tested. If the domain routes to several hosts, it is assumed that their | |
25513 | behaviour will be the same. | |
25514 | ||
25515 | ||
25516 | ||
9b371988 PH |
25517 | .section "Sender address verification reporting" "SECTsenaddver" |
25518 | .cindex "verifying" "suppressing error details" | |
168e428f PH |
25519 | When sender verification fails in an ACL, the details of the failure are |
25520 | given as additional output lines before the 550 response to the relevant | |
25521 | SMTP command (RCPT or DATA). For example, if sender callout is in use, | |
25522 | you might see: | |
9b371988 PH |
25523 | .code |
25524 | MAIL FROM:<xyz@abc.example> | |
25525 | 250 OK | |
25526 | RCPT TO:<pqr@def.example> | |
25527 | 550-Verification failed for <xyz@abc.example> | |
25528 | 550-Called: 192.168.34.43 | |
25529 | 550-Sent: RCPT TO:<xyz@abc.example> | |
25530 | 550-Response: 550 Unknown local part xyz in <xyz@abc.example> | |
25531 | 550 Sender verification failed | |
25532 | .endd | |
168e428f PH |
25533 | If more than one RCPT command fails in the same way, the details are given |
25534 | only for the first of them. However, some administrators do not want to send | |
25535 | out this much information. You can suppress the details by adding | |
9b371988 | 25536 | &"/no_details"& to the ACL statement that requests sender verification. For |
168e428f | 25537 | example: |
9b371988 PH |
25538 | .code |
25539 | verify = sender/no_details | |
25540 | .endd | |
168e428f | 25541 | |
9b371988 PH |
25542 | .section "Redirection while verifying" "SECTredirwhilveri" |
25543 | .cindex "verifying" "redirection while" | |
25544 | .cindex "address redirection" "while verifying" | |
168e428f PH |
25545 | A dilemma arises when a local address is redirected by aliasing or forwarding |
25546 | during verification: should the generated addresses themselves be verified, | |
25547 | or should the successful expansion of the original address be enough to verify | |
068aaea8 | 25548 | it? By default, Exim takes the following pragmatic approach: |
168e428f | 25549 | |
9b371988 PH |
25550 | .ilist |
25551 | When an incoming address is redirected to just one child address, verification | |
168e428f PH |
25552 | continues with the child address, and if that fails to verify, the original |
25553 | verification also fails. | |
9b371988 PH |
25554 | .next |
25555 | When an incoming address is redirected to more than one child address, | |
168e428f | 25556 | verification does not continue. A success result is returned. |
9b371988 | 25557 | .endlist |
168e428f PH |
25558 | |
25559 | This seems the most reasonable behaviour for the common use of aliasing as a | |
25560 | way of redirecting different local parts to the same mailbox. It means, for | |
25561 | example, that a pair of alias entries of the form | |
9b371988 PH |
25562 | .code |
25563 | A.Wol: aw123 | |
25564 | aw123: :fail: Gone away, no forwarding address | |
25565 | .endd | |
168e428f PH |
25566 | work as expected, with both local parts causing verification failure. When a |
25567 | redirection generates more than one address, the behaviour is more like a | |
25568 | mailing list, where the existence of the alias itself is sufficient for | |
25569 | verification to succeed. | |
25570 | ||
9b371988 | 25571 | .new |
068aaea8 PH |
25572 | It is possible, however, to change the default behaviour so that all successful |
25573 | redirections count as successful verifications, however many new addresses are | |
9b371988 PH |
25574 | generated. This is specified by the &%success_on_redirect%& verification |
25575 | option. For example: | |
25576 | .code | |
25577 | require verify = recipient/success_on_redirect/callout=10s | |
25578 | .endd | |
068aaea8 PH |
25579 | In this example, verification succeeds if a router generates a new address, and |
25580 | the callout does not occur, because no address was routed to a remote host. | |
9b371988 | 25581 | .wen |
068aaea8 PH |
25582 | |
25583 | ||
25584 | ||
25585 | ||
9b371988 PH |
25586 | .new |
25587 | .section "Client SMTP authorization (CSA)" "SECTverifyCSA" | |
25588 | .cindex "CSA" "verifying" | |
068aaea8 PH |
25589 | Client SMTP Authorization is a system that allows a site to advertise |
25590 | which machines are and are not permitted to send email. This is done by placing | |
25591 | special SRV records in the DNS; these are looked up using the client's HELO | |
25592 | domain. At the time of writing, CSA is still an Internet Draft. Client SMTP | |
25593 | Authorization checks in Exim are performed by the ACL condition: | |
9b371988 PH |
25594 | .code |
25595 | verify = csa | |
25596 | .endd | |
068aaea8 PH |
25597 | This fails if the client is not authorized. If there is a DNS problem, or if no |
25598 | valid CSA SRV record is found, or if the client is authorized, the condition | |
25599 | succeeds. These three cases can be distinguished using the expansion variable | |
9b371988 PH |
25600 | &$csa_status$&, which can take one of the values &"fail"&, &"defer"&, |
25601 | &"unknown"&, or &"ok"&. The condition does not itself defer because that would | |
068aaea8 PH |
25602 | be likely to cause problems for legitimate email. |
25603 | ||
068aaea8 | 25604 | The error messages produced by the CSA code include slightly more |
9b371988 | 25605 | detail. If &$csa_status$& is &"defer"&, this may be because of problems |
068aaea8 | 25606 | looking up the CSA SRV record, or problems looking up the CSA target |
9b371988 PH |
25607 | address record. There are four reasons for &$csa_status$& being &"fail"&: |
25608 | ||
25609 | .ilist | |
25610 | The client's host name is explicitly not authorized. | |
25611 | .next | |
25612 | The client's IP address does not match any of the CSA target IP addresses. | |
25613 | .next | |
25614 | The client's host name is authorized but it has no valid target IP addresses | |
068aaea8 | 25615 | (for example, the target's addresses are IPv6 and the client is using IPv4). |
9b371988 PH |
25616 | .next |
25617 | The client's host name has no CSA SRV record but a parent domain has asserted | |
068aaea8 | 25618 | that all subdomains must be explicitly authorized. |
9b371988 | 25619 | .endlist |
068aaea8 | 25620 | |
9b371988 | 25621 | The &%csa%& verification condition can take an argument which is the domain to |
068aaea8 | 25622 | use for the DNS query. The default is: |
9b371988 PH |
25623 | .code |
25624 | verify = csa/$sender_helo_name | |
25625 | .endd | |
068aaea8 PH |
25626 | This implementation includes an extension to CSA. If the query domain |
25627 | is an address literal such as [192.0.2.95], or if it is a bare IP | |
25628 | address, Exim searches for CSA SRV records in the reverse DNS as if | |
9b371988 | 25629 | the HELO domain was (for example) &'95.2.0.192.in-addr.arpa'&. Therefore it is |
068aaea8 | 25630 | meaningful to say: |
9b371988 PH |
25631 | .code |
25632 | verify = csa/$sender_host_address | |
25633 | .endd | |
068aaea8 PH |
25634 | In fact, this is the check that Exim performs if the client does not say HELO. |
25635 | This extension can be turned off by setting the main configuration option | |
9b371988 | 25636 | &%dns_csa_use_reverse%& to be false. |
068aaea8 | 25637 | |
068aaea8 PH |
25638 | If a CSA SRV record is not found for the domain itself, a search |
25639 | is performed through its parent domains for a record which might be | |
25640 | making assertions about subdomains. The maximum depth of this search is limited | |
9b371988 | 25641 | using the main configuration option &%dns_csa_search_limit%&, which is 5 by |
068aaea8 PH |
25642 | default. Exim does not look for CSA SRV records in a top level domain, so the |
25643 | default settings handle HELO domains as long as seven | |
9b371988 PH |
25644 | (&'hostname.five.four.three.two.one.com'&). This encompasses the vast majority |
25645 | of legitimate HELO domains. | |
068aaea8 | 25646 | |
9b371988 | 25647 | The &'dnsdb'& lookup also has support for CSA. Although &'dnsdb'& also supports |
068aaea8 | 25648 | direct SRV lookups, this is not sufficient because of the extra parent domain |
9b371988 | 25649 | search behaviour of CSA, and (as with PTR lookups) &'dnsdb'& also turns IP |
068aaea8 PH |
25650 | addresses into lookups in the reverse DNS space. The result of a successful |
25651 | lookup such as: | |
9b371988 | 25652 | .code |
068aaea8 | 25653 | ${lookup dnsdb {csa=$sender_helo_name}} |
9b371988 | 25654 | .endd |
068aaea8 | 25655 | has two space-separated fields: an authorization code and a target host name. |
9b371988 PH |
25656 | The authorization code can be &"Y"& for yes, &"N"& for no, &"X"& for explicit |
25657 | authorization required but absent, or &"?"& for unknown. | |
068aaea8 PH |
25658 | |
25659 | ||
25660 | ||
25661 | ||
9b371988 PH |
25662 | .section "Bounce address tag validation" "SECTverifyPRVS" |
25663 | .cindex "BATV" "verifying" | |
068aaea8 | 25664 | Bounce address tag validation (BATV) is a scheme whereby the envelope senders |
9b371988 | 25665 | of outgoing messages have a cryptographic, timestamped &"tag"& added to them. |
068aaea8 PH |
25666 | Genuine incoming bounce messages should therefore always be addressed to |
25667 | recipients that have a valid tag. This scheme is a way of detecting unwanted | |
9b371988 PH |
25668 | bounce messages caused by sender address forgeries (often called &"collateral |
25669 | spam"&), because the recipients of such messages will not include valid tags. | |
068aaea8 | 25670 | |
068aaea8 | 25671 | There are two expansion items to help with the implementation of the BATV |
9b371988 | 25672 | &"prvs"& (private signature) scheme in an Exim configuration. This scheme signs |
068aaea8 | 25673 | the original envelope sender address by using a simple shared key to add a hash |
9b371988 PH |
25674 | of the address and some time-based randomizing information. The &%prvs%& |
25675 | expansion item creates a signed address, and the &%prvscheck%& expansion item | |
068aaea8 | 25676 | checks one. The syntax of these expansion items is described in section |
9b371988 | 25677 | &<<SECTexpansionitems>>&. |
068aaea8 | 25678 | |
068aaea8 PH |
25679 | As an example, suppose the secret per-address keys are stored in an MySQL |
25680 | database. A query to look up the key for an address could be defined as a macro | |
25681 | like this: | |
9b371988 | 25682 | .code |
068aaea8 PH |
25683 | PRVSCHECK_SQL = ${lookup mysql{SELECT secret FROM batv_prvs \ |
25684 | WHERE sender='${quote_mysql:$prvscheck_address}'\ | |
25685 | }{$value}} | |
9b371988 | 25686 | .endd |
068aaea8 | 25687 | Suppose also that the senders who make use of BATV are defined by an address |
9b371988 | 25688 | list called &%batv_senders%&. Then, in the ACL for RCPT commands, you could |
068aaea8 | 25689 | use this: |
9b371988 | 25690 | .code |
068aaea8 PH |
25691 | # Bounces: drop unsigned addresses for BATV senders |
25692 | deny message = This address does not send an unsigned reverse path. | |
25693 | senders = : | |
25694 | recipients = +batv_senders | |
25695 | ||
25696 | # Bounces: In case of prvs-signed address, check signature. | |
25697 | deny message = Invalid reverse path signature. | |
25698 | senders = : | |
25699 | condition = ${prvscheck {$local_part@$domain}\ | |
25700 | {PRVSCHECK_SQL}{1}} | |
25701 | !condition = $prvscheck_result | |
9b371988 | 25702 | .endd |
068aaea8 PH |
25703 | The first statement rejects recipients for bounce messages that are addressed |
25704 | to plain BATV sender addresses, because it is known that BATV senders do not | |
25705 | send out messages with plain sender addresses. The second statement rejects | |
25706 | recipients that are prvs-signed, but with invalid signatures (either because | |
25707 | the key is wrong, or the signature has timed out). | |
25708 | ||
068aaea8 | 25709 | A non-prvs-signed address is not rejected by the second statement, because the |
9b371988 PH |
25710 | &%prvscheck%& expansion yields an empty string if its first argument is not a |
25711 | prvs-signed address, thus causing the &%condition%& condition to be false. If | |
25712 | the first argument is a syntactically valid prvs-signed address, the yield is | |
25713 | the third string (in this case &"1"&), whether or not the cryptographic and | |
25714 | timeout checks succeed. The &$prvscheck_result$& variable contains the result | |
25715 | of the checks (empty for failure, &"1"& for success). | |
25716 | ||
068aaea8 PH |
25717 | Of course, when you accept a prvs-signed address, you have to ensure that the |
25718 | routers accept it and deliver it correctly. The easiest way to handle this is | |
9b371988 | 25719 | to use a &(redirect)& router to remove the signature with a configuration along |
068aaea8 | 25720 | these lines: |
9b371988 | 25721 | .code |
068aaea8 PH |
25722 | batv_redirect: |
25723 | driver = redirect | |
25724 | data = ${prvscheck {$local_part@$domain}{PRVSCHECK_SQL}} | |
9b371988 PH |
25725 | .endd |
25726 | This works because, if the third argument of &%prvscheck%& is empty, the result | |
068aaea8 PH |
25727 | of the expansion of a prvs-signed address is the decoded value of the original |
25728 | address. This router should probably be the first of your routers that handles | |
25729 | local addresses. | |
25730 | ||
068aaea8 PH |
25731 | To create BATV-signed addresses in the first place, a transport of this form |
25732 | can be used: | |
9b371988 | 25733 | .code |
068aaea8 PH |
25734 | external_smtp_batv: |
25735 | driver = smtp | |
25736 | return_path = ${prvs {$return_path} \ | |
25737 | {${lookup mysql{SELECT \ | |
25738 | secret FROM batv_prvs WHERE \ | |
25739 | sender='${quote_mysql:$sender_address}'} \ | |
25740 | {$value}fail}}} | |
9b371988 | 25741 | .endd |
068aaea8 | 25742 | If no key can be found for the existing return path, no signing takes place. |
9b371988 | 25743 | .wen |
068aaea8 PH |
25744 | |
25745 | ||
168e428f | 25746 | |
9b371988 PH |
25747 | .section "Using an ACL to control relaying" "SECTrelaycontrol" |
25748 | .cindex "&ACL;" "relay control" | |
25749 | .cindex "relaying" "control by ACL" | |
25750 | .cindex "policy control" "relay control" | |
25751 | An MTA is said to &'relay'& a message if it receives it from some host and | |
168e428f PH |
25752 | delivers it directly to another host as a result of a remote address contained |
25753 | within it. Redirecting a local address via an alias or forward file and then | |
25754 | passing the message on to another host is not relaying, | |
9b371988 PH |
25755 | .cindex "&""percent hack""&" |
25756 | but a redirection as a result of the &"percent hack"& is. | |
168e428f | 25757 | |
9b371988 | 25758 | Two kinds of relaying exist, which are termed &"incoming"& and &"outgoing"&. |
168e428f PH |
25759 | A host which is acting as a gateway or an MX backup is concerned with incoming |
25760 | relaying from arbitrary hosts to a specific set of domains. On the other hand, | |
25761 | a host which is acting as a smart host for a number of clients is concerned | |
25762 | with outgoing relaying from those clients to the Internet at large. Often the | |
25763 | same host is fulfilling both functions, | |
9b371988 PH |
25764 | . /// |
25765 | . as illustrated in the diagram below, | |
25766 | . /// | |
168e428f PH |
25767 | but in principle these two kinds of relaying are entirely independent. What is |
25768 | not wanted is the transmission of mail from arbitrary remote hosts through your | |
25769 | system to arbitrary domains. | |
25770 | ||
25771 | ||
25772 | You can implement relay control by means of suitable statements in the ACL that | |
25773 | runs for each RCPT command. For convenience, it is often easiest to use | |
25774 | Exim's named list facility to define the domains and hosts involved. For | |
25775 | example, suppose you want to do the following: | |
25776 | ||
9b371988 PH |
25777 | .ilist |
25778 | Deliver a number of domains to mailboxes on the local host (or process them | |
25779 | locally in some other way). Let's say these are &'my.dom1.example'& and | |
25780 | &'my.dom2.example'&. | |
25781 | .next | |
25782 | Relay mail for a number of other domains for which you are the secondary MX. | |
25783 | These might be &'friend1.example'& and &'friend2.example'&. | |
25784 | .next | |
25785 | Relay mail from the hosts on your local LAN, to whatever domains are involved. | |
168e428f | 25786 | Suppose your LAN is 192.168.45.0/24. |
9b371988 | 25787 | .endlist |
168e428f PH |
25788 | |
25789 | ||
25790 | In the main part of the configuration, you put the following definitions: | |
9b371988 PH |
25791 | .code |
25792 | domainlist local_domains = my.dom1.example : my.dom2.example | |
25793 | domainlist relay_domains = friend1.example : friend2.example | |
25794 | hostlist relay_hosts = 192.168.45.0/24 | |
25795 | .endd | |
168e428f PH |
25796 | Now you can use these definitions in the ACL that is run for every RCPT |
25797 | command: | |
9b371988 PH |
25798 | .code |
25799 | acl_check_rcpt: | |
25800 | accept domains = +local_domains : +relay_domains | |
25801 | accept hosts = +relay_hosts | |
25802 | .endd | |
168e428f PH |
25803 | The first statement accepts any RCPT command that contains an address in |
25804 | the local or relay domains. For any other domain, control passes to the second | |
25805 | statement, which accepts the command only if it comes from one of the relay | |
25806 | hosts. In practice, you will probably want to make your ACL more sophisticated | |
25807 | than this, for example, by including sender and recipient verification. The | |
25808 | default configuration includes a more comprehensive example, which is described | |
9b371988 | 25809 | in chapter &<<CHAPdefconfil>>&. |
168e428f PH |
25810 | |
25811 | ||
25812 | ||
9b371988 PH |
25813 | .section "Checking a relay configuration" "SECTcheralcon" |
25814 | .cindex "relaying" "checking control of" | |
168e428f PH |
25815 | You can check the relay characteristics of your configuration in the same way |
25816 | that you can test any ACL behaviour for an incoming SMTP connection, by using | |
9b371988 | 25817 | the &%-bh%& option to run a fake SMTP session with which you interact. |
168e428f PH |
25818 | |
25819 | For specifically testing for unwanted relaying, the host | |
9b371988 | 25820 | &'relay-test.mail-abuse.org'& provides a useful service. If you telnet to this |
168e428f PH |
25821 | host from the host on which Exim is running, using the normal telnet port, you |
25822 | will see a normal telnet connection message and then quite a long delay. Be | |
25823 | patient. The remote host is making an SMTP connection back to your host, and | |
25824 | trying a number of common probes to test for open relay vulnerability. The | |
25825 | results of the tests will eventually appear on your terminal. | |
25826 | ||
25827 | ||
25828 | ||
25829 | ||
9b371988 PH |
25830 | . //////////////////////////////////////////////////////////////////////////// |
25831 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 25832 | |
9b371988 PH |
25833 | .chapter "Content scanning at ACL time" "CHAPexiscan" |
25834 | .cindex "content scanning" "at ACL time" | |
068aaea8 | 25835 | The extension of Exim to include content scanning at ACL time, formerly known |
9b371988 | 25836 | as &"exiscan"&, was originally implemented as a patch by Tom Kistner. The code |
068aaea8 PH |
25837 | was integrated into the main source for Exim release 4.50, and Tom continues to |
25838 | maintain it. Most of the wording of this chapter is taken from Tom's | |
25839 | specification. | |
25840 | ||
9b371988 | 25841 | .new |
068aaea8 | 25842 | It is also possible to scan the content of messages at other times. The |
9b371988 | 25843 | &[local_scan()]& function (see chapter &<<CHAPlocalscan>>&) allows for content |
068aaea8 | 25844 | scanning after all the ACLs have run. A transport filter can be used to scan |
9b371988 PH |
25845 | messages at delivery time (see the &%transport_filter%& option, described in |
25846 | chapter &<<CHAPtransportgeneric>>&). | |
25847 | .wen | |
068aaea8 PH |
25848 | |
25849 | If you want to include the ACL-time content-scanning features when you compile | |
25850 | Exim, you need to arrange for WITH_CONTENT_SCAN to be defined in your | |
9b371988 PH |
25851 | &_Local/Makefile_&. When you do that, the Exim binary is built with: |
25852 | ||
25853 | .ilist | |
25854 | .new | |
25855 | Two additional ACLs (&%acl_smtp_mime%& and &%acl_not_smtp_mime%&) that are run | |
25856 | for all MIME parts for SMTP and non-SMTP messages, respectively. | |
25857 | .wen | |
25858 | .next | |
25859 | Additional ACL conditions and modifiers: &%decode%&, &%malware%&, | |
25860 | &%mime_regex%&, &%regex%&, and &%spam%&. These can be used in the ACL that is | |
25861 | run at the end of message reception (the &%acl_smtp_data%& ACL). | |
25862 | .next | |
25863 | An additional control feature (&"no_mbox_unspool"&) that saves spooled copies | |
168e428f | 25864 | of messages, or parts of messages, for debugging purposes. |
9b371988 PH |
25865 | .next |
25866 | Additional expansion variables that are set in the new ACL and by the new | |
168e428f | 25867 | conditions. |
9b371988 PH |
25868 | .next |
25869 | Two new main configuration options: &%av_scanner%& and &%spamd_address%&. | |
25870 | .endlist | |
168e428f | 25871 | |
9b371988 PH |
25872 | There is another content-scanning configuration option for &_Local/Makefile_&, |
25873 | called WITH_OLD_DEMIME. If this is set, the old, deprecated &%demime%& ACL | |
168e428f PH |
25874 | condition is compiled, in addition to all the other content-scanning features. |
25875 | ||
25876 | Content-scanning is continually evolving, and new features are still being | |
25877 | added. While such features are still unstable and liable to incompatible | |
25878 | changes, they are made available in Exim by setting options whose names begin | |
9b371988 | 25879 | EXPERIMENTAL_ in &_Local/Makefile_&. Such features are not documented in |
168e428f | 25880 | this manual. You can find out about them by reading the file called |
9b371988 | 25881 | &_doc/experimental.txt_&. |
168e428f PH |
25882 | |
25883 | All the content-scanning facilites work on a MBOX copy of the message that is | |
25884 | temporarily created in a file called: | |
9b371988 PH |
25885 | .display |
25886 | <&'spool_directory'&>&`/scan/`&<&'message_id'&>/<&'message_id'&>&`.eml`& | |
25887 | .endd | |
25888 | The &_.eml_& extension is a friendly hint to virus scanners that they can | |
168e428f PH |
25889 | expect an MBOX-like structure inside that file. The file is created when the |
25890 | first content scanning facility is called. Subsequent calls to content | |
25891 | scanning conditions open the same file again. The directory is recursively | |
9b371988 PH |
25892 | removed when the &%acl_smtp_data%& ACL has finished running, unless |
25893 | .code | |
25894 | control = no_mbox_unspool | |
25895 | .endd | |
168e428f PH |
25896 | has been encountered. When the MIME ACL decodes files, they are put into the |
25897 | same directory by default. | |
25898 | ||
25899 | ||
25900 | ||
9b371988 PH |
25901 | .section "Scanning for viruses" "SECTscanvirus" |
25902 | .cindex "virus scanning" | |
25903 | .cindex "content scanning" "for viruses" | |
25904 | .cindex "content scanning" "the &%malware%& condition" | |
25905 | The &%malware%& ACL condition lets you connect virus scanner software to Exim. | |
25906 | It supports a &"generic"& interface to scanners called via the shell, and | |
25907 | specialized interfaces for &"daemon"& type virus scanners, which are resident | |
25908 | in memory and thus are much faster. | |
168e428f | 25909 | |
9b371988 PH |
25910 | .cindex "&%av_scanner%&" |
25911 | You can set the &%av_scanner%& option in first part of the Exim configuration | |
168e428f PH |
25912 | file to specify which scanner to use, together with any additional options that |
25913 | are needed. The basic syntax is as follows: | |
9b371988 PH |
25914 | .display |
25915 | &`av_scanner = <`&&'scanner-type'&&`>:<`&&'option1'&&`>:<`&&'option2'&&`>:[...]`& | |
25916 | .endd | |
25917 | If you do not set &%av_scanner%&, it defaults to | |
25918 | .code | |
25919 | av_scanner = sophie:/var/run/sophie | |
25920 | .endd | |
25921 | If the value of &%av_scanner%& starts with dollar character, it is expanded | |
25922 | before use. The following scanner types are supported in this release: | |
25923 | ||
25924 | .vlist | |
25925 | .vitem &%aveserver%& | |
25926 | .cindex "virus scanners" "Kaspersky" | |
168e428f | 25927 | This is the scanner daemon of Kaspersky Version 5. You can get a trial version |
9b371988 PH |
25928 | at &url(http://www.kaspersky.com). This scanner type takes one option, |
25929 | which is the path to the daemon's UNIX socket. The default is shown in this | |
25930 | example: | |
25931 | .code | |
25932 | av_scanner = aveserver:/var/run/aveserver | |
25933 | .endd | |
168e428f | 25934 | |
9b371988 PH |
25935 | .vitem &%clamd%& |
25936 | .cindex "virus scanners" "clamd" | |
168e428f | 25937 | This daemon-type scanner is GPL and free. You can get it at |
9b371988 PH |
25938 | &url(http://www.clamav.net/). Some older versions of clamd do not seem to |
25939 | unpack MIME containers, so it used to be recommended to unpack MIME attachments | |
25940 | in the MIME ACL. This no longer believed to be necessary. One option is | |
25941 | required: either the path and name of a UNIX socket file, or a hostname or IP | |
25942 | number, and a port, separated by space, as in the second of these examples: | |
25943 | .code | |
25944 | av_scanner = clamd:/opt/clamd/socket | |
25945 | av_scanner = clamd:192.168.2.100 1234 | |
25946 | .endd | |
25947 | If the option is unset, the default is &_/tmp/clamd_&. Thanks to David Saez for | |
168e428f PH |
25948 | contributing the code for this scanner. |
25949 | ||
9b371988 PH |
25950 | .vitem &%cmdline%& |
25951 | .cindex "virus scanners" "command line interface" | |
168e428f PH |
25952 | This is the keyword for the generic command line scanner interface. It can be |
25953 | used to attach virus scanners that are invoked from the shell. This scanner | |
25954 | type takes 3 mandatory options: | |
168e428f | 25955 | |
9b371988 PH |
25956 | .olist |
25957 | The full path and name of the scanner binary, with all command line options, | |
25958 | and a placeholder (&`%s`&) for the directory to scan. | |
25959 | ||
25960 | .next | |
25961 | A regular expression to match against the STDOUT and STDERR output of the | |
168e428f | 25962 | virus scanner. If the expression matches, a virus was found. You must make |
9b371988 PH |
25963 | absolutely sure that this expression matches on &"virus found"&. This is called |
25964 | the &"trigger"& expression. | |
168e428f | 25965 | |
9b371988 PH |
25966 | .next |
25967 | Another regular expression, containing exactly one pair of parentheses, to | |
168e428f | 25968 | match the name of the virus found in the scanners output. This is called the |
9b371988 PH |
25969 | &"name"& expression. |
25970 | .endlist olist | |
168e428f | 25971 | |
9b371988 PH |
25972 | For example, Sophos Sweep reports a virus on a line like this: |
25973 | .code | |
25974 | Virus 'W32/Magistr-B' found in file ./those.bat | |
25975 | .endd | |
25976 | For the trigger expression, we can just match the word &"found"&. For the name | |
168e428f PH |
25977 | expression, we want to extract the W32/Magistr-B string, so we can match for |
25978 | the single quotes left and right of it. Altogether, this makes the | |
25979 | configuration setting: | |
9b371988 | 25980 | .code |
168e428f PH |
25981 | av_scanner = cmdline:\ |
25982 | /path/to/sweep -all -rec -archive %s:\ | |
25983 | found:'(.+)' | |
9b371988 PH |
25984 | .endd |
25985 | .vitem &%drweb%& | |
25986 | .cindex "virus scanners" "DrWeb" | |
25987 | The DrWeb daemon scanner (&url(http://www.sald.com/)) interface takes one | |
168e428f | 25988 | argument, either a full path to a UNIX socket, or an IP address and port |
068aaea8 | 25989 | separated by white space, as in these examples: |
9b371988 PH |
25990 | .code |
25991 | av_scanner = drweb:/var/run/drwebd.sock | |
25992 | av_scanner = drweb:192.168.2.20 31337 | |
25993 | .endd | |
25994 | If you omit the argument, the default path &_/usr/local/drweb/run/drwebd.sock_& | |
168e428f PH |
25995 | is used. Thanks to Alex Miller for contributing the code for this scanner. |
25996 | ||
9b371988 PH |
25997 | .vitem &%fsecure%& |
25998 | .cindex "virus scanners" "F-Secure" | |
25999 | The F-Secure daemon scanner (&url(http://www.f-secure.com)) takes one | |
26000 | argument which is the path to a UNIX socket. For example: | |
26001 | .code | |
26002 | av_scanner = fsecure:/path/to/.fsav | |
26003 | .endd | |
26004 | If no argument is given, the default is &_/var/run/.fsav_&. Thanks to Johan | |
168e428f PH |
26005 | Thelmen for contributing the code for this scanner. |
26006 | ||
9b371988 PH |
26007 | .vitem &%kavdaemon%& |
26008 | .cindex "virus scanners" "Kaspersky" | |
168e428f | 26009 | This is the scanner daemon of Kaspersky Version 4. This version of the |
9b371988 | 26010 | Kaspersky scanner is outdated. Please upgrade (see &%aveserver%& above). This |
168e428f PH |
26011 | scanner type takes one option, which is the path to the daemon's UNIX socket. |
26012 | For example: | |
9b371988 PH |
26013 | .code |
26014 | av_scanner = kavdaemon:/opt/AVP/AvpCtl | |
26015 | .endd | |
26016 | The default path is &_/var/run/AvpCtl_&. | |
168e428f | 26017 | |
9b371988 PH |
26018 | .vitem &%mksd%& |
26019 | .cindex "virus scanners" "mksd" | |
168e428f PH |
26020 | This is a daemon type scanner that is aimed mainly at Polish users, though some |
26021 | parts of documentation are now available in English. You can get it at | |
9b371988 PH |
26022 | &url(http://linux.mks.com.pl/). The only option for this scanner type is |
26023 | the maximum number of processes used simultaneously to scan the attachments, | |
168e428f PH |
26024 | provided that the demime facility is employed and also provided that mksd has |
26025 | been run with at least the same number of child processes. For example: | |
9b371988 PH |
26026 | .code |
26027 | av_scanner = mksd:2 | |
26028 | .endd | |
168e428f PH |
26029 | You can safely omit this option (the default value is 1). |
26030 | ||
9b371988 PH |
26031 | .vitem &%sophie%& |
26032 | .cindex "virus scanners" "Sophos and Sophie" | |
26033 | Sophie is a daemon that uses Sophos' &%libsavi%& library to scan for viruses. | |
26034 | You can get Sophie at &url(http://www.vanja.com/tools/sophie/). The only | |
26035 | option for this scanner type is the path to the UNIX socket that Sophie uses | |
26036 | for client communication. For example: | |
26037 | .code | |
26038 | av_scanner = sophie:/tmp/sophie | |
26039 | .endd | |
26040 | The default path is &_/var/run/sophie_&, so if you are using this, you can omit | |
168e428f | 26041 | the option. |
9b371988 PH |
26042 | .endlist |
26043 | ||
26044 | .new | |
26045 | When &%av_scanner%& is correctly set, you can use the &%malware%& condition in | |
26046 | the DATA ACL. &*Note*&: You cannot use the &%malware%& condition in the MIME | |
26047 | ACL. | |
26048 | .wen | |
26049 | ||
26050 | The &%av_scanner%& option is expanded each time &%malware%& is called. This | |
26051 | makes it possible to use different scanners. See further below for an example. | |
26052 | The &%malware%& condition caches its results, so when you use it multiple times | |
26053 | for the same message, the actual scanning process is only carried out once. | |
26054 | However, using expandable items in &%av_scanner%& disables this caching, in | |
26055 | which case each use of the &%malware%& condition causes a new scan of the | |
26056 | message. | |
168e428f | 26057 | |
9b371988 | 26058 | The &%malware%& condition takes a right-hand argument that is expanded before |
168e428f PH |
26059 | use. It can then be one of |
26060 | ||
9b371988 PH |
26061 | .ilist |
26062 | &"true"&, &"*"&, or &"1"&, in which case the message is scanned for viruses. | |
168e428f PH |
26063 | The condition succeeds if a virus was found, and fail otherwise. This is the |
26064 | recommended usage. | |
9b371988 PH |
26065 | .next |
26066 | &"false"& or &"0"&, in which case no scanning is done and the condition fails | |
168e428f | 26067 | immediately. |
9b371988 PH |
26068 | .next |
26069 | A regular expression, in which case the message is scanned for viruses. The | |
168e428f PH |
26070 | condition succeeds if a virus is found and its name matches the regular |
26071 | expression. This allows you to take special actions on certain types of virus. | |
9b371988 | 26072 | .endlist |
168e428f | 26073 | |
9b371988 PH |
26074 | You can append &`/defer_ok`& to the &%malware%& condition to accept messages |
26075 | even if there is a problem with the virus scanner. | |
168e428f | 26076 | |
9b371988 | 26077 | .cindex "&$malware_name$&" |
168e428f | 26078 | When a virus is found, the condition sets up an expansion variable called |
9b371988 PH |
26079 | &$malware_name$& that contains the name of the virus. You can use it in a |
26080 | &%message%& modifier that specifies the error returned to the sender, and/or in | |
168e428f PH |
26081 | logging data. |
26082 | ||
26083 | If your virus scanner cannot unpack MIME and TNEF containers itself, you should | |
9b371988 PH |
26084 | use the &%demime%& condition (see section &<<SECTdemimecond>>&) before the |
26085 | &%malware%& condition. | |
168e428f PH |
26086 | |
26087 | Here is a very simple scanning example: | |
9b371988 PH |
26088 | .code |
26089 | deny message = This message contains malware ($malware_name) | |
168e428f PH |
26090 | demime = * |
26091 | malware = * | |
9b371988 | 26092 | .endd |
168e428f | 26093 | The next example accepts messages when there is a problem with the scanner: |
9b371988 PH |
26094 | .code |
26095 | deny message = This message contains malware ($malware_name) | |
168e428f PH |
26096 | demime = * |
26097 | malware = */defer_ok | |
9b371988 | 26098 | .endd |
168e428f PH |
26099 | The next example shows how to use an ACL variable to scan with both sophie and |
26100 | aveserver. It assumes you have set: | |
9b371988 PH |
26101 | .code |
26102 | av_scanner = $acl_m0 | |
26103 | .endd | |
168e428f | 26104 | in the main Exim configuration. |
9b371988 PH |
26105 | .code |
26106 | deny message = This message contains malware ($malware_name) | |
168e428f PH |
26107 | set acl_m0 = sophie |
26108 | malware = * | |
26109 | ||
9b371988 | 26110 | deny message = This message contains malware ($malware_name) |
168e428f PH |
26111 | set acl_m0 = aveserver |
26112 | malware = * | |
9b371988 | 26113 | .endd |
168e428f PH |
26114 | |
26115 | ||
9b371988 PH |
26116 | .section "Scanning with SpamAssassin" "SECTscanspamass" |
26117 | .cindex "content scanning" "for spam" | |
26118 | .cindex "spam scanning" | |
26119 | .cindex "SpamAssassin" "scanning with" | |
26120 | The &%spam%& ACL condition calls SpamAssassin's &%spamd%& daemon to get a spam | |
168e428f | 26121 | score and a report for the message. You can get SpamAssassin at |
9b371988 PH |
26122 | &url(http://www.spamassassin.org), or, if you have a working Perl |
26123 | installation, you can use CPAN by running: | |
26124 | .code | |
26125 | perl -MCPAN -e 'install Mail::SpamAssassin' | |
26126 | .endd | |
168e428f PH |
26127 | SpamAssassin has its own set of configuration files. Please review its |
26128 | documentation to see how you can tweak it. The default installation should work | |
26129 | nicely, however. | |
26130 | ||
9b371988 PH |
26131 | .cindex "&%spamd_address%&" |
26132 | After having installed and configured SpamAssassin, start the &%spamd%& daemon. | |
168e428f | 26133 | By default, it listens on 127.0.0.1, TCP port 783. If you use another host or |
9b371988 PH |
26134 | port for &%spamd%&, you must set the &%spamd_address%& option in the global |
26135 | part of the Exim configuration as follows (example): | |
26136 | .code | |
26137 | spamd_address = 192.168.99.45 387 | |
26138 | .endd | |
168e428f | 26139 | You do not need to set this option if you use the default. As of version 2.60, |
9b371988 PH |
26140 | &%spamd%& also supports communication over UNIX sockets. If you want to use |
26141 | these, supply &%spamd_address%& with an absolute file name instead of a | |
168e428f | 26142 | address/port pair: |
9b371988 PH |
26143 | .code |
26144 | spamd_address = /var/run/spamd_socket | |
26145 | .endd | |
26146 | You can have multiple &%spamd%& servers to improve scalability. These can | |
26147 | reside on other hardware reachable over the network. To specify multiple | |
26148 | &%spamd%& servers, put multiple address/port pairs in the &%spamd_address%& | |
26149 | option, separated with colons: | |
26150 | .code | |
168e428f PH |
26151 | spamd_address = 192.168.2.10 783 : \ |
26152 | 192.168.2.11 783 : \ | |
26153 | 192.168.2.12 783 | |
9b371988 PH |
26154 | .endd |
26155 | Up to 32 &%spamd%& servers are supported. The servers are queried in a random | |
068aaea8 | 26156 | fashion. When a server fails to respond to the connection attempt, all other |
9b371988 | 26157 | servers are tried until one succeeds. If no server responds, the &%spam%& |
168e428f PH |
26158 | condition defers. |
26159 | ||
9b371988 PH |
26160 | &*Warning*&: It is not possible to use the UNIX socket connection method with |
26161 | multiple &%spamd%& servers. | |
168e428f | 26162 | |
168e428f | 26163 | |
9b371988 PH |
26164 | .section "Calling SpamAssassin from an Exim ACL" |
26165 | Here is a simple example of the use of the &%spam%& condition in a DATA ACL: | |
26166 | .code | |
26167 | deny message = This message was classified as SPAM | |
26168 | spam = joe | |
26169 | .endd | |
26170 | The right-hand side of the &%spam%& condition specifies the username that | |
168e428f PH |
26171 | SpamAssassin should scan for. If you do not want to scan for a particular user, |
26172 | but rather use the SpamAssassin system-wide default profile, you can scan for | |
9b371988 | 26173 | an unknown user, or simply use &"nobody"&. However, you must put something on |
068aaea8 | 26174 | the right-hand side. |
168e428f PH |
26175 | |
26176 | The username allows you to use per-domain or per-user antispam profiles. The | |
26177 | right-hand side is expanded before being used, so you can put lookups or | |
9b371988 | 26178 | conditions there. When the right-hand side evaluates to &"0"& or &"false"&, no |
168e428f PH |
26179 | scanning is done and the condition fails immediately. |
26180 | ||
9b371988 | 26181 | .new |
068aaea8 PH |
26182 | Scanning with SpamAssassin uses a lot of resources. If you scan every message, |
26183 | large ones may cause significant performance degredation. As most spam messages | |
26184 | are quite small, it is recommended that you do not scan the big ones. For | |
26185 | example: | |
9b371988 | 26186 | .code |
068aaea8 PH |
26187 | deny message = This message was classified as SPAM |
26188 | condition = ${if < {$message_size}{10K}} | |
26189 | spam = nobody | |
9b371988 PH |
26190 | .endd |
26191 | .wen | |
068aaea8 | 26192 | |
9b371988 | 26193 | The &%spam%& condition returns true if the threshold specified in the user's |
168e428f | 26194 | SpamAssassin profile has been matched or exceeded. If you want to use the |
9b371988 PH |
26195 | &%spam%& condition for its side effects (see the variables below), you can make |
26196 | it always return &"true"& by appending &`:true`& to the username. | |
168e428f | 26197 | |
9b371988 PH |
26198 | .cindex "spam scanning" "returned variables" |
26199 | When the &%spam%& condition is run, it sets up the following expansion | |
168e428f PH |
26200 | variables: |
26201 | ||
9b371988 PH |
26202 | .vlist |
26203 | .vitem &$spam_score$& | |
26204 | The spam score of the message, for example &"3.4"& or &"30.5"&. This is useful | |
168e428f PH |
26205 | for inclusion in log or reject messages. |
26206 | ||
9b371988 | 26207 | .vitem &$spam_score_int$& |
168e428f | 26208 | The spam score of the message, multiplied by ten, as an integer value. For |
9b371988 | 26209 | example &"34"& or &"305"&. This is useful for numeric comparisons in |
168e428f PH |
26210 | conditions. This variable is special; it is saved with the message, and written |
26211 | to Exim's spool file. This means that it can be used during the whole life of | |
26212 | the message on your Exim system, in particular, in routers or transports during | |
26213 | the later delivery phase. | |
26214 | ||
9b371988 PH |
26215 | .vitem &$spam_bar$& |
26216 | A string consisting of a number of &"+"& or &"-"& characters, representing the | |
168e428f | 26217 | integer part of the spam score value. A spam score of 4.4 would have a |
9b371988 PH |
26218 | &$spam_bar$& value of &"++++"&. This is useful for inclusion in warning |
26219 | headers, since MUAs can match on such strings. | |
168e428f | 26220 | |
9b371988 | 26221 | .vitem &$spam_report$& |
168e428f PH |
26222 | A multiline text table, containing the full SpamAssassin report for the |
26223 | message. Useful for inclusion in headers or reject messages. | |
9b371988 | 26224 | .endlist |
168e428f | 26225 | |
9b371988 | 26226 | The &%spam%& condition caches its results. If you call it again with the same |
168e428f PH |
26227 | user name, it does not scan again, but rather returns the same values as |
26228 | before. | |
26229 | ||
9b371988 | 26230 | The &%spam%& condition returns DEFER if there is any error while running the |
168e428f | 26231 | message through SpamAssassin. If you want to treat DEFER as FAIL (to pass on to |
9b371988 | 26232 | the next ACL statement block), append &`/defer_ok`& to the right-hand side of |
168e428f | 26233 | the spam condition, like this: |
9b371988 PH |
26234 | .code |
26235 | deny message = This message was classified as SPAM | |
26236 | spam = joe/defer_ok | |
26237 | .endd | |
26238 | This causes messages to be accepted even if there is a problem with &%spamd%&. | |
168e428f | 26239 | |
9b371988 | 26240 | Here is a longer, commented example of the use of the &%spam%& |
168e428f | 26241 | condition: |
9b371988 PH |
26242 | .code |
26243 | # put headers in all messages (no matter if spam or not) | |
26244 | warn message = X-Spam-Score: $spam_score ($spam_bar) | |
26245 | spam = nobody:true | |
26246 | warn message = X-Spam-Report: $spam_report | |
26247 | spam = nobody:true | |
26248 | ||
26249 | # add second subject line with *SPAM* marker when message | |
26250 | # is over threshold | |
26251 | warn message = Subject: *SPAM* $h_Subject: | |
26252 | spam = nobody | |
26253 | ||
26254 | # reject spam at high scores (> 12) | |
26255 | deny message = This message scored $spam_score spam points. | |
26256 | spam = nobody:true | |
26257 | condition = ${if >{$spam_score_int}{120}{1}{0}} | |
26258 | .endd | |
26259 | ||
26260 | ||
26261 | ||
26262 | .section "Scanning MIME parts" "SECTscanmimepart" | |
26263 | .cindex "content scanning" "MIME parts" | |
26264 | .cindex "MIME content scanning" | |
26265 | .cindex "&%acl_smtp_mime%&" | |
26266 | .new | |
26267 | The &%acl_smtp_mime%& global option specifies an ACL that is called once for | |
26268 | each MIME part of an SMTP message, including multipart types, in the sequence | |
26269 | of their position in the message. Similarly, the &%acl_not_smtp_mime%& option | |
068aaea8 PH |
26270 | specifies an ACL that is used for the MIME parts of non-SMTP messages. These |
26271 | options may both refer to the same ACL if you want the same processing in both | |
26272 | cases. | |
26273 | ||
9b371988 PH |
26274 | These ACLs are called (possibly many times) just before the &%acl_smtp_data%& |
26275 | ACL in the case of an SMTP message, or just before a non-SMTP message is | |
26276 | accepted. However, a MIME ACL is called only if the message contains a | |
26277 | &'MIME-Version:'& header line. When a call to a MIME ACL does not yield | |
26278 | &"accept"&, ACL processing is aborted and the appropriate result code is sent | |
26279 | to the client. In the case of an SMTP message, the &%acl_smtp_data%& ACL is not | |
26280 | called when this happens. | |
26281 | ||
26282 | You cannot use the &%malware%& or &%spam%& conditions in a MIME ACL; these can | |
26283 | only be used in the DATA or non-SMTP ACLs. However, you can use the &%regex%& | |
26284 | condition to match against the raw MIME part. You can also use the | |
26285 | &%mime_regex%& condition to match against the decoded MIME part (see section | |
26286 | &<<SECTscanregex>>&). | |
26287 | .wen | |
168e428f | 26288 | |
068aaea8 | 26289 | At the start of a MIME ACL, a number of variables are set from the header |
168e428f PH |
26290 | information for the relevant MIME part. These are described below. The contents |
26291 | of the MIME part are not by default decoded into a disk file except for MIME | |
9b371988 PH |
26292 | parts whose content-type is &"message/rfc822"&. If you want to decode a MIME |
26293 | part into a disk file, you can use the &%decode%& modifier. The general syntax | |
068aaea8 | 26294 | is: |
9b371988 PH |
26295 | .display |
26296 | &`decode = [/`&<&'path'&>&`/]`&<&'filename'&> | |
26297 | .endd | |
168e428f PH |
26298 | The right hand side is expanded before use. After expansion, |
26299 | the value can be: | |
26300 | ||
9b371988 PH |
26301 | .olist |
26302 | &"0"& or &"false"&, in which case no decoding is done. | |
26303 | .next | |
26304 | The string &"default"&. In that case, the file is put in the temporary | |
26305 | &"default"& directory <&'spool_directory'&>&_/scan/_&<&'message_id'&>&_/_& with | |
26306 | a sequential file name consisting of the message id and a sequence number. The | |
26307 | full path and name is available in &$mime_decoded_filename$& after decoding. | |
26308 | .next | |
26309 | A full path name starting with a slash. If the full name is an existing | |
168e428f PH |
26310 | directory, it is used as a replacement for the default directory. The filename |
26311 | is then sequentially assigned. If the path does not exist, it is used as | |
26312 | the full path and file name. | |
9b371988 PH |
26313 | .next |
26314 | If the string does not start with a slash, it is used as the | |
168e428f | 26315 | filename, and the default path is then used. |
9b371988 | 26316 | .endlist |
168e428f PH |
26317 | |
26318 | You can easily decode a file with its original, proposed filename using | |
9b371988 PH |
26319 | .code |
26320 | decode = $mime_filename | |
26321 | .endd | |
26322 | However, you should keep in mind that &$mime_filename$& might contain | |
168e428f PH |
26323 | anything. If you place files outside of the default path, they are not |
26324 | automatically unlinked. | |
26325 | ||
26326 | For RFC822 attachments (these are messages attached to messages, with a | |
9b371988 PH |
26327 | content-type of &"message/rfc822"&), the ACL is called again in the same manner |
26328 | as for the primary message, only that the &$mime_is_rfc822$& expansion | |
168e428f PH |
26329 | variable is set (see below). Attached messages are always decoded to disk |
26330 | before being checked, and the files are unlinked once the check is done. | |
26331 | ||
9b371988 | 26332 | The MIME ACL supports the &%regex%& and &%mime_regex%& conditions. These can be |
168e428f | 26333 | used to match regular expressions against raw and decoded MIME parts, |
9b371988 | 26334 | respectively. They are described in section &<<SECTscanregex>>&. |
168e428f | 26335 | |
9b371988 | 26336 | .cindex "MIME content scanning" "returned variables" |
168e428f PH |
26337 | The following list describes all expansion variables that are |
26338 | available in the MIME ACL: | |
26339 | ||
9b371988 PH |
26340 | .vlist |
26341 | .vitem &$mime_boundary$& | |
26342 | If the current part is a multipart (see &$mime_is_multipart$&) below, it should | |
168e428f | 26343 | have a boundary string, which is stored in this variable. If the current part |
9b371988 PH |
26344 | has no boundary parameter in the &'Content-Type:'& header, this variable |
26345 | contains the empty string. | |
168e428f | 26346 | |
9b371988 | 26347 | .vitem &$mime_charset$& |
168e428f | 26348 | This variable contains the character set identifier, if one was found in the |
9b371988 PH |
26349 | &'Content-Type:'& header. Examples for charset identifiers are: |
26350 | .code | |
26351 | us-ascii | |
26352 | gb2312 (Chinese) | |
26353 | iso-8859-1 | |
26354 | .endd | |
168e428f PH |
26355 | Please note that this value is not normalized, so you should do matches |
26356 | case-insensitively. | |
26357 | ||
9b371988 PH |
26358 | .vitem &$mime_content_description$& |
26359 | This variable contains the normalized content of the &'Content-Description:'& | |
168e428f PH |
26360 | header. It can contain a human-readable description of the parts content. Some |
26361 | implementations repeat the filename for attachments here, but they are usually | |
26362 | only used for display purposes. | |
26363 | ||
9b371988 PH |
26364 | .vitem &$mime_content_disposition$& |
26365 | This variable contains the normalized content of the &'Content-Disposition:'& | |
26366 | header. You can expect strings like &"attachment"& or &"inline"& here. | |
168e428f | 26367 | |
9b371988 PH |
26368 | .vitem &$mime_content_id$& |
26369 | This variable contains the normalized content of the &'Content-ID:'& header. | |
168e428f PH |
26370 | This is a unique ID that can be used to reference a part from another part. |
26371 | ||
9b371988 PH |
26372 | .vitem &$mime_content_size$& |
26373 | This variable is set only after the &%decode%& modifier (see above) has been | |
168e428f PH |
26374 | successfully run. It contains the size of the decoded part in kilobytes. The |
26375 | size is always rounded up to full kilobytes, so only a completely empty part | |
9b371988 | 26376 | has a &$mime_content_size$& of zero. |
168e428f | 26377 | |
9b371988 | 26378 | .vitem &$mime_content_transfer_encoding$& |
168e428f | 26379 | This variable contains the normalized content of the |
9b371988 PH |
26380 | &'Content-transfer-encoding:'& header. This is a symbolic name for an encoding |
26381 | type. Typical values are &"base64"& and &"quoted-printable"&. | |
168e428f | 26382 | |
9b371988 PH |
26383 | .vitem &$mime_content_type$& |
26384 | If the MIME part has a &'Content-Type:'& header, this variable contains its | |
26385 | value, lowercased, and without any options (like &"name"& or &"charset"&). Here | |
168e428f | 26386 | are some examples of popular MIME types, as they may appear in this variable: |
9b371988 PH |
26387 | .code |
26388 | text/plain | |
26389 | text/html | |
26390 | application/octet-stream | |
26391 | image/jpeg | |
26392 | audio/midi | |
26393 | .endd | |
26394 | If the MIME part has no &'Content-Type:'& header, this variable contains the | |
168e428f PH |
26395 | empty string. |
26396 | ||
9b371988 PH |
26397 | .vitem &$mime_decoded_filename$& |
26398 | This variable is set only after the &%decode%& modifier (see above) has been | |
168e428f PH |
26399 | successfully run. It contains the full path and file name of the file |
26400 | containing the decoded data. | |
9b371988 | 26401 | .endlist |
168e428f | 26402 | |
9b371988 PH |
26403 | .cindex "RFC 2047" |
26404 | .vlist | |
26405 | .vitem &$mime_filename$& | |
168e428f PH |
26406 | This is perhaps the most important of the MIME variables. It contains a |
26407 | proposed filename for an attachment, if one was found in either the | |
9b371988 PH |
26408 | &'Content-Type:'& or &'Content-Disposition:'& headers. The filename will be |
26409 | RFC2047 decoded, but no additional sanity checks are done. If no filename was | |
26410 | found, this variable contains the empty string. | |
168e428f | 26411 | |
9b371988 PH |
26412 | .vitem &$mime_is_coverletter$& |
26413 | This variable attempts to differentiate the &"cover letter"& of an e-mail from | |
168e428f PH |
26414 | attached data. It can be used to clamp down on flashy or unneccessarily encoded |
26415 | content in the cover letter, while not restricting attachments at all. | |
9b371988 | 26416 | |
168e428f PH |
26417 | The variable contains 1 (true) for a MIME part believed to be part of the |
26418 | cover letter, and 0 (false) for an attachment. At present, the algorithm is as | |
26419 | follows: | |
168e428f | 26420 | |
9b371988 PH |
26421 | .olist |
26422 | The outermost MIME part of a message is always a cover letter. | |
26423 | ||
26424 | .next | |
26425 | If a multipart/alternative or multipart/related MIME part is a cover letter, | |
d1e83bff | 26426 | so are all MIME subparts within that multipart. |
168e428f | 26427 | |
9b371988 PH |
26428 | .next |
26429 | If any other multipart is a cover letter, the first subpart is a cover letter, | |
168e428f PH |
26430 | and the rest are attachments. |
26431 | ||
9b371988 PH |
26432 | .next |
26433 | All parts contained within an attachment multipart are attachments. | |
26434 | .endlist olist | |
26435 | ||
26436 | As an example, the following will ban &"HTML mail"& (including that sent with | |
168e428f PH |
26437 | alternative plain text), while allowing HTML files to be attached. HTML |
26438 | coverletter mail attached to non-HMTL coverletter mail will also be allowed: | |
9b371988 PH |
26439 | .code |
26440 | deny message = HTML mail is not accepted here | |
26441 | !condition = $mime_is_rfc822 | |
26442 | condition = $mime_is_coverletter | |
26443 | condition = ${if eq{$mime_content_type}{text/html}{1}{0}} | |
26444 | .endd | |
26445 | .vitem &$mime_is_multipart$& | |
168e428f | 26446 | This variable has the value 1 (true) when the current part has the main type |
9b371988 | 26447 | &"multipart"&, for example &"multipart/alternative"& or &"multipart/mixed"&. |
168e428f PH |
26448 | Since multipart entities only serve as containers for other parts, you may not |
26449 | want to carry out specific actions on them. | |
26450 | ||
9b371988 | 26451 | .vitem &$mime_is_rfc822$& |
168e428f PH |
26452 | This variable has the value 1 (true) if the current part is not a part of the |
26453 | checked message itself, but part of an attached message. Attached message | |
26454 | decoding is fully recursive. | |
26455 | ||
9b371988 | 26456 | .vitem &$mime_part_count$& |
168e428f PH |
26457 | This variable is a counter that is raised for each processed MIME part. It |
26458 | starts at zero for the very first part (which is usually a multipart). The | |
26459 | counter is per-message, so it is reset when processing RFC822 attachments (see | |
9b371988 | 26460 | &$mime_is_rfc822$&). The counter stays set after &%acl_smtp_mime%& is |
168e428f PH |
26461 | complete, so you can use it in the DATA ACL to determine the number of MIME |
26462 | parts of a message. For non-MIME messages, this variable contains the value -1. | |
9b371988 | 26463 | .endlist |
168e428f PH |
26464 | |
26465 | ||
26466 | ||
9b371988 PH |
26467 | .section "Scanning with regular expressions" "SECTscanregex" |
26468 | .cindex "content scanning" "with regular expressions" | |
26469 | .cindex "regular expressions" "content scanning with" | |
168e428f PH |
26470 | You can specify your own custom regular expression matches on the full body of |
26471 | the message, or on individual MIME parts. | |
26472 | ||
9b371988 | 26473 | The &%regex%& condition takes one or more regular expressions as arguments and |
168e428f | 26474 | matches them against the full message (when called in the DATA ACL) or a raw |
9b371988 | 26475 | MIME part (when called in the MIME ACL). The &%regex%& condition matches |
168e428f | 26476 | linewise, with a maximum line length of 32K characters. That means you cannot |
9b371988 | 26477 | have multiline matches with the &%regex%& condition. |
168e428f | 26478 | |
9b371988 | 26479 | The &%mime_regex%& condition can be called only in the MIME ACL. It matches up |
168e428f | 26480 | to 32K of decoded content (the whole content at once, not linewise). If the |
9b371988 PH |
26481 | part has not been decoded with the &%decode%& modifier earlier in the ACL, it |
26482 | is decoded automatically when &%mime_regex%& is executed (using default path | |
26483 | and filename values). If the decoded data is larger than 32K, only the first | |
26484 | 32K characters are checked. | |
168e428f PH |
26485 | |
26486 | The regular expressions are passed as a colon-separated list. To include a | |
26487 | literal colon, you must double it. Since the whole right-hand side string is | |
26488 | expanded before being used, you must also escape dollar signs and backslashes | |
9b371988 | 26489 | with more backslashes, or use the &`\N`& facility to disable expansion. |
168e428f | 26490 | Here is a simple example that contains two regular expressions: |
9b371988 PH |
26491 | .code |
26492 | deny message = contains blacklisted regex ($regex_match_string) | |
26493 | regex = [Mm]ortgage : URGENT BUSINESS PROPOSAL | |
26494 | .endd | |
168e428f | 26495 | The conditions returns true if any one of the regular expressions matches. The |
9b371988 | 26496 | &$regex_match_string$& expansion variable is then set up and contains the |
168e428f PH |
26497 | matching regular expression. |
26498 | ||
9b371988 | 26499 | &*Warning*&: With large messages, these conditions can be fairly |
168e428f PH |
26500 | CPU-intensive. |
26501 | ||
26502 | ||
26503 | ||
26504 | ||
9b371988 PH |
26505 | .section "The demime condition" "SECTdemimecond" |
26506 | .cindex "content scanning" "MIME checking" | |
26507 | .cindex "MIME content scanning" | |
26508 | The &%demime%& ACL condition provides MIME unpacking, sanity checking and file | |
068aaea8 | 26509 | extension blocking. It is usable only in the DATA and non-SMTP ACLs. The |
9b371988 PH |
26510 | &%demime%& condition uses a simpler interface to MIME decoding than the MIME |
26511 | ACL functionality, but provides no additional facilities. Please note that this | |
068aaea8 | 26512 | condition is deprecated and kept only for backward compatibility. You must set |
9b371988 PH |
26513 | the WITH_OLD_DEMIME option in &_Local/Makefile_& at build time to be able to |
26514 | use the &%demime%& condition. | |
168e428f | 26515 | |
9b371988 | 26516 | The &%demime%& condition unpacks MIME containers in the message. It detects |
168e428f PH |
26517 | errors in MIME containers and can match file extensions found in the message |
26518 | against a list. Using this facility produces files containing the unpacked MIME | |
26519 | parts of the message in the temporary scan directory. If you do antivirus | |
9b371988 PH |
26520 | scanning, it is recommened that you use the &%demime%& condition before the |
26521 | antivirus (&%malware%&) condition. | |
168e428f | 26522 | |
9b371988 PH |
26523 | On the right-hand side of the &%demime%& condition you can pass a |
26524 | colon-separated list of file extensions that it should match against. For | |
26525 | example: | |
26526 | .code | |
26527 | deny message = Found blacklisted file attachment | |
26528 | demime = vbs:com:bat:pif:prf:lnk | |
26529 | .endd | |
168e428f | 26530 | If one of the file extensions is found, the condition is true, otherwise it is |
9b371988 PH |
26531 | false. If there is a temporary error while demimeing (for example, &"disk |
26532 | full"&), the condition defers, and the message is temporarily rejected (unless | |
26533 | the condition is on a &%warn%& verb). | |
168e428f PH |
26534 | |
26535 | The right-hand side is expanded before being treated as a list, so you can have | |
9b371988 PH |
26536 | conditions and lookups there. If it expands to an empty string, &"false"&, or |
26537 | zero (&"0"&), no demimeing is done and the condition is false. | |
168e428f | 26538 | |
9b371988 | 26539 | The &%demime%& condition set the following variables: |
168e428f | 26540 | |
9b371988 PH |
26541 | .vlist |
26542 | .vitem &$demime_errorlevel$& | |
26543 | .cindex "&$demime_errorlevel$&" | |
168e428f PH |
26544 | When an error is detected in a MIME container, this variable contains the |
26545 | severity of the error, as an integer number. The higher the value, the more | |
068aaea8 PH |
26546 | severe the error (the current maximum value is 3). If this variable is unset or |
26547 | zero, no error occurred. | |
168e428f | 26548 | |
9b371988 PH |
26549 | .vitem &$demime_reason$& |
26550 | .cindex "&$demime_reason$&" | |
26551 | When &$demime_errorlevel$& is greater than zero, this variable contains a | |
168e428f | 26552 | human-readable text string describing the MIME error that occurred. |
9b371988 | 26553 | .endlist |
168e428f | 26554 | |
9b371988 PH |
26555 | .vlist |
26556 | .vitem &$found_extension$& | |
26557 | .cindex "&$found_extension$&" | |
26558 | When the &%demime%& condition is true, this variable contains the file | |
26559 | extension it found. | |
26560 | .endlist | |
168e428f | 26561 | |
9b371988 PH |
26562 | Both &$demime_errorlevel$& and &$demime_reason$& are set by the first call of |
26563 | the &%demime%& condition, and are not changed on subsequent calls. | |
168e428f | 26564 | |
9b371988 PH |
26565 | If you do not want to check for file extensions, but rather use the &%demime%& |
26566 | condition for unpacking or error checking purposes, pass &"*"& as the | |
168e428f PH |
26567 | right-hand side value. Here is a more elaborate example of how to use this |
26568 | facility: | |
9b371988 PH |
26569 | .code |
26570 | # Reject messages with serious MIME container errors | |
26571 | deny message = Found MIME error ($demime_reason). | |
26572 | demime = * | |
26573 | condition = ${if >{$demime_errorlevel}{2}{1}{0}} | |
168e428f | 26574 | |
9b371988 PH |
26575 | # Reject known virus spreading file extensions. |
26576 | # Accepting these is pretty much braindead. | |
26577 | deny message = contains $found_extension file (blacklisted). | |
26578 | demime = com:vbs:bat:pif:scr | |
168e428f | 26579 | |
9b371988 PH |
26580 | # Freeze .exe and .doc files. Postmaster can |
26581 | # examine them and eventually thaw them. | |
26582 | deny log_message = Another $found_extension file. | |
26583 | demime = exe:doc | |
26584 | control = freeze | |
26585 | .endd | |
168e428f PH |
26586 | |
26587 | ||
26588 | ||
26589 | ||
9b371988 PH |
26590 | . //////////////////////////////////////////////////////////////////////////// |
26591 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 26592 | |
9b371988 PH |
26593 | .chapter "Adding a local scan function to Exim" "CHAPlocalscan" &&& |
26594 | "Local scan function" | |
26595 | .cindex "&[local_scan()]& function" "description of" | |
26596 | .cindex "customizing" "input scan using C function" | |
26597 | .cindex "policy control" "by local scan function" | |
168e428f PH |
26598 | In these days of email worms, viruses, and ever-increasing spam, some sites |
26599 | want to apply a lot of checking to messages before accepting them. | |
26600 | ||
9b371988 | 26601 | The content scanning extension (chapter &<<CHAPexiscan>>&) has facilities for |
168e428f | 26602 | passing messages to external virus and spam scanning software. You can also do |
9b371988 | 26603 | a certain amount in Exim itself through string expansions and the &%condition%& |
168e428f | 26604 | condition in the ACL that runs after the SMTP DATA command or the ACL for |
9b371988 | 26605 | non-SMTP messages (see chapter &<<CHAPACL>>&), but this has its limitations. |
168e428f PH |
26606 | |
26607 | To allow for further customization to a site's own requirements, there is the | |
26608 | possibility of linking Exim with a private message scanning function, written | |
26609 | in C. If you want to run code that is written in something other than C, you | |
26610 | can of course use a little C stub to call it. | |
26611 | ||
26612 | The local scan function is run once for every incoming message, at the point | |
26613 | when Exim is just about to accept the message. | |
26614 | It can therefore be used to control non-SMTP messages from local processes as | |
26615 | well as messages arriving via SMTP. | |
26616 | ||
26617 | Exim applies a timeout to calls of the local scan function, and there is an | |
9b371988 PH |
26618 | option called &%local_scan_timeout%& for setting it. The default is 5 minutes. |
26619 | Zero means &"no timeout"&. | |
168e428f PH |
26620 | Exim also sets up signal handlers for SIGSEGV, SIGILL, SIGFPE, and SIGBUS |
26621 | before calling the local scan function, so that the most common types of crash | |
26622 | are caught. If the timeout is exceeded or one of those signals is caught, the | |
26623 | incoming message is rejected with a temporary error if it is an SMTP message. | |
26624 | For a non-SMTP message, the message is dropped and Exim ends with a non-zero | |
26625 | code. The incident is logged on the main and reject logs. | |
26626 | ||
26627 | ||
26628 | ||
9b371988 PH |
26629 | .section "Building Exim to use a local scan function" |
26630 | .cindex "&[local_scan()]& function" "building Exim to use" | |
168e428f PH |
26631 | To make use of the local scan function feature, you must tell Exim where your |
26632 | function is before building Exim, by setting LOCAL_SCAN_SOURCE in your | |
9b371988 | 26633 | &_Local/Makefile_&. A recommended place to put it is in the &_Local_& |
168e428f | 26634 | directory, so you might set |
9b371988 PH |
26635 | .code |
26636 | LOCAL_SCAN_SOURCE=Local/local_scan.c | |
26637 | .endd | |
26638 | for example. The function must be called &[local_scan()]&. It is called by | |
168e428f PH |
26639 | Exim after it has received a message, when the success return code is about to |
26640 | be sent. This is after all the ACLs have been run. The return code from your | |
26641 | function controls whether the message is actually accepted or not. There is a | |
26642 | commented template function (that just accepts the message) in the file | |
26643 | _src/local_scan.c_. | |
26644 | ||
26645 | If you want to make use of Exim's run time configuration file to set options | |
9b371988 PH |
26646 | for your &[local_scan()]& function, you must also set |
26647 | .code | |
26648 | LOCAL_SCAN_HAS_OPTIONS=yes | |
26649 | .endd | |
26650 | in &_Local/Makefile_& (see section &<<SECTconoptloc>>& below). | |
168e428f PH |
26651 | |
26652 | ||
26653 | ||
26654 | ||
9b371988 PH |
26655 | .section "API for local_scan()" "SECTapiforloc" |
26656 | .cindex "&[local_scan()]& function" "API description" | |
168e428f | 26657 | You must include this line near the start of your code: |
9b371988 PH |
26658 | .code |
26659 | #include "local_scan.h" | |
26660 | .endd | |
168e428f PH |
26661 | This header file defines a number of variables and other values, and the |
26662 | prototype for the function itself. Exim is coded to use unsigned char values | |
26663 | almost exclusively, and one of the things this header defines is a shorthand | |
9b371988 | 26664 | for &`unsigned char`& called &`uschar`&. |
168e428f PH |
26665 | It also contains the following macro definitions, to simplify casting character |
26666 | strings and pointers to character strings: | |
9b371988 PH |
26667 | .code |
26668 | #define CS (char *) | |
26669 | #define CCS (const char *) | |
26670 | #define CSS (char **) | |
26671 | #define US (unsigned char *) | |
26672 | #define CUS (const unsigned char *) | |
26673 | #define USS (unsigned char **) | |
26674 | .endd | |
26675 | The function prototype for &[local_scan()]& is: | |
26676 | .code | |
26677 | extern int local_scan(int fd, uschar **return_text); | |
26678 | .endd | |
168e428f PH |
26679 | The arguments are as follows: |
26680 | ||
9b371988 PH |
26681 | .ilist |
26682 | &%fd%& is a file descriptor for the file that contains the body of the message | |
168e428f | 26683 | (the -D file). The file is open for reading and writing, but updating it is not |
9b371988 PH |
26684 | recommended. &*Warning*&: You must &'not'& close this file descriptor. |
26685 | ||
168e428f PH |
26686 | The descriptor is positioned at character 19 of the file, which is the first |
26687 | character of the body itself, because the first 19 characters are the message | |
9b371988 | 26688 | id followed by &`-D`& and a newline. If you rewind the file, you should use the |
168e428f PH |
26689 | macro SPOOL_DATA_START_OFFSET to reset to the start of the data, just in |
26690 | case this changes in some future version. | |
9b371988 PH |
26691 | .next |
26692 | &%return_text%& is an address which you can use to return a pointer to a text | |
168e428f | 26693 | string at the end of the function. The value it points to on entry is NULL. |
9b371988 | 26694 | .endlist |
168e428f | 26695 | |
9b371988 | 26696 | The function must return an &%int%& value which is one of the following macros: |
168e428f | 26697 | |
9b371988 PH |
26698 | .vlist |
26699 | .vitem &`LOCAL_SCAN_ACCEPT`& | |
26700 | .cindex "&$local_scan_data$&" | |
168e428f | 26701 | The message is accepted. If you pass back a string of text, it is saved with |
9b371988 | 26702 | the message, and made available in the variable &$local_scan_data$&. No |
168e428f PH |
26703 | newlines are permitted (if there are any, they are turned into spaces) and the |
26704 | maximum length of text is 1000 characters. | |
26705 | ||
9b371988 | 26706 | .vitem &`LOCAL_SCAN_ACCEPT_FREEZE`& |
168e428f PH |
26707 | This behaves as LOCAL_SCAN_ACCEPT, except that the accepted message is |
26708 | queued without immediate delivery, and is frozen. | |
26709 | ||
9b371988 | 26710 | .vitem &`LOCAL_SCAN_ACCEPT_QUEUE`& |
168e428f PH |
26711 | This behaves as LOCAL_SCAN_ACCEPT, except that the accepted message is |
26712 | queued without immediate delivery. | |
26713 | ||
9b371988 | 26714 | .vitem &`LOCAL_SCAN_REJECT`& |
168e428f | 26715 | The message is rejected; the returned text is used as an error message which is |
9b371988 PH |
26716 | passed back to the sender and which is also logged. Newlines are permitted &-- |
26717 | they cause a multiline response for SMTP rejections, but are converted to | |
26718 | &`\n`& in log lines. If no message is given, &"Administrative prohibition"& is | |
26719 | used. | |
168e428f | 26720 | |
9b371988 | 26721 | .vitem &`LOCAL_SCAN_TEMPREJECT`& |
168e428f | 26722 | The message is temporarily rejected; the returned text is used as an error |
9b371988 PH |
26723 | message as for LOCAL_SCAN_REJECT. If no message is given, &"Temporary local |
26724 | problem"& is used. | |
168e428f | 26725 | |
9b371988 | 26726 | .vitem &`LOCAL_SCAN_REJECT_NOLOGHDR`& |
168e428f PH |
26727 | This behaves as LOCAL_SCAN_REJECT, except that the header of the rejected |
26728 | message is not written to the reject log. It has the effect of unsetting the | |
9b371988 PH |
26729 | &%rejected_header%& log selector for just this rejection. If |
26730 | &%rejected_header%& is already unset (see the discussion of the | |
26731 | &%log_selection%& option in section &<<SECTlogselector>>&), this code is the | |
26732 | same as LOCAL_SCAN_REJECT. | |
168e428f | 26733 | |
9b371988 | 26734 | .vitem &`LOCAL_SCAN_TEMPREJECT_NOLOGHDR`& |
168e428f PH |
26735 | This code is a variation of LOCAL_SCAN_TEMPREJECT in the same way that |
26736 | LOCAL_SCAN_REJECT_NOLOGHDR is a variation of LOCAL_SCAN_REJECT. | |
9b371988 | 26737 | .endlist |
168e428f PH |
26738 | |
26739 | If the message is not being received by interactive SMTP, rejections are | |
9b371988 PH |
26740 | reported by writing to &%stderr%& or by sending an email, as configured by the |
26741 | &%-oe%& command line options. | |
168e428f PH |
26742 | |
26743 | ||
26744 | ||
9b371988 PH |
26745 | .section "Configuration options for local_scan()" "SECTconoptloc" |
26746 | .cindex "&[local_scan()]& function" "configuration options" | |
168e428f | 26747 | It is possible to have option settings in the main configuration file |
9b371988 | 26748 | that set values in static variables in the &[local_scan()]& module. If you |
168e428f | 26749 | want to do this, you must have the line |
9b371988 PH |
26750 | .code |
26751 | LOCAL_SCAN_HAS_OPTIONS=yes | |
26752 | .endd | |
26753 | in your &_Local/Makefile_& when you build Exim. (This line is in | |
26754 | &_OS/Makefile-Default_&, commented out). Then, in the &[local_scan()]& source | |
26755 | file, you must define static variables to hold the option values, and a table | |
26756 | to define them. | |
26757 | ||
26758 | The table must be a vector called &%local_scan_options%&, of type | |
26759 | &`optionlist`&. Each entry is a triplet, consisting of a name, an option type, | |
168e428f | 26760 | and a pointer to the variable that holds the value. The entries must appear in |
9b371988 PH |
26761 | alphabetical order. Following &%local_scan_options%& you must also define a |
26762 | variable called &%local_scan_options_count%& that contains the number of | |
168e428f | 26763 | entries in the table. Here is a short example, showing two kinds of option: |
9b371988 PH |
26764 | .code |
26765 | static int my_integer_option = 42; | |
26766 | static uschar *my_string_option = US"a default string"; | |
26767 | ||
26768 | optionlist local_scan_options[] = { | |
26769 | { "my_integer", opt_int, &my_integer_option }, | |
26770 | { "my_string", opt_stringptr, &my_string_option } | |
26771 | }; | |
26772 | ||
26773 | int local_scan_options_count = | |
26774 | sizeof(local_scan_options)/sizeof(optionlist); | |
26775 | .endd | |
168e428f PH |
26776 | The values of the variables can now be changed from Exim's runtime |
26777 | configuration file by including a local scan section as in this example: | |
9b371988 PH |
26778 | .code |
26779 | begin local_scan | |
26780 | my_integer = 99 | |
26781 | my_string = some string of text... | |
26782 | .endd | |
168e428f PH |
26783 | The available types of option data are as follows: |
26784 | ||
9b371988 PH |
26785 | .vlist |
26786 | .vitem &*opt_bool*& | |
168e428f | 26787 | This specifies a boolean (true/false) option. The address should point to a |
9b371988 PH |
26788 | variable of type &`BOOL`&, which will be set to TRUE or FALSE, which are macros |
26789 | that are defined as &"1"& and &"0"&, respectively. If you want to detect | |
168e428f PH |
26790 | whether such a variable has been set at all, you can initialize it to |
26791 | TRUE_UNSET. (BOOL variables are integers underneath, so can hold more than two | |
26792 | values.) | |
26793 | ||
9b371988 | 26794 | .vitem &*opt_fixed*& |
168e428f | 26795 | This specifies a fixed point number, such as is used for load averages. |
9b371988 | 26796 | The address should point to a variable of type &`int`&. The value is stored |
168e428f PH |
26797 | multiplied by 1000, so, for example, 1.4142 is truncated and stored as 1414. |
26798 | ||
9b371988 | 26799 | .vitem &*opt_int*& |
168e428f | 26800 | This specifies an integer; the address should point to a variable of type |
9b371988 | 26801 | &`int`&. The value may be specified in any of the integer formats accepted by |
168e428f PH |
26802 | Exim. |
26803 | ||
9b371988 PH |
26804 | .vitem &*opt_mkint*& |
26805 | This is the same as &%opt_int%&, except that when such a value is output in a | |
26806 | &%-bP%& listing, if it is an exact number of kilobytes or megabytes, it is | |
168e428f PH |
26807 | printed with the suffix K or M. |
26808 | ||
9b371988 | 26809 | .vitem &*opt_octint*& |
168e428f PH |
26810 | This also specifies an integer, but the value is always interpeted as an |
26811 | octal integer, whether or not it starts with the digit zero, and it is | |
26812 | always output in octal. | |
26813 | ||
9b371988 | 26814 | .vitem &*opt_stringptr*& |
168e428f | 26815 | This specifies a string value; the address must be a pointer to a |
9b371988 | 26816 | variable that points to a string (for example, of type &`uschar *`&). |
168e428f | 26817 | |
9b371988 | 26818 | .vitem &*opt_time*& |
168e428f | 26819 | This specifies a time interval value. The address must point to a variable of |
9b371988 PH |
26820 | type &`int`&. The value that is placed there is a number of seconds. |
26821 | .endlist | |
168e428f | 26822 | |
9b371988 PH |
26823 | If the &%-bP%& command line option is followed by &`local_scan`&, Exim prints |
26824 | out the values of all the &[local_scan()]& options. | |
168e428f PH |
26825 | |
26826 | ||
26827 | ||
9b371988 PH |
26828 | .section "Available Exim variables" |
26829 | .cindex "&[local_scan()]& function" "available Exim variables" | |
26830 | The header &_local_scan.h_& gives you access to a number of C variables. These | |
168e428f PH |
26831 | are the only ones that are guaranteed to be maintained from release to release. |
26832 | Note, however, that you can obtain the value of any Exim variable by calling | |
9b371988 | 26833 | &'expand_string()'&. The exported variables are as follows: |
168e428f | 26834 | |
9b371988 PH |
26835 | .vlist |
26836 | .vitem &*unsigned&~int&~debug_selector*& | |
168e428f PH |
26837 | This variable is set to zero when no debugging is taking place. Otherwise, it |
26838 | is a bitmap of debugging selectors. Two bits are identified for use in | |
9b371988 PH |
26839 | &[local_scan()]&; they are defined as macros: |
26840 | ||
26841 | .ilist | |
26842 | The &`D_v`& bit is set when &%-v%& was present on the command line. This is a | |
26843 | testing option that is not privileged &-- any caller may set it. All the | |
168e428f PH |
26844 | other selector bits can be set only by admin users. |
26845 | ||
9b371988 PH |
26846 | .next |
26847 | The &`D_local_scan`& bit is provided for use by &[local_scan()]&; it is set | |
26848 | by the &`+local_scan`& debug selector. It is not included in the default set | |
168e428f | 26849 | of debugging bits. |
9b371988 | 26850 | .endlist ilist |
168e428f | 26851 | |
9b371988 PH |
26852 | Thus, to write to the debugging output only when &`+local_scan`& has been |
26853 | selected, you should use code like this: | |
26854 | .code | |
26855 | if ((debug_selector & D_local_scan) != 0) | |
26856 | debug_printf("xxx", ...); | |
26857 | .endd | |
26858 | .vitem &*uschar&~*expand_string_message*& | |
26859 | After a failing call to &'expand_string()'& (returned value NULL), the | |
26860 | variable &%expand_string_message%& contains the error message, zero-terminated. | |
26861 | ||
26862 | .vitem &*header_line&~*header_list*& | |
26863 | A pointer to a chain of header lines. The &%header_line%& structure is | |
26864 | discussed below. | |
26865 | ||
26866 | .vitem &*header_line&~*header_last*& | |
168e428f PH |
26867 | A pointer to the last of the header lines. |
26868 | ||
9b371988 PH |
26869 | .vitem &*uschar&~*headers_charset*& |
26870 | The value of the &%headers_charset%& configuration option. | |
168e428f | 26871 | |
9b371988 | 26872 | .vitem &*BOOL&~host_checking*& |
168e428f | 26873 | This variable is TRUE during a host checking session that is initiated by the |
9b371988 | 26874 | &%-bh%& command line option. |
168e428f | 26875 | |
9b371988 | 26876 | .vitem &*uschar&~*interface_address*& |
168e428f PH |
26877 | The IP address of the interface that received the message, as a string. This |
26878 | is NULL for locally submitted messages. | |
26879 | ||
9b371988 | 26880 | .vitem &*int&~interface_port*& |
168e428f PH |
26881 | The port on which this message was received. |
26882 | ||
9b371988 | 26883 | .vitem &*uschar&~*message_id*& |
d1e83bff | 26884 | This variable contains Exim's message id for the incoming message (the value of |
9b371988 | 26885 | &$message_exim_id$&) as a zero-terminated string. |
168e428f | 26886 | |
9b371988 | 26887 | .vitem &*uschar&~*received_protocol*& |
168e428f PH |
26888 | The name of the protocol by which the message was received. |
26889 | ||
9b371988 | 26890 | .vitem &*int&~recipients_count*& |
168e428f PH |
26891 | The number of accepted recipients. |
26892 | ||
9b371988 PH |
26893 | .vitem &*recipient_item&~*recipients_list*& |
26894 | .cindex "recipient" "adding in local scan" | |
26895 | .cindex "recipient" "removing in local scan" | |
26896 | The list of accepted recipients, held in a vector of length | |
26897 | &%recipients_count%&. The &%recipient_item%& structure is discussed below. You | |
26898 | can add additional recipients by calling &'receive_add_recipient()'& (see | |
26899 | below). You can delete recipients by removing them from the vector and adusting | |
26900 | the value in &%recipients_count%&. In particular, by setting | |
26901 | &%recipients_count%& to zero you remove all recipients. If you then return the | |
26902 | value &`LOCAL_SCAN_ACCEPT`&, the message is accepted, but immediately | |
26903 | blackholed. To replace the recipients, you can set &%recipients_count%& to zero | |
26904 | and then call &'receive_add_recipient()'& as often as needed. | |
26905 | ||
26906 | .vitem &*uschar&~*sender_address*& | |
168e428f PH |
26907 | The envelope sender address. For bounce messages this is the empty string. |
26908 | ||
9b371988 | 26909 | .vitem &*uschar&~*sender_host_address*& |
168e428f PH |
26910 | The IP address of the sending host, as a string. This is NULL for |
26911 | locally-submitted messages. | |
26912 | ||
9b371988 | 26913 | .vitem &*uschar&~*sender_host_authenticated*& |
168e428f PH |
26914 | The name of the authentication mechanism that was used, or NULL if the message |
26915 | was not received over an authenticated SMTP connection. | |
26916 | ||
9b371988 | 26917 | .vitem &*uschar&~*sender_host_name*& |
168e428f PH |
26918 | The name of the sending host, if known. |
26919 | ||
9b371988 | 26920 | .vitem &*int&~sender_host_port*& |
168e428f PH |
26921 | The port on the sending host. |
26922 | ||
9b371988 | 26923 | .vitem &*BOOL&~smtp_input*& |
168e428f PH |
26924 | This variable is TRUE for all SMTP input, including BSMTP. |
26925 | ||
9b371988 | 26926 | .vitem &*BOOL&~smtp_batched_input*& |
168e428f PH |
26927 | This variable is TRUE for BSMTP input. |
26928 | ||
9b371988 | 26929 | .vitem &*int&~store_pool*& |
168e428f | 26930 | The contents of this variable control which pool of memory is used for new |
9b371988 PH |
26931 | requests. See section &<<SECTmemhanloc>>& for details. |
26932 | .endlist | |
168e428f PH |
26933 | |
26934 | ||
9b371988 PH |
26935 | .section "Structure of header lines" |
26936 | The &%header_line%& structure contains the members listed below. | |
26937 | You can add additional header lines by calling the &'header_add()'& function | |
168e428f | 26938 | (see below). You can cause header lines to be ignored (deleted) by setting |
9b371988 | 26939 | their type to *. |
168e428f PH |
26940 | |
26941 | ||
9b371988 PH |
26942 | .vlist |
26943 | .vitem &*struct&~header_line&~*next*& | |
168e428f PH |
26944 | A pointer to the next header line, or NULL for the last line. |
26945 | ||
9b371988 | 26946 | .vitem &*int&~type*& |
168e428f | 26947 | A code identifying certain headers that Exim recognizes. The codes are printing |
9b371988 PH |
26948 | characters, and are documented in chapter &<<CHAPspool>>& of this manual. |
26949 | Notice in particular that any header line whose type is * is not transmitted | |
26950 | with the message. This flagging is used for header lines that have been | |
26951 | rewritten, or are to be removed (for example, &'Envelope-sender:'& header | |
26952 | lines.) Effectively, * means &"deleted"&. | |
168e428f | 26953 | |
9b371988 | 26954 | .vitem &*int&~slen*& |
168e428f PH |
26955 | The number of characters in the header line, including the terminating and any |
26956 | internal newlines. | |
26957 | ||
9b371988 | 26958 | .vitem &*uschar&~*text*& |
168e428f PH |
26959 | A pointer to the text of the header. It always ends with a newline, followed by |
26960 | a zero byte. Internal newlines are preserved. | |
9b371988 | 26961 | .endlist |
168e428f PH |
26962 | |
26963 | ||
26964 | ||
9b371988 PH |
26965 | .section "Structure of recipient items" |
26966 | The &%recipient_item%& structure contains these members: | |
168e428f | 26967 | |
9b371988 PH |
26968 | .vlist |
26969 | .vitem &*uschar&~*address*& | |
168e428f PH |
26970 | This is a pointer to the recipient address as it was received. |
26971 | ||
9b371988 | 26972 | .vitem &*int&~pno*& |
168e428f | 26973 | This is used in later Exim processing when top level addresses are created by |
9b371988 PH |
26974 | the &%one_time%& option. It is not relevant at the time &[local_scan()]& is run |
26975 | and must always contain -1 at this stage. | |
168e428f | 26976 | |
9b371988 | 26977 | .vitem &*uschar&~*errors_to*& |
168e428f PH |
26978 | If this value is not NULL, bounce messages caused by failing to deliver to the |
26979 | recipient are sent to the address it contains. In other words, it overrides the | |
9b371988 PH |
26980 | envelope sender for this one recipient. (Compare the &%errors_to%& generic |
26981 | router option.) If a &[local_scan()]& function sets an &%errors_to%& field to | |
26982 | an unqualified address, Exim qualifies it using the domain from | |
26983 | &%qualify_recipient%&. When &[local_scan()]& is called, the &%errors_to%& field | |
26984 | is NULL for all recipients. | |
26985 | .endlist | |
168e428f PH |
26986 | |
26987 | ||
26988 | ||
9b371988 PH |
26989 | .section "Available Exim functions" |
26990 | .cindex "&[local_scan()]& function" "available Exim functions" | |
26991 | The header &_local_scan.h_& gives you access to a number of Exim functions. | |
168e428f PH |
26992 | These are the only ones that are guaranteed to be maintained from release to |
26993 | release: | |
26994 | ||
9b371988 PH |
26995 | .vlist |
26996 | .vitem "&*pid_t&~child_open(uschar&~**argv,&~uschar&~**envp,&~int&~newumask,&&& | |
26997 | &~int&~*infdptr,&~int&~*outfdptr, &~&~BOOL&~make_leader)*&" | |
168e428f PH |
26998 | |
26999 | This function creates a child process that runs the command specified by | |
9b371988 PH |
27000 | &%argv%&. The environment for the process is specified by &%envp%&, which can |
27001 | be NULL if no environment variables are to be passed. A new umask is supplied | |
27002 | for the process in &%newumask%&. | |
27003 | ||
168e428f | 27004 | Pipes to the standard input and output of the new process are set up |
9b371988 | 27005 | and returned to the caller via the &%infdptr%& and &%outfdptr%& arguments. The |
168e428f | 27006 | standard error is cloned to the standard output. If there are any file |
9b371988 | 27007 | descriptors &"in the way"& in the new process, they are closed. If the final |
168e428f | 27008 | argument is TRUE, the new process is made into a process group leader. |
9b371988 | 27009 | |
168e428f PH |
27010 | The function returns the pid of the new process, or -1 if things go wrong. |
27011 | ||
9b371988 | 27012 | .vitem &*int&~child_close(pid_t&~pid,&~int&~timeout)*& |
168e428f PH |
27013 | This function waits for a child process to terminate, or for a timeout (in |
27014 | seconds) to expire. A timeout value of zero means wait as long as it takes. The | |
27015 | return value is as follows: | |
9b371988 PH |
27016 | |
27017 | .ilist | |
27018 | >= 0 | |
27019 | ||
27020 | The process terminated by a normal exit and the value is the process | |
27021 | ending status. | |
27022 | ||
27023 | .next | |
27024 | < 0 and > &--256 | |
27025 | ||
168e428f PH |
27026 | The process was terminated by a signal and the value is the negation of the |
27027 | signal number. | |
27028 | ||
9b371988 PH |
27029 | .next |
27030 | &--256 | |
168e428f | 27031 | |
9b371988 PH |
27032 | The process timed out. |
27033 | .next | |
27034 | &--257 | |
168e428f | 27035 | |
9b371988 PH |
27036 | The was some other error in wait(); &%errno%& is still set. |
27037 | .endlist | |
168e428f | 27038 | |
9b371988 | 27039 | .vitem &*pid_t&~child_open_exim(int&~*fd)*& |
168e428f | 27040 | This function provide you with a means of submitting a new message to |
9b371988 | 27041 | Exim. (Of course, you can also call &_/usr/sbin/sendmail_& yourself if you |
168e428f PH |
27042 | want, but this packages it all up for you.) The function creates a pipe, |
27043 | forks a subprocess that is running | |
9b371988 PH |
27044 | .code |
27045 | exim -t -oem -oi -f <> | |
27046 | .endd | |
27047 | and returns to you (via the &`int *`& argument) a file descriptor for the pipe | |
168e428f PH |
27048 | that is connected to the standard input. The yield of the function is the PID |
27049 | of the subprocess. You can then write a message to the file descriptor, with | |
9b371988 PH |
27050 | recipients in &'To:'&, &'Cc:'&, and/or &'Bcc:'& header lines. |
27051 | ||
27052 | When you have finished, call &'child_close()'& to wait for the process to | |
168e428f PH |
27053 | finish and to collect its ending status. A timeout value of zero is usually |
27054 | fine in this circumstance. Unless you have made a mistake with the recipient | |
27055 | addresses, you should get a return code of zero. | |
27056 | ||
9b371988 PH |
27057 | .vitem &*void&~debug_printf(char&~*,&~...)*& |
27058 | This is Exim's debugging function, with arguments as for &'(printf()'&. The | |
168e428f | 27059 | output is written to the standard error stream. If no debugging is selected, |
9b371988 PH |
27060 | calls to &'debug_printf()'& have no effect. Normally, you should make calls |
27061 | conditional on the &`local_scan`& debug selector by coding like this: | |
27062 | .code | |
27063 | if ((debug_selector & D_local_scan) != 0) | |
27064 | debug_printf("xxx", ...); | |
27065 | .endd | |
27066 | .vitem &*uschar&~*expand_string(uschar&~*string)*& | |
168e428f PH |
27067 | This is an interface to Exim's string expansion code. The return value is the |
27068 | expanded string, or NULL if there was an expansion failure. | |
9b371988 | 27069 | The C variable &%expand_string_message%& contains an error message after an |
168e428f PH |
27070 | expansion failure. If expansion does not change the string, the return value is |
27071 | the pointer to the input string. Otherwise, the return value points to a new | |
9b371988 PH |
27072 | block of memory that was obtained by a call to &'store_get()'&. See section |
27073 | &<<SECTmemhanloc>>& below for a discussion of memory handling. | |
168e428f | 27074 | |
9b371988 | 27075 | .vitem &*void&~header_add(int&~type,&~char&~*format,&~...)*& |
168e428f PH |
27076 | This function allows you to an add additional header line at the end of the |
27077 | existing ones. The first argument is the type, and should normally be a space | |
27078 | character. The second argument is a format string and any number of | |
9b371988 PH |
27079 | substitution arguments as for &[sprintf()]&. You may include internal newlines |
27080 | if you want, and you must ensure that the string ends with a newline. | |
168e428f | 27081 | |
9b371988 PH |
27082 | .vitem "&*void&~header_add_at_position(BOOL&~after,&~uschar&~*name,&~&&& |
27083 | BOOL&~topnot,&~int&~type,&~char&~*format, &~&~...)*&" | |
168e428f | 27084 | This function adds a new header line at a specified point in the header |
9b371988 PH |
27085 | chain. The header itself is specified as for &'header_add()'&. |
27086 | ||
27087 | If &%name%& is NULL, the new header is added at the end of the chain if | |
27088 | &%after%& is true, or at the start if &%after%& is false. If &%name%& is not | |
27089 | NULL, the header lines are searched for the first non-deleted header that | |
27090 | matches the name. If one is found, the new header is added before it if | |
27091 | &%after%& is false. If &%after%& is true, the new header is added after the | |
27092 | found header and any adjacent subsequent ones with the same name (even if | |
27093 | marked &"deleted"&). If no matching non-deleted header is found, the &%topnot%& | |
27094 | option controls where the header is added. If it is true, addition is at the | |
27095 | top; otherwise at the bottom. Thus, to add a header after all the &'Received:'& | |
27096 | headers, or at the top if there are no &'Received:'& headers, you could use | |
27097 | .code | |
27098 | header_add_at_position(TRUE, US"Received", TRUE, | |
27099 | ' ', "X-xxx: ..."); | |
27100 | .endd | |
27101 | Normally, there is always at least one non-deleted &'Received:'& header, but | |
27102 | there may not be if &%received_header_text%& expands to an empty string. | |
27103 | ||
27104 | ||
27105 | .vitem &*void&~header_remove(int&~occurrence,&~uschar&~*name)*& | |
27106 | This function removes header lines. If &%occurrence%& is zero or negative, all | |
168e428f PH |
27107 | occurrences of the header are removed. If occurrence is greater than zero, that |
27108 | particular instance of the header is removed. If no header(s) can be found that | |
27109 | match the specification, the function does nothing. | |
27110 | ||
27111 | ||
9b371988 PH |
27112 | .vitem "&*BOOL&~header_testname(header_line&~*hdr,&~uschar&~*name,&~&&& |
27113 | int&~length,&~BOOL&~notdel)*&" | |
168e428f | 27114 | This function tests whether the given header has the given name. It is not just |
068aaea8 | 27115 | a string comparison, because white space is permitted between the name and the |
9b371988 PH |
27116 | colon. If the &%notdel%& argument is true, a false return is forced for all |
27117 | &"deleted"& headers; otherwise they are not treated specially. For example: | |
27118 | .code | |
27119 | if (header_testname(h, US"X-Spam", 6, TRUE)) ... | |
27120 | .endd | |
27121 | .vitem &*uschar&~*lss_b64encode(uschar&~*cleartext,&~int&~length)*& | |
27122 | .cindex "base64 encoding" "functions for &[local_scan()]& use" | |
168e428f PH |
27123 | This function base64-encodes a string, which is passed by address and length. |
27124 | The text may contain bytes of any value, including zero. The result is passed | |
9b371988 | 27125 | back in dynamic memory that is obtained by calling &'store_get()'&. It is |
168e428f PH |
27126 | zero-terminated. |
27127 | ||
9b371988 | 27128 | .vitem &*int&~lss_b64decode(uschar&~*codetext,&~uschar&~**cleartext)*& |
168e428f PH |
27129 | This function decodes a base64-encoded string. Its arguments are a |
27130 | zero-terminated base64-encoded string and the address of a variable that is set | |
27131 | to point to the result, which is in dynamic memory. The length of the decoded | |
27132 | string is the yield of the function. If the input is invalid base64 data, the | |
27133 | yield is -1. A zero byte is added to the end of the output string to make it | |
27134 | easy to interpret as a C string (assuming it contains no zeros of its own). The | |
27135 | added zero byte is not included in the returned count. | |
27136 | ||
9b371988 | 27137 | .vitem &*int&~lss_match_domain(uschar&~*domain,&~uschar&~*list)*& |
168e428f PH |
27138 | This function checks for a match in a domain list. Domains are always |
27139 | matched caselessly. The return value is one of the following: | |
9b371988 PH |
27140 | .display |
27141 | &`OK `& match succeeded | |
27142 | &`FAIL `& match failed | |
27143 | &`DEFER `& match deferred | |
27144 | .endd | |
168e428f PH |
27145 | DEFER is usually caused by some kind of lookup defer, such as the |
27146 | inability to contact a database. | |
27147 | ||
9b371988 PH |
27148 | .vitem "&*int&~lss_match_local_part(uschar&~*localpart,&~uschar&~*list,&~&&& |
27149 | BOOL&~caseless)*&" | |
168e428f PH |
27150 | This function checks for a match in a local part list. The third argument |
27151 | controls case-sensitivity. The return values are as for | |
9b371988 | 27152 | &'lss_match_domain()'&. |
168e428f | 27153 | |
9b371988 PH |
27154 | .vitem "&*int&~lss_match_address(uschar&~*address,&~uschar&~*list,&~&&& |
27155 | BOOL&~caseless)*&" | |
168e428f PH |
27156 | This function checks for a match in an address list. The third argument |
27157 | controls the case-sensitivity of the local part match. The domain is always | |
9b371988 | 27158 | matched caselessly. The return values are as for &'lss_match_domain()'&. |
168e428f | 27159 | |
9b371988 PH |
27160 | .vitem "&*int&~lss_match_host(uschar&~*host_name,&~uschar&~*host_address,&~&&& |
27161 | uschar&~*list)*&" | |
168e428f PH |
27162 | This function checks for a match in a host list. The most common usage is |
27163 | expected to be | |
9b371988 PH |
27164 | .code |
27165 | lss_match_host(sender_host_name, sender_host_address, ...) | |
27166 | .endd | |
27167 | .cindex "&$sender_host_address$&" | |
068aaea8 | 27168 | An empty address field matches an empty item in the host list. If the host name |
9b371988 | 27169 | is NULL, the name corresponding to &$sender_host_address$& is automatically |
068aaea8 | 27170 | looked up if a host name is required to match an item in the list. The return |
9b371988 | 27171 | values are as for &'lss_match_domain()'&, but in addition, &'lss_match_host()'& |
068aaea8 PH |
27172 | returns ERROR in the case when it had to look up a host name, but the lookup |
27173 | failed. | |
168e428f | 27174 | |
9b371988 PH |
27175 | .vitem "&*void&~log_write(unsigned&~int&~selector,&~int&~which,&~char&~&&& |
27176 | *format,&~...)*&" | |
168e428f | 27177 | This function writes to Exim's log files. The first argument should be zero (it |
9b371988 PH |
27178 | is concerned with &%log_selector%&). The second argument can be &`LOG_MAIN`& or |
27179 | &`LOG_REJECT`& or &`LOG_PANIC`& or the inclusive &"or"& of any combination of | |
27180 | them. It specifies to which log or logs the message is written. The remaining | |
168e428f PH |
27181 | arguments are a format and relevant insertion arguments. The string should not |
27182 | contain any newlines, not even at the end. | |
27183 | ||
27184 | ||
9b371988 | 27185 | .vitem &*void&~receive_add_recipient(uschar&~*address,&~int&~pno)*& |
168e428f PH |
27186 | This function adds an additional recipient to the message. The first argument |
27187 | is the recipient address. If it is unqualified (has no domain), it is qualified | |
9b371988 PH |
27188 | with the &%qualify_recipient%& domain. The second argument must always be -1. |
27189 | ||
27190 | This function does not allow you to specify a private &%errors_to%& address (as | |
27191 | described with the structure of &%recipient_item%& above), because it pre-dates | |
168e428f PH |
27192 | the addition of that field to the structure. However, it is easy to add such a |
27193 | value afterwards. For example: | |
9b371988 PH |
27194 | .code |
27195 | receive_add_recipient(US"monitor@mydom.example", -1); | |
27196 | recipients_list[recipients_count-1].errors_to = | |
27197 | US"postmaster@mydom.example"; | |
27198 | .endd | |
168e428f | 27199 | |
9b371988 | 27200 | .vitem &*BOOL&~receive_remove_recipient(uschar&~*recipient)*& |
168e428f PH |
27201 | This is a convenience function to remove a named recipient from the list of |
27202 | recipients. It returns true if a recipient was removed, and false if no | |
27203 | matching recipient could be found. The argument must be a complete email | |
27204 | address. | |
9b371988 | 27205 | .endlist |
168e428f PH |
27206 | |
27207 | ||
9b371988 PH |
27208 | .cindex "RFC 2047" |
27209 | .vlist | |
27210 | .vitem "&*uschar&~rfc2047_decode(uschar&~*string,&~BOOL&~lencheck,&&& | |
27211 | &~uschar&~*target,&~int&~zeroval,&~int&~*lenptr, &~&~uschar&~**error)*&" | |
168e428f | 27212 | This function decodes strings that are encoded according to RFC 2047. Typically |
9b371988 | 27213 | these are the contents of header lines. First, each &"encoded word"& is decoded |
168e428f | 27214 | from the Q or B encoding into a byte-string. Then, if provided with the name of |
9b371988 | 27215 | a charset encoding, and if the &[iconv()]& function is available, an attempt is |
168e428f PH |
27216 | made to translate the result to the named character set. If this fails, the |
27217 | binary string is returned with an error message. | |
9b371988 PH |
27218 | |
27219 | The first argument is the string to be decoded. If &%lencheck%& is TRUE, the | |
168e428f PH |
27220 | maximum MIME word length is enforced. The third argument is the target |
27221 | encoding, or NULL if no translation is wanted. | |
9b371988 PH |
27222 | |
27223 | .cindex "binary zero" "in RFC 2047 decoding" | |
27224 | .cindex "RFC 2047" "binary zero in" | |
168e428f | 27225 | If a binary zero is encountered in the decoded string, it is replaced by the |
9b371988 | 27226 | contents of the &%zeroval%& argument. For use with Exim headers, the value must |
168e428f | 27227 | not be 0 because header lines are handled as zero-terminated strings. |
9b371988 | 27228 | |
168e428f | 27229 | The function returns the result of processing the string, zero-terminated; if |
9b371988 PH |
27230 | &%lenptr%& is not NULL, the length of the result is set in the variable to |
27231 | which it points. When &%zeroval%& is 0, &%lenptr%& should not be NULL. | |
27232 | ||
27233 | If an error is encountered, the function returns NULL and uses the &%error%& | |
27234 | argument to return an error message. The variable pointed to by &%error%& is | |
27235 | set to NULL if there is no error; it may be set non-NULL even when the function | |
168e428f PH |
27236 | returns a non-NULL value if decoding was successful, but there was a problem |
27237 | with translation. | |
27238 | ||
27239 | ||
9b371988 PH |
27240 | .vitem &*int&~smtp_fflush(void)*& |
27241 | This function is used in conjunction with &'smtp_printf()'&, as described | |
168e428f PH |
27242 | below. |
27243 | ||
9b371988 PH |
27244 | .vitem &*void&~smtp_printf(char&~*,&~...)*& |
27245 | The arguments of this function are like &[printf()]&; it writes to the SMTP | |
168e428f PH |
27246 | output stream. You should use this function only when there is an SMTP output |
27247 | stream, that is, when the incoming message is being received via interactive | |
9b371988 PH |
27248 | SMTP. This is the case when &%smtp_input%& is TRUE and &%smtp_batched_input%& |
27249 | is FALSE. If you want to test for an incoming message from another host (as | |
27250 | opposed to a local process that used the &%-bs%& command line option), you can | |
27251 | test the value of &%sender_host_address%&, which is non-NULL when a remote host | |
168e428f | 27252 | is involved. |
9b371988 PH |
27253 | |
27254 | If an SMTP TLS connection is established, &'smtp_printf()'& uses the TLS | |
168e428f | 27255 | output function, so it can be used for all forms of SMTP connection. |
9b371988 PH |
27256 | |
27257 | Strings that are written by &'smtp_printf()'& from within &[local_scan()]& | |
168e428f PH |
27258 | must start with an appropriate response code: 550 if you are going to return |
27259 | LOCAL_SCAN_REJECT, 451 if you are going to return | |
27260 | LOCAL_SCAN_TEMPREJECT, and 250 otherwise. Because you are writing the | |
27261 | initial lines of a multi-line response, the code must be followed by a hyphen | |
27262 | to indicate that the line is not the final response line. You must also ensure | |
27263 | that the lines you write terminate with CRLF. For example: | |
9b371988 PH |
27264 | .code |
27265 | smtp_printf("550-this is some extra info\r\n"); | |
27266 | return LOCAL_SCAN_REJECT; | |
27267 | .endd | |
168e428f | 27268 | Note that you can also create multi-line responses by including newlines in |
9b371988 PH |
27269 | the data returned via the &%return_text%& argument. The added value of using |
27270 | &'smtp_printf()'& is that, for instance, you could introduce delays between | |
168e428f | 27271 | multiple output lines. |
9b371988 PH |
27272 | |
27273 | The &'smtp_printf()'& function does not return any error indication, because it | |
168e428f PH |
27274 | does not automatically flush pending output, and therefore does not test |
27275 | the state of the stream. (In the main code of Exim, flushing and error | |
27276 | detection is done when Exim is ready for the next SMTP input command.) If | |
27277 | you want to flush the output and check for an error (for example, the | |
9b371988 | 27278 | dropping of a TCP/IP connection), you can call &'smtp_fflush()'&, which has no |
168e428f PH |
27279 | arguments. It flushes the output stream, and returns a non-zero value if there |
27280 | is an error. | |
27281 | ||
9b371988 | 27282 | .vitem &*void&~*store_get(int)*& |
168e428f PH |
27283 | This function accesses Exim's internal store (memory) manager. It gets a new |
27284 | chunk of memory whose size is given by the argument. Exim bombs out if it ever | |
27285 | runs out of memory. See the next section for a discussion of memory handling. | |
27286 | ||
9b371988 PH |
27287 | .vitem &*void&~*store_get_perm(int)*& |
27288 | This function is like &'store_get()'&, but it always gets memory from the | |
168e428f PH |
27289 | permanent pool. See the next section for a discussion of memory handling. |
27290 | ||
9b371988 | 27291 | .vitem &*uschar&~*string_copy(uschar&~*string)*& |
168e428f PH |
27292 | See below. |
27293 | ||
9b371988 | 27294 | .vitem &*uschar&~*string_copyn(uschar&~*string,&~int&~length)*& |
168e428f PH |
27295 | See below. |
27296 | ||
9b371988 | 27297 | .vitem &*uschar&~*string_sprintf(char&~*format,&~...)*& |
168e428f PH |
27298 | These three functions create strings using Exim's dynamic memory facilities. |
27299 | The first makes a copy of an entire string. The second copies up to a maximum | |
27300 | number of characters, indicated by the second argument. The third uses a format | |
27301 | and insertion arguments to create a new string. In each case, the result is a | |
27302 | pointer to a new string in the current memory pool. See the next section for | |
27303 | more discussion. | |
9b371988 | 27304 | .endlist |
168e428f PH |
27305 | |
27306 | ||
27307 | ||
9b371988 PH |
27308 | .section "More about Exim's memory handling" "SECTmemhanloc" |
27309 | .cindex "&[local_scan()]& function" "memory handling" | |
168e428f PH |
27310 | No function is provided for freeing memory, because that is never needed. |
27311 | The dynamic memory that Exim uses when receiving a message is automatically | |
27312 | recycled if another message is received by the same process (this applies only | |
9b371988 PH |
27313 | to incoming SMTP connections &-- other input methods can supply only one |
27314 | message at a time). After receiving the last message, a reception process | |
27315 | terminates. | |
168e428f PH |
27316 | |
27317 | Because it is recycled, the normal dynamic memory cannot be used for holding | |
27318 | data that must be preserved over a number of incoming messages on the same SMTP | |
27319 | connection. However, Exim in fact uses two pools of dynamic memory; the second | |
27320 | one is not recycled, and can be used for this purpose. | |
27321 | ||
27322 | If you want to allocate memory that remains available for subsequent messages | |
27323 | in the same SMTP connection, you should set | |
9b371988 PH |
27324 | .code |
27325 | store_pool = POOL_PERM | |
27326 | .endd | |
168e428f PH |
27327 | before calling the function that does the allocation. There is no need to |
27328 | restore the value if you do not need to; however, if you do want to revert to | |
9b371988 | 27329 | the normal pool, you can either restore the previous value of &%store_pool%& or |
168e428f PH |
27330 | set it explicitly to POOL_MAIN. |
27331 | ||
27332 | The pool setting applies to all functions that get dynamic memory, including | |
9b371988 PH |
27333 | &'expand_string()'&, &'store_get()'&, and the &'string_xxx()'& functions. |
27334 | There is also a convenience function called &'store_get_perm()'& that gets a | |
168e428f | 27335 | block of memory from the permanent pool while preserving the value of |
9b371988 | 27336 | &%store_pool%&. |
168e428f PH |
27337 | |
27338 | ||
27339 | ||
27340 | ||
27341 | ||
9b371988 PH |
27342 | . //////////////////////////////////////////////////////////////////////////// |
27343 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 27344 | |
9b371988 PH |
27345 | .chapter "System-wide message filtering" "CHAPsystemfilter" |
27346 | .cindex "filter" "system filter" | |
27347 | .cindex "filtering all mail" | |
27348 | .cindex "system filter" | |
168e428f PH |
27349 | The previous chapters (on ACLs and the local scan function) describe checks |
27350 | that can be applied to messages before they are accepted by a host. There is | |
27351 | also a mechanism for checking messages once they have been received, but before | |
9b371988 | 27352 | they are delivered. This is called the &'system filter'&. |
168e428f PH |
27353 | |
27354 | The system filter operates in a similar manner to users' filter files, but it | |
27355 | is run just once per message (however many recipients the message has). | |
9b371988 | 27356 | It should not normally be used as a substitute for routing, because &%deliver%& |
168e428f PH |
27357 | commands in a system router provide new envelope recipient addresses. |
27358 | The system filter must be an Exim filter. It cannot be a Sieve filter. | |
27359 | ||
27360 | The system filter is run at the start of a delivery attempt, before any routing | |
27361 | is done. If a message fails to be completely delivered at the first attempt, | |
27362 | the system filter is run again at the start of every retry. | |
27363 | If you want your filter to do something only once per message, you can make use | |
9b371988 PH |
27364 | of the &%first_delivery%& condition in an &%if%& command in the filter to |
27365 | prevent it happening on retries. | |
27366 | ||
27367 | .cindex "&$domain$&" | |
27368 | .cindex "&$local_part$&" | |
27369 | &*Warning*&: Because the system filter runs just once, variables that are | |
27370 | specific to individual recipient addresses, such as &$local_part$& and | |
27371 | &$domain$&, are not set, and the &"personal"& condition is not meaningful. If | |
27372 | you want to run a centrally-specified filter for each recipient address | |
27373 | independently, you can do so by setting up a suitable &(redirect)& router, as | |
27374 | described in section &<<SECTperaddfil>>& below. | |
27375 | ||
27376 | ||
27377 | .section "Specifying a system filter" | |
27378 | .cindex "uid (user id)" "system filter" | |
27379 | .cindex "gid (group id)" "system filter" | |
168e428f | 27380 | The name of the file that contains the system filter must be specified by |
9b371988 PH |
27381 | setting &%system_filter%&. If you want the filter to run under a uid and gid |
27382 | other than root, you must also set &%system_filter_user%& and | |
27383 | &%system_filter_group%& as appropriate. For example: | |
27384 | .code | |
27385 | system_filter = /etc/mail/exim.filter | |
27386 | system_filter_user = exim | |
27387 | .endd | |
168e428f | 27388 | If a system filter generates any deliveries directly to files or pipes (via the |
9b371988 PH |
27389 | &%save%& or &%pipe%& commands), transports to handle these deliveries must be |
27390 | specified by setting &%system_filter_file_transport%& and | |
27391 | &%system_filter_pipe_transport%&, respectively. Similarly, | |
27392 | &%system_filter_reply_transport%& must be set to handle any messages generated | |
27393 | by the &%reply%& command. | |
168e428f PH |
27394 | |
27395 | ||
9b371988 | 27396 | .section "Testing a system filter" |
168e428f | 27397 | You can run simple tests of a system filter in the same way as for a user |
9b371988 | 27398 | filter, but you should use &%-bF%& rather than &%-bf%&, so that features that |
168e428f PH |
27399 | are permitted only in system filters are recognized. |
27400 | ||
27401 | If you want to test the combined effect of a system filter and a user filter, | |
9b371988 | 27402 | you can use both &%-bF%& and &%-bf%& on the same command line. |
168e428f PH |
27403 | |
27404 | ||
27405 | ||
9b371988 | 27406 | .section "Contents of a system filter" |
168e428f | 27407 | The language used to specify system filters is the same as for users' filter |
9b371988 PH |
27408 | files. It is described in the separate end-user document &'Exim's interface to |
27409 | mail filtering'&. However, there are some additional features that are | |
168e428f | 27410 | available only in system filters; these are described in subsequent sections. |
9b371988 | 27411 | If they are encountered in a user's filter file or when testing with &%-bf%&, |
168e428f PH |
27412 | they cause errors. |
27413 | ||
9b371988 | 27414 | .cindex "frozen messages" "manual thaw; testing in filter" |
168e428f | 27415 | There are two special conditions which, though available in users' filter |
9b371988 | 27416 | files, are designed for use in system filters. The condition &%first_delivery%& |
168e428f | 27417 | is true only for the first attempt at delivering a message, and |
9b371988 | 27418 | &%manually_thawed%& is true only if the message has been frozen, and |
168e428f | 27419 | subsequently thawed by an admin user. An explicit forced delivery counts as a |
9b371988 | 27420 | manual thaw, but thawing as a result of the &%auto_thaw%& setting does not. |
168e428f | 27421 | |
9b371988 PH |
27422 | &*Warning*&: If a system filter uses the &%first_delivery%& condition to |
27423 | specify an &"unseen"& (non-significant) delivery, and that delivery does not | |
168e428f PH |
27424 | succeed, it will not be tried again. |
27425 | If you want Exim to retry an unseen delivery until it succeeds, you should | |
27426 | arrange to set it up every time the filter runs. | |
27427 | ||
9b371988 PH |
27428 | When a system filter finishes running, the values of the variables &$n0$& &-- |
27429 | &$n9$& are copied into &$sn0$& &-- &$sn9$& and are thereby made available to | |
27430 | users' filter files. Thus a system filter can, for example, set up &"scores"& | |
27431 | to which users' filter files can refer. | |
168e428f PH |
27432 | |
27433 | ||
27434 | ||
9b371988 PH |
27435 | .section "Additional variable for system filters" |
27436 | .cindex "&$recipients$&" | |
27437 | The expansion variable &$recipients$&, containing a list of all the recipients | |
168e428f PH |
27438 | of the message (separated by commas and white space), is available in system |
27439 | filters. It is not available in users' filters for privacy reasons. | |
27440 | ||
27441 | ||
27442 | ||
9b371988 PH |
27443 | .section "Defer, freeze, and fail commands for system filters" |
27444 | .cindex "freezing messages" | |
27445 | .cindex "message" "freezing" | |
27446 | .cindex "message" "forced failure" | |
27447 | .cindex "&%fail%&" "in system filter" | |
27448 | .cindex "&%freeze%& in system filter" | |
27449 | .cindex "&%defer%& in system filter" | |
27450 | There are three extra commands (&%defer%&, &%freeze%& and &%fail%&) which are | |
27451 | always available in system filters, but are not normally enabled in users' | |
27452 | filters. (See the &%allow_defer%&, &%allow_freeze%& and &%allow_fail%& options | |
27453 | for the &(redirect)& router.) These commands can optionally be followed by the | |
27454 | word &%text%& and a string containing an error message, for example: | |
27455 | .code | |
27456 | fail text "this message looks like spam to me" | |
27457 | .endd | |
27458 | The keyword &%text%& is optional if the next character is a double quote. | |
27459 | ||
27460 | The &%defer%& command defers delivery of the original recipients of the | |
27461 | message. The &%fail%& command causes all the original recipients to be failed, | |
27462 | and a bounce message to be created. The &%freeze%& command suspends all | |
27463 | delivery attempts for the original recipients. In all cases, any new deliveries | |
27464 | that are specified by the filter are attempted as normal after the filter has | |
27465 | run. | |
27466 | ||
27467 | The &%freeze%& command is ignored if the message has been manually unfrozen and | |
168e428f PH |
27468 | not manually frozen since. This means that automatic freezing by a system |
27469 | filter can be used as a way of checking out suspicious messages. If a message | |
27470 | is found to be all right, manually unfreezing it allows it to be delivered. | |
27471 | ||
9b371988 PH |
27472 | .cindex "log" "&%fail%& command log line" |
27473 | .cindex "&%fail%&" "log line; reducing" | |
168e428f PH |
27474 | The text given with a fail command is used as part of the bounce message as |
27475 | well as being written to the log. If the message is quite long, this can fill | |
27476 | up a lot of log space when such failures are common. To reduce the size of the | |
27477 | log message, Exim interprets the text in a special way if it starts with the | |
9b371988 | 27478 | two characters &`<<`& and contains &`>>`& later. The text between these two |
168e428f PH |
27479 | strings is written to the log, and the rest of the text is used in the bounce |
27480 | message. For example: | |
9b371988 | 27481 | .code |
168e428f PH |
27482 | fail "<<filter test 1>>Your message is rejected \ |
27483 | because it contains attachments that we are \ | |
27484 | not prepared to receive." | |
9b371988 PH |
27485 | .endd |
27486 | ||
27487 | .cindex "loop" "caused by &%fail%&" | |
27488 | Take great care with the &%fail%& command when basing the decision to fail on | |
27489 | the contents of the message, because the bounce message will of course include | |
27490 | the contents of the original message and will therefore trigger the &%fail%& | |
27491 | command again (causing a mail loop) unless steps are taken to prevent this. | |
27492 | Testing the &%error_message%& condition is one way to prevent this. You could | |
27493 | use, for example | |
27494 | .code | |
27495 | if $message_body contains "this is spam" and not error_message | |
27496 | then fail text "spam is not wanted here" endif | |
27497 | .endd | |
168e428f PH |
27498 | though of course that might let through unwanted bounce messages. The |
27499 | alternative is clever checking of the body and/or headers to detect bounces | |
27500 | generated by the filter. | |
27501 | ||
27502 | The interpretation of a system filter file ceases after a | |
9b371988 PH |
27503 | &%defer%&, |
27504 | &%freeze%&, or &%fail%& command is obeyed. However, any deliveries that were | |
27505 | set up earlier in the filter file are honoured, so you can use a sequence such | |
27506 | as | |
27507 | .code | |
27508 | mail ... | |
27509 | freeze | |
27510 | .endd | |
168e428f PH |
27511 | to send a specified message when the system filter is freezing (or deferring or |
27512 | failing) a message. The normal deliveries for the message do not, of course, | |
27513 | take place. | |
27514 | ||
27515 | ||
27516 | ||
9b371988 PH |
27517 | .section "Adding and removing headers in a system filter" "SECTaddremheasys" |
27518 | .cindex "header lines" "adding; in system filter" | |
27519 | .cindex "header lines" "removing; in system filter" | |
27520 | .cindex "filter" "header lines; adding/removing" | |
168e428f | 27521 | Two filter commands that are available only in system filters are: |
9b371988 PH |
27522 | .code |
27523 | headers add <string> | |
27524 | headers remove <string> | |
27525 | .endd | |
27526 | The argument for the &%headers add%& is a string that is expanded and then | |
27527 | added to the end of the message's headers. It is the responsibility of the | |
27528 | filter maintainer to make sure it conforms to RFC 2822 syntax. Leading white | |
27529 | space is ignored, and if the string is otherwise empty, or if the expansion is | |
27530 | forced to fail, the command has no effect. | |
27531 | ||
27532 | You can use &"\n"& within the string, followed by white space, to specify | |
168e428f | 27533 | continued header lines. More than one header may be added in one command by |
9b371988 | 27534 | including &"\n"& within the string without any following white space. For |
168e428f | 27535 | example: |
9b371988 | 27536 | .code |
168e428f PH |
27537 | headers add "X-header-1: ....\n \ |
27538 | continuation of X-header-1 ...\n\ | |
27539 | X-header-2: ...." | |
9b371988 | 27540 | .endd |
168e428f PH |
27541 | Note that the header line continuation white space after the first newline must |
27542 | be placed before the backslash that continues the input string, because white | |
27543 | space after input continuations is ignored. | |
27544 | ||
9b371988 | 27545 | The argument for &%headers remove%& is a colon-separated list of header names. |
168e428f | 27546 | This command applies only to those headers that are stored with the message; |
9b371988 PH |
27547 | those that are added at delivery time (such as &'Envelope-To:'& and |
27548 | &'Return-Path:'&) cannot be removed by this means. If there is more than one | |
168e428f PH |
27549 | header with the same name, they are all removed. |
27550 | ||
9b371988 | 27551 | The &%headers%& command in a system filter makes an immediate change to the set |
168e428f PH |
27552 | of header lines that was received with the message (with possible additions |
27553 | from ACL processing). Subsequent commands in the system filter operate on the | |
27554 | modified set, which also forms the basis for subsequent message delivery. | |
27555 | Unless further modified during routing or transporting, this set of headers is | |
27556 | used for all recipients of the message. | |
27557 | ||
27558 | During routing and transporting, the variables that refer to the contents of | |
27559 | header lines refer only to those lines that are in this set. Thus, header lines | |
27560 | that are added by a system filter are visible to users' filter files and to all | |
27561 | routers and transports. This contrasts with the manipulation of header lines by | |
27562 | routers and transports, which is not immediate, but which instead is saved up | |
9b371988 PH |
27563 | until the message is actually being written (see section |
27564 | &<<SECTheadersaddrem>>&). | |
168e428f PH |
27565 | |
27566 | If the message is not delivered at the first attempt, header lines that were | |
27567 | added by the system filter are stored with the message, and so are still | |
27568 | present at the next delivery attempt. Header lines that were removed are still | |
9b371988 PH |
27569 | present, but marked &"deleted"& so that they are not transported with the |
27570 | message. For this reason, it is usual to make the &%headers%& command | |
27571 | conditional on &%first_delivery%& so that the set of header lines is not | |
27572 | modified more than once. | |
168e428f PH |
27573 | |
27574 | Because header modification in a system filter acts immediately, you have to | |
27575 | use an indirect approach if you want to modify the contents of a header line. | |
27576 | For example: | |
9b371988 PH |
27577 | .code |
27578 | headers add "Old-Subject: $h_subject:" | |
27579 | headers remove "Subject" | |
27580 | headers add "Subject: new subject (was: $h_old-subject:)" | |
27581 | headers remove "Old-Subject" | |
27582 | .endd | |
168e428f PH |
27583 | |
27584 | ||
27585 | ||
9b371988 PH |
27586 | .section "Setting an errors address in a system filter" |
27587 | .cindex "envelope sender" | |
27588 | In a system filter, if a &%deliver%& command is followed by | |
27589 | .code | |
27590 | errors_to <some address> | |
27591 | .endd | |
168e428f PH |
27592 | in order to change the envelope sender (and hence the error reporting) for that |
27593 | delivery, any address may be specified. (In a user filter, only the current | |
27594 | user's address can be set.) For example, if some mail is being monitored, you | |
27595 | might use | |
9b371988 PH |
27596 | .code |
27597 | unseen deliver monitor@spying.example errors_to root@local.example | |
27598 | .endd | |
168e428f PH |
27599 | to take a copy which would not be sent back to the normal error reporting |
27600 | address if its delivery failed. | |
27601 | ||
27602 | ||
27603 | ||
9b371988 PH |
27604 | .section "Per-address filtering" "SECTperaddfil" |
27605 | .cindex "&$domain$&" | |
27606 | .cindex "&$local_part$&" | |
168e428f PH |
27607 | In contrast to the system filter, which is run just once per message for each |
27608 | delivery attempt, it is also possible to set up a system-wide filtering | |
27609 | operation that runs once for each recipient address. In this case, variables | |
9b371988 | 27610 | such as &$local_part$& and &$domain$& can be used, and indeed, the choice of |
168e428f PH |
27611 | filter file could be made dependent on them. This is an example of a router |
27612 | which implements such a filter: | |
9b371988 PH |
27613 | .code |
27614 | central_filter: | |
27615 | check_local_user | |
27616 | driver = redirect | |
27617 | domains = +local_domains | |
27618 | file = /central/filters/$local_part | |
27619 | no_verify | |
27620 | allow_filter | |
27621 | allow_freeze | |
27622 | .endd | |
168e428f | 27623 | The filter is run in a separate process under its own uid. Therefore, either |
9b371988 PH |
27624 | &%check_local_user%& must be set (as above), in which case the filter is run as |
27625 | the local user, or the &%user%& option must be used to specify which user to | |
27626 | use. If both are set, &%user%& overrides. | |
168e428f PH |
27627 | |
27628 | Care should be taken to ensure that none of the commands in the filter file | |
27629 | specify a significant delivery if the message is to go on to be delivered to | |
27630 | its intended recipient. The router will not then claim to have dealt with the | |
27631 | address, so it will be passed on to subsequent routers to be delivered in the | |
27632 | normal way. | |
27633 | ||
27634 | ||
27635 | ||
27636 | ||
27637 | ||
27638 | ||
9b371988 PH |
27639 | . //////////////////////////////////////////////////////////////////////////// |
27640 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 27641 | |
9b371988 PH |
27642 | .chapter "Message processing" "CHAPmsgproc" |
27643 | .cindex "message" "general processing" | |
168e428f PH |
27644 | Exim performs various transformations on the sender and recipient addresses of |
27645 | all messages that it handles, and also on the messages' header lines. Some of | |
27646 | these are optional and configurable, while others always take place. All of | |
27647 | this processing, except rewriting as a result of routing, and the addition or | |
27648 | removal of header lines while delivering, happens when a message is received, | |
27649 | before it is placed on Exim's queue. | |
27650 | ||
27651 | Some of the automatic processing takes place by default only for | |
9b371988 PH |
27652 | &"locally-originated"& messages. This adjective is used to describe messages |
27653 | that are not received over TCP/IP, but instead are passed to an Exim process on | |
27654 | its standard input. This includes the interactive &"local SMTP"& case that is | |
27655 | set up by the &%-bs%& command line option. | |
168e428f | 27656 | |
9b371988 | 27657 | &*Note*&: Messages received over TCP/IP on the loopback interface (127.0.0.1 |
168e428f PH |
27658 | or ::1) are not considered to be locally-originated. Exim does not treat the |
27659 | loopback interface specially in any way. | |
27660 | ||
27661 | If you want the loopback interface to be treated specially, you must ensure | |
27662 | that there are appropriate entries in your ACLs. | |
27663 | ||
27664 | ||
27665 | ||
27666 | ||
9b371988 PH |
27667 | .section "Submission mode for non-local messages" "SECTsubmodnon" |
27668 | .cindex "message" "submission" | |
27669 | .cindex "submission mode" | |
27670 | .new | |
068aaea8 | 27671 | Processing that happens automatically for locally-originated messages (unless |
9b371988 PH |
27672 | &%suppress_local_fixups%& is set) can also be requested for messages that are |
27673 | received over TCP/IP. The term &"submission mode"& is used to describe this | |
068aaea8 | 27674 | state. Submisssion mode is set by the modifier |
9b371988 PH |
27675 | .wen |
27676 | .code | |
27677 | control = submission | |
27678 | .endd | |
068aaea8 | 27679 | in a MAIL, RCPT, or pre-data ACL for an incoming message (see sections |
9b371988 PH |
27680 | &<<SECTACLmodi>>& and &<<SECTcontrols>>&). This makes Exim treat the message as |
27681 | a local submission, and is normally used when the source of the message is | |
27682 | known to be an MUA running on a client host (as opposed to an MTA). For | |
27683 | example, to set submission mode for messages originating on the IPv4 loopback | |
27684 | interface, you could include the following in the MAIL ACL: | |
27685 | .code | |
27686 | warn hosts = 127.0.0.1 | |
27687 | control = submission | |
27688 | .endd | |
27689 | .cindex "&%sender_retain%&" | |
168e428f PH |
27690 | There are some options that can be used when setting submission mode. A slash |
27691 | is used to separate options. For example: | |
9b371988 PH |
27692 | .code |
27693 | control = submission/sender_retain | |
27694 | .endd | |
27695 | Specifying &%sender_retain%& has the effect of setting &%local_sender_retain%& | |
27696 | true and &%local_from_check%& false for the current incoming message. The first | |
27697 | of these allows an existing &'Sender:'& header in the message to remain, and | |
27698 | the second suppresses the check to ensure that &'From:'& matches the | |
27699 | authenticated sender. With this setting, Exim still fixes up messages by adding | |
27700 | &'Date:'& and &'Message-ID:'& header lines if they are missing, but makes no | |
27701 | attempt to check sender authenticity in header lines. | |
27702 | ||
27703 | When &%sender_retain%& is not set, a submission mode setting may specify a | |
27704 | domain to be used when generating a &'From:'& or &'Sender:'& header line. For | |
27705 | example: | |
27706 | .code | |
27707 | control = submission/domain=some.domain | |
27708 | .endd | |
27709 | .new | |
168e428f | 27710 | The domain may be empty. How this value is used is described in sections |
9b371988 PH |
27711 | &<<SECTthefrohea>>& and &<<SECTthesenhea>>&. There is also a &%name%& option |
27712 | that allows you to specify the user's full name for inclusion in a created | |
27713 | &'Sender:'& or &'From:'& header line. For example: | |
27714 | .code | |
068aaea8 PH |
27715 | accept authenticated = * |
27716 | control = submission/domain=wonderland.example/\ | |
27717 | name=${lookup {$authenticated_id} \ | |
27718 | lsearch {/etc/exim/namelist}} | |
9b371988 PH |
27719 | .endd |
27720 | Because the name may contain any characters, including slashes, the &%name%& | |
068aaea8 | 27721 | option must be given last. The remainder of the string is used as the name. For |
9b371988 PH |
27722 | the example above, if &_/etc/exim/namelist_& contains: |
27723 | .code | |
068aaea8 | 27724 | bigegg: Humpty Dumpty |
9b371988 PH |
27725 | .endd |
27726 | then when the sender has authenticated as &'bigegg'&, the generated &'Sender:'& | |
068aaea8 | 27727 | line would be: |
9b371988 | 27728 | .code |
068aaea8 | 27729 | Sender: Humpty Dumpty <bigegg@wonderland.example> |
9b371988 PH |
27730 | .endd |
27731 | .cindex "return path" "in submission mode" | |
068aaea8 | 27732 | By default, submission mode forces the return path to the same address as is |
9b371988 PH |
27733 | used to create the &'Sender:'& header. However, if &%sender_retain%& is |
27734 | specified, the return path is also left unchanged. | |
068aaea8 | 27735 | |
9b371988 | 27736 | &*Note*&: The changes caused by submission mode take effect after the predata |
068aaea8 PH |
27737 | ACL. This means that any sender checks performed before the fix-ups use the |
27738 | untrusted sender address specified by the user, not the trusted sender address | |
27739 | specified by submission mode. Although this might be slightly unexpected, it | |
27740 | does mean that you can configure ACL checks to spot that a user is trying to | |
27741 | spoof another's address. | |
9b371988 | 27742 | .wen |
168e428f | 27743 | |
9b371988 PH |
27744 | .section "Line endings" "SECTlineendings" |
27745 | .cindex "line endings" | |
27746 | .cindex "carriage return" | |
27747 | .cindex "linefeed" | |
168e428f PH |
27748 | RFC 2821 specifies that CRLF (two characters: carriage-return, followed by |
27749 | linefeed) is the line ending for messages transmitted over the Internet using | |
27750 | SMTP over TCP/IP. However, within individual operating systems, different | |
27751 | conventions are used. For example, Unix-like systems use just LF, but others | |
27752 | use CRLF or just CR. | |
27753 | ||
27754 | Exim was designed for Unix-like systems, and internally, it stores messages | |
27755 | using the system's convention of a single LF as a line terminator. When | |
27756 | receiving a message, all line endings are translated to this standard format. | |
27757 | Originally, it was thought that programs that passed messages directly to an | |
27758 | MTA within an operating system would use that system's convention. Experience | |
27759 | has shown that this is not the case; for example, there are Unix applications | |
27760 | that use CRLF in this circumstance. For this reason, and for compatibility with | |
27761 | other MTAs, the way Exim handles line endings for all messages is now as | |
27762 | follows: | |
27763 | ||
9b371988 PH |
27764 | .ilist |
27765 | LF not preceded by CR is treated as a line ending. | |
27766 | .next | |
27767 | CR is treated as a line ending; if it is immediately followed by LF, the LF | |
168e428f | 27768 | is ignored. |
9b371988 PH |
27769 | .next |
27770 | The sequence &"CR, dot, CR"& does not terminate an incoming SMTP message, | |
168e428f PH |
27771 | nor a local message in the state where a line containing only a dot is a |
27772 | terminator. | |
9b371988 PH |
27773 | .next |
27774 | If a bare CR is encountered within a header line, an extra space is added after | |
168e428f PH |
27775 | the line terminator so as not to end the header line. The reasoning behind this |
27776 | is that bare CRs in header lines are most likely either to be mistakes, or | |
27777 | people trying to play silly games. | |
9b371988 PH |
27778 | .next |
27779 | If the first header line received in a message ends with CRLF, a subsequent | |
168e428f PH |
27780 | bare LF in a header line is treated in the same way as a bare CR in a header |
27781 | line. | |
9b371988 | 27782 | .endlist |
168e428f PH |
27783 | |
27784 | ||
27785 | ||
27786 | ||
27787 | ||
9b371988 PH |
27788 | .section "Unqualified addresses" |
27789 | .cindex "unqualified addresses" | |
27790 | .cindex "address" "qualification" | |
168e428f PH |
27791 | By default, Exim expects every envelope address it receives from an external |
27792 | host to be fully qualified. Unqualified addresses cause negative responses to | |
27793 | SMTP commands. However, because SMTP is used as a means of transporting | |
27794 | messages from MUAs running on personal workstations, there is sometimes a | |
27795 | requirement to accept unqualified addresses from specific hosts or IP networks. | |
27796 | ||
27797 | Exim has two options that separately control which hosts may send unqualified | |
27798 | sender or receipient addresses in SMTP commands, namely | |
9b371988 | 27799 | &%sender_unqualified_hosts%& and &%recipient_unqualified_hosts%&. In both |
168e428f | 27800 | cases, if an unqualified address is accepted, it is qualified by adding the |
9b371988 | 27801 | value of &%qualify_domain%& or &%qualify_recipient%&, as appropriate. |
168e428f | 27802 | |
9b371988 PH |
27803 | .cindex "&%qualify_domain%&" |
27804 | .cindex "&%qualify_recipient%&" | |
168e428f | 27805 | Unqualified addresses in header lines are automatically qualified for messages |
9b371988 | 27806 | that are locally originated, unless the &%-bnq%& option is given on the command |
168e428f PH |
27807 | line. For messages received over SMTP, unqualified addresses in header lines |
27808 | are qualified only if unqualified addresses are permitted in SMTP commands. In | |
27809 | other words, such qualification is also controlled by | |
9b371988 | 27810 | &%sender_unqualified_hosts%& and &%recipient_unqualified_hosts%&, |
168e428f PH |
27811 | |
27812 | ||
27813 | ||
27814 | ||
9b371988 PH |
27815 | .section "The UUCP From line" |
27816 | .cindex "&""From""& line" | |
27817 | .cindex "UUCP" "&""From""& line" | |
27818 | .cindex "sender" "address" | |
27819 | .cindex "&%uucp_from_pattern%&" | |
27820 | .cindex "&%uucp_from_sender%&" | |
27821 | .cindex "envelope sender" | |
27822 | .cindex "Sendmail compatibility" "&""From""& line" | |
168e428f PH |
27823 | Messages that have come from UUCP (and some other applications) often begin |
27824 | with a line containing the envelope sender and a timestamp, following the word | |
9b371988 PH |
27825 | &"From"&. Examples of two common formats are: |
27826 | .code | |
27827 | From a.oakley@berlin.mus Fri Jan 5 12:35 GMT 1996 | |
27828 | From f.butler@berlin.mus Fri, 7 Jan 97 14:00:00 GMT | |
27829 | .endd | |
168e428f PH |
27830 | This line precedes the RFC 2822 header lines. For compatibility with Sendmail, |
27831 | Exim recognizes such lines at the start of messages that are submitted to it | |
27832 | via the command line (that is, on the standard input). It does not recognize | |
27833 | such lines in incoming SMTP messages, unless the sending host matches | |
9b371988 PH |
27834 | &%ignore_fromline_hosts%& or the &%-bs%& option was used for a local message |
27835 | and &%ignore_fromline_local%& is set. The recognition is controlled by a | |
27836 | regular expression that is defined by the &%uucp_from_pattern%& option, whose | |
27837 | default value matches the two common cases shown above and puts the address | |
27838 | that follows &"From"& into &$1$&. | |
27839 | ||
27840 | .cindex "numerical variables (&$1$& &$2$& etc)" "in &""From ""& line handling" | |
27841 | When the caller of Exim for a non-SMTP message that contains a &"From"& line is | |
27842 | a trusted user, the message's sender address is constructed by expanding the | |
27843 | contents of &%uucp_sender_address%&, whose default value is &"$1"&. This is | |
27844 | then parsed as an RFC 2822 address. If there is no domain, the local part is | |
27845 | qualified with &%qualify_domain%& unless it is the empty string. However, if | |
27846 | the command line &%-f%& option is used, it overrides the &"From"& line. | |
27847 | ||
27848 | If the caller of Exim is not trusted, the &"From"& line is recognized, but the | |
168e428f | 27849 | sender address is not changed. This is also the case for incoming SMTP messages |
9b371988 | 27850 | that are permitted to contain &"From"& lines. |
168e428f | 27851 | |
9b371988 | 27852 | Only one &"From"& line is recognized. If there is more than one, the second is |
168e428f | 27853 | treated as a data line that starts the body of the message, as it is not valid |
9b371988 PH |
27854 | as a header line. This also happens if a &"From"& line is present in an |
27855 | incoming SMTP message from a source that is not permitted to send them. | |
168e428f PH |
27856 | |
27857 | ||
27858 | ||
9b371988 PH |
27859 | .section "Resent- header lines" |
27860 | .cindex "&%Resent-%& header lines" | |
168e428f | 27861 | RFC 2822 makes provision for sets of header lines starting with the string |
9b371988 PH |
27862 | &`Resent-`& to be added to a message when it is resent by the original |
27863 | recipient to somebody else. These headers are &'Resent-Date:'&, | |
27864 | &'Resent-From:'&, &'Resent-Sender:'&, &'Resent-To:'&, &'Resent-Cc:'&, | |
27865 | &'Resent-Bcc:'& and &'Resent-Message-ID:'&. The RFC says: | |
168e428f | 27866 | |
9b371988 PH |
27867 | .blockquote |
27868 | &'Resent fields are strictly informational. They MUST NOT be used in the normal | |
27869 | processing of replies or other such automatic actions on messages.'& | |
27870 | .endblockquote | |
168e428f PH |
27871 | |
27872 | This leaves things a bit vague as far as other processing actions such as | |
9b371988 | 27873 | address rewriting are concerned. Exim treats &%Resent-%& header lines as |
168e428f PH |
27874 | follows: |
27875 | ||
9b371988 PH |
27876 | .ilist |
27877 | A &'Resent-From:'& line that just contains the login id of the submitting user | |
27878 | is automatically rewritten in the same way as &'From:'& (see below). | |
27879 | .next | |
27880 | If there's a rewriting rule for a particular header line, it is also applied to | |
27881 | &%Resent-%& header lines of the same type. For example, a rule that rewrites | |
27882 | &'From:'& also rewrites &'Resent-From:'&. | |
27883 | .next | |
27884 | For local messages, if &'Sender:'& is removed on input, &'Resent-Sender:'& is | |
27885 | also removed. | |
27886 | .next | |
27887 | For a locally-submitted message, | |
27888 | if there are any &%Resent-%& header lines but no &'Resent-Date:'&, | |
27889 | &'Resent-From:'&, or &'Resent-Message-Id:'&, they are added as necessary. It is | |
27890 | the contents of &'Resent-Message-Id:'& (rather than &'Message-Id:'&) which are | |
168e428f | 27891 | included in log lines in this case. |
9b371988 PH |
27892 | .next |
27893 | The logic for adding &'Sender:'& is duplicated for &'Resent-Sender:'& when any | |
27894 | &%Resent-%& header lines are present. | |
27895 | .endlist | |
168e428f | 27896 | |
168e428f PH |
27897 | |
27898 | ||
27899 | ||
9b371988 | 27900 | .section "The Auto-Submitted: header line" |
168e428f | 27901 | Whenever Exim generates a bounce or a delay warning message, it includes the |
9b371988 PH |
27902 | header line: |
27903 | .new | |
27904 | .code | |
27905 | Auto-Submitted: auto-replied | |
27906 | .endd | |
27907 | .wen | |
27908 | ||
27909 | .section "The Bcc: header line" | |
27910 | .cindex "&'Bcc:'& header line" | |
27911 | If Exim is called with the &%-t%& option, to take recipient addresses from a | |
27912 | message's header, it removes any &'Bcc:'& header line that may exist (after | |
27913 | extracting its addresses). If &%-t%& is not present on the command line, any | |
27914 | existing &'Bcc:'& is not removed. | |
27915 | ||
27916 | ||
27917 | .section "The Date: header line" | |
27918 | .cindex "&'Date:'& header line" | |
27919 | .new | |
27920 | If a locally-generated or submission-mode message has no &'Date:'& header line, | |
068aaea8 | 27921 | Exim adds one, using the current date and time, unless the |
9b371988 PH |
27922 | &%suppress_local_fixups%& control has been specified. |
27923 | .wen | |
168e428f | 27924 | |
9b371988 PH |
27925 | .section "The Delivery-date: header line" |
27926 | .cindex "&'Delivery-date:'& header line" | |
27927 | .cindex "&%delivery_date_remove%&" | |
27928 | &'Delivery-date:'& header lines are not part of the standard RFC 2822 header | |
168e428f | 27929 | set. Exim can be configured to add them to the final delivery of messages. (See |
9b371988 PH |
27930 | the generic &%delivery_date_add%& transport option.) They should not be present |
27931 | in messages in transit. If the &%delivery_date_remove%& configuration option is | |
27932 | set (the default), Exim removes &'Delivery-date:'& header lines from incoming | |
168e428f PH |
27933 | messages. |
27934 | ||
27935 | ||
9b371988 PH |
27936 | .section "The Envelope-to: header line" |
27937 | .cindex "&'Envelope-to:'& header line" | |
27938 | .cindex "&%envelope_to_remove%&" | |
27939 | &'Envelope-to:'& header lines are not part of the standard RFC 2822 header set. | |
168e428f | 27940 | Exim can be configured to add them to the final delivery of messages. (See the |
9b371988 PH |
27941 | generic &%envelope_to_add%& transport option.) They should not be present in |
27942 | messages in transit. If the &%envelope_to_remove%& configuration option is set | |
27943 | (the default), Exim removes &'Envelope-to:'& header lines from incoming | |
168e428f PH |
27944 | messages. |
27945 | ||
27946 | ||
9b371988 PH |
27947 | .section "The From: header line" "SECTthefrohea" |
27948 | .cindex "&'From:'& header line" | |
27949 | .cindex "Sendmail compatibility" "&""From""& line" | |
27950 | .cindex "message" "submission" | |
27951 | .cindex "submission mode" | |
27952 | If a submission-mode message does not contain a &'From:'& header line, Exim | |
27953 | adds one if either of the following conditions is true: | |
168e428f | 27954 | |
9b371988 PH |
27955 | .ilist |
27956 | The envelope sender address is not empty (that is, this is not a bounce | |
168e428f | 27957 | message). The added header line copies the envelope sender address. |
9b371988 PH |
27958 | .next |
27959 | .cindex "&$authenticated_id$&" | |
27960 | The SMTP session is authenticated and &$authenticated_id$& is not empty. | |
27961 | .olist | |
27962 | .cindex "&$qualify_domain$&" | |
068aaea8 | 27963 | If no domain is specified by the submission control, the local part is |
9b371988 PH |
27964 | &$authenticated_id$& and the domain is &$qualify_domain$&. |
27965 | .next | |
27966 | If a non-empty domain is specified by the submission control, the local | |
27967 | part is &$authenticated_id$&, and the the domain is the specified domain. | |
27968 | .next | |
27969 | If an empty domain is specified by the submission control, | |
27970 | &$authenticated_id$& is assumed to be the complete address. | |
27971 | .endlist | |
27972 | .endlist | |
168e428f PH |
27973 | |
27974 | A non-empty envelope sender takes precedence. | |
27975 | ||
9b371988 PH |
27976 | .new |
27977 | If a locally-generated incoming message does not contain a &'From:'& header | |
27978 | line, and the &%suppress_local_fixups%& control is not set, Exim adds one | |
27979 | containing the sender's address. The calling user's login name and full name | |
27980 | are used to construct the address, as described in section &<<SECTconstr>>&. | |
27981 | They are obtained from the password data by calling &[getpwuid()]& (but see the | |
27982 | &%unknown_login%& configuration option). The address is qualified with | |
27983 | &%qualify_domain%&. | |
27984 | .wen | |
168e428f PH |
27985 | |
27986 | For compatibility with Sendmail, if an incoming, non-SMTP message has a | |
9b371988 | 27987 | &'From:'& header line containing just the unqualified login name of the calling |
168e428f | 27988 | user, this is replaced by an address containing the user's login name and full |
9b371988 | 27989 | name as described in section &<<SECTconstr>>&. |
168e428f PH |
27990 | |
27991 | ||
9b371988 PH |
27992 | .section "The Message-ID: header line" |
27993 | .cindex "&'Message-ID:'& header line" | |
27994 | .cindex "message" "submission" | |
27995 | .cindex "&%message_id_header_text%&" | |
27996 | .new | |
168e428f | 27997 | If a locally-generated or submission-mode incoming message does not contain a |
9b371988 PH |
27998 | &'Message-ID:'& or &'Resent-Message-ID:'& header line, and the |
27999 | &%suppress_local_fixups%& control is not set, Exim adds a suitable header line | |
28000 | to the message. If there are any &'Resent-:'& headers in the message, it | |
28001 | creates &'Resent-Message-ID:'&. The id is constructed from Exim's internal | |
28002 | message id, preceded by the letter E to ensure it starts with a letter, and | |
28003 | followed by @ and the primary host name. Additional information can be included | |
28004 | in this header line by setting the &%message_id_header_text%& and/or | |
28005 | &%message_id_header_domain%& options. | |
28006 | .wen | |
28007 | ||
28008 | ||
28009 | .section "The Received: header line" | |
28010 | .cindex "&'Received:'& header line" | |
28011 | A &'Received:'& header line is added at the start of every message. The | |
28012 | contents are defined by the &%received_header_text%& configuration option, and | |
28013 | Exim automatically adds a semicolon and a timestamp to the configured string. | |
28014 | ||
28015 | The &'Received:'& header is generated as soon as the message's header lines | |
28016 | have been received. At this stage, the timestamp in the &'Received:'& header | |
28017 | line is the time that the message started to be received. This is the value | |
28018 | that is seen by the DATA ACL and by the &[local_scan()]& function. | |
28019 | ||
28020 | Once a message is accepted, the timestamp in the &'Received:'& header line is | |
168e428f PH |
28021 | changed to the time of acceptance, which is (apart from a small delay while the |
28022 | -H spool file is written) the earliest time at which delivery could start. | |
28023 | ||
28024 | ||
28025 | ||
9b371988 PH |
28026 | .section "The Return-path: header line" |
28027 | .cindex "&'Return-path:'& header line" | |
28028 | .cindex "&%return_path_remove%&" | |
28029 | &'Return-path:'& header lines are defined as something an MTA may insert when | |
28030 | it does the final delivery of messages. (See the generic &%return_path_add%& | |
168e428f | 28031 | transport option.) Therefore, they should not be present in messages in |
9b371988 PH |
28032 | transit. If the &%return_path_remove%& configuration option is set (the |
28033 | default), Exim removes &'Return-path:'& header lines from incoming messages. | |
168e428f PH |
28034 | |
28035 | ||
28036 | ||
9b371988 PH |
28037 | .section "The Sender: header line" "SECTthesenhea" |
28038 | .cindex "&'Sender:'& header line" | |
28039 | .cindex "message" "submission" | |
28040 | .new | |
168e428f | 28041 | For a locally-originated message from an untrusted user, Exim may remove an |
9b371988 PH |
28042 | existing &'Sender:'& header line, and it may add a new one. You can modify |
28043 | these actions by setting the &%local_sender_retain%& option true, the | |
28044 | &%local_from_check%& option false, or by using the &%suppress_local_fixups%& | |
068aaea8 | 28045 | control setting. |
168e428f | 28046 | |
9b371988 PH |
28047 | When a local message is received from an untrusted user and |
28048 | &%local_from_check%& is true (the default), and the &%suppress_local_fixups%& | |
28049 | control has not been set, a check is made to see if the address given in the | |
28050 | &'From:'& header line is the correct (local) sender of the message. The address | |
28051 | that is expected has the login name as the local part and the value of | |
28052 | &%qualify_domain%& as the domain. Prefixes and suffixes for the local part can | |
28053 | be permitted by setting &%local_from_prefix%& and &%local_from_suffix%& | |
28054 | appropriately. If &'From:'& does not contain the correct sender, a &'Sender:'& | |
28055 | line is added to the message. | |
28056 | .wen | |
28057 | ||
28058 | If you set &%local_from_check%& false, this checking does not occur. However, | |
28059 | the removal of an existing &'Sender:'& line still happens, unless you also set | |
28060 | &%local_sender_retain%& to be true. It is not possible to set both of these | |
168e428f PH |
28061 | options true at the same time. |
28062 | ||
9b371988 PH |
28063 | .cindex "submission mode" |
28064 | By default, no processing of &'Sender:'& header lines is done for messages | |
168e428f | 28065 | received over TCP/IP or for messages submitted by trusted users. However, when |
9b371988 | 28066 | a message is received over TCP/IP in submission mode, and &%sender_retain%& is |
168e428f PH |
28067 | not specified on the submission control, the following processing takes place: |
28068 | ||
9b371988 PH |
28069 | .cindex "&$authenticated_id$&" |
28070 | First, any existing &'Sender:'& lines are removed. Then, if the SMTP session is | |
28071 | authenticated, and &$authenticated_id$& is not empty, a sender address is | |
168e428f PH |
28072 | created as follows: |
28073 | ||
9b371988 PH |
28074 | .ilist |
28075 | .cindex "&$qualify_domain$&" | |
068aaea8 | 28076 | If no domain is specified by the submission control, the local part is |
9b371988 PH |
28077 | &$authenticated_id$& and the domain is &$qualify_domain$&. |
28078 | .next | |
28079 | If a non-empty domain is specified by the submission control, the local part | |
28080 | is &$authenticated_id$&, and the the domain is the specified domain. | |
28081 | .next | |
28082 | If an empty domain is specified by the submission control, | |
28083 | &$authenticated_id$& is assumed to be the complete address. | |
28084 | .endlist | |
28085 | ||
28086 | This address is compared with the address in the &'From:'& header line. If they | |
28087 | are different, a &'Sender:'& header line containing the created address is | |
28088 | added. Prefixes and suffixes for the local part in &'From:'& can be permitted | |
28089 | by setting &%local_from_prefix%& and &%local_from_suffix%& appropriately. | |
28090 | ||
28091 | .new | |
28092 | .cindex "return path" "created from &'Sender:'&" | |
28093 | &*Note*&: Whenever a &'Sender:'& header line is created, the return path for | |
28094 | the message (the envelope sender address) is changed to be the same address, | |
28095 | except in the case of submission mode when &%sender_retain%& is specified. | |
28096 | .wen | |
28097 | ||
28098 | ||
28099 | ||
28100 | .section "Adding and removing header lines in routers and transports" &&& | |
28101 | "SECTheadersaddrem" | |
28102 | .cindex "header lines" "adding; in router or transport" | |
28103 | .cindex "header lines" "removing; in router or transport" | |
28104 | .new | |
168e428f PH |
28105 | When a message is delivered, the addition and removal of header lines can be |
28106 | specified in a system filter, or on any of the routers and transports that | |
9b371988 | 28107 | process the message. Section &<<SECTaddremheasys>>& contains details about |
068aaea8 | 28108 | modifying headers in a system filter. Header lines can also be added in an ACL |
9b371988 PH |
28109 | as a message is received (see section &<<SECTaddheadwarn>>&). |
28110 | .wen | |
168e428f PH |
28111 | |
28112 | In contrast to what happens in a system filter, header modifications that are | |
28113 | specified on routers and transports apply only to the particular recipient | |
28114 | addresses that are being processed by those routers and transports. These | |
28115 | changes do not actually take place until a copy of the message is being | |
28116 | transported. Therefore, they do not affect the basic set of header lines, and | |
28117 | they do not affect the values of the variables that refer to header lines. | |
28118 | ||
9b371988 PH |
28119 | .new |
28120 | &*Note*&: In particular, this means that any expansions in the configuration of | |
068aaea8 PH |
28121 | the transport cannot refer to the modified header lines, because such |
28122 | expansions all occur before the message is actually transported. | |
9b371988 | 28123 | .wen |
068aaea8 | 28124 | |
9b371988 | 28125 | For both routers and transports, the result of expanding a &%headers_add%& |
168e428f | 28126 | option must be in the form of one or more RFC 2822 header lines, separated by |
9b371988 PH |
28127 | newlines (coded as &"\n"&). For example: |
28128 | .code | |
168e428f PH |
28129 | headers_add = X-added-header: added by $primary_hostname\n\ |
28130 | X-added-second: another added header line | |
9b371988 | 28131 | .endd |
168e428f PH |
28132 | Exim does not check the syntax of these added header lines. |
28133 | ||
9b371988 | 28134 | The result of expanding &%headers_remove%& must consist of a colon-separated |
168e428f PH |
28135 | list of header names. This is confusing, because header names themselves are |
28136 | often terminated by colons. In this case, the colons are the list separators, | |
28137 | not part of the names. For example: | |
9b371988 PH |
28138 | .code |
28139 | headers_remove = return-receipt-to:acknowledge-to | |
28140 | .endd | |
28141 | When &%headers_add%& or &%headers_remove%& is specified on a router, its value | |
28142 | is expanded at routing time, and then associated with all addresses that are | |
168e428f PH |
28143 | accepted by that router, and also with any new addresses that it generates. If |
28144 | an address passes through several routers as a result of aliasing or | |
28145 | forwarding, the changes are cumulative. | |
28146 | ||
9b371988 | 28147 | .cindex "&%unseen%& option" |
168e428f | 28148 | However, this does not apply to multiple routers that result from the use of |
9b371988 PH |
28149 | the &%unseen%& option. Any header modifications that were specified by the |
28150 | &"unseen"& router or its predecessors apply only to the &"unseen"& delivery. | |
168e428f | 28151 | |
9b371988 | 28152 | Addresses that end up with different &%headers_add%& or &%headers_remove%& |
168e428f PH |
28153 | settings cannot be delivered together in a batch, so a transport is always |
28154 | dealing with a set of addresses that have the same header-processing | |
28155 | requirements. | |
28156 | ||
28157 | The transport starts by writing the original set of header lines that arrived | |
28158 | with the message, possibly modified by the system filter. As it writes out | |
28159 | these lines, it consults the list of header names that were attached to the | |
9b371988 PH |
28160 | recipient address(es) by &%headers_remove%& options in routers, and it also |
28161 | consults the transport's own &%headers_remove%& option. Header lines whose | |
28162 | names are on either of these lists are not written out. If there are multiple | |
168e428f PH |
28163 | instances of any listed header, they are all skipped. |
28164 | ||
28165 | After the remaining original header lines have been written, new header | |
9b371988 | 28166 | lines that were specified by routers' &%headers_add%& options are written, in |
168e428f | 28167 | the order in which they were attached to the address. These are followed by any |
9b371988 | 28168 | header lines specified by the transport's &%headers_add%& option. |
168e428f PH |
28169 | |
28170 | This way of handling header line modifications in routers and transports has | |
28171 | the following consequences: | |
28172 | ||
9b371988 PH |
28173 | .ilist |
28174 | The original set of header lines, possibly modified by the system filter, | |
28175 | remains &"visible"&, in the sense that the &$header_$&&'xxx'& variables refer | |
28176 | to it, at all times. | |
28177 | .next | |
28178 | Header lines that are added by a router's | |
28179 | &%headers_add%& option are not accessible by means of the &$header_$&&'xxx'& | |
168e428f | 28180 | expansion syntax in subsequent routers or the transport. |
9b371988 PH |
28181 | .next |
28182 | Conversely, header lines that are specified for removal by &%headers_remove%& | |
28183 | in a router remain visible to subsequent routers and the transport. | |
28184 | .next | |
28185 | Headers added to an address by &%headers_add%& in a router cannot be removed by | |
168e428f | 28186 | a later router or by a transport. |
9b371988 PH |
28187 | .next |
28188 | An added header can refer to the contents of an original header that is to be | |
168e428f | 28189 | removed, even it has the same name as the added header. For example: |
9b371988 PH |
28190 | .code |
28191 | headers_remove = subject | |
28192 | headers_add = Subject: new subject (was: $h_subject:) | |
28193 | .endd | |
28194 | .endlist | |
168e428f | 28195 | |
9b371988 PH |
28196 | &*Warning*&: The &%headers_add%& and &%headers_remove%& options cannot be used |
28197 | for a &(redirect)& router that has the &%one_time%& option set. | |
168e428f | 28198 | |
168e428f PH |
28199 | |
28200 | ||
28201 | ||
28202 | ||
9b371988 PH |
28203 | .section "Constructed addresses" "SECTconstr" |
28204 | .cindex "address" "constructed" | |
28205 | .cindex "constructed address" | |
168e428f PH |
28206 | When Exim constructs a sender address for a locally-generated message, it uses |
28207 | the form | |
9b371988 PH |
28208 | .display |
28209 | <&'user name'&>&~&~<&'login'&&`@`&&'qualify_domain'&> | |
28210 | .endd | |
168e428f | 28211 | For example: |
9b371988 PH |
28212 | .code |
28213 | Zaphod Beeblebrox <zaphod@end.univ.example> | |
28214 | .endd | |
28215 | The user name is obtained from the &%-F%& command line option if set, or | |
28216 | otherwise by looking up the calling user by &[getpwuid()]& and extracting the | |
28217 | &"gecos"& field from the password entry. If the &"gecos"& field contains an | |
168e428f PH |
28218 | ampersand character, this is replaced by the login name with the first letter |
28219 | upper cased, as is conventional in a number of operating systems. See the | |
9b371988 PH |
28220 | &%gecos_name%& option for a way to tailor the handling of the &"gecos"& field. |
28221 | The &%unknown_username%& option can be used to specify user names in cases when | |
168e428f PH |
28222 | there is no password file entry. |
28223 | ||
9b371988 | 28224 | .cindex "RFC 2047" |
168e428f PH |
28225 | In all cases, the user name is made to conform to RFC 2822 by quoting all or |
28226 | parts of it if necessary. In addition, if it contains any non-printing | |
28227 | characters, it is encoded as described in RFC 2047, which defines a way of | |
d1e83bff | 28228 | including non-ASCII characters in header lines. The value of the |
9b371988 | 28229 | &%headers_charset%& option specifies the name of the encoding that is used (the |
d1e83bff | 28230 | characters are assumed to be in this encoding). The setting of |
9b371988 PH |
28231 | &%print_topbitchars%& controls whether characters with the top bit set (that |
28232 | is, with codes greater than 127) count as printing characters or not. | |
168e428f PH |
28233 | |
28234 | ||
28235 | ||
9b371988 PH |
28236 | .section "Case of local parts" |
28237 | .cindex "case of local parts" | |
28238 | .cindex "local part" "case of" | |
168e428f PH |
28239 | RFC 2822 states that the case of letters in the local parts of addresses cannot |
28240 | be assumed to be non-significant. Exim preserves the case of local parts of | |
28241 | addresses, but by default it uses a lower-cased form when it is routing, | |
28242 | because on most Unix systems, usernames are in lower case and case-insensitive | |
28243 | routing is required. However, any particular router can be made to use the | |
9b371988 | 28244 | original case for local parts by setting the &%caseful_local_part%& generic |
168e428f PH |
28245 | router option. |
28246 | ||
9b371988 | 28247 | .cindex "mixed-case login names" |
168e428f PH |
28248 | If you must have mixed-case user names on your system, the best way to proceed, |
28249 | assuming you want case-independent handling of incoming email, is to set up | |
28250 | your first router to convert incoming local parts in your domains to the | |
28251 | correct case by means of a file lookup. For example: | |
9b371988 | 28252 | .code |
168e428f PH |
28253 | correct_case: |
28254 | driver = redirect | |
28255 | domains = +local_domains | |
28256 | data = ${lookup{$local_part}cdb\ | |
28257 | {/etc/usercased.cdb}{$value}fail}\ | |
28258 | @$domain | |
9b371988 | 28259 | .endd |
168e428f | 28260 | For this router, the local part is forced to lower case by the default action |
9b371988 PH |
28261 | (&%caseful_local_part%& is not set). The lower-cased local part is used to look |
28262 | up a new local part in the correct case. If you then set &%caseful_local_part%& | |
168e428f PH |
28263 | on any subsequent routers which process your domains, they will operate on |
28264 | local parts with the correct case in a case-sensitive manner. | |
28265 | ||
28266 | ||
28267 | ||
9b371988 PH |
28268 | .section "Dots in local parts" |
28269 | .cindex "dot" "in local part" | |
28270 | .cindex "local part" "dots in" | |
168e428f PH |
28271 | RFC 2822 forbids empty components in local parts. That is, an unquoted local |
28272 | part may not begin or end with a dot, nor have two consecutive dots in the | |
28273 | middle. However, it seems that many MTAs do not enforce this, so Exim permits | |
28274 | empty components for compatibility. | |
28275 | ||
28276 | ||
28277 | ||
9b371988 PH |
28278 | .section "Rewriting addresses" |
28279 | .cindex "rewriting" "addresses" | |
168e428f PH |
28280 | Rewriting of sender and recipient addresses, and addresses in headers, can |
28281 | happen automatically, or as the result of configuration options, as described | |
9b371988 PH |
28282 | in chapter &<<CHAPrewrite>>&. The headers that may be affected by this are |
28283 | &'Bcc:'&, &'Cc:'&, &'From:'&, &'Reply-To:'&, &'Sender:'&, and &'To:'&. | |
168e428f PH |
28284 | |
28285 | Automatic rewriting includes qualification, as mentioned above. The other case | |
28286 | in which it can happen is when an incomplete non-local domain is given. The | |
28287 | routing process may cause this to be expanded into the full domain name. For | |
28288 | example, a header such as | |
9b371988 PH |
28289 | .code |
28290 | To: hare@teaparty | |
28291 | .endd | |
168e428f | 28292 | might get rewritten as |
9b371988 PH |
28293 | .code |
28294 | To: hare@teaparty.wonderland.fict.example | |
28295 | .endd | |
168e428f PH |
28296 | Rewriting as a result of routing is the one kind of message processing that |
28297 | does not happen at input time, as it cannot be done until the address has | |
28298 | been routed. | |
28299 | ||
9b371988 | 28300 | Strictly, one should not do &'any'& deliveries of a message until all its |
168e428f PH |
28301 | addresses have been routed, in case any of the headers get changed as a |
28302 | result of routing. However, doing this in practice would hold up many | |
28303 | deliveries for unreasonable amounts of time, just because one address could not | |
28304 | immediately be routed. Exim therefore does not delay other deliveries when | |
28305 | routing of one or more addresses is deferred. | |
28306 | ||
28307 | ||
9b371988 PH |
28308 | . //////////////////////////////////////////////////////////////////////////// |
28309 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 28310 | |
9b371988 PH |
28311 | .chapter "SMTP processing" "CHAPSMTP" |
28312 | .cindex "SMTP" "processing details" | |
28313 | .cindex "LMTP" "processing details" | |
168e428f PH |
28314 | Exim supports a number of different ways of using the SMTP protocol, and its |
28315 | LMTP variant, which is an interactive protocol for transferring messages into a | |
28316 | closed mail store application. This chapter contains details of how SMTP is | |
28317 | processed. For incoming mail, the following are available: | |
28318 | ||
9b371988 PH |
28319 | .ilist |
28320 | SMTP over TCP/IP (Exim daemon or &'inetd'&); | |
28321 | .next | |
28322 | SMTP over the standard input and output (the &%-bs%& option); | |
28323 | .next | |
28324 | Batched SMTP on the standard input (the &%-bS%& option). | |
28325 | .endlist | |
168e428f PH |
28326 | |
28327 | For mail delivery, the following are available: | |
28328 | ||
9b371988 PH |
28329 | .ilist |
28330 | SMTP over TCP/IP (the &(smtp)& transport); | |
28331 | .next | |
28332 | LMTP over TCP/IP (the &(smtp)& transport with the &%protocol%& option set to | |
28333 | &"lmtp"&); | |
28334 | .next | |
28335 | LMTP over a pipe to a process running in the local host (the &(lmtp)& | |
168e428f | 28336 | transport); |
9b371988 PH |
28337 | .next |
28338 | Batched SMTP to a file or pipe (the &(appendfile)& and &(pipe)& transports with | |
28339 | the &%use_bsmtp%& option set). | |
28340 | .endlist | |
168e428f | 28341 | |
9b371988 | 28342 | &'Batched SMTP'& is the name for a process in which batches of messages are |
168e428f PH |
28343 | stored in or read from files (or pipes), in a format in which SMTP commands are |
28344 | used to contain the envelope information. | |
28345 | ||
28346 | ||
28347 | ||
9b371988 PH |
28348 | .section "Outgoing SMTP and LMTP over TCP/IP" "SECToutSMTPTCP" |
28349 | .cindex "SMTP" "outgoing over TCP/IP" | |
28350 | .cindex "outgoing SMTP over TCP/IP" | |
28351 | .cindex "LMTP" "over TCP/IP" | |
28352 | .cindex "outgoing LMTP over TCP/IP" | |
28353 | .cindex "EHLO" | |
28354 | .cindex "HELO" | |
28355 | .cindex "SIZE option on MAIL command" | |
28356 | Outgoing SMTP and LMTP over TCP/IP is implemented by the &(smtp)& transport. | |
28357 | The &%protocol%& option selects which protocol is to be used, but the actual | |
168e428f PH |
28358 | processing is the same in both cases. |
28359 | ||
28360 | If, in response to its EHLO command, Exim is told that the SIZE | |
9b371988 PH |
28361 | parameter is supported, it adds SIZE=<&'n'&> to each subsequent MAIL |
28362 | command. The value of <&'n'&> is the message size plus the value of the | |
28363 | &%size_addition%& option (default 1024) to allow for additions to the message | |
168e428f | 28364 | such as per-transport header lines, or changes made in a |
9b371988 PH |
28365 | .cindex "transport" "filter" |
28366 | .cindex "filter" "transport filter" | |
28367 | transport filter. If &%size_addition%& is set negative, the use of SIZE is | |
168e428f PH |
28368 | suppressed. |
28369 | ||
28370 | If the remote server advertises support for PIPELINING, Exim uses the | |
28371 | pipelining extension to SMTP (RFC 2197) to reduce the number of TCP/IP packets | |
28372 | required for the transaction. | |
28373 | ||
28374 | If the remote server advertises support for the STARTTLS command, and Exim | |
28375 | was built to support TLS encryption, it tries to start a TLS session unless the | |
9b371988 | 28376 | server matches &%hosts_avoid_tls%&. See chapter &<<CHAPTLS>>& for more details. |
168e428f PH |
28377 | |
28378 | If the remote server advertises support for the AUTH command, Exim scans | |
28379 | the authenticators configuration for any suitable client settings, as described | |
9b371988 | 28380 | in chapter &<<CHAPSMTPAUTH>>&. |
168e428f | 28381 | |
9b371988 PH |
28382 | .cindex "carriage return" |
28383 | .cindex "linefeed" | |
168e428f PH |
28384 | Responses from the remote host are supposed to be terminated by CR followed by |
28385 | LF. However, there are known to be hosts that do not send CR characters, so in | |
28386 | order to be able to interwork with such hosts, Exim treats LF on its own as a | |
28387 | line terminator. | |
28388 | ||
28389 | If a message contains a number of different addresses, all those with the same | |
28390 | characteristics (for example, the same envelope sender) that resolve to the | |
28391 | same set of hosts, in the same order, are sent in a single SMTP transaction, | |
28392 | even if they are for different domains, unless there are more than the setting | |
9b371988 PH |
28393 | of the &%max_rcpts%& option in the &(smtp)& transport allows, in which case |
28394 | they are split into groups containing no more than &%max_rcpts%& addresses | |
28395 | each. If &%remote_max_parallel%& is greater than one, such groups may be sent | |
28396 | in parallel sessions. The order of hosts with identical MX values is not | |
168e428f PH |
28397 | significant when checking whether addresses can be batched in this way. |
28398 | ||
9b371988 | 28399 | When the &(smtp)& transport suffers a temporary failure that is not |
168e428f PH |
28400 | message-related, Exim updates its transport-specific database, which contains |
28401 | records indexed by host name that remember which messages are waiting for each | |
28402 | particular host. It also updates the retry database with new retry times. | |
28403 | ||
9b371988 | 28404 | .cindex "hints database" "retry keys" |
168e428f PH |
28405 | Exim's retry hints are based on host name plus IP address, so if one address of |
28406 | a multi-homed host is broken, it will soon be skipped most of the time. | |
28407 | See the next section for more detail about error handling. | |
28408 | ||
9b371988 PH |
28409 | .cindex "SMTP" "passed connection" |
28410 | .cindex "SMTP" "batching over TCP/IP" | |
168e428f PH |
28411 | When a message is successfully delivered over a TCP/IP SMTP connection, Exim |
28412 | looks in the hints database for the transport to see if there are any queued | |
28413 | messages waiting for the host to which it is connected. If it finds one, it | |
9b371988 PH |
28414 | creates a new Exim process using the &%-MC%& option (which can only be used by |
28415 | a process running as root or the Exim user) and passes the TCP/IP socket to it | |
28416 | so that it can deliver another message using the same socket. The new process | |
28417 | does only those deliveries that are routed to the connected host, and may in | |
28418 | turn pass the socket on to a third process, and so on. | |
168e428f | 28419 | |
9b371988 | 28420 | The &%connection_max_messages%& option of the &(smtp)& transport can be used to |
168e428f PH |
28421 | limit the number of messages sent down a single TCP/IP connection. |
28422 | ||
9b371988 | 28423 | .cindex "asterisk" "after IP address" |
168e428f PH |
28424 | The second and subsequent messages delivered down an existing connection are |
28425 | identified in the main log by the addition of an asterisk after the closing | |
28426 | square bracket of the IP address. | |
28427 | ||
28428 | ||
28429 | ||
28430 | ||
9b371988 PH |
28431 | .section "Errors in outgoing SMTP" "SECToutSMTPerr" |
28432 | .cindex "error" "in outgoing SMTP" | |
28433 | .cindex "SMTP" "errors in outgoing" | |
28434 | .cindex "host" "error" | |
168e428f PH |
28435 | Three different kinds of error are recognized for outgoing SMTP: host errors, |
28436 | message errors, and recipient errors. | |
28437 | ||
9b371988 PH |
28438 | .vlist |
28439 | .vitem "&*Host errors*&" | |
28440 | A host error is not associated with a particular message or with a | |
168e428f | 28441 | particular recipient of a message. The host errors are: |
168e428f | 28442 | |
9b371988 PH |
28443 | .ilist |
28444 | Connection refused or timed out, | |
28445 | .next | |
28446 | Any error response code on connection, | |
28447 | .next | |
28448 | Any error response code to EHLO or HELO, | |
28449 | .next | |
28450 | Loss of connection at any time, except after &"."&, | |
28451 | .next | |
28452 | I/O errors at any time, | |
28453 | .next | |
28454 | Timeouts during the session, other than in response to MAIL, RCPT or | |
28455 | the &"."& at the end of the data. | |
28456 | .endlist ilist | |
168e428f | 28457 | |
168e428f PH |
28458 | For a host error, a permanent error response on connection, or in response to |
28459 | EHLO, causes all addresses routed to the host to be failed. Any other host | |
28460 | error causes all addresses to be deferred, and retry data to be created for the | |
28461 | host. It is not tried again, for any message, until its retry time arrives. If | |
28462 | the current set of addresses are not all delivered in this run (to some | |
28463 | alternative host), the message is added to the list of those waiting for this | |
28464 | host, so if it is still undelivered when a subsequent successful delivery is | |
28465 | made to the host, it will be sent down the same SMTP connection. | |
28466 | ||
9b371988 PH |
28467 | .vitem "&*Message errors*&" |
28468 | .cindex "message" "error" | |
168e428f PH |
28469 | A message error is associated with a particular message when sent to a |
28470 | particular host, but not with a particular recipient of the message. The | |
28471 | message errors are: | |
168e428f | 28472 | |
9b371988 PH |
28473 | .ilist |
28474 | Any error response code to MAIL, DATA, or the &"."& that terminates | |
28475 | the data, | |
28476 | .next | |
28477 | Timeout after MAIL, | |
28478 | .next | |
28479 | Timeout or loss of connection after the &"."& that terminates the data. A | |
168e428f PH |
28480 | timeout after the DATA command itself is treated as a host error, as is loss of |
28481 | connection at any other time. | |
9b371988 PH |
28482 | .endlist ilist |
28483 | ||
28484 | For a message error, a permanent error response (5&'xx'&) causes all addresses | |
168e428f | 28485 | to be failed, and a delivery error report to be returned to the sender. A |
9b371988 | 28486 | temporary error response (4&'xx'&), or one of the timeouts, causes all |
168e428f PH |
28487 | addresses to be deferred. Retry data is not created for the host, but instead, |
28488 | a retry record for the combination of host plus message id is created. The | |
28489 | message is not added to the list of those waiting for this host. This ensures | |
28490 | that the failing message will not be sent to this host again until the retry | |
28491 | time arrives. However, other messages that are routed to the host are not | |
28492 | affected, so if it is some property of the message that is causing the error, | |
28493 | it will not stop the delivery of other mail. | |
9b371988 | 28494 | |
168e428f | 28495 | If the remote host specified support for the SIZE parameter in its response |
9b371988 | 28496 | to EHLO, Exim adds SIZE=&'nnn'& to the MAIL command, so an |
168e428f PH |
28497 | over-large message will cause a message error because the error arrives as a |
28498 | response to MAIL. | |
28499 | ||
9b371988 PH |
28500 | .vitem "&*Recipient errors*&" |
28501 | .cindex "recipient" "error" | |
168e428f PH |
28502 | A recipient error is associated with a particular recipient of a message. The |
28503 | recipient errors are: | |
9b371988 PH |
28504 | |
28505 | .ilist | |
28506 | Any error response to RCPT, | |
28507 | .next | |
28508 | Timeout after RCPT. | |
28509 | .endlist | |
28510 | ||
28511 | For a recipient error, a permanent error response (5&'xx'&) causes the | |
168e428f | 28512 | recipient address to be failed, and a bounce message to be returned to the |
9b371988 | 28513 | sender. A temporary error response (4&'xx'&) or a timeout causes the failing |
168e428f PH |
28514 | address to be deferred, and routing retry data to be created for it. This is |
28515 | used to delay processing of the address in subsequent queue runs, until its | |
28516 | routing retry time arrives. This applies to all messages, but because it | |
28517 | operates only in queue runs, one attempt will be made to deliver a new message | |
28518 | to the failing address before the delay starts to operate. This ensures that, | |
28519 | if the failure is really related to the message rather than the recipient | |
9b371988 | 28520 | (&"message too big for this recipient"& is a possible example), other messages |
168e428f PH |
28521 | have a chance of getting delivered. If a delivery to the address does succeed, |
28522 | the retry information gets cleared, so all stuck messages get tried again, and | |
28523 | the retry clock is reset. | |
9b371988 | 28524 | |
168e428f PH |
28525 | The message is not added to the list of those waiting for this host. Use of the |
28526 | host for other messages is unaffected, and except in the case of a timeout, | |
28527 | other recipients are processed independently, and may be successfully delivered | |
28528 | in the current SMTP session. After a timeout it is of course impossible to | |
28529 | proceed with the session, so all addresses get deferred. However, those other | |
28530 | than the one that failed do not suffer any subsequent retry delays. Therefore, | |
28531 | if one recipient is causing trouble, the others have a chance of getting | |
28532 | through when a subsequent delivery attempt occurs before the failing | |
28533 | recipient's retry time. | |
9b371988 | 28534 | .endlist |
168e428f PH |
28535 | |
28536 | In all cases, if there are other hosts (or IP addresses) available for the | |
28537 | current set of addresses (for example, from multiple MX records), they are | |
28538 | tried in this run for any undelivered addresses, subject of course to their | |
28539 | own retry data. In other words, recipient error retry data does not take effect | |
28540 | until the next delivery attempt. | |
28541 | ||
28542 | Some hosts have been observed to give temporary error responses to every | |
9b371988 | 28543 | MAIL command at certain times (&"insufficient space"& has been seen). It |
168e428f PH |
28544 | would be nice if such circumstances could be recognized, and defer data for the |
28545 | host itself created, but this is not possible within the current Exim design. | |
28546 | What actually happens is that retry data for every (host, message) combination | |
28547 | is created. | |
28548 | ||
28549 | The reason that timeouts after MAIL and RCPT are treated specially is that | |
28550 | these can sometimes arise as a result of the remote host's verification | |
28551 | procedures. Exim makes this assumption, and treats them as if a temporary error | |
9b371988 | 28552 | response had been received. A timeout after &"."& is treated specially because |
168e428f PH |
28553 | it is known that some broken implementations fail to recognize the end of the |
28554 | message if the last character of the last line is a binary zero. Thus, it is | |
28555 | helpful to treat this case as a message error. | |
28556 | ||
28557 | Timeouts at other times are treated as host errors, assuming a problem with the | |
28558 | host, or the connection to it. If a timeout after MAIL, RCPT, | |
9b371988 | 28559 | or &"."& is really a connection problem, the assumption is that at the next try |
168e428f PH |
28560 | the timeout is likely to occur at some other point in the dialogue, causing it |
28561 | then to be treated as a host error. | |
28562 | ||
28563 | There is experimental evidence that some MTAs drop the connection after the | |
9b371988 PH |
28564 | terminating &"."& if they do not like the contents of the message for some |
28565 | reason, in contravention of the RFC, which indicates that a 5&'xx'& response | |
168e428f PH |
28566 | should be given. That is why Exim treats this case as a message rather than a |
28567 | host error, in order not to delay other messages to the same host. | |
28568 | ||
28569 | ||
28570 | ||
28571 | ||
28572 | ||
9b371988 PH |
28573 | .section "Variable Envelope Return Paths (VERP)" |
28574 | .cindex "VERP" | |
28575 | .cindex "Variable Envelope Return Paths" | |
28576 | .cindex "envelope sender" | |
28577 | Variable Envelope Return Paths &-- see | |
28578 | &*ftp://koobera.math.uic.edu/www/proto/verp.txt*& &-- can be supported in Exim | |
28579 | by using the &%return_path%& generic transport option to rewrite the return | |
28580 | path at transport time. For example, the following could be used on an &(smtp)& | |
168e428f | 28581 | transport: |
9b371988 | 28582 | .code |
168e428f PH |
28583 | return_path = \ |
28584 | ${if match {$return_path}{^(.+?)-request@your.dom.example\$}\ | |
28585 | {$1-request=$local_part%$domain@your.dom.example}fail} | |
9b371988 | 28586 | .endd |
168e428f PH |
28587 | This has the effect of rewriting the return path (envelope sender) on all |
28588 | outgoing SMTP messages, if the local part of the original return path ends in | |
9b371988 | 28589 | &"-request"&, and the domain is &'your.dom.example'&. The rewriting inserts the |
168e428f PH |
28590 | local part and domain of the recipient into the return path. Suppose, for |
28591 | example, that a message whose return path has been set to | |
9b371988 PH |
28592 | &'somelist-request@your.dom.example'& is sent to |
28593 | &'subscriber@other.dom.example'&. In the transport, the return path is | |
168e428f | 28594 | rewritten as |
9b371988 PH |
28595 | .code |
28596 | somelist-request=subscriber%other.dom.example@your.dom.example | |
28597 | .endd | |
28598 | For this to work, you must arrange for outgoing messages that have &"-request"& | |
168e428f PH |
28599 | in their return paths to have just a single recipient. This can be done by |
28600 | setting | |
9b371988 PH |
28601 | .code |
28602 | max_rcpt = 1 | |
28603 | .endd | |
28604 | .cindex "&$local_part$&" | |
28605 | in the &(smtp)& transport. Otherwise a single copy of a message might be | |
168e428f | 28606 | addressed to several different recipients in the same domain, in which case |
9b371988 | 28607 | &$local_part$& is not available (because it is not unique). Of course, if you |
168e428f PH |
28608 | do start sending out messages with this kind of return path, you must also |
28609 | configure Exim to accept the bounce messages that come back to those paths. | |
9b371988 | 28610 | Typically this would be done by setting an &%local_part_suffix%& option for a |
168e428f PH |
28611 | suitable router. |
28612 | ||
28613 | The overhead incurred in using VERP depends very much on the size of the | |
28614 | message, the number of recipient addresses that resolve to the same remote | |
28615 | host, and the speed of the connection over which the message is being sent. If | |
28616 | a lot of addresses resolve to the same host and the connection is slow, sending | |
28617 | a separate copy of the message for each address may take substantially longer | |
28618 | than sending a single copy with many recipients (for which VERP cannot be | |
28619 | used). | |
28620 | ||
28621 | ||
28622 | ||
9b371988 PH |
28623 | .section "Incoming SMTP messages over TCP/IP" |
28624 | .cindex "SMTP" "incoming over TCP/IP" | |
28625 | .cindex "incoming SMTP over TCP/IP" | |
28626 | .cindex "inetd" | |
28627 | .cindex "daemon" | |
168e428f | 28628 | Incoming SMTP messages can be accepted in one of two ways: by running a |
9b371988 PH |
28629 | listening daemon, or by using &'inetd'&. In the latter case, the entry in |
28630 | &_/etc/inetd.conf_& should be like this: | |
28631 | .code | |
28632 | smtp stream tcp nowait exim /opt/exim/bin/exim in.exim -bs | |
28633 | .endd | |
168e428f | 28634 | Exim distinguishes between this case and the case of a locally running user |
9b371988 | 28635 | agent using the &%-bs%& option by checking whether or not the standard input is |
168e428f PH |
28636 | a socket. When it is, either the port must be privileged (less than 1024), or |
28637 | the caller must be root or the Exim user. If any other user passes a socket | |
28638 | with an unprivileged port number, Exim prints a message on the standard error | |
28639 | stream and exits with an error code. | |
28640 | ||
28641 | By default, Exim does not make a log entry when a remote host connects or | |
9b371988 | 28642 | disconnects (either via the daemon or &'inetd'&), unless the disconnection is |
168e428f | 28643 | unexpected. It can be made to write such log entries by setting the |
9b371988 | 28644 | &%smtp_connection%& log selector. |
168e428f | 28645 | |
9b371988 PH |
28646 | .cindex "carriage return" |
28647 | .cindex "linefeed" | |
168e428f PH |
28648 | Commands from the remote host are supposed to be terminated by CR followed by |
28649 | LF. However, there are known to be hosts that do not send CR characters. In | |
28650 | order to be able to interwork with such hosts, Exim treats LF on its own as a | |
28651 | line terminator. | |
28652 | Furthermore, because common code is used for receiving messages from all | |
28653 | sources, a CR on its own is also interpreted as a line terminator. However, the | |
9b371988 | 28654 | sequence &"CR, dot, CR"& does not terminate incoming SMTP data. |
168e428f | 28655 | |
9b371988 PH |
28656 | .cindex "EHLO" "invalid data" |
28657 | .cindex "HELO" "invalid data" | |
168e428f PH |
28658 | One area that sometimes gives rise to problems concerns the EHLO or |
28659 | HELO commands. Some clients send syntactically invalid versions of these | |
28660 | commands, which Exim rejects by default. (This is nothing to do with verifying | |
9b371988 PH |
28661 | the data that is sent, so &%helo_verify_hosts%& is not relevant.) You can tell |
28662 | Exim not to apply a syntax check by setting &%helo_accept_junk_hosts%& to | |
168e428f PH |
28663 | match the broken hosts that send invalid commands. |
28664 | ||
9b371988 PH |
28665 | .cindex "SIZE option on MAIL command" |
28666 | .cindex "MAIL" "SIZE option" | |
168e428f | 28667 | The amount of disk space available is checked whenever SIZE is received on |
9b371988 PH |
28668 | a MAIL command, independently of whether &%message_size_limit%& or |
28669 | &%check_spool_space%& is configured, unless &%smtp_check_spool_space%& is set | |
168e428f | 28670 | false. A temporary error is given if there is not enough space. If |
9b371988 | 28671 | &%check_spool_space%& is set, the check is for that amount of space plus the |
168e428f PH |
28672 | value given with SIZE, that is, it checks that the addition of the incoming |
28673 | message will not reduce the space below the threshold. | |
28674 | ||
28675 | When a message is successfully received, Exim includes the local message id in | |
9b371988 PH |
28676 | its response to the final &"."& that terminates the data. If the remote host |
28677 | logs this text it can help with tracing what has happened to a message. | |
168e428f PH |
28678 | |
28679 | The Exim daemon can limit the number of simultaneous incoming connections it is | |
9b371988 | 28680 | prepared to handle (see the &%smtp_accept_max%& option). It can also limit the |
168e428f | 28681 | number of simultaneous incoming connections from a single remote host (see the |
9b371988 | 28682 | &%smtp_accept_max_per_host%& option). Additional connection attempts are |
168e428f PH |
28683 | rejected using the SMTP temporary error code 421. |
28684 | ||
28685 | The Exim daemon does not rely on the SIGCHLD signal to detect when a | |
28686 | subprocess has finished, as this can get lost at busy times. Instead, it looks | |
28687 | for completed subprocesses every time it wakes up. Provided there are other | |
28688 | things happening (new incoming calls, starts of queue runs), completed | |
28689 | processes will be noticed and tidied away. On very quiet systems you may | |
9b371988 PH |
28690 | sometimes see a &"defunct"& Exim process hanging about. This is not a problem; |
28691 | it will be noticed when the daemon next wakes up. | |
168e428f PH |
28692 | |
28693 | When running as a daemon, Exim can reserve some SMTP slots for specific hosts, | |
28694 | and can also be set up to reject SMTP calls from non-reserved hosts at times of | |
9b371988 PH |
28695 | high system load &-- for details see the &%smtp_accept_reserve%&, |
28696 | &%smtp_load_reserve%&, and &%smtp_reserve_hosts%& options. The load check | |
28697 | applies in both the daemon and &'inetd'& cases. | |
168e428f PH |
28698 | |
28699 | Exim normally starts a delivery process for each message received, though this | |
9b371988 PH |
28700 | can be varied by means of the &%-odq%& command line option and the |
28701 | &%queue_only%&, &%queue_only_file%&, and &%queue_only_load%& options. The | |
28702 | number of simultaneously running delivery processes started in this way from | |
28703 | SMTP input can be limited by the &%smtp_accept_queue%& and | |
28704 | &%smtp_accept_queue_per_connection%& options. When either limit is reached, | |
168e428f PH |
28705 | subsequently received messages are just put on the input queue without starting |
28706 | a delivery process. | |
28707 | ||
9b371988 PH |
28708 | The controls that involve counts of incoming SMTP calls (&%smtp_accept_max%&, |
28709 | &%smtp_accept_queue%&, &%smtp_accept_reserve%&) are not available when Exim is | |
28710 | started up from the &'inetd'& daemon, because in that case each connection is | |
168e428f | 28711 | handled by an entirely independent Exim process. Control by load average is, |
9b371988 | 28712 | however, available with &'inetd'&. |
168e428f PH |
28713 | |
28714 | Exim can be configured to verify addresses in incoming SMTP commands as they | |
9b371988 PH |
28715 | are received. See chapter &<<CHAPACL>>& for details. It can also be configured |
28716 | to rewrite addresses at this time &-- before any syntax checking is done. See | |
28717 | section &<<SECTrewriteS>>&. | |
168e428f PH |
28718 | |
28719 | Exim can also be configured to limit the rate at which a client host submits | |
28720 | MAIL and RCPT commands in a single SMTP session. See the | |
9b371988 | 28721 | &%smtp_ratelimit_hosts%& option. |
168e428f PH |
28722 | |
28723 | ||
28724 | ||
9b371988 PH |
28725 | .section "Unrecognized SMTP commands" |
28726 | .cindex "SMTP" "unrecognized commands" | |
28727 | If Exim receives more than &%smtp_max_unknown_commands%& unrecognized SMTP | |
168e428f PH |
28728 | commands during a single SMTP connection, it drops the connection after sending |
28729 | the error response to the last command. The default value for | |
9b371988 | 28730 | &%smtp_max_unknown_commands%& is 3. This is a defence against some kinds of |
168e428f PH |
28731 | abuse that subvert web servers into making connections to SMTP ports; in these |
28732 | circumstances, a number of non-SMTP lines are sent first. | |
28733 | ||
28734 | ||
9b371988 PH |
28735 | .section "Syntax and protocol errors in SMTP commands" |
28736 | .cindex "SMTP" "syntax errors" | |
28737 | .cindex "SMTP" "protocol errors" | |
168e428f PH |
28738 | A syntax error is detected if an SMTP command is recognized, but there is |
28739 | something syntactically wrong with its data, for example, a malformed email | |
28740 | address in a RCPT command. Protocol errors include invalid command | |
28741 | sequencing such as RCPT before MAIL. If Exim receives more than | |
9b371988 | 28742 | &%smtp_max_synprot_errors%& such commands during a single SMTP connection, it |
168e428f | 28743 | drops the connection after sending the error response to the last command. The |
9b371988 | 28744 | default value for &%smtp_max_synprot_errors%& is 3. This is a defence against |
168e428f PH |
28745 | broken clients that loop sending bad commands (yes, it has been seen). |
28746 | ||
28747 | ||
28748 | ||
9b371988 PH |
28749 | .section "Use of non-mail SMTP commands" |
28750 | .cindex "SMTP" "non-mail commands" | |
28751 | The &"non-mail"& SMTP commands are those other than MAIL, RCPT, and | |
168e428f PH |
28752 | DATA. Exim counts such commands, and drops the connection if there are too |
28753 | many of them in a single SMTP session. This action catches some | |
28754 | denial-of-service attempts and things like repeated failing AUTHs, or a mad | |
9b371988 PH |
28755 | client looping sending EHLO. The global option &%smtp_accept_max_nonmail%& |
28756 | defines what &"too many"& means. Its default value is 10. | |
168e428f PH |
28757 | |
28758 | When a new message is expected, one occurrence of RSET is not counted. This | |
28759 | allows a client to send one RSET between messages (this is not necessary, | |
28760 | but some clients do it). Exim also allows one uncounted occurence of HELO | |
28761 | or EHLO, and one occurrence of STARTTLS between messages. After | |
28762 | starting up a TLS session, another EHLO is expected, and so it too is not | |
28763 | counted. | |
28764 | ||
28765 | The first occurrence of AUTH in a connection, or immediately following | |
28766 | STARTTLS is also not counted. Otherwise, all commands other than MAIL, | |
28767 | RCPT, DATA, and QUIT are counted. | |
28768 | ||
28769 | You can control which hosts are subject to the limit set by | |
9b371988 PH |
28770 | &%smtp_accept_max_nonmail%& by setting |
28771 | &%smtp_accept_max_nonmail_hosts%&. The default value is &`*`&, which makes | |
168e428f PH |
28772 | the limit apply to all hosts. This option means that you can exclude any |
28773 | specific badly-behaved hosts that you have to live with. | |
28774 | ||
28775 | ||
28776 | ||
28777 | ||
9b371988 | 28778 | .section "The VRFY and EXPN commands" |
168e428f | 28779 | When Exim receives a VRFY or EXPN command on a TCP/IP connection, it |
9b371988 | 28780 | runs the ACL specified by &%acl_smtp_vrfy%& or &%acl_smtp_expn%& (as |
168e428f PH |
28781 | appropriate) in order to decide whether the command should be accepted or not. |
28782 | If no ACL is defined, the command is rejected. | |
28783 | ||
9b371988 | 28784 | .cindex "VRFY" "processing" |
168e428f | 28785 | When VRFY is accepted, it runs exactly the same code as when Exim is |
9b371988 | 28786 | called with the &%-bv%& option. |
168e428f | 28787 | |
9b371988 | 28788 | .cindex "EXPN" "processing" |
168e428f | 28789 | When EXPN is accepted, a single-level expansion of the address is done. |
9b371988 PH |
28790 | EXPN is treated as an &"address test"& (similar to the &%-bt%& option) rather |
28791 | than a verification (the &%-bv%& option). If an unqualified local part is given | |
28792 | as the argument to EXPN, it is qualified with &%qualify_domain%&. Rejections | |
168e428f PH |
28793 | of VRFY and EXPN commands are logged on the main and reject logs, and |
28794 | VRFY verification failures are logged on the main log for consistency with | |
28795 | RCPT failures. | |
28796 | ||
28797 | ||
28798 | ||
9b371988 PH |
28799 | .section "The ETRN command" "SECTETRN" |
28800 | .cindex "ETRN" "processing" | |
168e428f PH |
28801 | RFC 1985 describes an SMTP command called ETRN that is designed to |
28802 | overcome the security problems of the TURN command (which has fallen into | |
28803 | disuse). When Exim receives an ETRN command on a TCP/IP connection, it runs | |
9b371988 | 28804 | the ACL specified by &%acl_smtp_etrn%& in order to decide whether the command |
168e428f PH |
28805 | should be accepted or not. If no ACL is defined, the command is rejected. |
28806 | ||
9b371988 | 28807 | The ETRN command is concerned with &"releasing"& messages that are awaiting |
168e428f PH |
28808 | delivery to certain hosts. As Exim does not organize its message queue by host, |
28809 | the only form of ETRN that is supported by default is the one where the | |
9b371988 | 28810 | text starts with the &"#"& prefix, in which case the remainder of the text is |
168e428f | 28811 | specific to the SMTP server. A valid ETRN command causes a run of Exim with |
9b371988 | 28812 | the &%-R%& option to happen, with the remainder of the ETRN text as its |
168e428f | 28813 | argument. For example, |
9b371988 PH |
28814 | .code |
28815 | ETRN #brigadoon | |
28816 | .endd | |
168e428f | 28817 | runs the command |
9b371988 PH |
28818 | .code |
28819 | exim -R brigadoon | |
28820 | .endd | |
168e428f | 28821 | which causes a delivery attempt on all messages with undelivered addresses |
9b371988 | 28822 | containing the text &"brigadoon"&. When &%smtp_etrn_serialize%& is set (the |
168e428f PH |
28823 | default), Exim prevents the simultaneous execution of more than one queue run |
28824 | for the same argument string as a result of an ETRN command. This stops | |
28825 | a misbehaving client from starting more than one queue runner at once. | |
28826 | ||
9b371988 | 28827 | .cindex "hints database" "ETRN serialization" |
168e428f PH |
28828 | Exim implements the serialization by means of a hints database in which a |
28829 | record is written whenever a process is started by ETRN, and deleted when | |
28830 | the process completes. However, Exim does not keep the SMTP session waiting for | |
28831 | the ETRN process to complete. Once ETRN is accepted, the client is sent | |
9b371988 PH |
28832 | a &"success"& return code. Obviously there is scope for hints records to get |
28833 | left lying around if there is a system or program crash. To guard against this, | |
28834 | Exim ignores any records that are more than six hours old. | |
168e428f | 28835 | |
9b371988 PH |
28836 | .cindex "&%smtp_etrn_command%&" |
28837 | For more control over what ETRN does, the &%smtp_etrn_command%& option can | |
168e428f PH |
28838 | used. This specifies a command that is run whenever ETRN is received, |
28839 | whatever the form of its argument. For | |
28840 | example: | |
9b371988 PH |
28841 | .code |
28842 | smtp_etrn_command = /etc/etrn_command $domain \ | |
28843 | $sender_host_address | |
28844 | .endd | |
28845 | .cindex "&$domain$&" | |
168e428f | 28846 | The string is split up into arguments which are independently expanded. The |
9b371988 | 28847 | expansion variable &$domain$& is set to the argument of the ETRN command, |
168e428f PH |
28848 | and no syntax checking is done on the contents of this argument. Exim does not |
28849 | wait for the command to complete, so its status code is not checked. Exim runs | |
28850 | under its own uid and gid when receiving incoming SMTP, so it is not possible | |
28851 | for it to change them before running the command. | |
28852 | ||
28853 | ||
28854 | ||
9b371988 PH |
28855 | .section "Incoming local SMTP" |
28856 | .cindex "SMTP" "local incoming" | |
168e428f PH |
28857 | Some user agents use SMTP to pass messages to their local MTA using the |
28858 | standard input and output, as opposed to passing the envelope on the command | |
28859 | line and writing the message to the standard input. This is supported by the | |
9b371988 | 28860 | &%-bs%& option. This form of SMTP is handled in the same way as incoming |
168e428f PH |
28861 | messages over TCP/IP (including the use of ACLs), except that the envelope |
28862 | sender given in a MAIL command is ignored unless the caller is trusted. In | |
28863 | an ACL you can detect this form of SMTP input by testing for an empty host | |
28864 | identification. It is common to have this as the first line in the ACL that | |
28865 | runs for RCPT commands: | |
9b371988 PH |
28866 | .code |
28867 | accept hosts = : | |
28868 | .endd | |
168e428f PH |
28869 | This accepts SMTP messages from local processes without doing any other tests. |
28870 | ||
28871 | ||
28872 | ||
9b371988 PH |
28873 | .section "Outgoing batched SMTP" "SECTbatchSMTP" |
28874 | .cindex "SMTP" "batched outgoing" | |
28875 | .cindex "batched SMTP output" | |
28876 | Both the &(appendfile)& and &(pipe)& transports can be used for handling | |
28877 | batched SMTP. Each has an option called &%use_bsmtp%& which causes messages to | |
28878 | be output in BSMTP format. No SMTP responses are possible for this form of | |
28879 | delivery. All it is doing is using SMTP commands as a way of transmitting the | |
28880 | envelope along with the message. | |
168e428f PH |
28881 | |
28882 | The message is written to the file or pipe preceded by the SMTP commands | |
28883 | MAIL and RCPT, and followed by a line containing a single dot. Lines in | |
28884 | the message that start with a dot have an extra dot added. The SMTP command | |
9b371988 | 28885 | HELO is not normally used. If it is required, the &%message_prefix%& option |
168e428f PH |
28886 | can be used to specify it. |
28887 | ||
9b371988 | 28888 | Because &(appendfile)& and &(pipe)& are both local transports, they accept only |
168e428f | 28889 | one recipient address at a time by default. However, you can arrange for them |
9b371988 | 28890 | to handle several addresses at once by setting the &%batch_max%& option. When |
168e428f | 28891 | this is done for BSMTP, messages may contain multiple RCPT commands. See |
9b371988 | 28892 | chapter &<<CHAPbatching>>& for more details. |
168e428f | 28893 | |
9b371988 | 28894 | .cindex "&$host$&" |
168e428f PH |
28895 | When one or more addresses are routed to a BSMTP transport by a router that |
28896 | sets up a host list, the name of the first host on the list is available to the | |
9b371988 | 28897 | transport in the variable &$host$&. Here is an example of such a transport and |
168e428f | 28898 | router: |
9b371988 PH |
28899 | .code |
28900 | begin routers | |
28901 | route_append: | |
28902 | driver = manualroute | |
28903 | transport = smtp_appendfile | |
28904 | route_list = domain.example batch.host.example | |
168e428f | 28905 | |
9b371988 PH |
28906 | begin transports |
28907 | smtp_appendfile: | |
28908 | driver = appendfile | |
28909 | directory = /var/bsmtp/$host | |
28910 | batch_max = 1000 | |
28911 | use_bsmtp | |
28912 | user = exim | |
28913 | .endd | |
28914 | This causes messages addressed to &'domain.example'& to be written in BSMTP | |
28915 | format to &_/var/bsmtp/batch.host.example_&, with only a single copy of each | |
168e428f PH |
28916 | message (unless there are more than 1000 recipients). |
28917 | ||
28918 | ||
28919 | ||
9b371988 PH |
28920 | .section "Incoming batched SMTP" "SECTincomingbatchedSMTP" |
28921 | .cindex "SMTP" "batched incoming" | |
28922 | .cindex "batched SMTP input" | |
28923 | The &%-bS%& command line option causes Exim to accept one or more messages by | |
168e428f PH |
28924 | reading SMTP on the standard input, but to generate no responses. If the caller |
28925 | is trusted, the senders in the MAIL commands are believed; otherwise the | |
28926 | sender is always the caller of Exim. Unqualified senders and receivers are not | |
28927 | rejected (there seems little point) but instead just get qualified. HELO | |
28928 | and EHLO act as RSET; VRFY, EXPN, ETRN and HELP, act | |
28929 | as NOOP; QUIT quits. | |
28930 | ||
28931 | No policy checking is done for BSMTP input. That is, no ACL is run at anytime. | |
28932 | In this respect it is like non-SMTP local input. | |
28933 | ||
9b371988 | 28934 | If an error is detected while reading a message, including a missing &"."& at |
168e428f PH |
28935 | the end, Exim gives up immediately. It writes details of the error to the |
28936 | standard output in a stylized way that the calling program should be able to | |
28937 | make some use of automatically, for example: | |
9b371988 PH |
28938 | .code |
28939 | 554 Unexpected end of file | |
28940 | Transaction started in line 10 | |
28941 | Error detected in line 14 | |
28942 | .endd | |
168e428f PH |
28943 | It writes a more verbose version, for human consumption, to the standard error |
28944 | file, for example: | |
9b371988 PH |
28945 | .code |
28946 | An error was detected while processing a file of BSMTP input. | |
28947 | The error message was: | |
168e428f | 28948 | |
9b371988 | 28949 | 501 '>' missing at end of address |
168e428f | 28950 | |
9b371988 PH |
28951 | The SMTP transaction started in line 10. |
28952 | The error was detected in line 12. | |
28953 | The SMTP command at fault was: | |
168e428f | 28954 | |
9b371988 | 28955 | rcpt to:<malformed@in.com.plete |
168e428f | 28956 | |
9b371988 PH |
28957 | 1 previous message was successfully processed. |
28958 | The rest of the batch was abandoned. | |
28959 | .endd | |
168e428f PH |
28960 | The return code from Exim is zero only if there were no errors. It is 1 if some |
28961 | messages were accepted before an error was detected, and 2 if no messages were | |
28962 | accepted. | |
28963 | ||
28964 | ||
28965 | ||
9b371988 PH |
28966 | . //////////////////////////////////////////////////////////////////////////// |
28967 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 28968 | |
9b371988 PH |
28969 | .chapter "Customizing bounce and warning messages" "CHAPemsgcust" &&& |
28970 | "Customizing messages" | |
168e428f PH |
28971 | When a message fails to be delivered, or remains on the queue for more than a |
28972 | configured amount of time, Exim sends a message to the original sender, or | |
28973 | to an alternative configured address. The text of these messages is built into | |
28974 | the code of Exim, but it is possible to change it, either by adding a single | |
28975 | string, or by replacing each of the paragraphs by text supplied in a file. | |
28976 | ||
9b371988 PH |
28977 | The &'From:'& and &'To:'& header lines are automatically generated; you can |
28978 | cause a &'Reply-To:'& line to be added by setting the &%errors_reply_to%& | |
28979 | option. Exim also adds the line | |
28980 | .code | |
28981 | Auto-Submitted: auto-generated | |
28982 | .endd | |
168e428f PH |
28983 | to all warning and bounce messages, |
28984 | ||
28985 | ||
9b371988 PH |
28986 | .section "Customizing bounce messages" |
28987 | .cindex "customizing" "bounce message" | |
28988 | .cindex "bounce message" "customizing" | |
28989 | If &%bounce_message_text%& is set, its contents are included in the default | |
28990 | message immediately after &"This message was created automatically by mail | |
28991 | delivery software."& The string is not expanded. It is not used if | |
28992 | &%bounce_message_file%& is set. | |
168e428f | 28993 | |
9b371988 | 28994 | When &%bounce_message_file%& is set, it must point to a template file for |
168e428f PH |
28995 | constructing error messages. The file consists of a series of text items, |
28996 | separated by lines consisting of exactly four asterisks. If the file cannot be | |
28997 | opened, default text is used and a message is written to the main and panic | |
28998 | logs. If any text item in the file is empty, default text is used for that | |
28999 | item. | |
29000 | ||
9b371988 PH |
29001 | .cindex "&$bounce_recipient$&" |
29002 | .cindex "&$bounce_return_size_limit$&" | |
168e428f | 29003 | Each item of text that is read from the file is expanded, and there are two |
9b371988 PH |
29004 | expansion variables which can be of use here: &$bounce_recipient$& is set to |
29005 | the recipient of an error message while it is being created, and | |
29006 | &$bounce_return_size_limit$& contains the value of the &%return_size_limit%& | |
068aaea8 | 29007 | option, rounded to a whole number. |
168e428f PH |
29008 | |
29009 | The items must appear in the file in the following order: | |
29010 | ||
9b371988 PH |
29011 | .ilist |
29012 | The first item is included in the headers, and should include at least a | |
29013 | &'Subject:'& header. Exim does not check the syntax of these headers. | |
29014 | .next | |
29015 | The second item forms the start of the error message. After it, Exim lists the | |
168e428f | 29016 | failing addresses with their error messages. |
9b371988 PH |
29017 | .next |
29018 | The third item is used to introduce any text from pipe transports that is to be | |
168e428f | 29019 | returned to the sender. It is omitted if there is no such text. |
9b371988 PH |
29020 | .next |
29021 | The fourth item is used to introduce the copy of the message that is returned | |
168e428f | 29022 | as part of the error report. |
9b371988 PH |
29023 | .next |
29024 | The fifth item is added after the fourth one if the returned message is | |
29025 | truncated because it is bigger than &%return_size_limit%&. | |
29026 | .next | |
29027 | The sixth item is added after the copy of the original message. | |
29028 | .endlist | |
29029 | ||
29030 | The default state (&%bounce_message_file%& unset) is equivalent to the | |
29031 | following file, in which the sixth item is empty. The &'Subject:'& and some | |
29032 | other lines have been split in order to fit them on the page: | |
29033 | .code | |
29034 | Subject: Mail delivery failed | |
29035 | ${if eq{$sender_address}{$bounce_recipient} | |
29036 | {: returning message to sender}} | |
29037 | **** | |
29038 | This message was created automatically by mail delivery software. | |
29039 | ||
29040 | A message ${if eq{$sender_address}{$bounce_recipient} | |
29041 | {that you sent }{sent by | |
29042 | ||
29043 | <$sender_address> | |
29044 | ||
29045 | }}could not be delivered to all of its recipients. | |
29046 | The following address(es) failed: | |
29047 | **** | |
29048 | The following text was generated during the delivery attempt(s): | |
29049 | **** | |
29050 | ------ This is a copy of the message, including all the headers. | |
29051 | ------ | |
29052 | **** | |
29053 | ------ The body of the message is $message_size characters long; | |
29054 | only the first | |
29055 | ------ $bounce_return_size_limit or so are included here. | |
29056 | **** | |
29057 | .endd | |
29058 | .section "Customizing warning messages" "SECTcustwarn" | |
29059 | .cindex "customizing" "warning message" | |
29060 | .cindex "warning of delay" "customizing the message" | |
29061 | The option &%warn_message_file%& can be pointed at a template file for use when | |
168e428f PH |
29062 | warnings about message delays are created. In this case there are only three |
29063 | text sections: | |
29064 | ||
9b371988 PH |
29065 | .ilist |
29066 | The first item is included in the headers, and should include at least a | |
29067 | &'Subject:'& header. Exim does not check the syntax of these headers. | |
29068 | .next | |
29069 | The second item forms the start of the warning message. After it, Exim lists | |
168e428f | 29070 | the delayed addresses. |
9b371988 PH |
29071 | .next |
29072 | The third item then ends the message. | |
29073 | .endlist | |
29074 | ||
29075 | The default state is equivalent to the following file, except that some lines | |
29076 | have been split here, in order to fit them on the page: | |
29077 | .code | |
29078 | Subject: Warning: message $message_exim_id delayed | |
29079 | $warn_message_delay | |
29080 | **** | |
29081 | This message was created automatically by mail delivery software. | |
29082 | ||
29083 | A message ${if eq{$sender_address}{$warn_message_recipients} | |
29084 | {that you sent }{sent by | |
29085 | ||
29086 | <$sender_address> | |
29087 | ||
29088 | }}has not been delivered to all of its recipients after | |
29089 | more than $warn_message_delay on the queue on $primary_hostname. | |
29090 | ||
29091 | The message identifier is: $message_exim_id | |
29092 | The subject of the message is: $h_subject | |
29093 | The date of the message is: $h_date | |
29094 | ||
29095 | The following address(es) have not yet been delivered: | |
29096 | **** | |
29097 | No action is required on your part. Delivery attempts will | |
29098 | continue for some time, and this warning may be repeated at | |
29099 | intervals if the message remains undelivered. Eventually the | |
29100 | mail delivery software will give up, and when that happens, | |
29101 | the message will be returned to you. | |
29102 | .endd | |
29103 | .cindex "&$warn_message_delay$&" | |
29104 | .cindex "&$warn_message_recipients$&" | |
29105 | However, in the default state the subject and date lines are omitted if no | |
168e428f | 29106 | appropriate headers exist. During the expansion of this file, |
9b371988 PH |
29107 | &$warn_message_delay$& is set to the delay time in one of the forms &"<&'n'&> |
29108 | minutes"& or &"<&'n'&> hours"&, and &$warn_message_recipients$& contains a list | |
29109 | of recipients for the warning message. There may be more than one if there are | |
29110 | multiple addresses with different &%errors_to%& settings on the routers that | |
168e428f PH |
29111 | handled them. |
29112 | ||
29113 | ||
29114 | ||
29115 | ||
9b371988 PH |
29116 | . //////////////////////////////////////////////////////////////////////////// |
29117 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 29118 | |
9b371988 | 29119 | .chapter "Some common configuration settings" "CHAPcomconreq" |
168e428f PH |
29120 | This chapter discusses some configuration settings that seem to be fairly |
29121 | common. More examples and discussion can be found in the Exim book. | |
29122 | ||
29123 | ||
29124 | ||
9b371988 PH |
29125 | .section "Sending mail to a smart host" |
29126 | .cindex "smart host" "example router" | |
29127 | If you want to send all mail for non-local domains to a &"smart host"&, you | |
29128 | should replace the default &(dnslookup)& router with a router which does the | |
168e428f | 29129 | routing explicitly: |
9b371988 PH |
29130 | .code |
29131 | send_to_smart_host: | |
29132 | driver = manualroute | |
29133 | route_list = !+local_domains smart.host.name | |
29134 | transport = remote_smtp | |
29135 | .endd | |
168e428f | 29136 | You can use the smart host's IP address instead of the name if you wish. |
168e428f PH |
29137 | If you are using Exim only to submit messages to a smart host, and not for |
29138 | receiving incoming messages, you can arrange for it to do the submission | |
9b371988 PH |
29139 | synchronously by setting the &%mua_wrapper%& option (see chapter |
29140 | &<<CHAPnonqueueing>>&). | |
168e428f PH |
29141 | |
29142 | ||
29143 | ||
29144 | ||
9b371988 PH |
29145 | .section "Using Exim to handle mailing lists" "SECTmailinglists" |
29146 | .cindex "mailing lists" | |
168e428f PH |
29147 | Exim can be used to run simple mailing lists, but for large and/or complicated |
29148 | requirements, the use of additional specialized mailing list software such as | |
29149 | Majordomo or Mailman is recommended. | |
29150 | ||
9b371988 | 29151 | The &(redirect)& router can be used to handle mailing lists where each list |
168e428f | 29152 | is maintained in a separate file, which can therefore be managed by an |
9b371988 | 29153 | independent manager. The &%domains%& router option can be used to run these |
168e428f | 29154 | lists in a separate domain from normal mail. For example: |
9b371988 PH |
29155 | .code |
29156 | lists: | |
29157 | driver = redirect | |
29158 | domains = lists.example | |
29159 | file = /usr/lists/$local_part | |
29160 | forbid_pipe | |
29161 | forbid_file | |
29162 | errors_to = $local_part-request@lists.example | |
29163 | no_more | |
29164 | .endd | |
29165 | This router is skipped for domains other than &'lists.example'&. For addresses | |
168e428f | 29166 | in that domain, it looks for a file that matches the local part. If there is no |
9b371988 | 29167 | such file, the router declines, but because &%no_more%& is set, no subsequent |
168e428f PH |
29168 | routers are tried, and so the whole delivery fails. |
29169 | ||
9b371988 | 29170 | The &%forbid_pipe%& and &%forbid_file%& options prevent a local part from being |
168e428f PH |
29171 | expanded into a file name or a pipe delivery, which is usually inappropriate in |
29172 | a mailing list. | |
29173 | ||
9b371988 PH |
29174 | .cindex "&%errors_to%&" |
29175 | The &%errors_to%& option specifies that any delivery errors caused by addresses | |
168e428f PH |
29176 | taken from a mailing list are to be sent to the given address rather than the |
29177 | original sender of the message. However, before acting on this, Exim verifies | |
29178 | the error address, and ignores it if verification fails. | |
29179 | ||
29180 | For example, using the configuration above, mail sent to | |
9b371988 PH |
29181 | &'dicts@lists.example'& is passed on to those addresses contained in |
29182 | &_/usr/lists/dicts_&, with error reports directed to | |
29183 | &'dicts-request@lists.example'&, provided that this address can be verified. | |
29184 | There could be a file called &_/usr/lists/dicts-request_& containing | |
168e428f | 29185 | the address(es) of this particular list's manager(s), but other approaches, |
9b371988 PH |
29186 | such as setting up an earlier router (possibly using the &%local_part_prefix%& |
29187 | or &%local_part_suffix%& options) to handle addresses of the form | |
29188 | &%owner-%&&'xxx'& or &%xxx-%&&'request'&, are also possible. | |
168e428f PH |
29189 | |
29190 | ||
29191 | ||
9b371988 PH |
29192 | .section "Syntax errors in mailing lists" |
29193 | .cindex "mailing lists" "syntax errors in" | |
168e428f PH |
29194 | If an entry in redirection data contains a syntax error, Exim normally defers |
29195 | delivery of the original address. That means that a syntax error in a mailing | |
29196 | list holds up all deliveries to the list. This may not be appropriate when a | |
29197 | list is being maintained automatically from data supplied by users, and the | |
29198 | addresses are not rigorously checked. | |
29199 | ||
9b371988 | 29200 | If the &%skip_syntax_errors%& option is set, the &(redirect)& router just skips |
168e428f | 29201 | entries that fail to parse, noting the incident in the log. If in addition |
9b371988 | 29202 | &%syntax_errors_to%& is set to a verifiable address, a message is sent to it |
168e428f | 29203 | whenever a broken address is skipped. It is usually appropriate to set |
9b371988 | 29204 | &%syntax_errors_to%& to the same address as &%errors_to%&. |
168e428f PH |
29205 | |
29206 | ||
29207 | ||
9b371988 PH |
29208 | .section "Re-expansion of mailing lists" |
29209 | .cindex "mailing lists" "re-expansion of" | |
168e428f PH |
29210 | Exim remembers every individual address to which a message has been delivered, |
29211 | in order to avoid duplication, but it normally stores only the original | |
29212 | recipient addresses with a message. If all the deliveries to a mailing list | |
29213 | cannot be done at the first attempt, the mailing list is re-expanded when the | |
29214 | delivery is next tried. This means that alterations to the list are taken into | |
29215 | account at each delivery attempt, so addresses that have been added to | |
29216 | the list since the message arrived will therefore receive a copy of the | |
29217 | message, even though it pre-dates their subscription. | |
29218 | ||
9b371988 PH |
29219 | If this behaviour is felt to be undesirable, the &%one_time%& option can be set |
29220 | on the &(redirect)& router. If this is done, any addresses generated by the | |
168e428f | 29221 | router that fail to deliver at the first attempt are added to the message as |
9b371988 PH |
29222 | &"top level"& addresses, and the parent address that generated them is marked |
29223 | &"delivered"&. Thus, expansion of the mailing list does not happen again at the | |
168e428f PH |
29224 | subsequent delivery attempts. The disadvantage of this is that if any of the |
29225 | failing addresses are incorrect, correcting them in the file has no effect on | |
29226 | pre-existing messages. | |
29227 | ||
29228 | The original top-level address is remembered with each of the generated | |
29229 | addresses, and is output in any log messages. However, any intermediate parent | |
29230 | addresses are not recorded. This makes a difference to the log only if the | |
9b371988 | 29231 | &%all_parents%& selector is set, but for mailing lists there is normally only |
168e428f PH |
29232 | one level of expansion anyway. |
29233 | ||
29234 | ||
29235 | ||
9b371988 PH |
29236 | .section "Closed mailing lists" |
29237 | .cindex "mailing lists" "closed" | |
168e428f PH |
29238 | The examples so far have assumed open mailing lists, to which anybody may |
29239 | send mail. It is also possible to set up closed lists, where mail is accepted | |
29240 | from specified senders only. This is done by making use of the generic | |
9b371988 | 29241 | &%senders%& option to restrict the router that handles the list. |
168e428f PH |
29242 | |
29243 | The following example uses the same file as a list of recipients and as a list | |
29244 | of permitted senders. It requires three routers: | |
9b371988 | 29245 | .code |
168e428f PH |
29246 | lists_request: |
29247 | driver = redirect | |
29248 | domains = lists.example | |
29249 | local_part_suffix = -request | |
29250 | file = /usr/lists/$local_part$local_part_suffix | |
29251 | no_more | |
29252 | ||
29253 | lists_post: | |
29254 | driver = redirect | |
29255 | domains = lists.example | |
29256 | senders = ${if exists {/usr/lists/$local_part}\ | |
29257 | {lsearch;/usr/lists/$local_part}{*}} | |
29258 | file = /usr/lists/$local_part | |
29259 | forbid_pipe | |
29260 | forbid_file | |
29261 | errors_to = $local_part-request@lists.example | |
29262 | no_more | |
29263 | ||
29264 | lists_closed: | |
29265 | driver = redirect | |
29266 | domains = lists.example | |
29267 | allow_fail | |
29268 | data = :fail: $local_part@lists.example is a closed mailing list | |
9b371988 PH |
29269 | .endd |
29270 | All three routers have the same &%domains%& setting, so for any other domains, | |
168e428f | 29271 | they are all skipped. The first router runs only if the local part ends in |
9b371988 | 29272 | &%-request%&. It handles messages to the list manager(s) by means of an open |
168e428f PH |
29273 | mailing list. |
29274 | ||
9b371988 | 29275 | The second router runs only if the &%senders%& precondition is satisfied. It |
168e428f PH |
29276 | checks for the existence of a list that corresponds to the local part, and then |
29277 | checks that the sender is on the list by means of a linear search. It is | |
29278 | necessary to check for the existence of the file before trying to search it, | |
29279 | because otherwise Exim thinks there is a configuration error. If the file does | |
9b371988 | 29280 | not exist, the expansion of &%senders%& is *, which matches all senders. This |
168e428f | 29281 | means that the router runs, but because there is no list, declines, and |
9b371988 PH |
29282 | &%no_more%& ensures that no further routers are run. The address fails with an |
29283 | &"unrouteable address"& error. | |
168e428f PH |
29284 | |
29285 | The third router runs only if the second router is skipped, which happens when | |
29286 | a mailing list exists, but the sender is not on it. This router forcibly fails | |
29287 | the address, giving a suitable error message. | |
29288 | ||
29289 | ||
29290 | ||
29291 | ||
9b371988 PH |
29292 | .section "Virtual domains" "SECTvirtualdomains" |
29293 | .cindex "virtual domains" | |
29294 | .cindex "domain" "virtual" | |
29295 | The phrase &'virtual domain'& is unfortunately used with two rather different | |
168e428f PH |
29296 | meanings: |
29297 | ||
9b371988 PH |
29298 | .ilist |
29299 | A domain for which there are no real mailboxes; all valid local parts are | |
168e428f | 29300 | aliases for other email addresses. Common examples are organizational |
9b371988 PH |
29301 | top-level domains and &"vanity"& domains. |
29302 | .next | |
29303 | One of a number of independent domains that are all handled by the same host, | |
168e428f PH |
29304 | with mailboxes on that host, but where the mailbox owners do not necessarily |
29305 | have login accounts on that host. | |
9b371988 | 29306 | .endlist |
168e428f | 29307 | |
9b371988 PH |
29308 | The first usage is probably more common, and does seem more &"virtual"& than |
29309 | the second. This kind of domain can be handled in Exim with a straightforward | |
168e428f PH |
29310 | aliasing router. One approach is to create a separate alias file for each |
29311 | virtual domain. Exim can test for the existence of the alias file to determine | |
9b371988 | 29312 | whether the domain exists. The &(dsearch)& lookup type is useful here, leading |
168e428f | 29313 | to a router of this form: |
9b371988 PH |
29314 | .code |
29315 | virtual: | |
29316 | driver = redirect | |
29317 | domains = dsearch;/etc/mail/virtual | |
29318 | data = ${lookup{$local_part}lsearch{/etc/mail/virtual/$domain}} | |
29319 | no_more | |
29320 | .endd | |
29321 | The &%domains%& option specifies that the router is to be skipped, unless there | |
29322 | is a file in the &_/etc/mail/virtual_& directory whose name is the same as the | |
168e428f | 29323 | domain that is being processed. When the router runs, it looks up the local |
9b371988 PH |
29324 | part in the file to find a new address (or list of addresses). The &%no_more%& |
29325 | setting ensures that if the lookup fails (leading to &%data%& being an empty | |
168e428f PH |
29326 | string), Exim gives up on the address without trying any subsequent routers. |
29327 | ||
29328 | This one router can handle all the virtual domains because the alias file names | |
29329 | follow a fixed pattern. Permissions can be arranged so that appropriate people | |
29330 | can edit the different alias files. A successful aliasing operation results in | |
29331 | a new envelope recipient address, which is then routed from scratch. | |
29332 | ||
9b371988 | 29333 | The other kind of &"virtual"& domain can also be handled in a straightforward |
168e428f PH |
29334 | way. One approach is to create a file for each domain containing a list of |
29335 | valid local parts, and use it in a router like this: | |
9b371988 PH |
29336 | .code |
29337 | my_domains: | |
29338 | driver = accept | |
29339 | domains = dsearch;/etc/mail/domains | |
29340 | local_parts = lsearch;/etc/mail/domains/$domain | |
29341 | transport = my_mailboxes | |
29342 | .endd | |
168e428f | 29343 | The address is accepted if there is a file for the domain, and the local part |
9b371988 PH |
29344 | can be found in the file. The &%domains%& option is used to check for the |
29345 | file's existence because &%domains%& is tested before the &%local_parts%& | |
29346 | option (see section &<<SECTrouprecon>>&). You cannot use &%require_files%&, | |
29347 | because that option is tested after &%local_parts%&. The transport is as | |
29348 | follows: | |
29349 | .code | |
29350 | my_mailboxes: | |
29351 | driver = appendfile | |
29352 | file = /var/mail/$domain/$local_part | |
29353 | user = mail | |
29354 | .endd | |
29355 | This uses a directory of mailboxes for each domain. The &%user%& setting is | |
168e428f PH |
29356 | required, to specify which uid is to be used for writing to the mailboxes. |
29357 | ||
29358 | The configuration shown here is just one example of how you might support this | |
29359 | requirement. There are many other ways this kind of configuration can be set | |
29360 | up, for example, by using a database instead of separate files to hold all the | |
29361 | information about the domains. | |
29362 | ||
29363 | ||
29364 | ||
9b371988 PH |
29365 | .section "Multiple user mailboxes" "SECTmulbox" |
29366 | .cindex "multiple mailboxes" | |
29367 | .cindex "mailbox" "multiple" | |
29368 | .cindex "local part" "prefix" | |
29369 | .cindex "local part" "suffix" | |
168e428f PH |
29370 | Heavy email users often want to operate with multiple mailboxes, into which |
29371 | incoming mail is automatically sorted. A popular way of handling this is to | |
29372 | allow users to use multiple sender addresses, so that replies can easily be | |
29373 | identified. Users are permitted to add prefixes or suffixes to their local | |
29374 | parts for this purpose. The wildcard facility of the generic router options | |
9b371988 | 29375 | &%local_part_prefix%& and &%local_part_suffix%& can be used for this. For |
168e428f | 29376 | example, consider this router: |
9b371988 PH |
29377 | .code |
29378 | userforward: | |
29379 | driver = redirect | |
29380 | check_local_user | |
29381 | file = $home/.forward | |
29382 | local_part_suffix = -* | |
29383 | local_part_suffix_optional | |
29384 | allow_filter | |
29385 | .endd | |
29386 | .cindex "&$local_part_suffix$&" | |
29387 | It runs a user's &_.forward_& file for all local parts of the form | |
29388 | &'username-*'&. Within the filter file the user can distinguish different | |
29389 | cases by testing the variable &$local_part_suffix$&. For example: | |
29390 | .code | |
29391 | if $local_part_suffix contains -special then | |
29392 | save /home/$local_part/Mail/special | |
29393 | endif | |
29394 | .endd | |
168e428f PH |
29395 | If the filter file does not exist, or does not deal with such addresses, they |
29396 | fall through to subsequent routers, and, assuming no subsequent use of the | |
9b371988 | 29397 | &%local_part_suffix%& option is made, they presumably fail. Thus, users have |
168e428f PH |
29398 | control over which suffixes are valid. |
29399 | ||
29400 | Alternatively, a suffix can be used to trigger the use of a different | |
9b371988 | 29401 | &_.forward_& file &-- which is the way a similar facility is implemented in |
168e428f | 29402 | another MTA: |
9b371988 PH |
29403 | .code |
29404 | userforward: | |
29405 | driver = redirect | |
29406 | check_local_user | |
29407 | file = $home/.forward$local_part_suffix | |
29408 | local_part_suffix = -* | |
29409 | local_part_suffix_optional | |
29410 | allow_filter | |
29411 | .endd | |
29412 | If there is no suffix, &_.forward_& is used; if the suffix is &'-special'&, for | |
29413 | example, &_.forward-special_& is used. Once again, if the appropriate file | |
168e428f PH |
29414 | does not exist, or does not deal with the address, it is passed on to |
29415 | subsequent routers, which could, if required, look for an unqualified | |
9b371988 | 29416 | &_.forward_& file to use as a default. |
168e428f PH |
29417 | |
29418 | ||
29419 | ||
9b371988 PH |
29420 | .section "Simplified vacation processing" |
29421 | .cindex "vacation processing" | |
29422 | The traditional way of running the &'vacation'& program is for a user to set up | |
29423 | a pipe command in a &_.forward_& file | |
29424 | (see section &<<SECTspecitredli>>& for syntax details). | |
168e428f PH |
29425 | This is prone to error by inexperienced users. There are two features of Exim |
29426 | that can be used to make this process simpler for users: | |
29427 | ||
9b371988 PH |
29428 | .ilist |
29429 | A local part prefix such as &"vacation-"& can be specified on a router which | |
29430 | can cause the message to be delivered directly to the &'vacation'& program, or | |
29431 | alternatively can use Exim's &(autoreply)& transport. The contents of a user's | |
29432 | &_.forward_& file are then much simpler. For example: | |
29433 | .code | |
29434 | spqr, vacation-spqr | |
29435 | .endd | |
29436 | .next | |
29437 | The &%require_files%& generic router option can be used to trigger a | |
168e428f | 29438 | vacation delivery by checking for the existence of a certain file in the |
9b371988 | 29439 | user's home directory. The &%unseen%& generic option should also be used, to |
168e428f | 29440 | ensure that the original delivery also proceeds. In this case, all the user has |
9b371988 | 29441 | to do is to create a file called, say, &_.vacation_&, containing a vacation |
168e428f | 29442 | message. |
9b371988 | 29443 | .endlist |
168e428f PH |
29444 | |
29445 | Another advantage of both these methods is that they both work even when the | |
29446 | use of arbitrary pipes by users is locked out. | |
29447 | ||
29448 | ||
29449 | ||
9b371988 PH |
29450 | .section "Taking copies of mail" |
29451 | .cindex "message" "copying every" | |
168e428f PH |
29452 | Some installations have policies that require archive copies of all messages to |
29453 | be made. A single copy of each message can easily be taken by an appropriate | |
29454 | command in a system filter, which could, for example, use a different file for | |
29455 | each day's messages. | |
29456 | ||
29457 | There is also a shadow transport mechanism that can be used to take copies of | |
29458 | messages that are successfully delivered by local transports, one copy per | |
9b371988 | 29459 | delivery. This could be used, &'inter alia'&, to implement automatic |
168e428f PH |
29460 | notification of delivery by sites that insist on doing such things. |
29461 | ||
29462 | ||
29463 | ||
9b371988 PH |
29464 | .section "Intermittently connected hosts" |
29465 | .cindex "intermittently connected hosts" | |
168e428f PH |
29466 | It has become quite common (because it is cheaper) for hosts to connect to the |
29467 | Internet periodically rather than remain connected all the time. The normal | |
29468 | arrangement is that mail for such hosts accumulates on a system that is | |
29469 | permanently connected. | |
29470 | ||
29471 | Exim was designed for use on permanently connected hosts, and so it is not | |
29472 | particularly well-suited to use in an intermittently connected environment. | |
29473 | Nevertheless there are some features that can be used. | |
29474 | ||
29475 | ||
9b371988 | 29476 | .section "Exim on the upstream server host" |
168e428f PH |
29477 | It is tempting to arrange for incoming mail for the intermittently connected |
29478 | host to remain on Exim's queue until the client connects. However, this | |
29479 | approach does not scale very well. Two different kinds of waiting message are | |
9b371988 | 29480 | being mixed up in the same queue &-- those that cannot be delivered because of |
168e428f PH |
29481 | some temporary problem, and those that are waiting for their destination host |
29482 | to connect. This makes it hard to manage the queue, as well as wasting | |
29483 | resources, because each queue runner scans the entire queue. | |
29484 | ||
29485 | A better approach is to separate off those messages that are waiting for an | |
29486 | intermittently connected host. This can be done by delivering these messages | |
9b371988 | 29487 | into local files in batch SMTP, &"mailstore"&, or other envelope-preserving |
168e428f PH |
29488 | format, from where they are transmitted by other software when their |
29489 | destination connects. This makes it easy to collect all the mail for one host | |
29490 | in a single directory, and to apply local timeout rules on a per-message basis | |
29491 | if required. | |
29492 | ||
29493 | On a very small scale, leaving the mail on Exim's queue can be made to work. If | |
29494 | you are doing this, you should configure Exim with a long retry period for the | |
29495 | intermittent host. For example: | |
9b371988 PH |
29496 | .code |
29497 | cheshire.wonderland.fict.example * F,5d,24h | |
29498 | .endd | |
168e428f PH |
29499 | This stops a lot of failed delivery attempts from occurring, but Exim remembers |
29500 | which messages it has queued up for that host. Once the intermittent host comes | |
9b371988 PH |
29501 | online, forcing delivery of one message (either by using the &%-M%& or &%-R%& |
29502 | options, or by using the ETRN SMTP command (see section &<<SECTETRN>>&) | |
168e428f PH |
29503 | causes all the queued up messages to be delivered, often down a single SMTP |
29504 | connection. While the host remains connected, any new messages get delivered | |
29505 | immediately. | |
29506 | ||
29507 | If the connecting hosts do not have fixed IP addresses, that is, if a host is | |
29508 | issued with a different IP address each time it connects, Exim's retry | |
29509 | mechanisms on the holding host get confused, because the IP address is normally | |
29510 | used as part of the key string for holding retry information. This can be | |
9b371988 | 29511 | avoided by unsetting &%retry_include_ip_address%& on the &(smtp)& transport. |
168e428f PH |
29512 | Since this has disadvantages for permanently connected hosts, it is best to |
29513 | arrange a separate transport for the intermittently connected ones. | |
29514 | ||
29515 | ||
29516 | ||
9b371988 PH |
29517 | .section "Exim on the intermittently connected client host" |
29518 | The value of &%smtp_accept_queue_per_connection%& should probably be | |
168e428f PH |
29519 | increased, or even set to zero (that is, disabled) on the intermittently |
29520 | connected host, so that all incoming messages down a single connection get | |
29521 | delivered immediately. | |
29522 | ||
9b371988 PH |
29523 | .cindex "SMTP" "passed connection" |
29524 | .cindex "SMTP" "multiple deliveries" | |
29525 | .cindex "multiple SMTP deliveries" | |
168e428f PH |
29526 | Mail waiting to be sent from an intermittently connected host will probably |
29527 | not have been routed, because without a connection DNS lookups are not | |
29528 | possible. This means that if a normal queue run is done at connection time, | |
29529 | each message is likely to be sent in a separate SMTP session. This can be | |
29530 | avoided by starting the queue run with a command line option beginning with | |
9b371988 PH |
29531 | &%-qq%& instead of &%-q%&. In this case, the queue is scanned twice. In the |
29532 | first pass, routing is done but no deliveries take place. The second pass is a | |
29533 | normal queue run; since all the messages have been previously routed, those | |
29534 | destined for the same host are likely to get sent as multiple deliveries in a | |
29535 | single SMTP connection. | |
168e428f PH |
29536 | |
29537 | ||
29538 | ||
9b371988 PH |
29539 | . //////////////////////////////////////////////////////////////////////////// |
29540 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 29541 | |
9b371988 PH |
29542 | .chapter "Using Exim as a non-queueing client" "CHAPnonqueueing" &&& |
29543 | "Exim as a non-queueing client" | |
29544 | .cindex "client" "non-queueing" | |
29545 | .cindex "smart host" "queueing; suppressing" | |
168e428f | 29546 | On a personal computer, it is a common requirement for all |
9b371988 | 29547 | email to be sent to a &"smart host"&. There are plenty of MUAs that can be |
168e428f PH |
29548 | configured to operate that way, for all the popular operating systems. |
29549 | However, there are some MUAs for Unix-like systems that cannot be so | |
29550 | configured: they submit messages using the command line interface of | |
9b371988 | 29551 | &_/usr/sbin/sendmail_&. Furthermore, utility programs such as &'cron'& submit |
168e428f PH |
29552 | messages this way. |
29553 | ||
29554 | If the personal computer runs continuously, there is no problem, because it can | |
29555 | run a conventional MTA that handles delivery to the smart host, and deal with | |
29556 | any delays via its queueing mechanism. However, if the computer does not run | |
29557 | continuously or runs different operating systems at different times, queueing | |
29558 | email is not desirable. | |
29559 | ||
29560 | There is therefore a requirement for something that can provide the | |
9b371988 | 29561 | &_/usr/sbin/sendmail_& interface but deliver messages to a smart host without |
168e428f PH |
29562 | any queueing or retrying facilities. Furthermore, the delivery to the smart |
29563 | host should be synchronous, so that if it fails, the sending MUA is immediately | |
29564 | informed. In other words, we want something that extends an MUA that submits | |
29565 | to a local MTA via the command line so that it behaves like one that submits | |
29566 | to a remote smart host using TCP/SMTP. | |
29567 | ||
9b371988 | 29568 | There are a number of applications (for example, there is one called &'ssmtp'&) |
168e428f PH |
29569 | that do this job. However, people have found them to be lacking in various |
29570 | ways. For instance, you might want to allow aliasing and forwarding to be done | |
29571 | before sending a message to the smart host. | |
29572 | ||
29573 | Exim already had the necessary infrastructure for doing this job. Just a few | |
29574 | tweaks were needed to make it behave as required, though it is somewhat of an | |
29575 | overkill to use a fully-featured MTA for this purpose. | |
29576 | ||
9b371988 PH |
29577 | .cindex "&%mua_wrapper%&" |
29578 | There is a Boolean global option called &%mua_wrapper%&, defaulting false. | |
29579 | Setting &%mua_wrapper%& true causes Exim to run in a special mode where it | |
29580 | assumes that it is being used to &"wrap"& a command-line MUA in the manner | |
29581 | just described. As well as setting &%mua_wrapper%&, you also need to provide a | |
168e428f PH |
29582 | compatible router and transport configuration. Typically there will be just one |
29583 | router and one transport, sending everything to a smart host. | |
29584 | ||
29585 | When run in MUA wrapping mode, the behaviour of Exim changes in the | |
29586 | following ways: | |
29587 | ||
9b371988 PH |
29588 | .ilist |
29589 | A daemon cannot be run, nor will Exim accept incoming messages from &'inetd'&. | |
168e428f | 29590 | In other words, the only way to submit messages is via the command line. |
9b371988 PH |
29591 | .next |
29592 | Each message is synchonously delivered as soon as it is received (&%-odi%& is | |
29593 | assumed). All queueing options (&%queue_only%&, &%queue_smtp_domains%&, | |
29594 | &%control%& in an ACL, etc.) are quietly ignored. The Exim reception process | |
29595 | does not finish until the delivery attempt is complete. If the delivery is | |
168e428f | 29596 | successful, a zero return code is given. |
9b371988 PH |
29597 | .next |
29598 | Address redirection is permitted, but the final routing for all addresses must | |
168e428f PH |
29599 | be to the same remote transport, and to the same list of hosts. Furthermore, |
29600 | the return address (envelope sender) must be the same for all recipients, as | |
29601 | must any added or deleted header lines. In other words, it must be possible to | |
29602 | deliver the message in a single SMTP transaction, however many recipients there | |
29603 | are. | |
9b371988 PH |
29604 | .next |
29605 | If these conditions are not met, or if routing any address results in a | |
168e428f PH |
29606 | failure or defer status, or if Exim is unable to deliver all the recipients |
29607 | successfully to one of the smart hosts, delivery of the entire message fails. | |
9b371988 PH |
29608 | .next |
29609 | Because no queueing is allowed, all failures are treated as permanent; there | |
29610 | is no distinction between 4&'xx'& and 5&'xx'& SMTP response codes from the | |
168e428f PH |
29611 | smart host. Furthermore, because only a single yes/no response can be given to |
29612 | the caller, it is not possible to deliver to some recipients and not others. If | |
29613 | there is an error (temporary or permanent) for any recipient, all are failed. | |
9b371988 PH |
29614 | .next |
29615 | If more than one smart host is listed, Exim will try another host after a | |
168e428f PH |
29616 | connection failure or a timeout, in the normal way. However, if this kind of |
29617 | failure happens for all the hosts, the delivery fails. | |
9b371988 PH |
29618 | .next |
29619 | When delivery fails, an error message is written to the standard error stream | |
168e428f PH |
29620 | (as well as to Exim's log), and Exim exits to the caller with a return code |
29621 | value 1. The message is expunged from Exim's spool files. No bounce messages | |
29622 | are ever generated. | |
9b371988 PH |
29623 | .next |
29624 | No retry data is maintained, and any retry rules are ignored. | |
29625 | .next | |
29626 | A number of Exim options are overridden: &%deliver_drop_privilege%& is forced | |
29627 | true, &%max_rcpt%& in the smtp transport is forced to &"unlimited"&, | |
29628 | &%remote_max_parallel%& is forced to one, and fallback hosts are ignored. | |
29629 | .endlist | |
168e428f PH |
29630 | |
29631 | The overall effect is that Exim makes a single synchronous attempt to deliver | |
29632 | the message, failing if there is any kind of problem. Because no local | |
29633 | deliveries are done and no daemon can be run, Exim does not need root | |
9b371988 PH |
29634 | privilege. It should be possible to run it setuid to &'exim'& instead of setuid |
29635 | to &'root'&. See section &<<SECTrunexiwitpri>>& for a general discussion about | |
29636 | the advantages and disadvantages of running without root privilege. | |
168e428f PH |
29637 | |
29638 | ||
29639 | ||
29640 | ||
9b371988 PH |
29641 | . //////////////////////////////////////////////////////////////////////////// |
29642 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 29643 | |
9b371988 PH |
29644 | .chapter "Log files" "CHAPlog" |
29645 | .cindex "log" "types of" | |
29646 | .cindex "log" "general description" | |
168e428f PH |
29647 | Exim writes three different logs, referred to as the main log, the reject log, |
29648 | and the panic log: | |
29649 | ||
9b371988 PH |
29650 | .ilist |
29651 | .cindex "main log" | |
168e428f PH |
29652 | The main log records the arrival of each message and each delivery in a single |
29653 | line in each case. The format is as compact as possible, in an attempt to keep | |
29654 | down the size of log files. Two-character flag sequences make it easy to pick | |
29655 | out these lines. A number of other events are recorded in the main log. Some of | |
9b371988 PH |
29656 | them are optional, in which case the &%log_selector%& option controls whether |
29657 | they are included or not. A Perl script called &'eximstats'&, which does simple | |
168e428f | 29658 | analysis of main log files, is provided in the Exim distribution (see section |
9b371988 PH |
29659 | &<<SECTmailstat>>&). |
29660 | .next | |
29661 | .cindex "reject log" | |
168e428f PH |
29662 | The reject log records information from messages that are rejected as a result |
29663 | of a configuration option (that is, for policy reasons). | |
29664 | The first line of each rejection is a copy of the line that is also written to | |
29665 | the main log. Then, if the message's header has been read at the time the log | |
29666 | is written, its contents are written to this log. Only the original header | |
29667 | lines are available; header lines added by ACLs are not logged. You can use the | |
29668 | reject log to check that your policy controls are working correctly; on a busy | |
29669 | host this may be easier than scanning the main log for rejection messages. You | |
9b371988 PH |
29670 | can suppress the writing of the reject log by setting &%write_rejectlog%& |
29671 | false. | |
29672 | .next | |
29673 | .cindex "panic log" | |
29674 | .cindex "system log" | |
168e428f PH |
29675 | When certain serious errors occur, Exim writes entries to its panic log. If the |
29676 | error is sufficiently disastrous, Exim bombs out afterwards. Panic log entries | |
29677 | are usually written to the main log as well, but can get lost amid the mass of | |
29678 | other entries. The panic log should be empty under normal circumstances. It is | |
9b371988 | 29679 | therefore a good idea to check it (or to have a &'cron'& script check it) |
168e428f PH |
29680 | regularly, in order to become aware of any problems. When Exim cannot open its |
29681 | panic log, it tries as a last resort to write to the system log (syslog). This | |
29682 | is opened with LOG_PID+LOG_CONS and the facility code of LOG_MAIL. The | |
29683 | message itself is written at priority LOG_CRIT. | |
9b371988 PH |
29684 | .endlist |
29685 | ||
29686 | Every log line starts with a timestamp, in the format shown in the following | |
29687 | example. Note that many of the examples shown in this chapter are line-wrapped. | |
29688 | In the log file, this would be all on one line: | |
29689 | .code | |
29690 | 2001-09-16 16:09:47 SMTP connection from [127.0.0.1] closed | |
29691 | by QUIT | |
29692 | .endd | |
168e428f PH |
29693 | By default, the timestamps are in the local timezone. There are two |
29694 | ways of changing this: | |
29695 | ||
9b371988 PH |
29696 | .ilist |
29697 | You can set the &%timezone%& option to a different time zone; in particular, if | |
168e428f | 29698 | you set |
9b371988 PH |
29699 | .code |
29700 | timezone = UTC | |
29701 | .endd | |
168e428f | 29702 | the timestamps will be in UTC (aka GMT). |
9b371988 PH |
29703 | .next |
29704 | If you set &%log_timezone%& true, the time zone is added to the timestamp, for | |
168e428f | 29705 | example: |
9b371988 PH |
29706 | .code |
29707 | 2003-04-25 11:17:07 +0100 Start queue run: pid=12762 | |
29708 | .endd | |
29709 | .endlist | |
168e428f PH |
29710 | |
29711 | ||
29712 | ||
29713 | ||
9b371988 PH |
29714 | .section "Where the logs are written" "SECTwhelogwri" |
29715 | .cindex "log" "destination" | |
29716 | .cindex "log" "to file" | |
29717 | .cindex "log" "to syslog" | |
29718 | .cindex "syslog" | |
168e428f PH |
29719 | The logs may be written to local files, or to syslog, or both. However, it |
29720 | should be noted that many syslog implementations use UDP as a transport, and | |
29721 | are therefore unreliable in the sense that messages are not guaranteed to | |
29722 | arrive at the loghost, nor is the ordering of messages necessarily maintained. | |
29723 | It has also been reported that on large log files (tens of megabytes) you may | |
9b371988 PH |
29724 | need to tweak syslog to prevent it syncing the file with each write &-- on |
29725 | Linux this has been seen to make syslog take 90% plus of CPU time. | |
168e428f PH |
29726 | |
29727 | The destination for Exim's logs is configured by setting LOG_FILE_PATH in | |
9b371988 | 29728 | &_Local/Makefile_& or by setting &%log_file_path%& in the run time |
168e428f PH |
29729 | configuration. This latter string is expanded, so it can contain, for example, |
29730 | references to the host name: | |
9b371988 PH |
29731 | .code |
29732 | log_file_path = /var/log/$primary_hostname/exim_%slog | |
29733 | .endd | |
29734 | It is generally advisable, however, to set the string in &_Local/Makefile_& | |
168e428f PH |
29735 | rather than at run time, because then the setting is available right from the |
29736 | start of Exim's execution. Otherwise, if there's something it wants to log | |
29737 | before it has read the configuration file (for example, an error in the | |
29738 | configuration file) it will not use the path you want, and may not be able to | |
29739 | log at all. | |
29740 | ||
9b371988 | 29741 | The value of LOG_FILE_PATH or &%log_file_path%& is a colon-separated |
168e428f PH |
29742 | list, currently limited to at most two items. This is one option where the |
29743 | facility for changing a list separator may not be used. The list must always be | |
9b371988 PH |
29744 | colon-separated. If an item in the list is &"syslog"& then syslog is used; |
29745 | otherwise the item must either be an absolute path, containing &`%s`& at the | |
29746 | point where &"main"&, &"reject"&, or &"panic"& is to be inserted, or be empty, | |
168e428f PH |
29747 | implying the use of a default path. |
29748 | ||
29749 | When Exim encounters an empty item in the list, it searches the list defined by | |
29750 | LOG_FILE_PATH, and uses the first item it finds that is neither empty nor | |
9b371988 PH |
29751 | &"syslog"&. This means that an empty item in &%log_file_path%& can be used to |
29752 | mean &"use the path specified at build time"&. It no such item exists, log | |
29753 | files are written in the &_log_& subdirectory of the spool directory. This is | |
168e428f | 29754 | equivalent to the setting: |
9b371988 PH |
29755 | .code |
29756 | log_file_path = $spool_directory/log/%slog | |
29757 | .endd | |
168e428f PH |
29758 | If you do not specify anything at build time or run time, that is where the |
29759 | logs are written. | |
29760 | ||
9b371988 PH |
29761 | A log file path may also contain &`%D`& if datestamped log file names are in |
29762 | use &-- see section &<<SECTdatlogfil>>& below. | |
168e428f PH |
29763 | |
29764 | Here are some examples of possible settings: | |
9b371988 PH |
29765 | .display |
29766 | &`LOG_FILE_PATH=syslog `& syslog only | |
29767 | &`LOG_FILE_PATH=:syslog `& syslog and default path | |
29768 | &`LOG_FILE_PATH=syslog : /usr/log/exim_%s `& syslog and specified path | |
29769 | &`LOG_FILE_PATH=/usr/log/exim_%s `& specified path only | |
29770 | .endd | |
168e428f PH |
29771 | If there are more than two paths in the list, the first is used and a panic |
29772 | error is logged. | |
29773 | ||
29774 | ||
29775 | ||
9b371988 PH |
29776 | .section "Logging to local files that are periodically &""cycled""&" |
29777 | .cindex "log" "cycling local files" | |
29778 | .cindex "cycling logs" | |
29779 | .cindex "&'exicyclog'&" | |
29780 | .cindex "log" "local files; writing to" | |
168e428f | 29781 | Some operating systems provide centralized and standardised methods for cycling |
9b371988 PH |
29782 | log files. For those that do not, a utility script called &'exicyclog'& is |
29783 | provided (see section &<<SECTcyclogfil>>&). This renames and compresses the | |
29784 | main and reject logs each time it is called. The maximum number of old logs to | |
29785 | keep can be set. It is suggested this script is run as a daily &'cron'& job. | |
168e428f PH |
29786 | |
29787 | An Exim delivery process opens the main log when it first needs to write to it, | |
9b371988 | 29788 | and it keeps the file open in case subsequent entries are required &-- for |
168e428f PH |
29789 | example, if a number of different deliveries are being done for the same |
29790 | message. However, remote SMTP deliveries can take a long time, and this means | |
9b371988 | 29791 | that the file may be kept open long after it is renamed if &'exicyclog'& or |
168e428f PH |
29792 | something similar is being used to rename log files on a regular basis. To |
29793 | ensure that a switch of log files is noticed as soon as possible, Exim calls | |
9b371988 | 29794 | &[stat()]& on the main log's name before reusing an open file, and if the file |
168e428f PH |
29795 | does not exist, or its inode has changed, the old file is closed and Exim |
29796 | tries to open the main log from scratch. Thus, an old log file may remain open | |
29797 | for quite some time, but no Exim processes should write to it once it has been | |
29798 | renamed. | |
29799 | ||
29800 | ||
29801 | ||
9b371988 PH |
29802 | .section "Datestamped log files" "SECTdatlogfil" |
29803 | .cindex "log" "datestamped files" | |
168e428f PH |
29804 | Instead of cycling the main and reject log files by renaming them |
29805 | periodically, some sites like to use files whose names contain a datestamp, | |
9b371988 | 29806 | for example, &_mainlog-20031225_&. The datestamp is in the form &_yyyymmdd_&. |
168e428f | 29807 | Exim has support for this way of working. It is enabled by setting the |
9b371988 | 29808 | &%log_file_path%& option to a path that includes &`%D`& at the point where the |
168e428f | 29809 | datestamp is required. For example: |
9b371988 PH |
29810 | .code |
29811 | log_file_path = /var/spool/exim/log/%slog-%D | |
29812 | log_file_path = /var/log/exim-%s-%D.log | |
29813 | log_file_path = /var/spool/exim/log/%D-%slog | |
29814 | .endd | |
29815 | As before, &`%s`& is replaced by &"main"& or &"reject"&; the following are | |
29816 | examples of names generated by the above examples: | |
29817 | .code | |
29818 | /var/spool/exim/log/mainlog-20021225 | |
29819 | /var/log/exim-reject-20021225.log | |
29820 | /var/spool/exim/log/20021225-mainlog | |
29821 | .endd | |
168e428f PH |
29822 | When this form of log file is specified, Exim automatically switches to new |
29823 | files at midnight. It does not make any attempt to compress old logs; you | |
29824 | will need to write your own script if you require this. You should not | |
9b371988 | 29825 | run &'exicyclog'& with this form of logging. |
168e428f | 29826 | |
9b371988 | 29827 | The location of the panic log is also determined by &%log_file_path%&, but it |
168e428f | 29828 | is not datestamped, because rotation of the panic log does not make sense. |
9b371988 | 29829 | When generating the name of the panic log, &`%D`& is removed from the string. |
168e428f PH |
29830 | In addition, if it immediately follows a slash, a following non-alphanumeric |
29831 | character is removed; otherwise a preceding non-alphanumeric character is | |
29832 | removed. Thus, the three examples above would give these panic log names: | |
9b371988 PH |
29833 | .code |
29834 | /var/spool/exim/log/paniclog | |
29835 | /var/log/exim-panic.log | |
29836 | /var/spool/exim/log/paniclog | |
29837 | .endd | |
168e428f PH |
29838 | |
29839 | ||
9b371988 PH |
29840 | .section "Logging to syslog" |
29841 | .cindex "log" "syslog; writing to" | |
168e428f | 29842 | The use of syslog does not change what Exim logs or the format of its messages, |
9b371988 | 29843 | except in one respect. If &%syslog_timestamp%& is set false, the timestamps on |
168e428f PH |
29844 | Exim's log lines are omitted when these lines are sent to syslog. Apart from |
29845 | that, the same strings are written to syslog as to log files. The syslog | |
9b371988 PH |
29846 | &"facility"& is set to LOG_MAIL, and the program name to &"exim"& |
29847 | by default, but you can change these by setting the &%syslog_facility%& and | |
29848 | &%syslog_processname%& options, respectively. If Exim was compiled with | |
29849 | SYSLOG_LOG_PID set in &_Local/Makefile_& (this is the default in | |
29850 | &_src/EDITME_&), then, on systems that permit it (all except ULTRIX), the | |
29851 | LOG_PID flag is set so that the &[syslog()]& call adds the pid as well as | |
168e428f PH |
29852 | the time and host name to each line. |
29853 | The three log streams are mapped onto syslog priorities as follows: | |
29854 | ||
9b371988 PH |
29855 | .ilist |
29856 | &'mainlog'& is mapped to LOG_INFO | |
29857 | .next | |
29858 | &'rejectlog'& is mapped to LOG_NOTICE | |
29859 | .next | |
29860 | &'paniclog'& is mapped to LOG_ALERT | |
29861 | .endlist | |
168e428f | 29862 | |
9b371988 PH |
29863 | Many log lines are written to both &'mainlog'& and &'rejectlog'&, and some are |
29864 | written to both &'mainlog'& and &'paniclog'&, so there will be duplicates if | |
168e428f | 29865 | these are routed by syslog to the same place. You can suppress this duplication |
9b371988 | 29866 | by setting &%syslog_duplication%& false. |
168e428f | 29867 | |
9b371988 | 29868 | Exim's log lines can sometimes be very long, and some of its &'rejectlog'& |
168e428f | 29869 | entries contain multiple lines when headers are included. To cope with both |
9b371988 | 29870 | these cases, entries written to syslog are split into separate &[syslog()]& |
168e428f PH |
29871 | calls at each internal newline, and also after a maximum of |
29872 | 870 data characters. (This allows for a total syslog line length of 1024, when | |
29873 | additions such as timestamps are added.) If you are running a syslog | |
29874 | replacement that can handle lines longer than the 1024 characters allowed by | |
29875 | RFC 3164, you should set | |
9b371988 PH |
29876 | .code |
29877 | SYSLOG_LONG_LINES=yes | |
29878 | .endd | |
29879 | in &_Local/Makefile_& before building Exim. That stops Exim from splitting long | |
29880 | lines, but it still splits at internal newlines in &'reject'& log entries. | |
168e428f PH |
29881 | |
29882 | To make it easy to re-assemble split lines later, each component of a split | |
9b371988 PH |
29883 | entry starts with a string of the form [<&'n'&>/<&'m'&>] or [<&'n'&>\<&'m'&>] |
29884 | where <&'n'&> is the component number and <&'m'&> is the total number of | |
29885 | components in the entry. The / delimiter is used when the line was split | |
29886 | because it was too long; if it was split because of an internal newline, the \ | |
29887 | delimiter is used. For example, supposing the length limit to be 50 instead of | |
29888 | 870, the following would be the result of a typical rejection message to | |
29889 | &'mainlog'& (LOG_INFO), each line in addition being preceded by the time, host | |
29890 | name, and pid as added by syslog: | |
29891 | .code | |
29892 | [1/5] 2002-09-16 16:09:43 16RdAL-0006pc-00 rejected from | |
29893 | [2/5] [127.0.0.1] (ph10): syntax error in 'From' header | |
29894 | [3/5] when scanning for sender: missing or malformed lo | |
29895 | [4/5] cal part in "<>" (envelope sender is <ph10@cam.exa | |
29896 | [5/5] mple>) | |
29897 | .endd | |
29898 | The same error might cause the following lines to be written to &"rejectlog"& | |
168e428f | 29899 | (LOG_NOTICE): |
9b371988 PH |
29900 | .code |
29901 | [1/18] 2002-09-16 16:09:43 16RdAL-0006pc-00 rejected fro | |
29902 | [2/18] m [127.0.0.1] (ph10): syntax error in 'From' head | |
29903 | [3/18] er when scanning for sender: missing or malformed | |
29904 | [4/18] local part in "<>" (envelope sender is <ph10@cam | |
29905 | [5\18] .example>) | |
29906 | [6\18] Recipients: ph10@some.domain.cam.example | |
29907 | [7\18] P Received: from [127.0.0.1] (ident=ph10) | |
29908 | [8\18] by xxxxx.cam.example with smtp (Exim 4.00) | |
29909 | [9\18] id 16RdAL-0006pc-00 | |
29910 | [10/18] for ph10@cam.example; Mon, 16 Sep 2002 16: | |
29911 | [11\18] 09:43 +0100 | |
29912 | [12\18] F From: <> | |
29913 | [13\18] Subject: this is a test header | |
29914 | [18\18] X-something: this is another header | |
29915 | [15/18] I Message-Id: <E16RdAL-0006pc-00@xxxxx.cam.examp | |
29916 | [16\18] le> | |
29917 | [17\18] B Bcc: | |
29918 | [18/18] Date: Mon, 16 Sep 2002 16:09:43 +0100 | |
29919 | .endd | |
168e428f PH |
29920 | Log lines that are neither too long nor contain newlines are written to syslog |
29921 | without modification. | |
29922 | ||
29923 | If only syslog is being used, the Exim monitor is unable to provide a log tail | |
9b371988 | 29924 | display, unless syslog is routing &'mainlog'& to a file on the local host and |
168e428f PH |
29925 | the environment variable EXIMON_LOG_FILE_PATH is set to tell the monitor |
29926 | where it is. | |
29927 | ||
29928 | ||
29929 | ||
9b371988 | 29930 | .section "Log line flags" |
168e428f PH |
29931 | One line is written to the main log for each message received, and for each |
29932 | successful, unsuccessful, and delayed delivery. These lines can readily be | |
29933 | picked out by the distinctive two-character flags that immediately follow the | |
29934 | timestamp. The flags are: | |
9b371988 PH |
29935 | .display |
29936 | &`<=`& message arrival | |
29937 | &`=>`& normal message delivery | |
29938 | &`->`& additional address in same delivery | |
29939 | &`*>`& delivery suppressed by &%-N%& | |
29940 | &`**`& delivery failed; address bounced | |
29941 | &`==`& delivery deferred; temporary problem | |
29942 | .endd | |
29943 | ||
29944 | ||
29945 | .section "Logging message reception" | |
29946 | .cindex "log" "reception line" | |
168e428f PH |
29947 | The format of the single-line entry in the main log that is written for every |
29948 | message received is shown in the basic example below, which is split over | |
29949 | several lines in order to fit it on the page: | |
9b371988 PH |
29950 | .code |
29951 | 2002-10-31 08:57:53 16ZCW1-0005MB-00 <= kryten@dwarf.fict.example | |
29952 | H=mailer.fict.example [192.168.123.123] U=exim | |
29953 | P=smtp S=5678 id=<incoming message id> | |
29954 | .endd | |
29955 | The address immediately following &"<="& is the envelope sender address. A | |
29956 | bounce message is shown with the sender address &"<>"&, and if it is locally | |
29957 | generated, this is followed by an item of the form | |
29958 | .code | |
29959 | R=<message id> | |
29960 | .endd | |
168e428f PH |
29961 | which is a reference to the message that caused the bounce to be sent. |
29962 | ||
9b371988 PH |
29963 | .cindex "HELO" |
29964 | .cindex "EHLO" | |
168e428f PH |
29965 | For messages from other hosts, the H and U fields identify the remote host and |
29966 | record the RFC 1413 identity of the user that sent the message, if one was | |
29967 | received. The number given in square brackets is the IP address of the sending | |
29968 | host. If there is a single, unparenthesized host name in the H field, as | |
29969 | above, it has been verified to correspond to the IP address (see the | |
9b371988 | 29970 | &%host_lookup%& option). If the name is in parentheses, it was the name quoted |
168e428f PH |
29971 | by the remote host in the SMTP HELO or EHLO command, and has not been |
29972 | verified. If verification yields a different name to that given for HELO or | |
29973 | EHLO, the verified name appears first, followed by the HELO or EHLO | |
29974 | name in parentheses. | |
29975 | ||
29976 | Misconfigured hosts (and mail forgers) sometimes put an IP address, with or | |
29977 | without brackets, in the HELO or EHLO command, leading to entries in | |
29978 | the log containing text like these examples: | |
9b371988 PH |
29979 | .code |
29980 | H=(10.21.32.43) [192.168.8.34] | |
29981 | H=([10.21.32.43]) [192.168.8.34] | |
29982 | .endd | |
168e428f PH |
29983 | This can be confusing. Only the final address in square brackets can be relied |
29984 | on. | |
29985 | ||
29986 | For locally generated messages (that is, messages not received over TCP/IP), | |
29987 | the H field is omitted, and the U field contains the login name of the caller | |
29988 | of Exim. | |
29989 | ||
9b371988 PH |
29990 | .cindex "authentication" "logging" |
29991 | .cindex "AUTH" "logging" | |
29992 | .new | |
168e428f | 29993 | For all messages, the P field specifies the protocol used to receive the |
9b371988 | 29994 | message. This is the value that is stored in &$received_protocol$&. In the case |
068aaea8 PH |
29995 | of incoming SMTP messages, the value indicates whether or not any SMTP |
29996 | extensions (ESMTP), encryption, or authentication were used. If the SMTP | |
29997 | session was encrypted, there is an additional X field that records the cipher | |
29998 | suite that was used. | |
29999 | ||
9b371988 | 30000 | The protocol is set to &"esmptsa"& or &"esmtpa"& for messages received from |
068aaea8 | 30001 | hosts that have authenticated themselves using the SMTP AUTH command. The first |
9b371988 | 30002 | value is used when the SMTP connection was encrypted (&"secure"&). In this case |
068aaea8 PH |
30003 | there is an additional item A= followed by the name of the authenticator that |
30004 | was used. If an authenticated identification was set up by the authenticator's | |
9b371988 | 30005 | &%server_set_id%& option, this is logged too, separated by a colon from the |
168e428f | 30006 | authenticator name. |
9b371988 | 30007 | .wen |
168e428f | 30008 | |
9b371988 | 30009 | .cindex "size" "of message" |
068aaea8 PH |
30010 | The id field records the existing message id, if present. The size of the |
30011 | received message is given by the S field. When the message is delivered, | |
30012 | headers may be removed or added, so that the size of delivered copies of the | |
30013 | message may not correspond with this value (and indeed may be different to each | |
30014 | other). | |
168e428f | 30015 | |
9b371988 PH |
30016 | The &%log_selector%& option can be used to request the logging of additional |
30017 | data when a message is received. See section &<<SECTlogselector>>& below. | |
168e428f PH |
30018 | |
30019 | ||
30020 | ||
9b371988 PH |
30021 | .section "Logging deliveries" |
30022 | .cindex "log" "delivery line" | |
168e428f | 30023 | The format of the single-line entry in the main log that is written for every |
9b371988 PH |
30024 | delivery is shown in one of the examples below, for local and remote |
30025 | deliveries, respectively. Each example has been split into two lines in order | |
30026 | to fit it on the page: | |
30027 | .code | |
30028 | 2002-10-31 08:59:13 16ZCW1-0005MB-00 => marv | |
30029 | <marv@hitch.fict.example> R=localuser T=local_delivery | |
30030 | 2002-10-31 09:00:10 16ZCW1-0005MB-00 => | |
30031 | monk@holistic.fict.example R=dnslookup T=remote_smtp | |
30032 | H=holistic.fict.example [192.168.234.234] | |
30033 | .endd | |
168e428f PH |
30034 | For ordinary local deliveries, the original address is given in angle brackets |
30035 | after the final delivery address, which might be a pipe or a file. If | |
30036 | intermediate address(es) exist between the original and the final address, the | |
30037 | last of these is given in parentheses after the final address. The R and T | |
30038 | fields record the router and transport that were used to process the address. | |
30039 | ||
30040 | If a shadow transport was run after a successful local delivery, the log line | |
30041 | for the successful delivery has an item added on the end, of the form | |
9b371988 PH |
30042 | .display |
30043 | &`ST=<`&&'shadow transport name'&&`>`& | |
30044 | .endd | |
168e428f PH |
30045 | If the shadow transport did not succeed, the error message is put in |
30046 | parentheses afterwards. | |
30047 | ||
9b371988 | 30048 | .cindex "asterisk" "after IP address" |
168e428f | 30049 | When more than one address is included in a single delivery (for example, two |
068aaea8 | 30050 | SMTP RCPT commands in one transaction) the second and subsequent addresses are |
9b371988 PH |
30051 | flagged with &`->`& instead of &`=>`&. When two or more messages are delivered |
30052 | down a single SMTP connection, an asterisk follows the IP address in the log | |
30053 | lines for the second and subsequent messages. | |
168e428f | 30054 | |
9b371988 PH |
30055 | The generation of a reply message by a filter file gets logged as a |
30056 | &"delivery"& to the addressee, preceded by &">"&. | |
168e428f | 30057 | |
9b371988 PH |
30058 | The &%log_selector%& option can be used to request the logging of additional |
30059 | data when a message is delivered. See section &<<SECTlogselector>>& below. | |
168e428f PH |
30060 | |
30061 | ||
9b371988 PH |
30062 | .section "Discarded deliveries" |
30063 | .cindex "discarded messages" | |
30064 | .cindex "message" "discarded" | |
30065 | .cindex "delivery" "discarded; logging" | |
30066 | When a message is discarded as a result of the command &"seen finish"& being | |
168e428f | 30067 | obeyed in a filter file which generates no deliveries, a log entry of the form |
9b371988 PH |
30068 | .code |
30069 | 2002-12-10 00:50:49 16auJc-0001UB-00 => discarded | |
30070 | <low.club@bridge.example> R=userforward | |
30071 | .endd | |
168e428f | 30072 | is written, to record why no deliveries are logged. When a message is discarded |
9b371988 PH |
30073 | because it is aliased to &":blackhole:"& the log line is like this: |
30074 | .code | |
30075 | 1999-03-02 09:44:33 10HmaX-0005vi-00 => :blackhole: | |
30076 | <hole@nowhere.example> R=blackhole_router | |
30077 | .endd | |
168e428f PH |
30078 | |
30079 | ||
9b371988 | 30080 | .section "Deferred deliveries" |
168e428f | 30081 | When a delivery is deferred, a line of the following form is logged: |
9b371988 PH |
30082 | .code |
30083 | 2002-12-19 16:20:23 16aiQz-0002Q5-00 == marvin@endrest.example | |
30084 | R=dnslookup T=smtp defer (146): Connection refused | |
30085 | .endd | |
168e428f PH |
30086 | In the case of remote deliveries, the error is the one that was given for the |
30087 | last IP address that was tried. Details of individual SMTP failures are also | |
30088 | written to the log, so the above line would be preceded by something like | |
9b371988 PH |
30089 | .code |
30090 | 2002-12-19 16:20:23 16aiQz-0002Q5-00 Failed to connect to | |
30091 | mail1.endrest.example [192.168.239.239]: Connection refused | |
30092 | .endd | |
168e428f PH |
30093 | When a deferred address is skipped because its retry time has not been reached, |
30094 | a message is written to the log, but this can be suppressed by setting an | |
9b371988 | 30095 | appropriate value in &%log_selector%&. |
168e428f PH |
30096 | |
30097 | ||
30098 | ||
9b371988 PH |
30099 | .section "Delivery failures" |
30100 | .cindex "delivery" "failure; logging" | |
168e428f PH |
30101 | If a delivery fails because an address cannot be routed, a line of the |
30102 | following form is logged: | |
9b371988 PH |
30103 | .code |
30104 | 1995-12-19 16:20:23 0tRiQz-0002Q5-00 ** jim@trek99.example | |
30105 | <jim@trek99.example>: unknown mail domain | |
30106 | .endd | |
168e428f PH |
30107 | If a delivery fails at transport time, the router and transport are shown, and |
30108 | the response from the remote host is included, as in this example: | |
9b371988 PH |
30109 | .code |
30110 | 2002-07-11 07:14:17 17SXDU-000189-00 ** ace400@pb.example | |
30111 | R=dnslookup T=remote_smtp: SMTP error from remote mailer | |
30112 | after pipelined RCPT TO:<ace400@pb.example>: host | |
30113 | pbmail3.py.example [192.168.63.111]: 553 5.3.0 | |
30114 | <ace400@pb.example>...Addressee unknown | |
30115 | .endd | |
30116 | The word &"pipelined"& indicates that the SMTP PIPELINING extension was being | |
30117 | used. See &%hosts_avoid_esmtp%& in the &(smtp)& transport for a way of | |
30118 | disabling PIPELINING. The log lines for all forms of delivery failure are | |
30119 | flagged with &`**`&. | |
30120 | ||
30121 | ||
30122 | ||
30123 | .section "Fake deliveries" | |
30124 | .cindex "delivery" "fake; logging" | |
30125 | If a delivery does not actually take place because the &%-N%& option has been | |
168e428f | 30126 | used to suppress it, a normal delivery line is written to the log, except that |
9b371988 | 30127 | &"=>"& is replaced by &"*>"&. |
168e428f PH |
30128 | |
30129 | ||
30130 | ||
9b371988 | 30131 | .section "Completion" |
168e428f | 30132 | A line of the form |
9b371988 PH |
30133 | .code |
30134 | 2002-10-31 09:00:11 16ZCW1-0005MB-00 Completed | |
30135 | .endd | |
168e428f PH |
30136 | is written to the main log when a message is about to be removed from the spool |
30137 | at the end of its processing. | |
30138 | ||
30139 | ||
30140 | ||
30141 | ||
9b371988 PH |
30142 | .section "Summary of Fields in Log Lines" |
30143 | .cindex "log" "summary of fields" | |
168e428f PH |
30144 | A summary of the field identifiers that are used in log lines is shown in |
30145 | the following table: | |
9b371988 PH |
30146 | .display |
30147 | &`A `& authenticator name (and optional id) | |
30148 | &`C `& SMTP confirmation on delivery | |
30149 | &`CV `& certificate verification status | |
30150 | &`DN `& distinguished name from peer certificate | |
30151 | &`DT `& on &`=>`& lines: time taken for a delivery | |
30152 | &`F `& sender address (on delivery lines) | |
30153 | &`H `& host name and IP address | |
30154 | &`I `& local interface used | |
30155 | &`id `& message id for incoming message | |
30156 | &`P `& on &`<=`& lines: protocol used | |
30157 | &` `& on &`=>`& and &`**`& lines: return path | |
30158 | &`QT `& on &`=>`& lines: time spent on queue so far | |
30159 | &` `& on &"Completed"& lines: time spent on queue | |
30160 | &`R `& on &`<=`& lines: reference for local bounce | |
30161 | &` `& on &`=>`& &`**`& and &`==`& lines: router name | |
30162 | &`S `& size of message | |
30163 | &`ST `& shadow transport name | |
30164 | &`T `& on &`<=`& lines: message subject (topic) | |
30165 | &` `& on &`=>`& &`**`& and &`==`& lines: transport name | |
30166 | &`U `& local user or RFC 1413 identity | |
30167 | &`X `& TLS cipher suite | |
30168 | .endd | |
30169 | ||
30170 | ||
30171 | .section "Other log entries" | |
168e428f PH |
30172 | Various other types of log entry are written from time to time. Most should be |
30173 | self-explanatory. Among the more common are: | |
30174 | ||
9b371988 PH |
30175 | .ilist |
30176 | .cindex "retry" "time not reached" | |
30177 | &'retry time not reached'&&~&~An address previously suffered a temporary error | |
168e428f PH |
30178 | during routing or local delivery, and the time to retry has not yet arrived. |
30179 | This message is not written to an individual message log file unless it happens | |
30180 | during the first delivery attempt. | |
9b371988 PH |
30181 | .next |
30182 | &'retry time not reached for any host'&&~&~An address previously suffered | |
168e428f PH |
30183 | temporary errors during remote delivery, and the retry time has not yet arrived |
30184 | for any of the hosts to which it is routed. | |
9b371988 PH |
30185 | .next |
30186 | .cindex "spool directory" "file locked" | |
30187 | &'spool file locked'&&~&~An attempt to deliver a message cannot proceed because | |
168e428f PH |
30188 | some other Exim process is already working on the message. This can be quite |
30189 | common if queue running processes are started at frequent intervals. The | |
9b371988 | 30190 | &'exiwhat'& utility script can be used to find out what Exim processes are |
168e428f | 30191 | doing. |
9b371988 PH |
30192 | .next |
30193 | .cindex "error" "ignored" | |
30194 | &'error ignored'&&~&~There are several circumstances that give rise to this | |
168e428f | 30195 | message: |
9b371988 PH |
30196 | .olist |
30197 | Exim failed to deliver a bounce message whose age was greater than | |
30198 | &%ignore_bounce_errors_after%&. The bounce was discarded. | |
30199 | .next | |
30200 | A filter file set up a delivery using the &"noerror"& option, and the delivery | |
168e428f | 30201 | failed. The delivery was discarded. |
9b371988 PH |
30202 | .next |
30203 | A delivery set up by a router configured with | |
30204 | . ==== As this is a nested list, any displays it contains must be indented | |
30205 | . ==== as otherwise they are too far to the left. | |
30206 | .code | |
168e428f | 30207 | errors_to = <> |
9b371988 | 30208 | .endd |
168e428f | 30209 | failed. The delivery was discarded. |
9b371988 PH |
30210 | .endlist olist |
30211 | .endlist ilist | |
168e428f PH |
30212 | |
30213 | ||
30214 | ||
30215 | ||
30216 | ||
9b371988 PH |
30217 | .section "Reducing or increasing what is logged" "SECTlogselector" |
30218 | .cindex "log" "selectors" | |
30219 | By setting the &%log_selector%& global option, you can disable some of Exim's | |
168e428f | 30220 | default logging, or you can request additional logging. The value of |
9b371988 | 30221 | &%log_selector%& is made up of names preceded by plus or minus characters. For |
168e428f | 30222 | example: |
9b371988 PH |
30223 | .code |
30224 | log_selector = +arguments -retry_defer | |
30225 | .endd | |
168e428f PH |
30226 | The list of optional log items is in the following table, with the default |
30227 | selection marked by asterisks: | |
9b371988 PH |
30228 | .display |
30229 | &`*acl_warn_skipped `& skipped &%warn%& statement in ACL | |
30230 | &` address_rewrite `& address rewriting | |
30231 | &` all_parents `& all parents in => lines | |
30232 | &` arguments `& command line arguments | |
30233 | &`*connection_reject `& connection rejections | |
30234 | &`*delay_delivery `& immediate delivery delayed | |
30235 | &` deliver_time `& time taken to perform delivery | |
30236 | &` delivery_size `& add &`S=`&&'nnn'& to => lines | |
30237 | &`*dnslist_defer `& defers of DNS list (aka RBL) lookups | |
30238 | &`*etrn `& ETRN commands | |
30239 | &`*host_lookup_failed `& as it says | |
30240 | &` ident_timeout `& timeout for ident connection | |
30241 | &` incoming_interface `& incoming interface on <= lines | |
30242 | &` incoming_port `& incoming port on <= lines | |
30243 | &`*lost_incoming_connection `& as it says (includes timeouts) | |
30244 | &` outgoing_port `& add remote port to => lines | |
30245 | &`*queue_run `& start and end queue runs | |
30246 | &` queue_time `& time on queue for one recipient | |
30247 | &` queue_time_overall `& time on queue for whole message | |
30248 | &` received_recipients `& recipients on <= lines | |
30249 | &` received_sender `& sender on <= lines | |
30250 | &`*rejected_header `& header contents on reject log | |
30251 | &`*retry_defer `& &"retry time not reached"& | |
30252 | &` return_path_on_delivery `& put return path on => and *\ lines | |
30253 | &` sender_on_delivery `& add sender to => lines | |
30254 | &`*size_reject `& rejection because too big | |
30255 | &`*skip_delivery `& delivery skipped in a queue run | |
30256 | &` smtp_confirmation `& SMTP confirmation on => lines | |
30257 | &` smtp_connection `& SMTP connections | |
30258 | &` smtp_incomplete_transaction`& incomplete SMTP transactions | |
30259 | &` smtp_protocol_error `& SMTP protocol errors | |
30260 | &` smtp_syntax_error `& SMTP syntax errors | |
30261 | &` subject `& contents of &'Subject:'& on <= lines | |
30262 | &` tls_certificate_verified `& certificate verification status | |
30263 | &`*tls_cipher `& TLS cipher suite on <= and => lines | |
30264 | &` tls_peerdn `& TLS peer DN on <= and => lines | |
30265 | &` unknown_in_list `& DNS lookup failed in list match | |
30266 | ||
30267 | &` all `& all of the above | |
30268 | .endd | |
168e428f PH |
30269 | More details on each of these items follows: |
30270 | ||
9b371988 PH |
30271 | .ilist |
30272 | .cindex "&%warn%& statement" "log when skipping" | |
30273 | .new | |
30274 | &%acl_warn_skipped%&: When an ACL &%warn%& statement is skipped because one of | |
30275 | its conditions cannot be evaluated, a log line to this effect is written if | |
30276 | this log selector is set. | |
30277 | .wen | |
30278 | .next | |
30279 | .cindex "log" "rewriting" | |
30280 | .cindex "rewriting" "logging" | |
30281 | &%address_rewrite%&: This applies both to global rewrites and per-transport | |
d1e83bff PH |
30282 | rewrites, but not to rewrites in filters run as an unprivileged user (because |
30283 | such users cannot access the log). | |
9b371988 PH |
30284 | .next |
30285 | .cindex "log" "full parentage" | |
30286 | &%all_parents%&: Normally only the original and final addresses are logged on | |
168e428f PH |
30287 | delivery lines; with this selector, intermediate parents are given in |
30288 | parentheses between them. | |
9b371988 PH |
30289 | .next |
30290 | .cindex "log" "Exim arguments" | |
30291 | .cindex "Exim arguments" "logging" | |
30292 | &%arguments%&: This causes Exim to write the arguments with which it was called | |
168e428f PH |
30293 | to the main log, preceded by the current working directory. This is a debugging |
30294 | feature, added to make it easier to find out how certain MUAs call | |
9b371988 PH |
30295 | &_/usr/sbin/sendmail_&. The logging does not happen if Exim has given up root |
30296 | privilege because it was called with the &%-C%& or &%-D%& options. Arguments | |
30297 | that are empty or that contain white space are quoted. Non-printing characters | |
30298 | are shown as escape sequences. This facility cannot log unrecognized arguments, | |
168e428f | 30299 | because the arguments are checked before the configuration file is read. The |
9b371988 | 30300 | only way to log such cases is to interpose a script such as &_util/logargs.sh_& |
168e428f | 30301 | between the caller and Exim. |
9b371988 PH |
30302 | .next |
30303 | .cindex "log" "connection rejections" | |
30304 | &%connection_reject%&: A log entry is written whenever an incoming SMTP | |
168e428f | 30305 | connection is rejected, for whatever reason. |
9b371988 PH |
30306 | .next |
30307 | .cindex "log" "delayed delivery" | |
30308 | .cindex "delayed delivery" "logging" | |
30309 | &%delay_delivery%&: A log entry is written whenever a delivery process is not | |
168e428f PH |
30310 | started for an incoming message because the load is too high or too many |
30311 | messages were received on one connection. Logging does not occur if no delivery | |
9b371988 PH |
30312 | process is started because &%queue_only%& is set or &%-odq%& was used. |
30313 | .next | |
30314 | .cindex "log" "delivery duration" | |
30315 | &%deliver_time%&: For each delivery, the amount of real time it has taken to | |
30316 | perform the actual delivery is logged as DT=<&'time'&>, for example, &`DT=1s`&. | |
30317 | .next | |
30318 | .cindex "log" "message size on delivery" | |
30319 | .cindex "size" "of message" | |
30320 | &%delivery_size%&: For each delivery, the size of message delivered is added to | |
30321 | the &"=>"& line, tagged with S=. | |
30322 | .next | |
30323 | .cindex "log" "dnslist defer" | |
30324 | .cindex "DNS list" "logging defer" | |
30325 | .cindex "black list (DNS)" | |
30326 | &%dnslist_defer%&: A log entry is written if an attempt to look up a host in a | |
168e428f | 30327 | DNS black list suffers a temporary error. |
9b371988 PH |
30328 | .next |
30329 | .cindex "log" "ETRN commands" | |
30330 | .cindex "ETRN" "logging" | |
30331 | &%etrn%&: Every legal ETRN command that is received is logged, before the ACL | |
30332 | is run to determine whether or not it is actually accepted. An invalid ETRN | |
168e428f | 30333 | command, or one received within a message transaction is not logged by this |
9b371988 PH |
30334 | selector (see &%smtp_syntax_error%& and &%smtp_protocol_error%&). |
30335 | .next | |
30336 | .cindex "log" "host lookup failure" | |
30337 | &%host_lookup_failed%&: When a lookup of a host's IP addresses fails to find | |
168e428f PH |
30338 | any addresses, or when a lookup of an IP address fails to find a host name, a |
30339 | log line is written. This logging does not apply to direct DNS lookups when | |
9b371988 PH |
30340 | routing email addresses, but it does apply to &"byname"& lookups. |
30341 | .next | |
30342 | .cindex "log" "ident timeout" | |
30343 | .cindex "RFC 1413" "logging timeout" | |
30344 | &%ident_timeout%&: A log line is written whenever an attempt to connect to a | |
168e428f | 30345 | client's ident port times out. |
9b371988 PH |
30346 | .next |
30347 | .cindex "log" "incoming interface" | |
30348 | .cindex "interface" "logging" | |
30349 | &%incoming_interface%&: The interface on which a message was received is added | |
30350 | to the &"<="& line as an IP address in square brackets, tagged by I= and | |
30351 | followed by a colon and the port number. The local interface and port are also | |
30352 | added to other SMTP log lines, for example &"SMTP connection from"&, and to | |
30353 | rejection lines. | |
30354 | .next | |
30355 | .cindex "log" "incoming remote port" | |
30356 | .cindex "port" "logging remote" | |
30357 | .cindex "TCP/IP" "logging incoming remote port" | |
30358 | .cindex "&$sender_fullhost$&" | |
30359 | .cindex "&$sender_rcvhost$&" | |
30360 | &%incoming_port%&: The remote port number from which a message was received is | |
30361 | added to log entries and &'Received:'& header lines, following the IP address | |
30362 | in square brackets, and separated from it by a colon. This is implemented by | |
30363 | changing the value that is put in the &$sender_fullhost$& and | |
30364 | &$sender_rcvhost$& variables. Recording the remote port number has become more | |
168e428f | 30365 | important with the widening use of NAT (see RFC 2505). |
9b371988 PH |
30366 | .next |
30367 | .cindex "log" "dropped connection" | |
30368 | &%lost_incoming_connection%&: A log line is written when an incoming SMTP | |
168e428f | 30369 | connection is unexpectedly dropped. |
9b371988 PH |
30370 | .next |
30371 | .cindex "log" "outgoing remote port" | |
30372 | .cindex "port" "logging outgoint remote" | |
30373 | .cindex "TCP/IP" "logging ougtoing remote port" | |
30374 | &%outgoing_port%&: The remote port number is added to delivery log lines (those | |
168e428f PH |
30375 | containing => tags) following the IP address. This option is not included in |
30376 | the default setting, because for most ordinary configurations, the remote port | |
30377 | number is always 25 (the SMTP port). | |
9b371988 PH |
30378 | .next |
30379 | .cindex "log" "queue run" | |
30380 | .cindex "queue runner" "logging" | |
30381 | &%queue_run%&: The start and end of every queue run are logged. | |
30382 | .next | |
30383 | .cindex "log" "queue time" | |
30384 | &%queue_time%&: The amount of time the message has been in the queue on the | |
30385 | local host is logged as QT=<&'time'&> on delivery (&`=>`&) lines, for example, | |
30386 | &`QT=3m45s`&. The clock starts when Exim starts to receive the message, so it | |
168e428f PH |
30387 | includes reception time as well as the delivery time for the current address. |
30388 | This means that it may be longer than the difference between the arrival and | |
30389 | delivery log line times, because the arrival log line is not written until the | |
30390 | message has been successfully received. | |
9b371988 PH |
30391 | .next |
30392 | &%queue_time_overall%&: The amount of time the message has been in the queue on | |
30393 | the local host is logged as QT=<&'time'&> on &"Completed"& lines, for | |
30394 | example, &`QT=3m45s`&. The clock starts when Exim starts to receive the | |
168e428f | 30395 | message, so it includes reception time as well as the total delivery time. |
9b371988 PH |
30396 | .next |
30397 | .cindex "log" "recipients" | |
30398 | &%received_recipients%&: The recipients of a message are listed in the main log | |
168e428f | 30399 | as soon as the message is received. The list appears at the end of the log line |
9b371988 | 30400 | that is written when a message is received, preceded by the word &"for"&. The |
168e428f PH |
30401 | addresses are listed after they have been qualified, but before any rewriting |
30402 | has taken place. | |
30403 | Recipients that were discarded by an ACL for MAIL or RCPT do not appear | |
30404 | in the list. | |
9b371988 PH |
30405 | .next |
30406 | .cindex "log" "sender reception" | |
30407 | &%received_sender%&: The unrewritten original sender of a message is added to | |
168e428f | 30408 | the end of the log line that records the message's arrival, after the word |
9b371988 PH |
30409 | &"from"& (before the recipients if &%received_recipients%& is also set). |
30410 | .next | |
30411 | .cindex "log" "header lines for rejection" | |
30412 | &%rejected_header%&: If a message's header has been received at the time a | |
168e428f PH |
30413 | rejection is written to the reject log, the complete header is added to the |
30414 | log. Header logging can be turned off individually for messages that are | |
9b371988 PH |
30415 | rejected by the &[local_scan()]& function (see section &<<SECTapiforloc>>&). |
30416 | .next | |
30417 | .cindex "log" "retry defer" | |
30418 | &%retry_defer%&: A log line is written if a delivery is deferred because a | |
30419 | retry time has not yet been reached. However, this &"retry time not reached"& | |
30420 | message is always omitted from individual message logs after the first delivery | |
168e428f | 30421 | attempt. |
9b371988 PH |
30422 | .next |
30423 | .cindex "log" "return path" | |
30424 | &%return_path_on_delivery%&: The return path that is being transmitted with | |
168e428f PH |
30425 | the message is included in delivery and bounce lines, using the tag P=. |
30426 | This is omitted if no delivery actually happens, for example, if routing fails, | |
9b371988 PH |
30427 | or if delivery is to &_/dev/null_& or to &`:blackhole:`&. |
30428 | .next | |
30429 | .cindex "log" "sender on delivery" | |
30430 | &%sender_on_delivery%&: The message's sender address is added to every delivery | |
30431 | and bounce line, tagged by F= (for &"from"&). | |
168e428f PH |
30432 | This is the original sender that was received with the message; it is not |
30433 | necessarily the same as the outgoing return path. | |
9b371988 PH |
30434 | .next |
30435 | .cindex "log" "size rejection" | |
30436 | &%size_reject%&: A log line is written whenever a message is rejected because | |
30437 | it is too big. | |
30438 | .next | |
30439 | .cindex "log" "frozen messages; skipped" | |
30440 | .cindex "frozen messages" "logging skipping" | |
30441 | &%skip_delivery%&: A log line is written whenever a message is skipped during a | |
168e428f PH |
30442 | queue run because it is frozen or because another process is already delivering |
30443 | it. | |
9b371988 PH |
30444 | .cindex "&""spool file is locked""&" |
30445 | The message that is written is &"spool file is locked"&. | |
30446 | .next | |
30447 | .cindex "log" "smtp confirmation" | |
30448 | .cindex "SMTP" "logging confirmation" | |
30449 | &%smtp_confirmation%&: The response to the final &"."& in the SMTP dialogue for | |
30450 | outgoing messages is added to delivery log lines in the form &`C=`&<&'text'&>. | |
30451 | A number of MTAs (including Exim) return an identifying string in this | |
30452 | response. | |
30453 | .next | |
30454 | .cindex "log" "SMTP connections" | |
30455 | .cindex "SMTP" "logging connections" | |
30456 | &%smtp_connection%&: A log line is written whenever an SMTP connection is | |
168e428f | 30457 | established or closed, unless the connection is from a host that matches |
9b371988 PH |
30458 | &%hosts_connection_nolog%&. (In contrast, &%lost_incoming_connection%& applies |
30459 | only when the closure is unexpected.) This applies to connections from local | |
30460 | processes that use &%-bs%& as well as to TCP/IP connections. If a connection is | |
168e428f PH |
30461 | dropped in the middle of a message, a log line is always written, whether or |
30462 | not this selector is set, but otherwise nothing is written at the start and end | |
30463 | of connections unless this selector is enabled. | |
9b371988 | 30464 | |
168e428f PH |
30465 | For TCP/IP connections to an Exim daemon, the current number of connections is |
30466 | included in the log message for each new connection, but note that the count is | |
30467 | reset if the daemon is restarted. | |
30468 | Also, because connections are closed (and the closure is logged) in | |
30469 | subprocesses, the count may not include connections that have been closed but | |
30470 | whose termination the daemon has not yet noticed. Thus, while it is possible to | |
30471 | match up the opening and closing of connections in the log, the value of the | |
30472 | logged counts may not be entirely accurate. | |
9b371988 PH |
30473 | .next |
30474 | .cindex "log" "SMTP transaction; incomplete" | |
30475 | .cindex "SMTP" "logging incomplete transactions" | |
30476 | &%smtp_incomplete_transaction%&: When a mail transaction is aborted by | |
168e428f PH |
30477 | RSET, QUIT, loss of connection, or otherwise, the incident is logged, |
30478 | and the message sender plus any accepted recipients are included in the log | |
30479 | line. This can provide evidence of dictionary attacks. | |
9b371988 PH |
30480 | .next |
30481 | .cindex "log" "SMTP protocol error" | |
30482 | .cindex "SMTP" "logging protocol error" | |
30483 | &%smtp_protocol_error%&: A log line is written for every SMTP protocol error | |
168e428f PH |
30484 | encountered. Exim does not have perfect detection of all protocol errors |
30485 | because of transmission delays and the use of pipelining. If PIPELINING has | |
30486 | been advertised to a client, an Exim server assumes that the client will use | |
9b371988 | 30487 | it, and therefore it does not count &"expected"& errors (for example, RCPT |
168e428f | 30488 | received after rejecting MAIL) as protocol errors. |
9b371988 PH |
30489 | .next |
30490 | .cindex "SMTP" "logging syntax errors" | |
30491 | .cindex "SMTP" "syntax errors; logging" | |
30492 | .cindex "SMTP" "unknown command; logging" | |
30493 | .cindex "log" "unknown SMTP command" | |
30494 | .cindex "log" "SMTP syntax error" | |
30495 | &%smtp_syntax_error%&: A log line is written for every SMTP syntax error | |
168e428f PH |
30496 | encountered. An unrecognized command is treated as a syntax error. For an |
30497 | external connection, the host identity is given; for an internal connection | |
9b371988 PH |
30498 | using &%-bs%& the sender identification (normally the calling user) is given. |
30499 | .next | |
30500 | .cindex "log" "subject" | |
30501 | .cindex "subject" "logging" | |
30502 | &%subject%&: The subject of the message is added to the arrival log line, | |
30503 | preceded by &"T="& (T for &"topic"&, since S is already used for &"size"&). | |
30504 | Any MIME &"words"& in the subject are decoded. The &%print_topbitchars%& option | |
168e428f PH |
30505 | specifies whether characters with values greater than 127 should be logged |
30506 | unchanged, or whether they should be rendered as escape sequences. | |
9b371988 PH |
30507 | .next |
30508 | .cindex "log" "certificate verification" | |
30509 | &%tls_certificate_verified%&: An extra item is added to <= and => log lines | |
30510 | when TLS is in use. The item is &`CV=yes`& if the peer's certificate was | |
30511 | verified, and &`CV=no`& if not. | |
30512 | .next | |
30513 | .cindex "log" "TLS cipher" | |
30514 | .cindex "TLS" "logging cipher" | |
30515 | &%tls_cipher%&: When a message is sent or received over an encrypted | |
30516 | connection, the cipher suite used is added to the log line, preceded by X=. | |
30517 | .next | |
30518 | .cindex "log" "TLS peer DN" | |
30519 | .cindex "TLS" "logging peer DN" | |
30520 | &%tls_peerdn%&: When a message is sent or received over an encrypted | |
30521 | connection, and a certificate is supplied by the remote host, the peer DN is | |
30522 | added to the log line, preceded by DN=. | |
30523 | .next | |
30524 | .new | |
30525 | .cindex "log" "DNS failure in list" | |
30526 | &%unknown_in_list%&: This setting causes a log entry to be written when the | |
068aaea8 | 30527 | result of a list match is failure because a DNS lookup failed. |
9b371988 PH |
30528 | .wen |
30529 | .endlist | |
168e428f PH |
30530 | |
30531 | ||
9b371988 PH |
30532 | .section "Message log" |
30533 | .cindex "message" "log file for" | |
30534 | .cindex "log" "message log; description of" | |
30535 | .cindex "&_msglog_& directory" | |
30536 | .cindex "&%preserve_message_logs%&" | |
168e428f PH |
30537 | In addition to the general log files, Exim writes a log file for each message |
30538 | that it handles. The names of these per-message logs are the message ids, and | |
9b371988 | 30539 | they are kept in the &_msglog_& sub-directory of the spool directory. Each |
168e428f PH |
30540 | message log contains copies of the log lines that apply to the message. This |
30541 | makes it easier to inspect the status of an individual message without having | |
30542 | to search the main log. A message log is deleted when processing of the message | |
9b371988 PH |
30543 | is complete, unless &%preserve_message_logs%& is set, but this should be used |
30544 | only with great care because they can fill up your disk very quickly. | |
168e428f PH |
30545 | |
30546 | On a heavily loaded system, it may be desirable to disable the use of | |
30547 | per-message logs, in order to reduce disk I/O. This can be done by setting the | |
9b371988 | 30548 | &%message_logs%& option false. |
168e428f PH |
30549 | |
30550 | ||
30551 | ||
9b371988 PH |
30552 | . //////////////////////////////////////////////////////////////////////////// |
30553 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 30554 | |
9b371988 PH |
30555 | .chapter "Exim utilities" "CHAPutils" |
30556 | .cindex "utilities" | |
168e428f PH |
30557 | A number of utility scripts and programs are supplied with Exim and are |
30558 | described in this chapter. There is also the Exim Monitor, which is covered in | |
30559 | the next chapter. The utilities described here are: | |
30560 | ||
9b371988 PH |
30561 | .itable none 0 0 4 2* left 8* left 30* left 40* left |
30562 | .row "" &<<SECTfinoutwha>>& &'exiwhat'& &&& | |
30563 | "list what Exim processes are doing" | |
30564 | .row "" &<<SECTgreptheque>>& &'exiqgrep'& "grep the queue" | |
30565 | .row "" &<<SECTsumtheque>>& &'exiqsumm'& "summarize the queue" | |
30566 | .row "" &<<SECTextspeinf>>& &'exigrep'& "search the main log" | |
30567 | .row "" &<<SECTexipick>>& &'exipick'& "select messages on &&& | |
30568 | various criteria" | |
30569 | .row "" &<<SECTcyclogfil>>& &'exicyclog'& "cycle (rotate) log files" | |
30570 | .row "" &<<SECTmailstat>>& &'eximstats'& &&& | |
30571 | "extract statistics from the log" | |
30572 | .row "" &<<SECTcheckaccess>>& &'exim_checkaccess'& &&& | |
30573 | "check address acceptance from given IP" | |
30574 | .row "" &<<SECTdbmbuild>>& &'exim_dbmbuild'& "build a DBM file" | |
30575 | .row "" &<<SECTfinindret>>& &'exinext'& "extract retry information" | |
30576 | .row "" &<<SECThindatmai>>& &'exim_dumpdb'& "dump a hints database" | |
30577 | .row "" &<<SECThindatmai>>& &'exim_tidydb'& "clean up a hints database" | |
30578 | .row "" &<<SECThindatmai>>& &'exim_fixdb'& "patch a hints database" | |
30579 | .row "" &<<SECTmailboxmaint>>& &'exim_lock'& "lock a mailbox file" | |
30580 | .endtable | |
30581 | ||
30582 | .new | |
068aaea8 | 30583 | Another utility that might be of use to sites with many MTAs is Tom Kistner's |
9b371988 PH |
30584 | &'exilog'&. It provides log visualizations across multiple Exim servers. See |
30585 | &url(http://duncanthrax.net/exilog/) for details. | |
30586 | .wen | |
068aaea8 PH |
30587 | |
30588 | ||
30589 | ||
30590 | ||
9b371988 PH |
30591 | .section "Finding out what Exim processes are doing (exiwhat)" "SECTfinoutwha" |
30592 | .cindex "&'exiwhat'&" | |
30593 | .cindex "process" "querying" | |
30594 | .cindex "SIGUSR1" | |
168e428f PH |
30595 | On operating systems that can restart a system call after receiving a signal |
30596 | (most modern OS), an Exim process responds to the SIGUSR1 signal by writing | |
9b371988 PH |
30597 | a line describing what it is doing to the file &_exim-process.info_& in the |
30598 | Exim spool directory. The &'exiwhat'& script sends the signal to all Exim | |
168e428f PH |
30599 | processes it can find, having first emptied the file. It then waits for one |
30600 | second to allow the Exim processes to react before displaying the results. In | |
9b371988 | 30601 | order to run &'exiwhat'& successfully you have to have sufficient privilege to |
168e428f PH |
30602 | send the signal to the Exim processes, so it is normally run as root. |
30603 | ||
9b371988 | 30604 | &*Warning*&: This is not an efficient process. It is intended for occasional |
168e428f PH |
30605 | use by system administrators. It is not sensible, for example, to set up a |
30606 | script that sends SIGUSR1 signals to Exim processes at short intervals. | |
30607 | ||
30608 | ||
9b371988 | 30609 | Unfortunately, the &'ps'& command that &'exiwhat'& uses to find Exim processes |
168e428f PH |
30610 | varies in different operating systems. Not only are different options used, |
30611 | but the format of the output is different. For this reason, there are some | |
9b371988 PH |
30612 | system configuration options that configure exactly how &'exiwhat'& works. If |
30613 | it doesn't seem to be working for you, check the following compile-time | |
30614 | options: | |
30615 | .display | |
30616 | &`EXIWHAT_PS_CMD `& the command for running &'ps'& | |
30617 | &`EXIWHAT_PS_ARG `& the argument for &'ps'& | |
30618 | &`EXIWHAT_EGREP_ARG `& the argument for &'egrep'& to select from &'ps'& output | |
30619 | &`EXIWHAT_KILL_ARG `& the argument for the &'kill'& command | |
30620 | .endd | |
30621 | An example of typical output from &'exiwhat'& is | |
30622 | .code | |
30623 | 164 daemon: -q1h, listening on port 25 | |
30624 | 10483 running queue: waiting for 0tAycK-0002ij-00 (10492) | |
30625 | 10492 delivering 0tAycK-0002ij-00 to mail.ref.example | |
30626 | [10.19.42.42] (editor@ref.example) | |
30627 | 10592 handling incoming call from [192.168.243.242] | |
30628 | 10628 accepting a local non-SMTP message | |
30629 | .endd | |
168e428f PH |
30630 | The first number in the output line is the process number. The third line has |
30631 | been split here, in order to fit it on the page. | |
30632 | ||
30633 | ||
30634 | ||
9b371988 PH |
30635 | .section "Selective queue listing (exiqgrep)" "SECTgreptheque" |
30636 | .cindex "&'exiqgrep'&" | |
30637 | .cindex "queue" "grepping" | |
168e428f | 30638 | This utility is a Perl script contributed by Matt Hubbard. It runs |
9b371988 PH |
30639 | .code |
30640 | exim -bpu | |
30641 | .endd | |
168e428f PH |
30642 | to obtain a queue listing with undelivered recipients only, and then greps the |
30643 | output to select messages that match given criteria. The following selection | |
30644 | options are available: | |
30645 | ||
9b371988 PH |
30646 | .vlist |
30647 | .vitem &*-f*&&~<&'regex'&> | |
168e428f PH |
30648 | Match the sender address. The field that is tested is enclosed in angle |
30649 | brackets, so you can test for bounce messages with | |
9b371988 PH |
30650 | .code |
30651 | exiqgrep -f '^<>$' | |
30652 | .endd | |
30653 | .vitem &*-r*&&~<&'regex'&> | |
168e428f PH |
30654 | Match a recipient address. The field that is tested is not enclosed in angle |
30655 | brackets. | |
30656 | ||
9b371988 | 30657 | .vitem &*-s*&&~<&'regex'&> |
168e428f PH |
30658 | Match against the size field. |
30659 | ||
9b371988 | 30660 | .vitem &*-y*&&~<&'seconds'&> |
168e428f PH |
30661 | Match messages that are younger than the given time. |
30662 | ||
9b371988 | 30663 | .vitem &*-o*&&~<&'seconds'&> |
168e428f PH |
30664 | Match messages that are older than the given time. |
30665 | ||
9b371988 | 30666 | .vitem &*-z*& |
168e428f PH |
30667 | Match only frozen messages. |
30668 | ||
9b371988 | 30669 | .vitem &*-x*& |
168e428f | 30670 | Match only non-frozen messages. |
9b371988 | 30671 | .endlist |
168e428f PH |
30672 | |
30673 | The following options control the format of the output: | |
30674 | ||
9b371988 PH |
30675 | .vlist |
30676 | .vitem &*-c*& | |
168e428f PH |
30677 | Display only the count of matching messages. |
30678 | ||
9b371988 PH |
30679 | .vitem &*-l*& |
30680 | Long format &-- display the full message information as output by Exim. This is | |
168e428f PH |
30681 | the default. |
30682 | ||
9b371988 | 30683 | .vitem &*-i*& |
168e428f PH |
30684 | Display message ids only. |
30685 | ||
9b371988 PH |
30686 | .vitem &*-b*& |
30687 | Brief format &-- one line per message. | |
168e428f | 30688 | |
9b371988 | 30689 | .vitem &*-R*& |
168e428f | 30690 | Display messages in reverse order. |
9b371988 | 30691 | .endlist |
168e428f | 30692 | |
9b371988 | 30693 | There is one more option, &%-h%&, which outputs a list of options. |
168e428f | 30694 | |
168e428f PH |
30695 | |
30696 | ||
9b371988 PH |
30697 | .section "Summarising the queue (exiqsumm)" "SECTsumtheque" |
30698 | .cindex "&'exiqsumm'&" | |
30699 | .cindex "queue" "summary" | |
30700 | The &'exiqsumm'& utility is a Perl script which reads the output of &`exim | |
30701 | -bp`& and produces a summary of the messages on the queue. Thus, you use it by | |
168e428f | 30702 | running a command such as |
9b371988 PH |
30703 | .code |
30704 | exim -bp | exiqsumm | |
30705 | .endd | |
168e428f PH |
30706 | The output consists of one line for each domain that has messages waiting for |
30707 | it, as in the following example: | |
9b371988 PH |
30708 | .code |
30709 | 3 2322 74m 66m msn.com.example | |
30710 | .endd | |
168e428f PH |
30711 | Each line lists the number of |
30712 | pending deliveries for a domain, their total volume, and the length of time | |
30713 | that the oldest and the newest messages have been waiting. Note that the number | |
30714 | of pending deliveries is greater than the number of messages when messages | |
30715 | have more than one recipient. | |
30716 | ||
30717 | A summary line is output at the end. By default the output is sorted on the | |
9b371988 PH |
30718 | domain name, but &'exiqsumm'& has the options &%-a%& and &%-c%&, which cause |
30719 | the output to be sorted by oldest message and by count of messages, | |
30720 | respectively. | |
168e428f | 30721 | |
9b371988 PH |
30722 | The output of &'exim -bp'& contains the original addresses in the message, so |
30723 | this also applies to the output from &'exiqsumm'&. No domains from addresses | |
30724 | generated by aliasing or forwarding are included (unless the &%one_time%& | |
30725 | option of the &(redirect)& router has been used to convert them into &"top | |
30726 | level"& addresses). | |
168e428f PH |
30727 | |
30728 | ||
30729 | ||
30730 | ||
9b371988 PH |
30731 | .section "Extracting specific information from the log (exigrep)" &&& |
30732 | "SECTextspeinf" | |
30733 | .cindex "&'exigrep'&" | |
30734 | .cindex "log" "extracts; grepping for" | |
30735 | .new | |
30736 | The &'exigrep'& utility is a Perl script that searches one or more main log | |
168e428f PH |
30737 | files for entries that match a given pattern. When it finds a match, it |
30738 | extracts all the log entries for the relevant message, not just those that | |
9b371988 | 30739 | match the pattern. Thus, &'exigrep'& can extract complete log entries for a |
168e428f | 30740 | given message, or all mail for a given user, or for a given host, for example. |
068aaea8 | 30741 | The input files can be in Exim log format or syslog format. |
9b371988 | 30742 | .wen |
168e428f PH |
30743 | |
30744 | If a matching log line is not associated with a specific message, it is always | |
9b371988 PH |
30745 | included in &'exigrep'&'s output. The usage is: |
30746 | .display | |
30747 | &`exigrep [-l] [-t<`&&'n'&&`>] <`&&'pattern'&&`> [<`&&'log file'&&`>] ...`& | |
30748 | .endd | |
30749 | The &%-t%& argument specifies a number of seconds. It adds an additional | |
168e428f | 30750 | condition for message selection. Messages that are complete are shown only if |
9b371988 | 30751 | they spent more than <&'n'&> seconds on the queue. |
168e428f | 30752 | |
9b371988 | 30753 | The &%-l%& flag means &"literal"&, that is, treat all characters in the |
168e428f PH |
30754 | pattern as standing for themselves. Otherwise the pattern must be a Perl |
30755 | regular expression. The pattern match is case-insensitive. If no file names are | |
30756 | given on the command line, the standard input is read. | |
30757 | ||
9b371988 PH |
30758 | If the location of a &'zcat'& command is known from the definition of |
30759 | ZCAT_COMMAND in &_Local/Makefile_&, &'exigrep'& automatically passes any file | |
30760 | whose name ends in COMPRESS_SUFFIX through &'zcat'& as it searches it. | |
168e428f PH |
30761 | |
30762 | ||
9b371988 PH |
30763 | .section "Selecting messages by various criteria (exipick)" "SECTexipick" |
30764 | .cindex "&'exipick'&" | |
30765 | John Jetmore's &'exipick'& utility is included in the Exim distribution. It | |
168e428f PH |
30766 | lists messages from the queue according to a variety of criteria. For details, |
30767 | run: | |
9b371988 PH |
30768 | .code |
30769 | exipick --help | |
30770 | .endd | |
168e428f PH |
30771 | |
30772 | ||
9b371988 PH |
30773 | .section "Cycling log files (exicyclog)" "SECTcyclogfil" |
30774 | .cindex "log" "cycling local files" | |
30775 | .cindex "cycling logs" | |
30776 | .cindex "&'exicyclog'&" | |
30777 | The &'exicyclog'& script can be used to cycle (rotate) &'mainlog'& and | |
30778 | &'rejectlog'& files. This is not necessary if only syslog is being used, or if | |
168e428f | 30779 | you are using log files with datestamps in their names (see section |
9b371988 PH |
30780 | &<<SECTdatlogfil>>&). Some operating systems have their own standard mechanisms |
30781 | for log cycling, and these can be used instead of &'exicyclog'& if preferred. | |
168e428f | 30782 | |
9b371988 PH |
30783 | Each time &'exicyclog'& is run the file names get &"shuffled down"& by one. If |
30784 | the main log file name is &_mainlog_& (the default) then when &'exicyclog'& is | |
30785 | run &_mainlog_& becomes &_mainlog.01_&, the previous &_mainlog.01_& becomes | |
30786 | &_mainlog.02_& and so on, up to a limit which is set in the script, and which | |
168e428f PH |
30787 | defaults to 10. Log files whose numbers exceed the limit are discarded. Reject |
30788 | logs are handled similarly. | |
30789 | ||
30790 | If the limit is greater than 99, the script uses 3-digit numbers such as | |
9b371988 PH |
30791 | &_mainlog.001_&, &_mainlog.002_&, etc. If you change from a number less than 99 |
30792 | to one that is greater, or &'vice versa'&, you will have to fix the names of | |
168e428f PH |
30793 | any existing log files. |
30794 | ||
30795 | ||
9b371988 | 30796 | If no &_mainlog_& file exists, the script does nothing. Files that &"drop off"& |
168e428f PH |
30797 | the end are deleted. All files with numbers greater than 01 are compressed, |
30798 | using a compression command which is configured by the COMPRESS_COMMAND | |
9b371988 PH |
30799 | setting in &_Local/Makefile_&. It is usual to run &'exicyclog'& daily from a |
30800 | root &%crontab%& entry of the form | |
30801 | .code | |
30802 | 1 0 * * * su exim -c /usr/exim/bin/exicyclog | |
30803 | .endd | |
30804 | assuming you have used the name &"exim"& for the Exim user. You can run | |
30805 | &'exicyclog'& as root if you wish, but there is no need. | |
168e428f PH |
30806 | |
30807 | ||
30808 | ||
9b371988 PH |
30809 | .section "Mail statistics (eximstats)" "SECTmailstat" |
30810 | .cindex "statistics" | |
30811 | .cindex "&'eximstats'&" | |
30812 | A Perl script called &'eximstats'& is provided for extracting statistical | |
168e428f | 30813 | information from log files. The output is either plain text, or HTML. |
9b371988 PH |
30814 | Exim log files are also suported by the &'Lire'& system produced by the |
30815 | LogReport Foundation &url(http://www.logreport.org). | |
168e428f | 30816 | |
9b371988 | 30817 | The &'eximstats'& script has been hacked about quite a bit over time. The |
168e428f PH |
30818 | latest version is the result of some extensive revision by Steve Campbell. A |
30819 | lot of information is given by default, but there are options for suppressing | |
30820 | various parts of it. Following any options, the arguments to the script are a | |
30821 | list of files, which should be main log files. For example: | |
9b371988 PH |
30822 | .code |
30823 | eximstats -nr /var/spool/exim/log/mainlog.01 | |
30824 | .endd | |
30825 | By default, &'eximstats'& extracts information about the number and volume of | |
168e428f PH |
30826 | messages received from or delivered to various hosts. The information is sorted |
30827 | both by message count and by volume, and the top fifty hosts in each category | |
30828 | are listed on the standard output. Similar information, based on email | |
30829 | addresses or domains instead of hosts can be requested by means of various | |
30830 | options. For messages delivered and received locally, similar statistics are | |
30831 | also produced per user. | |
30832 | ||
30833 | The output also includes total counts and statistics about delivery errors, and | |
30834 | histograms showing the number of messages received and deliveries made in each | |
30835 | hour of the day. A delivery with more than one address in its envelope (for | |
30836 | example, an SMTP transaction with more than one RCPT command) is counted | |
9b371988 | 30837 | as a single delivery by &'eximstats'&. |
168e428f PH |
30838 | |
30839 | Though normally more deliveries than receipts are reported (as messages may | |
9b371988 | 30840 | have multiple recipients), it is possible for &'eximstats'& to report more |
168e428f PH |
30841 | messages received than delivered, even though the queue is empty at the start |
30842 | and end of the period in question. If an incoming message contains no valid | |
30843 | recipients, no deliveries are recorded for it. A bounce message is handled as | |
30844 | an entirely separate message. | |
30845 | ||
9b371988 | 30846 | &'eximstats'& always outputs a grand total summary giving the volume and number |
168e428f PH |
30847 | of messages received and deliveries made, and the number of hosts involved in |
30848 | each case. It also outputs the number of messages that were delayed (that is, | |
30849 | not completely delivered at the first attempt), and the number that had at | |
30850 | least one address that failed. | |
30851 | ||
30852 | The remainder of the output is in sections that can be independently disabled | |
30853 | or modified by various options. It consists of a summary of deliveries by | |
30854 | transport, histograms of messages received and delivered per time interval | |
30855 | (default per hour), information about the time messages spent on the queue, | |
30856 | a list of relayed messages, lists of the top fifty sending hosts, local | |
30857 | senders, destination hosts, and destination local users by count and by volume, | |
30858 | and a list of delivery errors that occurred. | |
30859 | ||
30860 | The relay information lists messages that were actually relayed, that is, they | |
30861 | came from a remote host and were directly delivered to some other remote host, | |
30862 | without being processed (for example, for aliasing or forwarding) locally. | |
30863 | ||
9b371988 | 30864 | There are quite a few options for &'eximstats'& to control exactly what it |
168e428f | 30865 | outputs. These are documented in the Perl script itself, and can be extracted |
9b371988 PH |
30866 | by running the command &(perldoc)& on the script. For example: |
30867 | .code | |
30868 | perldoc /usr/exim/bin/eximstats | |
30869 | .endd | |
30870 | ||
30871 | .section "Checking access policy (exim_checkaccess)" "SECTcheckaccess" | |
30872 | .cindex "&'exim_checkaccess'&" | |
30873 | .cindex "policy control" "checking access" | |
30874 | .cindex "checking access" | |
30875 | The &%-bh%& command line argument allows you to run a fake SMTP session with | |
168e428f PH |
30876 | debugging output, in order to check what Exim is doing when it is applying |
30877 | policy controls to incoming SMTP mail. However, not everybody is sufficiently | |
9b371988 PH |
30878 | familiar with the SMTP protocol to be able to make full use of &%-bh%&, and |
30879 | sometimes you just want to answer the question &"Does this address have | |
30880 | access?"& without bothering with any further details. | |
168e428f | 30881 | |
9b371988 | 30882 | The &'exim_checkaccess'& utility is a &"packaged"& version of &%-bh%&. It takes |
168e428f | 30883 | two arguments, an IP address and an email address: |
9b371988 PH |
30884 | .code |
30885 | exim_checkaccess 10.9.8.7 A.User@a.domain.example | |
30886 | .endd | |
30887 | The utility runs a call to Exim with the &%-bh%& option, to test whether the | |
168e428f PH |
30888 | given email address would be accepted in a RCPT command in a TCP/IP |
30889 | connection from the host with the given IP address. The output of the utility | |
9b371988 PH |
30890 | is either the word &"accepted"&, or the SMTP error response, for example: |
30891 | .code | |
30892 | Rejected: | |
30893 | 550 Relay not permitted | |
30894 | .endd | |
30895 | When running this test, the utility uses &`<>`& as the envelope sender address | |
168e428f PH |
30896 | for the MAIL command, but you can change this by providing additional |
30897 | options. These are passed directly to the Exim command. For example, to specify | |
9b371988 | 30898 | that the test is to be run with the sender address &'himself@there.example'& |
168e428f | 30899 | you can use: |
9b371988 | 30900 | .code |
168e428f PH |
30901 | exim_checkaccess 10.9.8.7 A.User@a.domain.example \ |
30902 | -f himself@there.example | |
9b371988 | 30903 | .endd |
168e428f PH |
30904 | Note that these additional Exim command line items must be given after the two |
30905 | mandatory arguments. | |
30906 | ||
9b371988 PH |
30907 | Because the &%exim_checkaccess%& uses &%-bh%&, it does not perform callouts |
30908 | while running its checks. You can run checks that include callouts by using | |
30909 | &%-bhc%&, but this is not yet available in a &"packaged"& form. | |
168e428f PH |
30910 | |
30911 | ||
30912 | ||
9b371988 PH |
30913 | .section "Making DBM files (exim_dbmbuild)" "SECTdbmbuild" |
30914 | .cindex "DBM" "building dbm files" | |
30915 | .cindex "building DBM files" | |
30916 | .cindex "&'exim_dbmbuild'&" | |
30917 | .cindex "lower casing" | |
30918 | .cindex "binary zero" "in lookup key" | |
30919 | The &'exim_dbmbuild'& program reads an input file containing keys and data in | |
30920 | the format used by the &(lsearch)& lookup (see section | |
30921 | &<<SECTsinglekeylookups>>&). It writes a DBM file using the lower-cased alias | |
30922 | names as keys and the remainder of the information as data. The lower-casing | |
30923 | can be prevented by calling the program with the &%-nolc%& option. | |
168e428f PH |
30924 | |
30925 | A terminating zero is included as part of the key string. This is expected by | |
9b371988 PH |
30926 | the &(dbm)& lookup type. However, if the option &%-nozero%& is given, |
30927 | &'exim_dbmbuild'& creates files without terminating zeroes in either the key | |
30928 | strings or the data strings. The &(dbmnz)& lookup type can be used with such | |
168e428f PH |
30929 | files. |
30930 | ||
30931 | The program requires two arguments: the name of the input file (which can be a | |
30932 | single hyphen to indicate the standard input), and the name of the output file. | |
30933 | It creates the output under a temporary name, and then renames it if all went | |
30934 | well. | |
30935 | ||
9b371988 | 30936 | .cindex "USE_DB" |
168e428f | 30937 | If the native DB interface is in use (USE_DB is set in a compile-time |
9b371988 | 30938 | configuration file &-- this is common in free versions of Unix) the two file |
168e428f PH |
30939 | names must be different, because in this mode the Berkeley DB functions create |
30940 | a single output file using exactly the name given. For example, | |
9b371988 PH |
30941 | .code |
30942 | exim_dbmbuild /etc/aliases /etc/aliases.db | |
30943 | .endd | |
168e428f | 30944 | reads the system alias file and creates a DBM version of it in |
9b371988 | 30945 | &_/etc/aliases.db_&. |
168e428f | 30946 | |
9b371988 PH |
30947 | In systems that use the &'ndbm'& routines (mostly proprietary versions of |
30948 | Unix), two files are used, with the suffixes &_.dir_& and &_.pag_&. In this | |
168e428f | 30949 | environment, the suffixes are added to the second argument of |
9b371988 | 30950 | &'exim_dbmbuild'&, so it can be the same as the first. This is also the case |
168e428f | 30951 | when the Berkeley functions are used in compatibility mode (though this is not |
9b371988 | 30952 | recommended), because in that case it adds a &_.db_& suffix to the file name. |
168e428f PH |
30953 | |
30954 | If a duplicate key is encountered, the program outputs a warning, and when it | |
9b371988 PH |
30955 | finishes, its return code is 1 rather than zero, unless the &%-noduperr%& |
30956 | option is used. By default, only the first of a set of duplicates is used &-- | |
30957 | this makes it compatible with &(lsearch)& lookups. There is an option | |
30958 | &%-lastdup%& which causes it to use the data for the last duplicate instead. | |
30959 | There is also an option &%-nowarn%&, which stops it listing duplicate keys to | |
30960 | &%stderr%&. For other errors, where it doesn't actually make a new file, the | |
30961 | return code is 2. | |
168e428f PH |
30962 | |
30963 | ||
30964 | ||
30965 | ||
9b371988 PH |
30966 | .section "Finding individual retry times (exinext)" "SECTfinindret" |
30967 | .cindex "retry" "times" | |
30968 | .cindex "&'exinext'&" | |
30969 | A utility called &'exinext'& (mostly a Perl script) provides the ability to | |
30970 | fish specific information out of the retry database. Given a mail domain (or a | |
168e428f PH |
30971 | complete address), it looks up the hosts for that domain, and outputs any retry |
30972 | information for the hosts or for the domain. At present, the retry information | |
9b371988 | 30973 | is obtained by running &'exim_dumpdb'& (see below) and post-processing the |
168e428f | 30974 | output. For example: |
9b371988 PH |
30975 | .code |
30976 | $ exinext piglet@milne.fict.example | |
30977 | kanga.milne.example:192.168.8.1 error 146: Connection refused | |
30978 | first failed: 21-Feb-1996 14:57:34 | |
30979 | last tried: 21-Feb-1996 14:57:34 | |
30980 | next try at: 21-Feb-1996 15:02:34 | |
30981 | roo.milne.example:192.168.8.3 error 146: Connection refused | |
30982 | first failed: 20-Jan-1996 13:12:08 | |
30983 | last tried: 21-Feb-1996 11:42:03 | |
30984 | next try at: 21-Feb-1996 19:42:03 | |
30985 | past final cutoff time | |
30986 | .endd | |
30987 | You can also give &'exinext'& a local part, without a domain, and it | |
168e428f PH |
30988 | will give any retry information for that local part in your default domain. |
30989 | A message id can be used to obtain retry information pertaining to a specific | |
30990 | message. This exists only when an attempt to deliver a message to a remote host | |
9b371988 PH |
30991 | suffers a message-specific error (see section &<<SECToutSMTPerr>>&). |
30992 | &'exinext'& is not particularly efficient, but then it is not expected to be | |
30993 | run very often. | |
168e428f | 30994 | |
9b371988 PH |
30995 | The &'exinext'& utility calls Exim to find out information such as the location |
30996 | of the spool directory. The utility has &%-C%& and &%-D%& options, which are | |
30997 | passed on to the &'exim'& commands. The first specifies an alternate Exim | |
168e428f PH |
30998 | configuration file, and the second sets macros for use within the configuration |
30999 | file. These features are mainly to help in testing, but might also be useful in | |
31000 | environments where more than one configuration file is in use. | |
31001 | ||
31002 | ||
31003 | ||
9b371988 PH |
31004 | .section "Hints database maintenance" "SECThindatmai" |
31005 | .cindex "hints database" "maintenance" | |
31006 | .cindex "maintaining Exim's hints database" | |
168e428f PH |
31007 | Three utility programs are provided for maintaining the DBM files that Exim |
31008 | uses to contain its delivery hint information. Each program requires two | |
31009 | arguments. The first specifies the name of Exim's spool directory, and the | |
068aaea8 | 31010 | second is the name of the database it is to operate on. These are as follows: |
168e428f | 31011 | |
9b371988 PH |
31012 | .ilist |
31013 | &'retry'&: the database of retry information | |
31014 | .next | |
31015 | &'wait-'&<&'transport name'&>: databases of information about messages waiting | |
168e428f | 31016 | for remote hosts |
9b371988 PH |
31017 | .next |
31018 | &'callout'&: the callout cache | |
31019 | .new | |
31020 | .next | |
31021 | &'ratelimit'&: the data for implementing the ratelimit ACL condition | |
31022 | .wen | |
31023 | .next | |
31024 | &'misc'&: other hints data | |
31025 | .endlist | |
168e428f | 31026 | |
9b371988 | 31027 | The &'misc'& database is used for |
168e428f | 31028 | |
9b371988 PH |
31029 | .ilist |
31030 | Serializing ETRN runs (when &%smtp_etrn_serialize%& is set) | |
31031 | .next | |
31032 | Serializing delivery to a specific host (when &%serialize_hosts%& is set in an | |
31033 | &(smtp)& transport) | |
31034 | .endlist | |
168e428f | 31035 | |
168e428f PH |
31036 | |
31037 | ||
9b371988 PH |
31038 | .section "exim_dumpdb" |
31039 | .cindex "&'exim_dumpdb'&" | |
168e428f | 31040 | The entire contents of a database are written to the standard output by the |
9b371988 | 31041 | &'exim_dumpdb'& program, which has no options or arguments other than the |
168e428f | 31042 | spool and database names. For example, to dump the retry database: |
9b371988 PH |
31043 | .code |
31044 | exim_dumpdb /var/spool/exim retry | |
31045 | .endd | |
168e428f | 31046 | Two lines of output are produced for each entry: |
9b371988 PH |
31047 | .code |
31048 | T:mail.ref.example:192.168.242.242 146 77 Connection refused | |
31049 | 31-Oct-1995 12:00:12 02-Nov-1995 12:21:39 02-Nov-1995 20:21:39 * | |
31050 | .endd | |
168e428f PH |
31051 | The first item on the first line is the key of the record. It starts with one |
31052 | of the letters R, or T, depending on whether it refers to a routing or | |
31053 | transport retry. For a local delivery, the next part is the local address; for | |
31054 | a remote delivery it is the name of the remote host, followed by its failing IP | |
9b371988 | 31055 | address (unless &%no_retry_include_ip_address%& is set on the &(smtp)& |
168e428f PH |
31056 | transport). If the remote port is not the standard one (port 25), it is added |
31057 | to the IP address. Then there follows an error code, an additional error code, | |
31058 | and a textual description of the error. | |
31059 | ||
31060 | The three times on the second line are the time of first failure, the time of | |
31061 | the last delivery attempt, and the computed time for the next attempt. The line | |
31062 | ends with an asterisk if the cutoff time for the last retry rule has been | |
31063 | exceeded. | |
31064 | ||
9b371988 | 31065 | Each output line from &'exim_dumpdb'& for the &'wait-xxx'& databases |
168e428f PH |
31066 | consists of a host name followed by a list of ids for messages that are or were |
31067 | waiting to be delivered to that host. If there are a very large number for any | |
31068 | one host, continuation records, with a sequence number added to the host name, | |
31069 | may be seen. The data in these records is often out of date, because a message | |
31070 | may be routed to several alternative hosts, and Exim makes no effort to keep | |
31071 | cross-references. | |
31072 | ||
31073 | ||
31074 | ||
9b371988 PH |
31075 | .section "exim_tidydb" |
31076 | .cindex "&'exim_tidydb'&" | |
31077 | .new | |
31078 | The &'exim_tidydb'& utility program is used to tidy up the contents of a hints | |
068aaea8 PH |
31079 | database. If run with no options, it removes all records that are more than 30 |
31080 | days old. The age is calculated from the date and time that the record was last | |
9b371988 | 31081 | updated. Note that, in the case of the retry database, it is &'not'& the time |
068aaea8 PH |
31082 | since the first delivery failure. Information about a host that has been down |
31083 | for more than 30 days will remain in the database, provided that the record is | |
31084 | updated sufficiently often. | |
9b371988 | 31085 | .wen |
068aaea8 | 31086 | |
9b371988 | 31087 | The cutoff date can be altered by means of the &%-t%& option, which must be |
068aaea8 PH |
31088 | followed by a time. For example, to remove all records older than a week from |
31089 | the retry database: | |
9b371988 PH |
31090 | .code |
31091 | exim_tidydb -t 7d /var/spool/exim retry | |
31092 | .endd | |
31093 | Both the &'wait-xxx'& and &'retry'& databases contain items that involve | |
31094 | message ids. In the former these appear as data in records keyed by host &-- | |
31095 | they were messages that were waiting for that host &-- and in the latter they | |
168e428f | 31096 | are the keys for retry information for messages that have suffered certain |
9b371988 | 31097 | types of error. When &'exim_tidydb'& is run, a check is made to ensure that |
168e428f PH |
31098 | message ids in database records are those of messages that are still on the |
31099 | queue. Message ids for messages that no longer exist are removed from | |
9b371988 PH |
31100 | &'wait-xxx'& records, and if this leaves any records empty, they are deleted. |
31101 | For the &'retry'& database, records whose keys are non-existent message ids are | |
31102 | removed. The &'exim_tidydb'& utility outputs comments on the standard output | |
31103 | whenever it removes information from the database. | |
168e428f PH |
31104 | |
31105 | Certain records are automatically removed by Exim when they are no longer | |
31106 | needed, but others are not. For example, if all the MX hosts for a domain are | |
31107 | down, a retry record is created for each one. If the primary MX host comes back | |
31108 | first, its record is removed when Exim successfully delivers to it, but the | |
31109 | records for the others remain because Exim has not tried to use those hosts. | |
31110 | ||
9b371988 | 31111 | It is important, therefore, to run &'exim_tidydb'& periodically on all the |
168e428f PH |
31112 | hints databases. You should do this at a quiet time of day, because it requires |
31113 | a database to be locked (and therefore inaccessible to Exim) while it does its | |
31114 | work. Removing records from a DBM file does not normally make the file smaller, | |
31115 | but all the common DBM libraries are able to re-use the space that is released. | |
31116 | After an initial phase of increasing in size, the databases normally reach a | |
31117 | point at which they no longer get any bigger, as long as they are regularly | |
31118 | tidied. | |
31119 | ||
9b371988 | 31120 | &*Warning*&: If you never run &'exim_tidydb'&, the space used by the hints |
168e428f PH |
31121 | databases is likely to keep on increasing. |
31122 | ||
31123 | ||
31124 | ||
31125 | ||
9b371988 PH |
31126 | .section "exim_fixdb" |
31127 | .cindex "&'exim_fixdb'&" | |
31128 | The &'exim_fixdb'& program is a utility for interactively modifying databases. | |
168e428f PH |
31129 | Its main use is for testing Exim, but it might also be occasionally useful for |
31130 | getting round problems in a live system. It has no options, and its interface | |
31131 | is somewhat crude. On entry, it prompts for input with a right angle-bracket. A | |
31132 | key of a database record can then be entered, and the data for that record is | |
31133 | displayed. | |
31134 | ||
9b371988 PH |
31135 | If &"d"& is typed at the next prompt, the entire record is deleted. For all |
31136 | except the &'retry'& database, that is the only operation that can be carried | |
31137 | out. For the &'retry'& database, each field is output preceded by a number, and | |
168e428f PH |
31138 | data for individual fields can be changed by typing the field number followed |
31139 | by new data, for example: | |
9b371988 PH |
31140 | .code |
31141 | > 4 951102:1000 | |
31142 | .endd | |
168e428f PH |
31143 | resets the time of the next delivery attempt. Time values are given as a |
31144 | sequence of digit pairs for year, month, day, hour, and minute. Colons can be | |
31145 | used as optional separators. | |
31146 | ||
31147 | ||
31148 | ||
31149 | ||
9b371988 PH |
31150 | .section "Mailbox maintenance (exim_lock)" "SECTmailboxmaint" |
31151 | .cindex "mailbox" "maintenance" | |
31152 | .cindex "&'exim_lock'&" | |
31153 | .cindex "locking mailboxes" | |
31154 | The &'exim_lock'& utility locks a mailbox file using the same algorithm as | |
31155 | Exim. For a discussion of locking issues, see section &<<SECTopappend>>&. | |
31156 | &'Exim_lock'& can be used to prevent any modification of a mailbox by Exim or | |
168e428f PH |
31157 | a user agent while investigating a problem. The utility requires the name of |
31158 | the file as its first argument. If the locking is successful, the second | |
9b371988 | 31159 | argument is run as a command (using C's &[system()]& function); if there is no |
168e428f | 31160 | second argument, the value of the SHELL environment variable is used; if this |
9b371988 | 31161 | is unset or empty, &_/bin/sh_& is run. When the command finishes, the mailbox |
168e428f PH |
31162 | is unlocked and the utility ends. The following options are available: |
31163 | ||
9b371988 PH |
31164 | .vlist |
31165 | .vitem &%-fcntl%& | |
31166 | Use &[fcntl()]& locking on the open mailbox. | |
31167 | ||
31168 | .vitem &%-flock%& | |
31169 | Use &[flock()]& locking on the open mailbox, provided the operating system | |
31170 | supports it. | |
31171 | ||
31172 | .vitem &%-interval%& | |
31173 | This must be followed by a number, which is a number of seconds; it sets the | |
31174 | interval to sleep between retries (default 3). | |
31175 | ||
31176 | .vitem &%-lockfile%& | |
31177 | Create a lock file before opening the mailbox. | |
31178 | ||
31179 | .vitem &%-mbx%& | |
31180 | Lock the mailbox using MBX rules. | |
31181 | ||
31182 | .vitem &%-q%& | |
31183 | Suppress verification output. | |
31184 | ||
31185 | .vitem &%-retries%& | |
31186 | This must be followed by a number; it sets the number of times to try to get | |
31187 | the lock (default 10). | |
31188 | ||
31189 | .vitem &%-restore_time%& | |
31190 | This option causes &%exim_lock%& to restore the modified and read times to the | |
31191 | locked file before exiting. This allows you to access a locked mailbox (for | |
31192 | example, to take a backup copy) without disturbing the times that the user | |
31193 | subsequently sees. | |
31194 | ||
31195 | .vitem &%-timeout%& | |
31196 | This must be followed by a number, which is a number of seconds; it sets a | |
31197 | timeout to be used with a blocking &[fcntl()]& lock. If it is not set (the | |
31198 | default), a non-blocking call is used. | |
31199 | ||
31200 | .vitem &%-v%& | |
31201 | Generate verbose output. | |
31202 | .endlist | |
31203 | ||
31204 | If none of &%-fcntl%&, &%-flock%&, &%-lockfile%& or &%-mbx%& are given, the | |
31205 | default is to create a lock file and also to use &[fcntl()]& locking on the | |
31206 | mailbox, which is the same as Exim's default. The use of &%-flock%& or | |
31207 | &%-fcntl%& requires that the file be writeable; the use of &%-lockfile%& | |
31208 | requires that the directory containing the file be writeable. Locking by lock | |
31209 | file does not last for ever; Exim assumes that a lock file is expired if it is | |
31210 | more than 30 minutes old. | |
31211 | ||
31212 | The &%-mbx%& option can be used with either or both of &%-fcntl%& or | |
31213 | &%-flock%&. It assumes &%-fcntl%& by default. MBX locking causes a shared lock | |
31214 | to be taken out on the open mailbox, and an exclusive lock on the file | |
31215 | &_/tmp/.n.m_& where &'n'& and &'m'& are the device number and inode | |
31216 | number of the mailbox file. When the locking is released, if an exclusive lock | |
31217 | can be obtained for the mailbox, the file in &_/tmp_& is deleted. | |
168e428f PH |
31218 | |
31219 | The default output contains verification of the locking that takes place. The | |
9b371988 | 31220 | &%-v%& option causes some additional information to be given. The &%-q%& option |
168e428f PH |
31221 | suppresses all output except error messages. |
31222 | ||
31223 | A command such as | |
9b371988 PH |
31224 | .code |
31225 | exim_lock /var/spool/mail/spqr | |
31226 | .endd | |
168e428f | 31227 | runs an interactive shell while the file is locked, whereas |
9b371988 PH |
31228 | .display |
31229 | &`exim_lock -q /var/spool/mail/spqr <<End`& | |
31230 | <&'some commands'&> | |
31231 | &`End`& | |
31232 | .endd | |
168e428f PH |
31233 | runs a specific non-interactive sequence of commands while the file is locked, |
31234 | suppressing all verification output. A single command can be run by a command | |
31235 | such as | |
9b371988 | 31236 | .code |
168e428f PH |
31237 | exim_lock -q /var/spool/mail/spqr \ |
31238 | "cp /var/spool/mail/spqr /some/where" | |
9b371988 | 31239 | .endd |
168e428f | 31240 | Note that if a command is supplied, it must be entirely contained within the |
9b371988 | 31241 | second argument &-- hence the quotes. |
168e428f PH |
31242 | |
31243 | ||
31244 | ||
9b371988 PH |
31245 | . //////////////////////////////////////////////////////////////////////////// |
31246 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 31247 | |
9b371988 PH |
31248 | .chapter "The Exim monitor" "CHAPeximon" |
31249 | .cindex "Exim monitor" "description" | |
31250 | .cindex "X-windows" | |
31251 | .cindex "&'eximon'&" | |
31252 | .cindex "Local/eximon.conf" | |
31253 | .cindex "_exim_monitor/EDITME_" | |
168e428f PH |
31254 | The Exim monitor is an application which displays in an X window information |
31255 | about the state of Exim's queue and what Exim is doing. An admin user can | |
31256 | perform certain operations on messages from this GUI interface; however all | |
31257 | such facilities are also available from the command line, and indeed, the | |
31258 | monitor itself makes use of the command line to perform any actions requested. | |
31259 | ||
31260 | ||
31261 | ||
9b371988 PH |
31262 | .section "Running the monitor" |
31263 | The monitor is started by running the script called &'eximon'&. This is a shell | |
168e428f | 31264 | script that sets up a number of environment variables, and then runs the |
9b371988 PH |
31265 | binary called &_eximon.bin_&. The default appearance of the monitor window can |
31266 | be changed by editing the &_Local/eximon.conf_& file created by editing | |
31267 | &_exim_monitor/EDITME_&. Comments in that file describe what the various | |
168e428f PH |
31268 | parameters are for. |
31269 | ||
9b371988 PH |
31270 | The parameters that get built into the &'eximon'& script can be overridden for |
31271 | a particular invocation by setting up environment variables of the same names, | |
31272 | preceded by &`EXIMON_`&. For example, a shell command such as | |
31273 | .code | |
31274 | EXIMON_LOG_DEPTH=400 eximon | |
31275 | .endd | |
31276 | (in a Bourne-compatible shell) runs &'eximon'& with an overriding setting of | |
31277 | the LOG_DEPTH parameter. If EXIMON_LOG_FILE_PATH is set in the environment, it | |
31278 | overrides the Exim log file configuration. This makes it possible to have | |
31279 | &'eximon'& tailing log data that is written to syslog, provided that MAIL.INFO | |
31280 | syslog messages are routed to a file on the local host. | |
168e428f PH |
31281 | |
31282 | X resources can be used to change the appearance of the window in the normal | |
31283 | way. For example, a resource setting of the form | |
9b371988 PH |
31284 | .code |
31285 | Eximon*background: gray94 | |
31286 | .endd | |
168e428f PH |
31287 | changes the colour of the background to light grey rather than white. The |
31288 | stripcharts are drawn with both the data lines and the reference lines in | |
31289 | black. This means that the reference lines are not visible when on top of the | |
31290 | data. However, their colour can be changed by setting a resource called | |
9b371988 | 31291 | &"highlight"& (an odd name, but that's what the Athena stripchart widget uses). |
168e428f PH |
31292 | For example, if your X server is running Unix, you could set up lighter |
31293 | reference lines in the stripcharts by obeying | |
9b371988 PH |
31294 | .code |
31295 | xrdb -merge <<End | |
31296 | Eximon*highlight: gray | |
31297 | End | |
31298 | .endd | |
31299 | .cindex "admin user" | |
168e428f | 31300 | In order to see the contents of messages on the queue, and to operate on them, |
9b371988 | 31301 | &'eximon'& must either be run as root or by an admin user. |
168e428f PH |
31302 | |
31303 | The monitor's window is divided into three parts. The first contains one or | |
9b371988 | 31304 | more stripcharts and two action buttons, the second contains a &"tail"& of the |
168e428f PH |
31305 | main log file, and the third is a display of the queue of messages awaiting |
31306 | delivery, with two more action buttons. The following sections describe these | |
31307 | different parts of the display. | |
31308 | ||
31309 | ||
31310 | ||
31311 | ||
9b371988 PH |
31312 | .section "The stripcharts" |
31313 | .cindex "stripchart" | |
168e428f PH |
31314 | The first stripchart is always a count of messages on the queue. Its name can |
31315 | be configured by setting QUEUE_STRIPCHART_NAME in the | |
9b371988 | 31316 | &_Local/eximon.conf_& file. The remaining stripcharts are defined in the |
168e428f PH |
31317 | configuration script by regular expression matches on log file entries, making |
31318 | it possible to display, for example, counts of messages delivered to certain | |
31319 | hosts or using certain transports. The supplied defaults display counts of | |
31320 | received and delivered messages, and of local and SMTP deliveries. The default | |
31321 | period between stripchart updates is one minute; this can be adjusted by a | |
9b371988 | 31322 | parameter in the &_Local/eximon.conf_& file. |
168e428f PH |
31323 | |
31324 | The stripchart displays rescale themselves automatically as the value they are | |
31325 | displaying changes. There are always 10 horizontal lines in each chart; the | |
31326 | title string indicates the value of each division when it is greater than one. | |
9b371988 | 31327 | For example, &"x2"& means that each division represents a value of 2. |
168e428f PH |
31328 | |
31329 | It is also possible to have a stripchart which shows the percentage fullness of | |
31330 | a particular disk partition, which is useful when local deliveries are confined | |
31331 | to a single partition. | |
31332 | ||
9b371988 PH |
31333 | .cindex "&%statvfs%& function" |
31334 | This relies on the availability of the &[statvfs()]& function or equivalent in | |
168e428f PH |
31335 | the operating system. Most, but not all versions of Unix that support Exim have |
31336 | this. For this particular stripchart, the top of the chart always represents | |
9b371988 | 31337 | 100%, and the scale is given as &"x10%"&. This chart is configured by setting |
168e428f | 31338 | SIZE_STRIPCHART and (optionally) SIZE_STRIPCHART_NAME in the |
9b371988 | 31339 | &_Local/eximon.conf_& file. |
168e428f PH |
31340 | |
31341 | ||
31342 | ||
31343 | ||
9b371988 PH |
31344 | .section "Main action buttons" |
31345 | .cindex "size" "of monitor window" | |
31346 | .cindex "Exim monitor" "window size" | |
31347 | .cindex "window size" | |
168e428f | 31348 | Below the stripcharts there is an action button for quitting the monitor. Next |
9b371988 PH |
31349 | to this is another button marked &"Size"&. They are placed here so that |
31350 | shrinking the window to its default minimum size leaves just the queue count | |
31351 | stripchart and these two buttons visible. Pressing the &"Size"& button causes | |
31352 | the window to expand to its maximum size, unless it is already at the maximum, | |
31353 | in which case it is reduced to its minimum. | |
168e428f PH |
31354 | |
31355 | When expanding to the maximum, if the window cannot be fully seen where it | |
31356 | currently is, it is moved back to where it was the last time it was at full | |
31357 | size. When it is expanding from its minimum size, the old position is | |
31358 | remembered, and next time it is reduced to the minimum it is moved back there. | |
31359 | ||
31360 | The idea is that you can keep a reduced window just showing one or two | |
31361 | stripcharts at a convenient place on your screen, easily expand it to show | |
31362 | the full window when required, and just as easily put it back to what it was. | |
9b371988 PH |
31363 | The idea is copied from what the &'twm'& window manager does for its |
31364 | &'f.fullzoom'& action. The minimum size of the window can be changed by setting | |
31365 | the MIN_HEIGHT and MIN_WIDTH values in &_Local/eximon.conf_&. | |
168e428f PH |
31366 | |
31367 | Normally, the monitor starts up with the window at its full size, but it can be | |
31368 | built so that it starts up with the window at its smallest size, by setting | |
9b371988 | 31369 | START_SMALL=yes in &_Local/eximon.conf_&. |
168e428f PH |
31370 | |
31371 | ||
31372 | ||
9b371988 PH |
31373 | .section "The log display" |
31374 | .cindex "log" "tail of; in monitor" | |
168e428f PH |
31375 | The second section of the window is an area in which a display of the tail of |
31376 | the main log is maintained. | |
31377 | To save space on the screen, the timestamp on each log line is shortened by | |
9b371988 | 31378 | removing the date and, if &%log_timezone%& is set, the timezone. |
168e428f PH |
31379 | The log tail is not available when the only destination for logging data is |
31380 | syslog, unless the syslog lines are routed to a local file whose name is passed | |
9b371988 | 31381 | to &'eximon'& via the EXIMON_LOG_FILE_PATH environment variable. |
168e428f PH |
31382 | |
31383 | The log sub-window has a scroll bar at its lefthand side which can be used to | |
31384 | move back to look at earlier text, and the up and down arrow keys also have a | |
31385 | scrolling effect. The amount of log that is kept depends on the setting of | |
9b371988 PH |
31386 | LOG_BUFFER in &_Local/eximon.conf_&, which specifies the amount of memory |
31387 | to use. When this is full, the earlier 50% of data is discarded &-- this is | |
31388 | much more efficient than throwing it away line by line. The sub-window also has | |
31389 | a horizontal scroll bar for accessing the ends of long log lines. This is the | |
168e428f PH |
31390 | only means of horizontal scrolling; the right and left arrow keys are not |
31391 | available. Text can be cut from this part of the window using the mouse in the | |
31392 | normal way. The size of this subwindow is controlled by parameters in the | |
9b371988 | 31393 | configuration file &_Local/eximon.conf_&. |
168e428f PH |
31394 | |
31395 | Searches of the text in the log window can be carried out by means of the ^R | |
31396 | and ^S keystrokes, which default to a reverse and a forward search, | |
31397 | respectively. The search covers only the text that is displayed in the window. | |
31398 | It cannot go further back up the log. | |
31399 | ||
31400 | The point from which the search starts is indicated by a caret marker. This is | |
31401 | normally at the end of the text in the window, but can be positioned explicitly | |
31402 | by pointing and clicking with the left mouse button, and is moved automatically | |
31403 | by a successful search. If new text arrives in the window when it is scrolled | |
31404 | back, the caret remains where it is, but if the window is not scrolled back, | |
31405 | the caret is moved to the end of the new text. | |
31406 | ||
31407 | Pressing ^R or ^S pops up a window into which the search text can be typed. | |
31408 | There are buttons for selecting forward or reverse searching, for carrying out | |
9b371988 | 31409 | the search, and for cancelling. If the &"Search"& button is pressed, the search |
168e428f | 31410 | happens and the window remains so that further searches can be done. If the |
9b371988 | 31411 | &"Return"& key is pressed, a single search is done and the window is closed. If |
168e428f PH |
31412 | ^C is typed the search is cancelled. |
31413 | ||
31414 | The searching facility is implemented using the facilities of the Athena text | |
9b371988 PH |
31415 | widget. By default this pops up a window containing both &"search"& and |
31416 | &"replace"& options. In order to suppress the unwanted &"replace"& portion for | |
31417 | eximon, a modified version of the &%TextPop%& widget is distributed with Exim. | |
31418 | However, the linkers in BSDI and HP-UX seem unable to handle an externally | |
31419 | provided version of &%TextPop%& when the remaining parts of the text widget | |
31420 | come from the standard libraries. The compile-time option EXIMON_TEXTPOP can be | |
31421 | unset to cut out the modified &%TextPop%&, making it possible to build Eximon | |
31422 | on these systems, at the expense of having unwanted items in the search popup | |
31423 | window. | |
168e428f PH |
31424 | |
31425 | ||
31426 | ||
9b371988 PH |
31427 | .section "The queue display" |
31428 | .cindex "queue" "display in monitor" | |
168e428f PH |
31429 | The bottom section of the monitor window contains a list of all messages that |
31430 | are on the queue, which includes those currently being received or delivered, | |
31431 | as well as those awaiting delivery. The size of this subwindow is controlled by | |
9b371988 PH |
31432 | parameters in the configuration file &_Local/eximon.conf_&, and the frequency |
31433 | at which it is updated is controlled by another parameter in the same file &-- | |
168e428f | 31434 | the default is 5 minutes, since queue scans can be quite expensive. However, |
9b371988 PH |
31435 | there is an &"Update"& action button just above the display which can be used |
31436 | to force an update of the queue display at any time. | |
168e428f PH |
31437 | |
31438 | When a host is down for some time, a lot of pending mail can build up for it, | |
31439 | and this can make it hard to deal with other messages on the queue. To help | |
9b371988 PH |
31440 | with this situation there is a button next to &"Update"& called &"Hide"&. If |
31441 | pressed, a dialogue box called &"Hide addresses ending with"& is put up. If you | |
31442 | type anything in here and press &"Return"&, the text is added to a chain of | |
31443 | such texts, and if every undelivered address in a message matches at least one | |
168e428f PH |
31444 | of the texts, the message is not displayed. |
31445 | ||
31446 | If there is an address that does not match any of the texts, all the addresses | |
31447 | are displayed as normal. The matching happens on the ends of addresses so, for | |
9b371988 PH |
31448 | example, &'cam.ac.uk'& specifies all addresses in Cambridge, while |
31449 | &'xxx@foo.com.example'& specifies just one specific address. When any hiding | |
31450 | has been set up, a button called &"Unhide"& is displayed. If pressed, it | |
31451 | cancels all hiding. Also, to ensure that hidden messages do not get forgotten, | |
31452 | a hide request is automatically cancelled after one hour. | |
168e428f PH |
31453 | |
31454 | While the dialogue box is displayed, you can't press any buttons or do anything | |
31455 | else to the monitor window. For this reason, if you want to cut text from the | |
31456 | queue display to use in the dialogue box, you have to do the cutting before | |
9b371988 | 31457 | pressing the &"Hide"& button. |
168e428f PH |
31458 | |
31459 | The queue display contains, for each unhidden queued message, the length of | |
31460 | time it has been on the queue, the size of the message, the message id, the | |
31461 | message sender, and the first undelivered recipient, all on one line. If it is | |
9b371988 | 31462 | a bounce message, the sender is shown as &"<>"&. If there is more than one |
168e428f PH |
31463 | recipient to which the message has not yet been delivered, subsequent ones are |
31464 | listed on additional lines, up to a maximum configured number, following which | |
31465 | an ellipsis is displayed. Recipients that have already received the message are | |
31466 | not shown. | |
31467 | ||
9b371988 | 31468 | .cindex "frozen messages" "display" |
168e428f PH |
31469 | If a message is frozen, an asterisk is displayed at the left-hand side. |
31470 | ||
31471 | The queue display has a vertical scroll bar, and can also be scrolled by means | |
31472 | of the arrow keys. Text can be cut from it using the mouse in the normal way. | |
31473 | The text searching facilities, as described above for the log window, are also | |
31474 | available, but the caret is always moved to the end of the text when the queue | |
31475 | display is updated. | |
31476 | ||
31477 | ||
31478 | ||
9b371988 PH |
31479 | .section "The queue menu" |
31480 | .cindex "queue" "menu in monitor" | |
31481 | If the &%shift%& key is held down and the left button is clicked when the mouse | |
168e428f PH |
31482 | pointer is over the text for any message, an action menu pops up, and the first |
31483 | line of the queue display for the message is highlighted. This does not affect | |
31484 | any selected text. | |
31485 | ||
31486 | If you want to use some other event for popping up the menu, you can set the | |
9b371988 | 31487 | MENU_EVENT parameter in &_Local/eximon.conf_& to change the default, or |
168e428f PH |
31488 | set EXIMON_MENU_EVENT in the environment before starting the monitor. The |
31489 | value set in this parameter is a standard X event description. For example, to | |
9b371988 PH |
31490 | run eximon using &%ctrl%& rather than &%shift%& you could use |
31491 | .code | |
31492 | EXIMON_MENU_EVENT='Ctrl<Btn1Down>' eximon | |
31493 | .endd | |
168e428f PH |
31494 | The title of the menu is the message id, and it contains entries which act as |
31495 | follows: | |
31496 | ||
9b371988 PH |
31497 | .ilist |
31498 | &'message log'&: The contents of the message log for the message are displayed | |
31499 | in a new text window. | |
31500 | .next | |
31501 | &'headers'&: Information from the spool file that contains the envelope | |
168e428f | 31502 | information and headers is displayed in a new text window. See chapter |
9b371988 PH |
31503 | &<<CHAPspool>>& for a description of the format of spool files. |
31504 | .next | |
31505 | &'body'&: The contents of the spool file containing the body of the message are | |
168e428f PH |
31506 | displayed in a new text window. There is a default limit of 20,000 bytes to the |
31507 | amount of data displayed. This can be changed by setting the BODY_MAX | |
31508 | option at compile time, or the EXIMON_BODY_MAX option at run time. | |
9b371988 PH |
31509 | .next |
31510 | &'deliver message'&: A call to Exim is made using the &%-M%& option to request | |
168e428f | 31511 | delivery of the message. This causes an automatic thaw if the message is |
9b371988 | 31512 | frozen. The &%-v%& option is also set, and the output from Exim is displayed in |
168e428f PH |
31513 | a new text window. The delivery is run in a separate process, to avoid holding |
31514 | up the monitor while the delivery proceeds. | |
9b371988 PH |
31515 | .next |
31516 | &'freeze message'&: A call to Exim is made using the &%-Mf%& option to request | |
168e428f | 31517 | that the message be frozen. |
9b371988 PH |
31518 | .next |
31519 | .cindex "thawing messages" | |
31520 | .cindex "unfreezing messages" | |
31521 | .cindex "frozen messages" "thawing" | |
31522 | &'thaw message'&: A call to Exim is made using the &%-Mt%& option to request | |
31523 | that the message be thawed. | |
31524 | .next | |
31525 | .cindex "delivery" "forcing failure" | |
31526 | &'give up on msg'&: A call to Exim is made using the &%-Mg%& option to request | |
168e428f PH |
31527 | that Exim gives up trying to deliver the message. A bounce message is generated |
31528 | for any remaining undelivered addresses. | |
9b371988 PH |
31529 | .next |
31530 | &'remove message'&: A call to Exim is made using the &%-Mrm%& option to request | |
168e428f PH |
31531 | that the message be deleted from the system without generating a bounce |
31532 | message. | |
9b371988 PH |
31533 | .next |
31534 | &'add recipient'&: A dialog box is displayed into which a recipient address can | |
168e428f | 31535 | be typed. If the address is not qualified and the QUALIFY_DOMAIN parameter |
9b371988 | 31536 | is set in &_Local/eximon.conf_&, the address is qualified with that domain. |
168e428f | 31537 | Otherwise it must be entered as a fully qualified address. Pressing RETURN |
9b371988 | 31538 | causes a call to Exim to be made using the &%-Mar%& option to request that an |
168e428f PH |
31539 | additional recipient be added to the message, unless the entry box is empty, in |
31540 | which case no action is taken. | |
9b371988 PH |
31541 | .next |
31542 | &'mark delivered'&: A dialog box is displayed into which a recipient address | |
31543 | can be typed. If the address is not qualified and the QUALIFY_DOMAIN parameter | |
31544 | is set in &_Local/eximon.conf_&, the address is qualified with that domain. | |
168e428f | 31545 | Otherwise it must be entered as a fully qualified address. Pressing RETURN |
9b371988 | 31546 | causes a call to Exim to be made using the &%-Mmd%& option to mark the given |
168e428f PH |
31547 | recipient address as already delivered, unless the entry box is empty, in which |
31548 | case no action is taken. | |
9b371988 PH |
31549 | .next |
31550 | &'mark all delivered'&: A call to Exim is made using the &%-Mmad%& option to | |
31551 | mark all recipient addresses as already delivered. | |
31552 | .next | |
31553 | &'edit sender'&: A dialog box is displayed initialized with the current | |
31554 | sender's address. Pressing RETURN causes a call to Exim to be made using the | |
31555 | &%-Mes%& option to replace the sender address, unless the entry box is empty, | |
31556 | in which case no action is taken. If you want to set an empty sender (as in | |
31557 | bounce messages), you must specify it as &"<>"&. Otherwise, if the address is | |
31558 | not qualified and the QUALIFY_DOMAIN parameter is set in &_Local/eximon.conf_&, | |
31559 | the address is qualified with that domain. | |
31560 | .endlist | |
31561 | ||
31562 | When a delivery is forced, a window showing the &%-v%& output is displayed. In | |
168e428f PH |
31563 | other cases when a call to Exim is made, if there is any output from Exim (in |
31564 | particular, if the command fails) a window containing the command and the | |
31565 | output is displayed. Otherwise, the results of the action are normally apparent | |
31566 | from the log and queue displays. However, if you set ACTION_OUTPUT=yes in | |
9b371988 | 31567 | &_Local/eximon.conf_&, a window showing the Exim command is always opened, even |
168e428f PH |
31568 | if no output is generated. |
31569 | ||
31570 | The queue display is automatically updated for actions such as freezing and | |
31571 | thawing, unless ACTION_QUEUE_UPDATE=no has been set in | |
9b371988 PH |
31572 | &_Local/eximon.conf_&. In this case the &"Update"& button has to be used to |
31573 | force an update of the display after one of these actions. | |
168e428f PH |
31574 | |
31575 | In any text window that is displayed as result of a menu action, the normal | |
31576 | cut-and-paste facility is available, and searching can be carried out using ^R | |
31577 | and ^S, as described above for the log tail window. | |
31578 | ||
31579 | ||
31580 | ||
31581 | ||
31582 | ||
31583 | ||
9b371988 PH |
31584 | . //////////////////////////////////////////////////////////////////////////// |
31585 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 31586 | |
9b371988 PH |
31587 | .chapter "Security considerations" "CHAPsecurity" |
31588 | .cindex "security" | |
168e428f PH |
31589 | This chapter discusses a number of issues concerned with security, some of |
31590 | which are also covered in other parts of this manual. | |
31591 | ||
31592 | For reasons that this author does not understand, some people have promoted | |
9b371988 PH |
31593 | Exim as a &"particularly secure"& mailer. Perhaps it is because of the |
31594 | existence of this chapter in the documentation. However, the intent of the | |
31595 | chapter is simply to describe the way Exim works in relation to certain | |
31596 | security concerns, not to make any specific claims about the effectiveness of | |
31597 | its security as compared with other MTAs. | |
168e428f PH |
31598 | |
31599 | What follows is a description of the way Exim is supposed to be. Best efforts | |
31600 | have been made to try to ensure that the code agrees with the theory, but an | |
31601 | absence of bugs can never be guaranteed. Any that are reported will get fixed | |
31602 | as soon as possible. | |
31603 | ||
31604 | ||
9b371988 PH |
31605 | .section "Building a more &""hardened""& Exim" |
31606 | .cindex "security" "build-time features" | |
31607 | There are a number of build-time options that can be set in &_Local/Makefile_& | |
31608 | to create Exim binaries that are &"harder"& to attack, in particular by a rogue | |
168e428f PH |
31609 | Exim administrator who does not have the root password, or by someone who has |
31610 | penetrated the Exim (but not the root) account. These options are as follows: | |
31611 | ||
9b371988 PH |
31612 | .ilist |
31613 | ALT_CONFIG_PREFIX can be set to a string that is required to match the | |
31614 | start of any file names used with the &%-C%& option. When it is set, these file | |
31615 | names are also not allowed to contain the sequence &"/../"&. (However, if the | |
31616 | value of the &%-C%& option is identical to the value of CONFIGURE_FILE in | |
31617 | &_Local/Makefile_&, Exim ignores &%-C%& and proceeds as usual.) There is no | |
31618 | default setting for &%ALT_CONFIG_PREFIX%&. | |
31619 | ||
168e428f PH |
31620 | If the permitted configuration files are confined to a directory to |
31621 | which only root has access, this guards against someone who has broken | |
31622 | into the Exim account from running a privileged Exim with an arbitrary | |
31623 | configuration file, and using it to break into other accounts. | |
9b371988 PH |
31624 | .next |
31625 | If ALT_CONFIG_ROOT_ONLY is defined, root privilege is retained for &%-C%& | |
31626 | and &%-D%& only if the caller of Exim is root. Without it, the Exim user may | |
31627 | also use &%-C%& and &%-D%& and retain privilege. Setting this option locks out | |
31628 | the possibility of testing a configuration using &%-C%& right through message | |
168e428f PH |
31629 | reception and delivery, even if the caller is root. The reception works, but by |
31630 | that time, Exim is running as the Exim user, so when it re-execs to regain | |
9b371988 | 31631 | privilege for the delivery, the use of &%-C%& causes privilege to be lost. |
168e428f PH |
31632 | However, root can test reception and delivery using two separate commands. |
31633 | ALT_CONFIG_ROOT_ONLY is not set by default. | |
9b371988 PH |
31634 | .next |
31635 | If DISABLE_D_OPTION is defined, the use of the &%-D%& command line option | |
168e428f | 31636 | is disabled. |
9b371988 PH |
31637 | .next |
31638 | FIXED_NEVER_USERS can be set to a colon-separated list of users that are | |
31639 | never to be used for any deliveries. This is like the &%never_users%& runtime | |
168e428f | 31640 | option, but it cannot be overridden; the runtime option adds additional users |
9b371988 | 31641 | to the list. The default setting is &"root"&; this prevents a non-root user who |
168e428f | 31642 | is permitted to modify the runtime file from using Exim as a way to get root. |
9b371988 | 31643 | .endlist |
168e428f PH |
31644 | |
31645 | ||
31646 | ||
31647 | ||
9b371988 PH |
31648 | .section "Root privilege" |
31649 | .cindex "setuid" | |
31650 | .cindex "root privilege" | |
168e428f PH |
31651 | The Exim binary is normally setuid to root, which means that it gains root |
31652 | privilege (runs as root) when it starts execution. In some special cases (for | |
31653 | example, when the daemon is not in use and there are no local deliveries), it | |
31654 | may be possible to run Exim setuid to some user other than root. This is | |
31655 | discussed in the next section. However, in most installations, root privilege | |
31656 | is required for two things: | |
31657 | ||
9b371988 PH |
31658 | .ilist |
31659 | To set up a socket connected to the standard SMTP port (25) when initialising | |
31660 | the listening daemon. If Exim is run from &'inetd'&, this privileged action is | |
168e428f | 31661 | not required. |
9b371988 PH |
31662 | .next |
31663 | To be able to change uid and gid in order to read users' &_.forward_& files and | |
168e428f PH |
31664 | perform local deliveries as the receiving user or as specified in the |
31665 | configuration. | |
9b371988 | 31666 | .endlist |
168e428f PH |
31667 | |
31668 | It is not necessary to be root to do any of the other things Exim does, such as | |
31669 | receiving messages and delivering them externally over SMTP, and it is | |
31670 | obviously more secure if Exim does not run as root except when necessary. | |
31671 | For this reason, a user and group for Exim to use must be defined in | |
9b371988 PH |
31672 | &_Local/Makefile_&. These are known as &"the Exim user"& and &"the Exim |
31673 | group"&. Their values can be changed by the run time configuration, though this | |
31674 | is not recommended. Often a user called &'exim'& is used, but some sites use | |
31675 | &'mail'& or another user name altogether. | |
168e428f | 31676 | |
9b371988 | 31677 | Exim uses &[setuid()]& whenever it gives up root privilege. This is a permanent |
168e428f | 31678 | abdication; the process cannot regain root afterwards. Prior to release 4.00, |
9b371988 | 31679 | &[seteuid()]& was used in some circumstances, but this is no longer the case. |
168e428f PH |
31680 | |
31681 | After a new Exim process has interpreted its command line options, it changes | |
31682 | uid and gid in the following cases: | |
31683 | ||
9b371988 PH |
31684 | .ilist |
31685 | .cindex "&%-C%& option" | |
31686 | .cindex "&%-D%& option" | |
31687 | If the &%-C%& option is used to specify an alternate configuration file, or if | |
31688 | the &%-D%& option is used to define macro values for the configuration, and the | |
168e428f PH |
31689 | calling process is not running as root or the Exim user, the uid and gid are |
31690 | changed to those of the calling process. | |
9b371988 PH |
31691 | However, if ALT_CONFIG_ROOT_ONLY is defined in &_Local/Makefile_&, only |
31692 | root callers may use &%-C%& and &%-D%& without losing privilege, and if | |
31693 | DISABLE_D_OPTION is set, the &%-D%& option may not be used at all. | |
31694 | .next | |
31695 | .cindex "&%-be%& option" | |
31696 | .cindex "&%-bf%& option" | |
31697 | .cindex "&%-bF%& option" | |
31698 | If the expansion test option (&%-be%&) or one of the filter testing options | |
31699 | (&%-bf%& or &%-bF%&) are used, the uid and gid are changed to those of the | |
168e428f | 31700 | calling process. |
9b371988 PH |
31701 | .next |
31702 | If the process is not a daemon process or a queue runner process or a delivery | |
31703 | process or a process for testing address routing (started with &%-bt%&), the | |
31704 | uid and gid are changed to the Exim user and group. This means that Exim always | |
168e428f PH |
31705 | runs under its own uid and gid when receiving messages. This also applies when |
31706 | testing address verification | |
9b371988 PH |
31707 | .cindex "&%-bv%& option" |
31708 | .cindex "&%-bh%& option" | |
31709 | (the &%-bv%& option) and testing incoming message policy controls (the &%-bh%& | |
168e428f | 31710 | option). |
9b371988 PH |
31711 | .next |
31712 | For a daemon, queue runner, delivery, or address testing process, the uid | |
168e428f | 31713 | remains as root at this stage, but the gid is changed to the Exim group. |
9b371988 | 31714 | .endlist |
168e428f PH |
31715 | |
31716 | The processes that initially retain root privilege behave as follows: | |
31717 | ||
9b371988 PH |
31718 | .ilist |
31719 | A daemon process changes the gid to the Exim group and the uid to the Exim | |
31720 | user after setting up one or more listening sockets. The &[initgroups()]& | |
168e428f PH |
31721 | function is called, so that if the Exim user is in any additional groups, they |
31722 | will be used during message reception. | |
9b371988 PH |
31723 | .next |
31724 | A queue runner process retains root privilege throughout its execution. Its | |
168e428f | 31725 | job is to fork a controlled sequence of delivery processes. |
9b371988 PH |
31726 | .next |
31727 | A delivery process retains root privilege throughout most of its execution, | |
168e428f PH |
31728 | but any actual deliveries (that is, the transports themselves) are run in |
31729 | subprocesses which always change to a non-root uid and gid. For local | |
31730 | deliveries this is typically the uid and gid of the owner of the mailbox; for | |
31731 | remote deliveries, the Exim uid and gid are used. Once all the delivery | |
31732 | subprocesses have been run, a delivery process changes to the Exim uid and gid | |
31733 | while doing post-delivery tidying up such as updating the retry database and | |
31734 | generating bounce and warning messages. | |
9b371988 | 31735 | |
168e428f PH |
31736 | While the recipient addresses in a message are being routed, the delivery |
31737 | process runs as root. However, if a user's filter file has to be processed, | |
31738 | this is done in a subprocess that runs under the individual user's uid and | |
9b371988 PH |
31739 | gid. A system filter is run as root unless &%system_filter_user%& is set. |
31740 | .next | |
31741 | A process that is testing addresses (the &%-bt%& option) runs as root so that | |
168e428f | 31742 | the routing is done in the same environment as a message delivery. |
9b371988 | 31743 | .endlist |
168e428f PH |
31744 | |
31745 | ||
31746 | ||
31747 | ||
9b371988 PH |
31748 | .section "Running Exim without privilege" "SECTrunexiwitpri" |
31749 | .cindex "privilege" "running without" | |
31750 | .cindex "unprivileged running" | |
31751 | .cindex "root privilege" "running without" | |
168e428f PH |
31752 | Some installations like to run Exim in an unprivileged state for more of its |
31753 | operation, for added security. Support for this mode of operation is provided | |
9b371988 | 31754 | by the global option &%deliver_drop_privilege%&. When this is set, the uid and |
168e428f PH |
31755 | gid are changed to the Exim user and group at the start of a delivery process |
31756 | (and also queue runner and address testing processes). This means that address | |
31757 | routing is no longer run as root, and the deliveries themselves cannot change | |
31758 | to any other uid. | |
31759 | ||
9b371988 | 31760 | Leaving the binary setuid to root, but setting &%deliver_drop_privilege%& means |
168e428f PH |
31761 | that the daemon can still be started in the usual way, and it can respond |
31762 | correctly to SIGHUP because the re-invocation regains root privilege. | |
31763 | ||
31764 | An alternative approach is to make Exim setuid to the Exim user and also setgid | |
31765 | to the Exim group. | |
31766 | If you do this, the daemon must be started from a root process. (Calling | |
31767 | Exim from a root process makes it behave in the way it does when it is setuid | |
31768 | root.) However, the daemon cannot restart itself after a SIGHUP signal because | |
31769 | it cannot regain privilege. | |
31770 | ||
9b371988 | 31771 | It is still useful to set &%deliver_drop_privilege%& in this case, because it |
168e428f PH |
31772 | stops Exim from trying to re-invoke itself to do a delivery after a message has |
31773 | been received. Such a re-invocation is a waste of resources because it has no | |
31774 | effect. | |
31775 | ||
9b371988 PH |
31776 | If restarting the daemon is not an issue (for example, if &%mua_wrapper%& is |
31777 | set, or &'inetd'& is being used instead of a daemon), having the binary setuid | |
31778 | to the Exim user seems a clean approach, but there is one complication: | |
168e428f PH |
31779 | |
31780 | In this style of operation, Exim is running with the real uid and gid set to | |
31781 | those of the calling process, and the effective uid/gid set to Exim's values. | |
31782 | Ideally, any association with the calling process' uid/gid should be dropped, | |
31783 | that is, the real uid/gid should be reset to the effective values so as to | |
31784 | discard any privileges that the caller may have. While some operating systems | |
31785 | have a function that permits this action for a non-root effective uid, quite a | |
31786 | number of them do not. Because of this lack of standardization, Exim does not | |
31787 | address this problem at this time. | |
31788 | ||
9b371988 PH |
31789 | For this reason, the recommended approach for &"mostly unprivileged"& running |
31790 | is to keep the Exim binary setuid to root, and to set | |
31791 | &%deliver_drop_privilege%&. This also has the advantage of allowing a daemon to | |
31792 | be used in the most straightforward way. | |
168e428f PH |
31793 | |
31794 | If you configure Exim not to run delivery processes as root, there are a | |
31795 | number of restrictions on what you can do: | |
31796 | ||
9b371988 PH |
31797 | .ilist |
31798 | You can deliver only as the Exim user/group. You should explicitly use the | |
31799 | &%user%& and &%group%& options to override routers or local transports that | |
168e428f PH |
31800 | normally deliver as the recipient. This makes sure that configurations that |
31801 | work in this mode function the same way in normal mode. Any implicit or | |
31802 | explicit specification of another user causes an error. | |
9b371988 PH |
31803 | .next |
31804 | Use of &_.forward_& files is severely restricted, such that it is usually | |
168e428f | 31805 | not worthwhile to include them in the configuration. |
9b371988 PH |
31806 | .next |
31807 | Users who wish to use &_.forward_& would have to make their home directory and | |
168e428f PH |
31808 | the file itself accessible to the Exim user. Pipe and append-to-file entries, |
31809 | and their equivalents in Exim filters, cannot be used. While they could be | |
31810 | enabled in the Exim user's name, that would be insecure and not very useful. | |
9b371988 PH |
31811 | .next |
31812 | Unless the local user mailboxes are all owned by the Exim user (possible in | |
168e428f PH |
31813 | some POP3 or IMAP-only environments): |
31814 | ||
9b371988 PH |
31815 | .olist |
31816 | They must be owned by the Exim group and be writable by that group. This | |
31817 | implies you must set &%mode%& in the appendfile configuration, as well as the | |
168e428f | 31818 | mode of the mailbox files themselves. |
9b371988 PH |
31819 | .next |
31820 | You must set &%no_check_owner%&, since most or all of the files will not be | |
168e428f | 31821 | owned by the Exim user. |
9b371988 PH |
31822 | .next |
31823 | You must set &%file_must_exist%&, because Exim cannot set the owner correctly | |
168e428f PH |
31824 | on a newly created mailbox when unprivileged. This also implies that new |
31825 | mailboxes need to be created manually. | |
9b371988 PH |
31826 | .endlist olist |
31827 | .endlist ilist | |
31828 | ||
168e428f PH |
31829 | |
31830 | These restrictions severely restrict what can be done in local deliveries. | |
31831 | However, there are no restrictions on remote deliveries. If you are running a | |
9b371988 | 31832 | gateway host that does no local deliveries, setting &%deliver_drop_privilege%& |
168e428f PH |
31833 | gives more security at essentially no cost. |
31834 | ||
9b371988 PH |
31835 | If you are using the &%mua_wrapper%& facility (see chapter |
31836 | &<<CHAPnonqueueing>>&), &%deliver_drop_privilege%& is forced to be true. | |
168e428f PH |
31837 | |
31838 | ||
31839 | ||
31840 | ||
9b371988 PH |
31841 | .section "Delivering to local files" |
31842 | Full details of the checks applied by &(appendfile)& before it writes to a file | |
31843 | are given in chapter &<<CHAPappendfile>>&. | |
168e428f PH |
31844 | |
31845 | ||
31846 | ||
9b371988 PH |
31847 | .section "IPv4 source routing" |
31848 | .cindex "source routing" "in IP packets" | |
31849 | .cindex "IP source routing" | |
168e428f PH |
31850 | Many operating systems suppress IP source-routed packets in the kernel, but |
31851 | some cannot be made to do this, so Exim does its own check. It logs incoming | |
31852 | IPv4 source-routed TCP calls, and then drops them. Things are all different in | |
31853 | IPv6. No special checking is currently done. | |
31854 | ||
31855 | ||
31856 | ||
9b371988 | 31857 | .section "The VRFY, EXPN, and ETRN commands in SMTP" |
168e428f PH |
31858 | Support for these SMTP commands is disabled by default. If required, they can |
31859 | be enabled by defining suitable ACLs. | |
31860 | ||
31861 | ||
31862 | ||
31863 | ||
9b371988 PH |
31864 | .section "Privileged users" |
31865 | .cindex "trusted user" | |
31866 | .cindex "admin user" | |
31867 | .cindex "privileged user" | |
31868 | .cindex "user" "trusted" | |
31869 | .cindex "user" "admin" | |
168e428f PH |
31870 | Exim recognises two sets of users with special privileges. Trusted users are |
31871 | able to submit new messages to Exim locally, but supply their own sender | |
31872 | addresses and information about a sending host. For other users submitting | |
31873 | local messages, Exim sets up the sender address from the uid, and doesn't | |
31874 | permit a remote host to be specified. | |
31875 | ||
9b371988 PH |
31876 | .cindex "&%-f%& option" |
31877 | However, an untrusted user is permitted to use the &%-f%& command line option | |
31878 | in the special form &%-f <>%& to indicate that a delivery failure for the | |
31879 | message should not cause an error report. This affects the message's envelope, | |
31880 | but it does not affect the &'Sender:'& header. Untrusted users may also be | |
31881 | permitted to use specific forms of address with the &%-f%& option by setting | |
31882 | the &%untrusted_set_sender%& option. | |
168e428f PH |
31883 | |
31884 | Trusted users are used to run processes that receive mail messages from some | |
31885 | other mail domain and pass them on to Exim for delivery either locally, or over | |
31886 | the Internet. Exim trusts a caller that is running as root, as the Exim user, | |
9b371988 PH |
31887 | as any user listed in the &%trusted_users%& configuration option, or under any |
31888 | group listed in the &%trusted_groups%& option. | |
168e428f PH |
31889 | |
31890 | Admin users are permitted to do things to the messages on Exim's queue. They | |
31891 | can freeze or thaw messages, cause them to be returned to their senders, remove | |
31892 | them entirely, or modify them in various ways. In addition, admin users can run | |
31893 | the Exim monitor and see all the information it is capable of providing, which | |
31894 | includes the contents of files on the spool. | |
31895 | ||
9b371988 PH |
31896 | .cindex "&%-M%& option" |
31897 | .cindex "&%-q%& option" | |
31898 | By default, the use of the &%-M%& and &%-q%& options to cause Exim to attempt | |
168e428f | 31899 | delivery of messages on its queue is restricted to admin users. This |
9b371988 PH |
31900 | restriction can be relaxed by setting the &%no_prod_requires_admin%& option. |
31901 | Similarly, the use of &%-bp%& (and its variants) to list the contents of the | |
168e428f | 31902 | queue is also restricted to admin users. This restriction can be relaxed by |
9b371988 | 31903 | setting &%no_queue_list_requires_admin%&. |
168e428f PH |
31904 | |
31905 | Exim recognises an admin user if the calling process is running as root or as | |
31906 | the Exim user or if any of the groups associated with the calling process is | |
31907 | the Exim group. It is not necessary actually to be running under the Exim | |
31908 | group. However, if admin users who are not root or the Exim user are to access | |
31909 | the contents of files on the spool via the Exim monitor (which runs | |
31910 | unprivileged), Exim must be built to allow group read access to its spool | |
31911 | files. | |
31912 | ||
31913 | ||
31914 | ||
9b371988 PH |
31915 | .section "Spool files" |
31916 | .cindex "spool directory" "files" | |
168e428f PH |
31917 | Exim's spool directory and everything it contains is owned by the Exim user and |
31918 | set to the Exim group. The mode for spool files is defined in the | |
9b371988 | 31919 | &_Local/Makefile_& configuration file, and defaults to 0640. This means that |
168e428f PH |
31920 | any user who is a member of the Exim group can access these files. |
31921 | ||
31922 | ||
31923 | ||
9b371988 PH |
31924 | .section "Use of argv[0]" |
31925 | Exim examines the last component of &%argv[0]%&, and if it matches one of a set | |
168e428f | 31926 | of specific strings, Exim assumes certain options. For example, calling Exim |
9b371988 PH |
31927 | with the last component of &%argv[0]%& set to &"rsmtp"& is exactly equivalent |
31928 | to calling it with the option &%-bS%&. There are no security implications in | |
31929 | this. | |
168e428f PH |
31930 | |
31931 | ||
31932 | ||
9b371988 PH |
31933 | .section "Use of %f formatting" |
31934 | The only use made of &"%f"& by Exim is in formatting load average values. These | |
168e428f PH |
31935 | are actually stored in integer variables as 1000 times the load average. |
31936 | Consequently, their range is limited and so therefore is the length of the | |
31937 | converted output. | |
31938 | ||
31939 | ||
31940 | ||
9b371988 | 31941 | .section "Embedded Exim path" |
168e428f PH |
31942 | Exim uses its own path name, which is embedded in the code, only when it needs |
31943 | to re-exec in order to regain root privilege. Therefore, it is not root when it | |
31944 | does so. If some bug allowed the path to get overwritten, it would lead to an | |
31945 | arbitrary program's being run as exim, not as root. | |
31946 | ||
31947 | ||
31948 | ||
9b371988 PH |
31949 | .section "Use of sprintf()" |
31950 | .cindex "&[sprintf()]&" | |
31951 | A large number of occurrences of &"sprintf"& in the code are actually calls to | |
31952 | &'string_sprintf()'&, a function that returns the result in malloc'd store. | |
168e428f PH |
31953 | The intermediate formatting is done into a large fixed buffer by a function |
31954 | that runs through the format string itself, and checks the length of each | |
31955 | conversion before performing it, thus preventing buffer overruns. | |
31956 | ||
9b371988 | 31957 | The remaining uses of &[sprintf()]& happen in controlled circumstances where |
168e428f PH |
31958 | the output buffer is known to be sufficiently long to contain the converted |
31959 | string. | |
31960 | ||
31961 | ||
31962 | ||
9b371988 | 31963 | .section "Use of debug_printf() and log_write()" |
168e428f | 31964 | Arbitrary strings are passed to both these functions, but they do their |
9b371988 | 31965 | formatting by calling the function &'string_vformat()'&, which runs through |
168e428f PH |
31966 | the format string itself, and checks the length of each conversion. |
31967 | ||
31968 | ||
31969 | ||
9b371988 | 31970 | .section "Use of strcat() and strcpy()" |
168e428f PH |
31971 | These are used only in cases where the output buffer is known to be large |
31972 | enough to hold the result. | |
31973 | ||
31974 | ||
31975 | ||
31976 | ||
9b371988 PH |
31977 | . //////////////////////////////////////////////////////////////////////////// |
31978 | . //////////////////////////////////////////////////////////////////////////// | |
168e428f | 31979 | |
9b371988 PH |
31980 | .chapter "Format of spool files" "CHAPspool" |
31981 | .cindex "format" "spool files" | |
31982 | .cindex "spool directory" "format of files" | |
31983 | .cindex "spool files" "format of" | |
31984 | .cindex "spool files" "editing" | |
168e428f PH |
31985 | A message on Exim's queue consists of two files, whose names are the message id |
31986 | followed by -D and -H, respectively. The data portion of the message is kept in | |
31987 | the -D file on its own. The message's envelope, status, and headers are all | |
31988 | kept in the -H file, whose format is described in this chapter. Each of these | |
31989 | two files contains the final component of its own name as its first line. This | |
31990 | is insurance against disk crashes where the directory is lost but the files | |
31991 | themselves are recoverable. | |
31992 | ||
31993 | Some people are tempted into editing -D files in order to modify messages. You | |
31994 | need to be extremely careful if you do this; it is not recommended and you are | |
31995 | on your own if you do it. Here are some of the pitfalls: | |
31996 | ||
9b371988 PH |
31997 | .ilist |
31998 | .new | |
31999 | You must ensure that Exim does not try to deliver the message while you are | |
068aaea8 | 32000 | fiddling with it. The safest way is to take out a write lock on the -D file, |
9b371988 | 32001 | which is what Exim itself does, using &[fcntl()]&. If you update the file in |
068aaea8 PH |
32002 | place, the lock will be retained. If you write a new file and rename it, the |
32003 | lock will be lost at the instant of rename. | |
9b371988 PH |
32004 | .next |
32005 | .cindex "&$body_linecount$&" | |
068aaea8 | 32006 | If you change the number of lines in the file, the value of |
9b371988 | 32007 | &$body_linecount$&, which is stored in the -H file, will be incorrect. At |
068aaea8 PH |
32008 | present, this value is not used by Exim, but there is no guarantee that this |
32009 | will always be the case. | |
9b371988 PH |
32010 | .wen |
32011 | .next | |
32012 | If the message is in MIME format, you must take care not to break it. | |
32013 | .next | |
32014 | If the message is cryptographically signed, any change will invalidate the | |
168e428f | 32015 | signature. |
9b371988 | 32016 | .endlist |
168e428f PH |
32017 | |
32018 | ||
9b371988 PH |
32019 | Files whose names end with -J may also be seen in the &_input_& directory (or |
32020 | its subdirectories when &%split_spool_directory%& is set). These are journal | |
168e428f PH |
32021 | files, used to record addresses to which the message has been delivered during |
32022 | the course of a delivery run. At the end of the run, the -H file is updated, | |
32023 | and the -J file is deleted. | |
32024 | ||
32025 | ||
9b371988 PH |
32026 | .section "Format of the -H file" |
32027 | .cindex "uid (user id)" "in spool file" | |
32028 | .cindex "gid (group id)" "in spool file" | |
168e428f PH |
32029 | The second line of the -H file contains the login name for the uid of the |
32030 | process that called Exim to read the message, followed by the numerical uid and | |
32031 | gid. For a locally generated message, this is normally the user who sent the | |
32032 | message. For a message received over TCP/IP, it is normally the Exim user. | |
32033 | ||
32034 | The third line of the file contains the address of the message's sender as | |
32035 | transmitted in the envelope, contained in angle brackets. The sender address is | |
32036 | empty for bounce messages. For incoming SMTP mail, the sender address is given | |
32037 | in the MAIL command. For locally generated mail, the sender address is | |
32038 | created by Exim from the login name of the current user and the configured | |
9b371988 PH |
32039 | &%qualify_domain%&. However, this can be overridden by the &%-f%& option or a |
32040 | leading &"From&~"& line if the caller is trusted, or if the supplied address is | |
32041 | &"<>"& or an address that matches &%untrusted_set_senders%&. | |
168e428f PH |
32042 | |
32043 | The fourth line contains two numbers. The first is the time that the message | |
9b371988 | 32044 | was received, in the conventional Unix form &-- the number of seconds since the |
168e428f PH |
32045 | start of the epoch. The second number is a count of the number of messages |
32046 | warning of delayed delivery that have been sent to the sender. | |
32047 | ||
32048 | There follow a number of lines starting with a hyphen. These can appear in any | |
32049 | order, and are omitted when not relevant: | |
32050 | ||
9b371988 PH |
32051 | .vlist |
32052 | .vitem "&%-acl%& <&'number'&> <&'length'&>" | |
168e428f | 32053 | A line of this form is present for every ACL variable that is not empty. The |
9b371988 PH |
32054 | number identifies the variable; the &%acl_c%&&*x*& variables are numbered 0&--9 |
32055 | and the &%acl_m%&&*x*& variables are numbered 10&--19. The length is the length | |
32056 | of the data string for the variable. The string itself starts at the beginning | |
32057 | of the next line, and is followed by a newline character. It may contain | |
32058 | internal newlines. | |
168e428f | 32059 | |
9b371988 | 32060 | .vitem "&%-active_hostname%& <&'hostname'&>" |
168e428f | 32061 | This is present if, when the message was received over SMTP, the value of |
9b371988 | 32062 | &$smtp_active_hostname$& was different to the value of &$primary_hostname$&. |
168e428f | 32063 | |
9b371988 | 32064 | .vitem &%-allow_unqualified_recipient%& |
168e428f PH |
32065 | This is present if unqualified recipient addresses are permitted in header |
32066 | lines (to stop such addresses from being qualified if rewriting occurs at | |
9b371988 PH |
32067 | transport time). Local messages that were input using &%-bnq%& and remote |
32068 | messages from hosts that match &%recipient_unqualified_hosts%& set this flag. | |
168e428f | 32069 | |
9b371988 | 32070 | .vitem &%-allow_unqualified_sender%& |
168e428f PH |
32071 | This is present if unqualified sender addresses are permitted in header lines |
32072 | (to stop such addresses from being qualified if rewriting occurs at transport | |
9b371988 PH |
32073 | time). Local messages that were input using &%-bnq%& and remote messages from |
32074 | hosts that match &%sender_unqualified_hosts%& set this flag. | |
168e428f | 32075 | |
9b371988 | 32076 | .vitem "&%-auth_id%& <&'text'&>" |
168e428f | 32077 | The id information for a message received on an authenticated SMTP connection |
9b371988 | 32078 | &-- the value of the &$authenticated_id$& variable. |
168e428f | 32079 | |
9b371988 PH |
32080 | .vitem "&%-auth_sender%& <&'address'&>" |
32081 | The address of an authenticated sender &-- the value of the | |
32082 | &$authenticated_sender$& variable. | |
168e428f | 32083 | |
9b371988 | 32084 | .vitem "&%-body_linecount%& <&'number'&>" |
168e428f PH |
32085 | This records the number of lines in the body of the message, and is always |
32086 | present. | |
32087 | ||
9b371988 | 32088 | .vitem "&%-body_zerocount%& <&'number'&>" |
168e428f PH |
32089 | This records the number of binary zero bytes in the body of the message, and is |
32090 | present if the number is greater than zero. | |
32091 | ||
9b371988 | 32092 | .vitem &%-deliver_firsttime%& |
168e428f PH |
32093 | This is written when a new message is first added to the spool. When the spool |
32094 | file is updated after a deferral, it is omitted. | |
32095 | ||
9b371988 PH |
32096 | .vitem "&%-frozen%& <&'time'&>" |
32097 | .cindex "frozen messages" "spool data" | |
32098 | The message is frozen, and the freezing happened at <&'time'&>. | |
168e428f | 32099 | |
9b371988 | 32100 | .vitem "&%-helo_name%& <&'text'&>" |
168e428f PH |
32101 | This records the host name as specified by a remote host in a HELO or EHLO |
32102 | command. | |
32103 | ||
9b371988 | 32104 | .vitem "&%-host_address%& <&'address'&>.<&'port'&>" |
168e428f PH |
32105 | This records the IP address of the host from which the message was received and |
32106 | the remote port number that was used. It is omitted for locally generated | |
32107 | messages. | |
32108 | ||
9b371988 | 32109 | .vitem "&%-host_auth%& <&'text'&>" |
168e428f | 32110 | If the message was received on an authenticated SMTP connection, this records |
9b371988 PH |
32111 | the name of the authenticator &-- the value of the |
32112 | &$sender_host_authenticated$& variable. | |
168e428f | 32113 | |
9b371988 | 32114 | .vitem &%-host_lookup_failed%& |
168e428f | 32115 | This is present if an attempt to look up the sending host's name from its IP |
9b371988 | 32116 | address failed. It corresponds to the &$host_lookup_failed$& variable. |
168e428f | 32117 | |
9b371988 PH |
32118 | .vitem "&%-host_name%& <&'text'&>" |
32119 | .cindex "reverse DNS lookup" | |
32120 | .cindex "DNS" "reverse lookup" | |
168e428f PH |
32121 | This records the name of the remote host from which the message was received, |
32122 | if the host name was looked up from the IP address when the message was being | |
32123 | received. It is not present if no reverse lookup was done. | |
32124 | ||
9b371988 | 32125 | .vitem "&%-ident%& <&'text'&>" |
168e428f | 32126 | For locally submitted messages, this records the login of the originating user, |
9b371988 PH |
32127 | unless it was a trusted user and the &%-oMt%& option was used to specify an |
32128 | ident value. For messages received over TCP/IP, this records the ident string | |
168e428f PH |
32129 | supplied by the remote host, if any. |
32130 | ||
9b371988 | 32131 | .vitem "&%-interface_address%& <&'address'&>.<&'port'&>" |
168e428f PH |
32132 | This records the IP address of the local interface and the port number through |
32133 | which a message was received from a remote host. It is omitted for locally | |
32134 | generated messages. | |
32135 | ||
9b371988 | 32136 | .vitem &%-local%& |
168e428f PH |
32137 | The message is from a local sender. |
32138 | ||
9b371988 | 32139 | .vitem &%-localerror%& |
168e428f PH |
32140 | The message is a locally-generated bounce message. |
32141 | ||
9b371988 PH |
32142 | .vitem "&%-local_scan%& <&'string'&>" |
32143 | This records the data string that was returned by the &[local_scan()]& function | |
32144 | when the message was received &-- the value of the &$local_scan_data$& | |
32145 | variable. It is omitted if no data was returned. | |
168e428f | 32146 | |
9b371988 | 32147 | .vitem &%-manual_thaw%& |
168e428f PH |
32148 | The message was frozen but has been thawed manually, that is, by an explicit |
32149 | Exim command rather than via the auto-thaw process. | |
32150 | ||
9b371988 PH |
32151 | .vitem &%-N%& |
32152 | A testing delivery process was started using the &%-N%& option to suppress any | |
168e428f | 32153 | actual deliveries, but delivery was deferred. At any further delivery attempts, |
9b371988 | 32154 | &%-N%& is assumed. |
168e428f | 32155 | |
9b371988 PH |
32156 | .vitem &%-received_protocol%& |
32157 | This records the value of the &$received_protocol$& variable, which contains | |
32158 | the name of the protocol by which the message was received. | |
168e428f | 32159 | |
9b371988 | 32160 | .vitem &%-sender_set_untrusted%& |
168e428f PH |
32161 | The envelope sender of this message was set by an untrusted local caller (used |
32162 | to ensure that the caller is displayed in queue listings). | |
32163 | ||
9b371988 | 32164 | .vitem "&%-spam_score_int%& <&'number'&>" |
168e428f | 32165 | If a message was scanned by SpamAssassin, this is present. It records the value |
9b371988 | 32166 | of &$spam_score_int$&. |
168e428f | 32167 | |
9b371988 | 32168 | .vitem &%-tls_certificate_verified%& |
168e428f PH |
32169 | A TLS certificate was received from the client that sent this message, and the |
32170 | certificate was verified by the server. | |
32171 | ||
9b371988 | 32172 | .vitem "&%-tls_cipher%& <&'cipher name'&>" |
168e428f PH |
32173 | When the message was received over an encrypted connection, this records the |
32174 | name of the cipher suite that was used. | |
32175 | ||
9b371988 | 32176 | .vitem "&%-tls_peerdn%& <&'peer DN'&>" |
168e428f PH |
32177 | When the message was received over an encrypted connection, and a certificate |
32178 | was received from the client, this records the Distinguished Name from that | |
32179 | certificate. | |
9b371988 | 32180 | .endlist |
168e428f PH |
32181 | |
32182 | Following the options there is a list of those addresses to which the message | |
32183 | is not to be delivered. This set of addresses is initialized from the command | |
9b371988 | 32184 | line when the &%-t%& option is used and &%extract_addresses_remove_arguments%& |
168e428f PH |
32185 | is set; otherwise it starts out empty. Whenever a successful delivery is made, |
32186 | the address is added to this set. The addresses are kept internally as a | |
32187 | balanced binary tree, and it is a representation of that tree which is written | |
32188 | to the spool file. If an address is expanded via an alias or forward file, the | |
32189 | original address is added to the tree when deliveries to all its child | |
32190 | addresses are complete. | |
32191 | ||
32192 | If the tree is empty, there is a single line in the spool file containing just | |
9b371988 | 32193 | the text &"XX"&. Otherwise, each line consists of two letters, which are either |
168e428f PH |
32194 | Y or N, followed by an address. The address is the value for the node of the |
32195 | tree, and the letters indicate whether the node has a left branch and/or a | |
32196 | right branch attached to it, respectively. If branches exist, they immediately | |
32197 | follow. Here is an example of a three-node tree: | |
9b371988 PH |
32198 | .code |
32199 | YY darcy@austen.fict.example | |
32200 | NN alice@wonderland.fict.example | |
32201 | NN editor@thesaurus.ref.example | |
32202 | .endd | |
168e428f PH |
32203 | After the non-recipients tree, there is a list of the message's recipients. |
32204 | This is a simple list, preceded by a count. It includes all the original | |
32205 | recipients of the message, including those to whom the message has already been | |
32206 | delivered. In the simplest case, the list contains one address per line. For | |
32207 | example: | |
9b371988 PH |
32208 | .code |
32209 | 4 | |
32210 | editor@thesaurus.ref.example | |
32211 | darcy@austen.fict.example | |
32212 | rdo@foundation | |
32213 | alice@wonderland.fict.example | |
32214 | .endd | |
168e428f | 32215 | However, when a child address has been added to the top-level addresses as a |
9b371988 PH |
32216 | result of the use of the &%one_time%& option on a &(redirect)& router, each |
32217 | line is of the following form: | |
32218 | .display | |
32219 | <&'top-level address'&> <&'errors_to address'&> &&& | |
32220 | <&'length'&>,<&'parent number'&>#<&'flag bits'&> | |
32221 | .endd | |
168e428f PH |
32222 | The 01 flag bit indicates the presence of the three other fields that follow |
32223 | the top-level address. Other bits may be used in future to support additional | |
9b371988 PH |
32224 | fields. The <&'parent number'&> is the offset in the recipients list of the |
32225 | original parent of the &"one time"& address. The first two fields are the | |
168e428f PH |
32226 | envelope sender that is associated with this address and its length. If the |
32227 | length is zero, there is no special envelope sender (there are then two space | |
9b371988 PH |
32228 | characters in the line). A non-empty field can arise from a &(redirect)& router |
32229 | that has an &%errors_to%& setting. | |
168e428f PH |
32230 | |
32231 | ||
32232 | A blank line separates the envelope and status information from the headers | |
32233 | which follow. A header may occupy several lines of the file, and to save effort | |
32234 | when reading it in, each header is preceded by a number and an identifying | |
32235 | character. The number is the number of characters in the header, including any | |
32236 | embedded newlines and the terminating newline. The character is one of the | |
32237 | following: | |
32238 | ||
9b371988 PH |
32239 | .table2 50pt |
32240 | .row <&'blank'&> "header in which Exim has no special interest" | |
32241 | .row &`B`& "&'Bcc:'& header" | |
32242 | .row &`C`& "&'Cc:'& header" | |
32243 | .row &`F`& "&'From:'& header" | |
32244 | .row &`I`& "&'Message-id:'& header" | |
32245 | .row &`P`& "&'Received:'& header &-- P for &""postmark""&" | |
32246 | .row &`R`& "&'Reply-To:'& header" | |
32247 | .row &`S`& "&'Sender:'& header" | |
32248 | .row &`T`& "&'To:'& header" | |
32249 | .row &`*`& "replaced or deleted header" | |
32250 | .endtable | |
168e428f PH |
32251 | |
32252 | Deleted or replaced (rewritten) headers remain in the spool file for debugging | |
32253 | purposes. They are not transmitted when the message is delivered. Here is a | |
32254 | typical set of headers: | |
9b371988 PH |
32255 | .code |
32256 | 111P Received: by hobbit.fict.example with local (Exim 4.00) | |
32257 | id 14y9EI-00026G-00; Fri, 11 May 2001 10:28:59 +0100 | |
32258 | 049 Message-Id: <E14y9EI-00026G-00@hobbit.fict.example> | |
32259 | 038* X-rewrote-sender: bb@hobbit.fict.example | |
32260 | 042* From: Bilbo Baggins <bb@hobbit.fict.example> | |
32261 | 049F From: Bilbo Baggins <B.Baggins@hobbit.fict.example> | |
32262 | 099* To: alice@wonderland.fict.example, rdo@foundation, | |
32263 | darcy@austen.fict.example, editor@thesaurus.ref.example | |
32264 | 104T To: alice@wonderland.fict.example, rdo@foundation.example, | |
32265 | darcy@austen.fict.example, editor@thesaurus.ref.example | |
32266 | 038 Date: Fri, 11 May 2001 10:28:59 +0100 | |
32267 | .endd | |
32268 | The asterisked headers indicate that the envelope sender, &'From:'& header, and | |
32269 | &'To:'& header have been rewritten, the last one because routing expanded the | |
32270 | unqualified domain &'foundation'&. | |
32271 | ||
32272 | ||
32273 | ||
32274 | ||
32275 | . //////////////////////////////////////////////////////////////////////////// | |
32276 | . //////////////////////////////////////////////////////////////////////////// | |
32277 | ||
32278 | .chapter "Adding new drivers or lookup types" "" &&& | |
32279 | "Adding drivers or lookups" | |
32280 | .cindex "adding drivers" | |
32281 | .cindex "new drivers" "adding" | |
32282 | .cindex "drivers" "adding new" | |
168e428f PH |
32283 | The following actions have to be taken in order to add a new router, transport, |
32284 | authenticator, or lookup type to Exim: | |
32285 | ||
9b371988 PH |
32286 | .olist |
32287 | Choose a name for the driver or lookup type that does not conflict with any | |
32288 | existing name; I will use &"newdriver"& in what follows. | |
32289 | .next | |
32290 | Add to &_src/EDITME_& the line: | |
32291 | .display | |
32292 | <&'type'&>&`_NEWDRIVER=yes`& | |
32293 | .endd | |
32294 | where <&'type'&> is ROUTER, TRANSPORT, AUTH, or LOOKUP. If the | |
168e428f PH |
32295 | code is not to be included in the binary by default, comment this line out. You |
32296 | should also add any relevant comments about the driver or lookup type. | |
9b371988 PH |
32297 | .next |
32298 | Add to &_src/config.h.defaults_& the line: | |
32299 | .code | |
32300 | #define <type>_NEWDRIVER | |
32301 | .endd | |
32302 | .next | |
32303 | Edit &_src/drtables.c_&, adding conditional code to pull in the private header | |
168e428f | 32304 | and create a table entry as is done for all the other drivers and lookup types. |
9b371988 PH |
32305 | .next |
32306 | Edit &_Makefile_& in the appropriate sub-directory (&_src/routers_&, | |
32307 | &_src/transports_&, &_src/auths_&, or &_src/lookups_&); add a line for the new | |
168e428f | 32308 | driver or lookup type and add it to the definition of OBJ. |
9b371988 PH |
32309 | .next |
32310 | Create &_newdriver.h_& and &_newdriver.c_& in the appropriate sub-directory of | |
32311 | &_src_&. | |
32312 | .next | |
32313 | Edit &_scripts/MakeLinks_& and add commands to link the &_.h_& and &_.c_& files | |
168e428f | 32314 | as for other drivers and lookups. |
9b371988 | 32315 | .endlist |
168e428f PH |
32316 | |
32317 | Then all you need to do is write the code! A good way to start is to make a | |
32318 | proforma by copying an existing module of the same type, globally changing all | |
32319 | occurrences of the name, and cutting out most of the code. Note that any | |
32320 | options you create must be listed in alphabetical order, because the tables are | |
32321 | searched using a binary chop procedure. | |
32322 | ||
9b371988 | 32323 | There is a &_README_& file in each of the sub-directories of &_src_& describing |
168e428f PH |
32324 | the interface that is expected. |
32325 | ||
32326 | ||
32327 | ||
32328 | ||
9b371988 PH |
32329 | . //////////////////////////////////////////////////////////////////////////// |
32330 | . //////////////////////////////////////////////////////////////////////////// | |
32331 | ||
32332 | .makeindex "Option index" "option" | |
168e428f | 32333 | |
9b371988 | 32334 | .makeindex "Concept index" "concept" |
168e428f | 32335 | |
168e428f | 32336 | |
9b371988 PH |
32337 | . ///////////////////////////////////////////////////////////////////////////// |
32338 | . ///////////////////////////////////////////////////////////////////////////// |